AgencyOps

AgencyOps is the operating manual and reusable knowledge base for a small modern web agency. It records stable ways of working, reusable standards, and lessons worth carrying between projects.

It is not a client project, a dumping ground for notes, or an Astro starter itself. Client-specific decisions stay with the client project. Executable starter code stays in a starter repository.

Repository shape

Create a directory only when it has a real first document. The intended structure is:

AgencyOps/
├── README.md
├── ROADMAP.md
├── AGENTS.md
├── principles/
├── standards/
├── sops/
├── checklists/
├── playbooks/
├── templates/
├── reference/
├── legal/
├── decisions/
└── starters/

Directory	Purpose
principles/	Enduring beliefs and decision criteria that explain how the agency chooses, especially when no rule covers the situation.
standards/	Durable rules and quality bars that apply across projects: accessibility, code quality, content, security, performance, and delivery.
sops/	Repeatable procedures with an owner, trigger, inputs, ordered steps, and completion criteria.
checklists/	Concise verification lists used at a specific control point to prevent omissions.
playbooks/	Situation-specific guidance that requires judgment, such as handling an incident or rescuing a delayed launch.
templates/	Copyable starting structures for artifacts such as briefs, reports, and handoff notes. A template should usually support an SOP or playbook.
reference/	Non-prescriptive facts and lookup material such as definitions, supported platforms, tool maps, and glossaries.
legal/	Controlled, counsel-reviewed reusable legal templates and their index when they eventually exist. It never stores executed client agreements or legal advice.
decisions/	Short architecture decision records for consequential AgencyOps choices, including superseded decisions.
starters/	Contracts and adoption guidance shared by Astro starter repositories. It describes expectations; it does not duplicate starter source code.

Where content belongs

• A durable belief that guides tradeoffs belongs in principles/.
• A testable requirement or quality threshold belongs in standards/.
• An ordered, repeatable procedure belongs in sops/.
• A short verification aid used at a control point belongs in checklists/.
• Branching guidance for a situation requiring judgment belongs in playbooks/.
• A fill-in or copyable artifact structure belongs in templates/.
• Factual lookup material that does not direct action belongs in reference/.
• A reusable legal instrument belongs in legal/ only after appropriate legal review and approval; operational rules about using it belong in standards/ or sops/.
• The reason behind a lasting repository-level choice belongs in decisions/.
• A requirement or mapping for Astro starters belongs in starters/.

If content does not clearly fit, keep it in an issue or working note until its purpose is understood. Do not create a miscellaneous directory.

The legal/ directory is a controlled artifact boundary rather than an eighth operational knowledge category. Create it only when the agency has a genuinely approved reusable legal template. A minimal future shape is legal/README.md as the template index and legal/templates/ for canonical source files. Add jurisdiction or service-specific subdirectories only when real variants require them. Executed agreements, client-specific drafts, signatures, legal advice, negotiation records, and privileged communications belong in an approved contract or client-record system, not this repository.

Foundational documents

The first useful documents should follow real agency work, not an attempt to map the entire business. In priority order:

1. standards/definition-of-done.md — the shared quality threshold for shipped work.
2. sops/project-lifecycle.md — the path from qualified lead through handoff and support.
3. standards/web-baseline.md — the cross-project accessibility, performance, SEO, security, and browser baseline.
4. sops/change-control.md — how scope, approvals, and client-impacting changes are handled.
5. starters/astro-contract.md — what every Astro starter must expose, enforce, and document.
6. templates/project-brief.md — the smallest useful project intake artifact, created alongside the lifecycle process.

Add these one at a time according to the roadmap. Each must have an owner and a concrete use before it is written.

Documentation philosophy

AgencyOps follows a few rules:

• One canonical home. Link to a rule instead of repeating it. Project repositories may record a deliberate exception.
• Minimum useful detail. Prefer a checklist, example, or decision table over broad prose. Include enough context to act correctly.
• Stable knowledge only. Drafts, task tracking, and meeting notes belong in working tools. Promote them here when they become reusable.
• Docs beside decisions. Update the relevant documentation in the same change that alters a shared practice.
• Human- and machine-readable. Use descriptive headings, explicit requirements, relative links, simple Markdown, and unambiguous language such as MUST, SHOULD, and MAY where strength matters.
• Ownership and review. Operational documents state an owner and review date. Review does not imply rewriting; it confirms continued validity.
• Archive through history. Prefer Git history and decision supersession to parallel old, new, or final copies.

Most operational documents should begin with compact metadata:

---
title: Definition of Done
status: draft # draft | tested | standard | archived
owner: delivery
last_reviewed: 2026-07-13
review_cycle: 6 months
---

Decision records may use proposed, accepted, superseded, or rejected instead.

Knowledge model

The seven operational categories answer different questions. A document should have one primary category even when it links to several others.

Principles — why we choose

Purpose: State durable beliefs and tradeoff criteria that guide decisions when rules or procedures do not fully apply.

Create one when the same underlying judgment recurs across multiple areas and is expected to remain useful for years. Do not put measurable requirements, ordered instructions, slogans, or project-specific opinions here.

Principles may motivate standards and help resolve branches in playbooks. Those documents should link to the principle; the principle should not duplicate their rules or steps.

Standards — what must be true

Purpose: Define testable requirements, constraints, defaults, and quality thresholds.

Create one when multiple projects need the same enforceable expectation and compliance can be assessed. Do not put detailed procedures, aspirational beliefs, vendor documentation, or a task list here.

A standard may cite the principles behind it. SOPs and checklists should link to the standard they implement or verify instead of restating its rationale and full requirements.

SOPs — how repeatable work is done

Purpose: Give an owner a dependable sequence for a recurring operation, including its trigger, inputs, steps, exceptions, and completion criteria.

Create one when work repeats, sequence matters, and variation causes risk or waste. Do not use an SOP for one-off projects, broad policy, simple verification lists, or situations whose response must substantially change with context.

An SOP links to governing standards, invokes checklists at control points, and uses templates for outputs. It may hand exceptional conditions to a playbook rather than embedding every branch.

Checklists — what must not be missed

Purpose: Provide a short, usable verification aid at a defined moment such as pre-launch or handoff.

Create one when a trained person understands the work but omissions remain likely or costly. Do not put training, rationale, extensive instructions, branching diagnosis, or blank artifact fields here.

A checklist should link to the SOP that calls it and to standards for item details. Checklist items stay terse; canonical explanations stay in the linked source.

Playbooks — how to respond with judgment

Purpose: Guide action in variable or exceptional situations using signals, options, decision points, escalation paths, and recovery actions.

Create one when the objective repeats but the correct path depends on context, such as an incident or a troubled delivery. Do not turn routine linear work into a playbook, promise a single universal response, or use it as a collection of unrelated tips.

A playbook links to relevant principles for tradeoffs, standards for boundaries, SOPs for routine sub-procedures, checklists for critical verification, and templates for communications or records.

Templates — what an output starts from

Purpose: Provide a reusable structure for producing a consistent artifact efficiently.

Create one when the same deliverable is repeatedly recreated and consistent fields or presentation matter. Do not embed policy, explanatory guidance, completed client data, or a disguised checklist here.

The calling SOP or playbook explains when and how to use a template. The template links back to that guidance and links to standards only where a field needs interpretation.

Reference material — facts to look up

Purpose: Make stable, reusable facts easy to retrieve without prescribing a decision or workflow.

Create one when people repeatedly need the same definitions, compatibility data, ownership map, or tool facts. Do not use reference material for rules, procedures, uncurated links, temporary research, or information better maintained by an authoritative external source.

Operational documents link to reference entries for shared facts. Reference material may point to its authoritative source, but it should not silently become a standard or duplicate instructions.

Linking without duplication

Use this dependency direction as a default:

principles -> standards -> SOPs -> checklists
                    \        \-> templates
                     \-> playbooks -> checklists/templates
reference <---- linked wherever shared facts are needed

Each fact, rule, rationale, procedure, and artifact structure has one canonical home. Other documents give a short statement of relevance and a relative link. They do not copy sections for convenience. Links may flow both ways for navigation, but authority remains with the category that owns the information.

Document lifecycle

Operational documents use four statuses:

1. Draft — an owner and use case exist, but the content has not yet been used end to end. Drafts may change freely and are not agency requirements.
2. Tested — used in at least one real workflow and revised from evidence. The owner records where or when it was tested in the change history or pull request.
3. Standard — approved as the current agency-wide source and safe for projects and starters to depend on. Promotion requires a named owner, valid links, resolved test feedback, and a review cycle.
4. Archived — no longer applicable or replaced. The document states why and links to its replacement when one exists; it is excluded from current guidance.

Promotion is deliberate, not automatic with age. A document can return from tested to draft after major revision. A breaking change to a standard document is reviewed and released according to the versioning policy. Prefer Git history over retaining archived files; keep an archived document only when its context or inbound links still have operational value.

Naming conventions

• Use lowercase kebab-case for directories and Markdown files: change-control.md.
• Name documents for the concept, not the department or date: project-lifecycle.md, not ops-process-v2.md.
• Use numbered filenames only where order and identity matter. Decision records use NNNN-short-title.md, beginning with 0001.
• Use stable, descriptive headings; assistants and links depend on them.
• Give templates the name of the artifact they produce: project-brief.md, not brief-template.md. A template for a conventional root-level repository file MAY preserve that uppercase filename, such as PROJECT.md.
• Avoid misc, general, notes, new, final, and personal names.

Versioning and change practice

Use Git as the primary history and release mechanism.

• Make small changes with commit messages that explain the operational outcome.
• Review changes through pull requests once more than one maintainer is active.
• Use decision records for choices that are costly to reverse or affect multiple repositories.
• Mark replaced documents archived and link to their replacement; delete them after consumers have migrated when history alone is sufficient.
• Tag coherent published baselines using Semantic Versioning, for example v1.0.0. A breaking requirement for consuming starters is major, a backward-compatible new standard is minor, and clarification or correction is patch.
• Maintain a changelog only when tagged releases are actively consumed. Until then, Git history and release notes are enough.

Dates communicate review freshness, not document versions. Do not put version numbers in filenames.

Astro starter integration

AgencyOps should be the policy source; each Astro starter should be an executable implementation of a declared AgencyOps baseline.

Each starter should:

1. Record the AgencyOps release or commit it implements in a small manifest such as agencyops.json.
2. Link to the relevant canonical standards rather than copy their prose.
3. Turn objective rules into local automation: linting, tests, CI checks, budgets, and scaffolding.
4. Keep starter-specific architecture and setup in the starter repository.
5. Document intentional deviations locally with a reason, owner, and review condition.
6. Upgrade AgencyOps deliberately through a reviewed dependency-style change, using release notes to identify required migrations.

Start with a plain manifest and links. Do not introduce a package, Git submodule, or synchronization tool until repetition demonstrates a need. Later, stable machine-readable configuration may be published as a versioned package, while explanatory guidance remains here.

Contributing

Before adding a document, answer three questions: Who uses it? At what moment? What mistake or decision does it improve? If those answers are unclear, do not add the document yet.

See ROADMAP.md for the intentionally small growth plan and AGENTS.md for repository editing guidance.

Maintainer

AgencyOps is maintained by Jason Correia.

Disclaimer

AgencyOps provides general operational guidance. It does not constitute legal, financial, security, or other professional advice. Obtain advice from appropriately qualified professionals for decisions that require it.

License

Copyright 2026 Jason Correia.

AgencyOps documentation, standards, SOPs, templates, and other repository content are licensed under the Creative Commons Attribution 4.0 International License unless otherwise noted.