source

https://github.com/juliusz-cwiakalski/agentic-delivery-os/blob/main/doc/documentation-handbook.md

ados_distribution

redistributable

DOC-HANDBOOK

status

Accepted

created

2025-09-22

last_updated

2026-06-26

owners

engineering

summary

Repository documentation structure, conventions, and workflow.

Documentation Handbook - Structure, Conventions & Workflow (Per-Repository Standard)

Audience: Engineers, product/design, operators, and AI coding/analysis agents.

Goal: A single, predictable docs layout that scales across all repositories (UI apps, microservices, libraries), is easy for humans to navigate, and is highly effective for AI agents to find the right context and write/update specs.

1) Where this document lives

Path in every repo: doc/documentation-handbook.md
Linked from:
- /README.md → add a short “Docs at a glance” section linking here and to doc/00-index.md.
- doc/00-index.md → add a prominent link “Documentation Handbook (how docs work)”.

Keep this file identical across repos. Treat it as shared (see §10) with your chosen sync mechanism ( submodule/subtree/automation).

2) Principles

Separation of Concerns:
- Humans primarily read and write under /doc.
- OpenCode tooling (agents/commands) lives under /.opencode.
- Repo-specific agent instructions live under /.ai/agent.
- Local agent context lives under /.ai/local and is git-ignored.
Single Source of Truth: Contracts (OpenAPI/AsyncAPI/schemas) are canonical under /doc/contracts in the owning repo; consumers pull them as versioned artifacts.
Evolution is Trackable: New behavior starts as a Change (/doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/), settles with a Decision Record, and updates the Spec (/doc/spec).
Predictable Conventions: Numbering, front-matter, and naming are consistent and enforced by lightweight checks.

2a) Documentation Profiles (Safety Gate Before Writing)

Before creating new documentation areas, humans and agents must determine the active repository profile.

Supported profiles

engineering-repo
central-product-docs-repo
business-strategy-repo
mixed-product-engineering-repo

Repository profile contract (`doc/documentation-profile.md`)

If present, this file is the deterministic write-safety contract for docs creation:

id
status
profile
business_docs_enabled
business_docs_root
canonical_strategy_repo
allowed_write_roots
forbidden_write_roots
owners
last_updated

Missing-profile fallback (required)

If doc/documentation-profile.md is missing, assume:

profile: engineering-repo
business_docs_enabled: false
No new business documentation content should be created unless a user explicitly requests it. Because the profile is missing, there is no configured business_docs_root; if business docs are intentionally enabled later, assume the default root is doc/business (contents under doc/business/**) unless doc/documentation-profile.md specifies a different business_docs_root.

If a user asks for business artifacts while disabled, explain the constraint and suggest either:

Using the canonical strategy repository configured by the team, or
Intentionally adding/updating doc/documentation-profile.md first.

Optional business documentation capability map (not a bootstrap tree)

When business docs are enabled, the configured business_docs_root may be used as a capability map (default: doc/business, i.e., the tree under doc/business/**; create only what is needed). The areas below are relative to that configured root:

context/
market/
customers/
product-strategy/
discovery/
growth/
marketing/
sales/
customer-success/
finance/
metrics/
operations/
research/
meetings/

This is an optional map for navigation and ownership boundaries, not a requirement to create a full empty folder tree or placeholder documents.

Current truth vs raw evidence

Current-truth docs represent accepted strategy and should be maintained.
Raw notes (interviews, feedback, research, meeting notes) are supporting evidence and should not override current truth until synthesized.
Raw evidence should include:
- source_type (for example: interview, sales-call, support-feedback, market-research)
- synthesis_status (raw, in-review, synthesized)

Minimal examples policy (cap, not manifest)

The first iteration commits at most the following examples; none are required and none have been committed yet. Treat this list as a ceiling, not an inventory.

Engineering profile example
Central product docs profile example
BDR example
Experiment register example
Minimal business index example

2b) Meeting documentation conventions

Meeting agendas, minutes/summaries, and transcripts use a single combined meeting-notes-template.md that starts as an agenda before the meeting and is extended into a summary afterward. The document has distinct sections for agenda/prep (copy/paste-friendly), discussion, decisions, action items, ideas, open questions, parked items, and notes worth keeping.

Document lifecycle:

Before the meeting: fill in the "Agenda & Preparation" block (goal, time-boxed topics, prep, attendees, roles).
During the meeting: capture discussion, decisions, action items, ideas, open questions, parked items.
After the meeting: finalize the summary, update status to Accepted, document_classification to current-truth, synthesis_status to synthesized. Send action items within 60 minutes; distribute the full summary within 24 hours.

Two ways to share the agenda:

Copy/paste: select the "Agenda & Preparation" block from the meeting notes file and paste it into the calendar invite.
Git-native: commit the meeting notes file (or open a PR) before the meeting and share the file/PR URL as the calendar invite link. Collaborators can comment on the agenda, ask questions, and propose additions before the meeting starts.

Storage rules:

Repo-scoped meetings (e.g., a microservice planning session, a service team retro) live in doc/meetings/ of the implementation repository. This is engineering-safe and allowed by default in all profiles.
Cross-repo, product, or business meetings (e.g., product strategy review, all-hands, leadership sync) live in doc/business/meetings/ of the canonical strategy repository. This requires business_docs_enabled: true or explicit user direction.
When in doubt, an agent asks the user whether the meeting is repo-scoped or cross-repo before selecting the write location.

Filename and transcript convention:

doc/meetings/YYYY-MM-DD-<topic-slug>.md — single file with agenda + summary + decisions + action items.
doc/meetings/transcripts/YYYY-MM-DD-<topic-slug>.txt — full transcripts stored in a transcripts/ subfolder (one click away, not inlined).
For business meetings: doc/business/meetings/YYYY-MM-DD-<topic-slug>.md and doc/business/meetings/transcripts/.
Link transcripts and recordings via transcript_url and recording_url in front matter.

Classification:

Raw agendas, live notes, and transcripts are document_classification: raw-evidence with source_type: meeting.
When the summary, decisions, and action items are accepted, update the document to document_classification: current-truth and synthesis_status: synthesized.
Significant decisions recorded in a meeting should also be filed as ADR/PDR/BDR records in doc/decisions/ and cross-linked via related_decisions.

3) Repository Layout (Standard Tree)

/README.md                        # Short repo intro + quick links to doc/
/CONTRIBUTING.md                  # PR/MR rules, coding & docs conventions
/CHANGELOG.md                     # Keep a Changelog style (optional)

/.opencode/                         # OpenCode agents + commands (repo-local tooling)
  /agent/                           # One file per agent prompt
  /command/                          # Repeatable commands/macros

/.ai/                               # Repo-specific agent config + local context
  /agent/                            # Repo-specific agent instructions (committed, incl. code-review checklist)
  /local/                            # Local agent context (git-ignored)
  /rules/                            # Optional org-wide rules

/doc/
  00-index.md                      # Manual TOC + “For humans”/“For AI agents” entry points
  /guides/                         # Developer how-to guides (local setup, tooling, debugging)
  /overview/
    01-north-star.md               # Repo-appropriate extract if not the product root
    02-roadmap.md                  # High-level phases + links to changes/ADRs
    architecture-overview.md       # C4/mermaid overview diagrams
    glossary.md                    # See §9 for scope
    ubiquitous-language.md         # See §9 for scope
  /spec/                           # Current truth (coherent, post-change)
    features/                      # Feature-level specs (UI or service)
    api/                           # Endpoint/operation descriptions (human layer)
    nonfunctional.md               # Perf, security, scalability envelopes
  /changes/                        # Proposed & accepted changes (evolution log)
    YYYY-MM/
      YYYY-MM-DD--<workItemRef>--<slug>/
        chg-<workItemRef>-spec.md       # Canonical change spec (with front-matter)
        chg-<workItemRef>-test-plan.md  # Per-change test plan (traceable to AC)
        chg-<workItemRef>-plan.md       # Implementation plan (phases/tasks)
        chg-<workItemRef>-pm-notes.yaml # PM progress + decisions + open questions
        chg-<workItemRef>-notes.md      # Optional free-form notes
  /decisions/                      # Decision Records (ADR/PDR/TDR/BDR/ODR)
    ADR-0001-short-title.md        # Type-prefixed, zero-padded 4-digit number
  /contracts/
    rest/
      openapi.yaml                 # Can be generated; is canonical in owning repo
      examples/                    # HTTP request/response samples
    events/
      asyncapi.yaml                # Event catalog; channels, messages, bindings
      schemas/                     # JSON Schema / Avro for event payloads
    data/
      schemas/                     # DB/Dynamo/ES schemas (if applicable)
  /domain/
    ubiquitous-language.md         # (Mirrors /overview file or links to global)
    aggregates-and-entities.md     # Domain model at rest
    events-catalog.md              # Business events (domain perspective)
  /quality/
    test-specs/                    # Tessa’s output; manual/automated test specs
    performance/                   # Perf test plans & SLAs
    security/                      # Threat model (STRIDE/LINDDUN), controls
  /ops/
    runbooks/                      # On-call playbooks
    observability/                 # Metrics, logs, traces, dashboards
    troubleshooting/               # Known issues, fixes, log signatures
    incident-reviews/              # Post-incident docs (blameless)
  /analytics/
    tracking-taxonomy.md           # App/UX events mapping (UI repos esp.)
  /i18n/                           # Translation notes, error terms (UI repos)
  /tools/                          # User guides for CLI tools in tools/ (one per tool)
  /diagrams/                       # Mermaid/PlantUML sources; exported PNG/SVG
  /examples/                       # Payloads, fixtures, UI mocks (shared samples)
  /meetings/                       # Repo-scoped meeting notes (agenda + summary + decisions + action items)
    /transcripts/                  # Full meeting transcripts (linked via transcript_url, not inlined)
  /templates/                      # Authoring templates (change spec, decision record, feature, test, plan)
  /prompts/                        # Human-facing generation prompts (copy/UX)

/scripts/
  doc/
    doc-checks.sh                    # Lints front-matter, numbering, links (optional; see §14 for current availability)
    build-docs.sh                    # Optional mkdocs/docusaurus export

4) Folder-by-Folder Guide

4.1 `/.ai/` (for Agents)

/agent/: Repo-specific instructions that agents must follow (committed). Includes pm-instructions.md (issue tracker config) and pr-instructions.md (PR/MR platform config).
/local/: Local-only agent context (git-ignored). Never commit content from here.
/rules/: Optional rules such as the spec workflow, naming conventions, review criteria.

4.1a `/.opencode/` (OpenCode tooling)

/agent/: Agent prompts.
/command/: CLI commands that compose agents.

Why: Agents become deterministic and fast by loading only the relevant context (see AGENTS.md and .opencode/agent/ for agent definitions).

4.2 `/doc/` (for Humans, yet agent-friendly)

00-index.md: Landing page for docs. Include:
- “Start here” (overview, architecture, current spec)
- “Changing behavior?” (how to write a change)
- “For AI agents” (link to AGENTS.md and .opencode/agent/)
/overview/:
- 01-north-star.md and 02-roadmap.md: Keep concise, repo-relevant extracts (if the full product vision lives elsewhere, link to it).
- architecture-overview.md: High-level C4/mermaid; link to /doc/diagrams for sources.
- glossary.md vs ubiquitous-language.md: See §9 for the difference and usage.
- For the full set of overview files with Recommended / Conditional / Optional classification (including product-discovery and UX artifacts), see the Inception Artifact Catalog section below and the Project Inception guide.
/spec/: The coherent, up-to-date description of the system after applying accepted changes. Split into features/, api/, and a single nonfunctional.md (SLOs, auth, rate limits, perf goals).
/guides/: Practical, step-by-step developer guides for common tasks. This is the home for "how-to" documentation, such as local environment setup, debugging procedures, and using repository-specific tooling (e.g., AI-powered MR helpers). While /ops/runbooks are for on-call procedures, /guides are for day-to-day development workflows.
/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/:
- chg-<workItemRef>-spec.md (required): The proposal accepted change (CHANGE SPEC).
- chg-<workItemRef>-test-plan.md (recommended): Per-change test plan aligned to the CHANGE SPEC.
- chg-<workItemRef>-plan.md (recommended): Work breakdown, risks, rollout/rollback (IMPLEMENTATION PLAN).
- chg-<workItemRef>-pm-notes.yaml (recommended): PM progress + decisions + open questions.
- examples.json (optional): Requests/responses, UI screenshots links.
/decisions/<TYPE>-<zeroPad4>-<slug>.md: Decision records (ADR/PDR/TDR/BDR/ODR). A change may produce 0..n decision records. Link them both ways:
- From the change front-matter: links.decisions: ["ADR-0021"]
- From the decision record: reference the workItemRef in the body or via front-matter links.related_changes.
/contracts/:
- rest/openapi.yaml: HTTP contracts (server = owner). Generated clients should come from this file’s versioned release.
- events/asyncapi.yaml + events/schemas/: Event channels and payload types. Producer owns the event. Consumers align via versioned schemas.
- data/schemas/: Schema docs for databases/collections/tables (for operators & migration planning).
/domain/:
- ubiquitous-language.md: The authoritative terms for this bounded context.
- aggregates-and-entities.md: Classifies aggregates, entities, value objects.
- events-catalog.md: Business/domain events (their meaning, not transport details).
/quality/:
- test-specs/ (Tessa output + human additions, organized by feature as test-spec-<feature-slug>.md (e.g., test-spec-tenants.md))
- performance/ (perf test plans, load profiles, thresholds)
- security/ (threat model, mitigations, test procedures)
/ops/:
- runbooks/ (operational procedures)
- observability/ (dashboards, metrics, log fields, trace spans)
- troubleshooting/ (known issues, queries, checklists)
- incident-reviews/ (postmortems)
/tools/: User guides for standalone CLI tools published under tools/ at the repo root. Each tool gets a dedicated file: doc/tools/<tool-name>.md with version, provider/backend setup, usage examples, configuration, troubleshooting, CLI reference, and changelog. See doc/guides/tools-convention.md for the full standard.
/analytics/: Tracking taxonomy & mapping to GA/PostHog (mostly UI repos).
/i18n/: Internationalization specifics (UI repos).
/diagrams/: Source first (mermaid/PUML), plus exported artifacts.
/examples/: Cross-cutting example payloads & mocks.
/meetings/: Repo-scoped meeting notes following the meeting-notes-template.md. Filename: YYYY-MM-DD-<topic-slug>.md. Each meeting file starts as an agenda and is extended into a summary. Transcripts live in /meetings/transcripts/. See §2b for lifecycle, cross-repo/business meeting storage rules, and agenda-sharing workflows.
/templates/: All authoring templates (change spec, decision record, feature spec, test spec, test plan, implementation plan).
/prompts/: Human-facing content prompts (marketing copy, release notes). Agent system prompts remain in .opencode/agent/.

4.3 `/scripts/doc`

doc-checks.sh (optional; see §14 for current availability): Lints front-matter and file naming, checks cross-links.
build-docs.sh: Optional static site build (mkdocs + mermaid plugin recommended).

5) Front‑Matter & Naming

Use front-matter on every doc under /doc so humans & agents can parse metadata.

---
id: GH-456 # or ADR-0021, SPEC-UNITS-DISPLAY, etc.
status: Proposed # Proposed | Accepted | Rejected | Superseded | Deprecated
created: 2025-09-05
last_updated: 2025-09-05
owners: ["juliusz"]
service: "recipes-service" # or "ui-app"
links:
  adr: ["ADR-0021"]
  supersedes: []
  related_changes: ["GH-455"]
  contracts:
    - "contracts/rest/openapi.yaml#/paths/~1recipes~1search"
summary: "Unify units display across UI using unit IDs + i18n."
---

Change conventions:

Folder: doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/.
Filenames are stable and slug-free:
- chg-<workItemRef>-spec.md
- chg-<workItemRef>-test-plan.md
- chg-<workItemRef>-plan.md
- chg-<workItemRef>-pm-notes.yaml
workItemRef is tracker-linked (e.g., PDEV-123, GH-456).
Decision records: <TYPE>-<zeroPad4>-<slug>.md (e.g., ADR-0001-event-bus-selection.md, PDR-0001-free-tier-scope.md).
Kebab-case filenames, short and descriptive.

6) Lifecycle: From Change → Decision Record → Spec → Contracts

Propose a change in /doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/chg-<workItemRef>-spec.md (or via /write-spec <workItemRef>).
Discuss & revise until Accepted/Rejected.
If the change settles a decision, write a decision record under /doc/decisions/ (or use /plan-decision + /write-decision) and link it from the change.
Create or update the per-change TEST PLAN alongside the spec as chg-<workItemRef>-test-plan.md (or via /write-test-plan <workItemRef>).
Create or update the IMPLEMENTATION PLAN alongside the spec as chg-<workItemRef>-plan.md (or via /write-plan <workItemRef>).
Update /doc/spec/ to reflect the final, coherent behavior (ideally via /sync-docs <workItemRef>).
Update /doc/contracts/ (OpenAPI/AsyncAPI/schemas) if any external surface changes.
Align test specs under /doc/quality/test-specs/ with the per-change TEST PLAN.
Implementation: code + tests, referencing the change ID in commit/PR titles.
Release notes: Use /doc/prompts/ to generate drafts, then publish.

For significant business/product strategy changes, reuse the same lifecycle and naming (chg-*) and capture validation with methods such as interviews, experiments, landing-page checks, sales calls, metric checks, launch criteria, stop criteria, and pivot criteria.

Agents: see AGENTS.md for the delivery workflow and .opencode/command/*.md for per-step context loading.

7) How Humans Work with the Docs

New feature/behavior: start with a Change spec (template in /doc/templates/).
Decision needed: author an ADR/TDR/PDR/BDR/ODR under doc/decisions/; link it to the Change. Pricing defaults to BDR unless product scope (PDR) or operational scope (ODR) is a better fit.
Keep Spec fresh: any merged change must update /doc/spec/ in the same PR.
Contracts:
- If you own the API/event: edit /doc/contracts/**, bump version, regenerate clients.
- If you consume it: update the dependency version; never hand-edit owned contracts.
Ops knowledge: add runbooks/troubleshooting as you learn.
Review checklist: PRs must include updated docs or an explicit N/A with rationale.

8) How AI Agents Use the Docs

Plan & Implement: load the current Change spec, referenced decision records, impacted Spec sections, Contracts, and testing strategy per AGENTS.md and .opencode/command/*.md.
Write artifacts to the right place:
- Implementation plan -> /doc/changes/**/chg-<workItemRef>-plan.md (or via /write-plan <workItemRef>)
- Per-change TEST PLAN -> /doc/changes/**/chg-<workItemRef>-test-plan.md (or via /write-test-plan <workItemRef>)
- PM progress notes -> /doc/changes/**/chg-<workItemRef>-pm-notes.yaml
- Broader test specs -> /doc/quality/test-specs/
- Updated OpenAPI/AsyncAPI -> /doc/contracts/**
- Final edits to /doc/spec/** per the change outcome (ideally via /sync-docs <workItemRef>)
Cross-linking: update front-matter links.* so the web of docs stays navigable.
Decision compatibility: business/product/operational metadata fields in the decision template are optional; ADR/TDR records remain valid without them.

9) Glossary vs Ubiquitous Language (UL)

Ubiquitous Language (DDD):

A precise, bounded-context vocabulary used by domain experts and developers.
Names the core domain concepts (Aggregates, Entities, Value Objects, Domain Events) and their relationships.
Normative: terms here are binding within this context.
Location: /doc/overview/ubiquitous-language.md (and mirrored under /doc/domain/ if you prefer domain-centric grouping).

Glossary:

A broader, reader-friendly list of terms and acronyms used in this repository.
Includes general tech acronyms (e.g., P90, SLO, JWT), business abbreviations, and any terms that are not part of the domain model but appear in docs/specs.
Descriptive: helps new readers; not necessarily binding as model terms.
Location: /doc/overview/glossary.md.

Global vs Local:

Keep a global UL (product-level, authoritative across all repos) in a central product docs repo; each repo keeps a local UL that either mirrors the global terms relevant to this bounded context or refines them for this context ( without contradictions).
Keep a global Glossary for organization-wide acronyms/terms; each repo may keep a local Glossary for repo-specific terms.

Rule of thumb: If a term names a domain model element or behavior, it belongs in UL. If it explains an acronym, tool, or a non-model concept, it belongs in the Glossary.

10) Multi‑Repo: Shared vs Repo‑Specific (and Sync)

The table below indicates what is shared across repos (kept identical or centrally managed), what is **domain-scoped ** (shared across a subset), and what is repo-specific.

Area	Location	Scope	Ownership	Sync Mechanism
Documentation Handbook (this file)	`doc/documentation-handbook.md`	Shared (global)	Platform/Product	Git submodule/subtree; automated sync
Templates (ADR/Change/Test/MR)	`doc/templates/`	Shared (global)	Platform/Product	Submodule/subtree; versioned
AI Rules & Agents	`/.ai/rules/`, `.opencode/agent/`	Shared (global)	Platform/Product	Submodule/subtree; versioned
Ubiquitous Language (Global)	Central product docs repo	Shared (global)	Domain leadership	Single source; repos link/mirror needed parts
Ubiquitous Language (Local)	`/doc/overview/ubiquitous-language.md`	Repo (bounded context)	Repo owners	Local file; must not contradict global
Glossary (Global)	Central product docs repo	Shared (global)	Docs team	Single source; repos may link
Glossary (Local)	`/doc/overview/glossary.md`	Repo	Repo owners	Local file
Decision Records (Cross‑cutting)	`/doc/decisions/`	Domain-scoped (affected repos)	Decision owner(s)	Copy or link to affected repos; reference canonical source
Decision Records (Local)	`/doc/decisions/`	Repo	Repo owners	Local
Contracts (OpenAPI/AsyncAPI)	`/doc/contracts/**`	Owner = producer repo	Service owner	Consumers import versioned artifact; do not fork
Data Schemas	`/doc/contracts/data/`	Repo	Service owner	Local (unless explicitly shared DB)
Domain Model Docs	`/doc/domain/**`	Repo	Repo owners	Local with links to global UL
Quality/Test Specs	`/doc/quality/**`	Repo	Repo owners	Local
Ops Runbooks	`/doc/ops/**`	Repo	SRE/Team	Local
Analytics Taxonomy	`/doc/analytics/**`	Domain-scoped (UI apps)	Product Analytics	Shared baseline + app overlays

Notes & Patterns

Decision Records: If a decision record affects multiple repos, keep a canonical record in the decision’s home repo (or a central “architecture” repo) and replicate a copy (or link) to affected repos. Each copy should include a header referencing the canonical source and version.
Events & Schemas: The producer is the single source of truth. Publish schemas as versioned artifacts ( npm/maven/container images/docs package). Consumers import instead of copying.
Global Docs: For UL, Glossary, templates, and AI rules/agents, prefer a single central repo and sync to all service repos via submodule/subtree or automation.
Business strategy ownership: In multi-repo setups, canonical business/product strategy belongs in a central product/business repository. Implementation repositories keep implementation truth (doc/spec/**, contracts, operations, local technical decisions) and link back to canonical strategy instead of duplicating it.

11) Ownership & Governance

Change specs: authored by implementers or product; approved by tech lead/product.
ADRs: authored by decision owner(s); approved by architecture reviewers.
Spec: maintained by the feature owners; must be updated in the same PR as the change.
Contracts: owned by the producer repo; versioned (SemVer); published artifacts.
UL/Glossary: global maintained by domain leadership/docs; local by repo owners.

12) Quickstart Checklists

New Feature/Change

Create doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/chg-<workItemRef>-spec.md from template or via /write-spec <workItemRef>.
Add front-matter; link related ADRs/contracts.
Create/Update per-change TEST PLAN as chg-<workItemRef>-test-plan.md (or via /write-test-plan <workItemRef>), then align broader test specs under /doc/quality/test-specs/ to it.
Create/Update IMPLEMENTATION PLAN as chg-<workItemRef>-plan.md (or via /write-plan <workItemRef>).
Update /doc/contracts/** if surfaces change; bump version.
Update /doc/spec/** to reflect final behavior (ideally via /sync-docs <workItemRef>).
If a docs validation entry point exists, run it. If absent, run git diff --check + manual docs review and record follow-up.

New Cross‑cutting Decision

Draft ADR in home repo (or central arch repo).
Cross-link impacting changes.
Replicate/link ADR to affected repos with canonical reference.

New Event/Schema

Update events/asyncapi.yaml + events/schemas/ in producer repo.
Version bump & publish artifact.
Notify consumers; update dependency versions.

13) Examples

13.1 Example Change Folder

/doc/changes/2026-01/2026-01-22--GH-456--units-unified-display/
  chg-GH-456-spec.md
  chg-GH-456-test-plan.md
  chg-GH-456-plan.md
  chg-GH-456-pm-notes.yaml
  chg-GH-456-notes.md
  examples.json

chg-GH-456-spec.md (excerpt):

---
id: GH-456
status: Accepted
created: 2025-09-05
owners: ["juliusz"]
links:
  adr: ["ADR-0021"]
  contracts: ["contracts/rest/openapi.yaml#/paths/~1items~1display"]
summary: "Unify units display across UI using unit IDs + i18n with pluralization."
---

## Problem

Currently unit display is inconsistent across screens…

## Solution

- Introduce a `UnitDisplay` component reading i18n keys `units.<unitId>`…
- Add fallback rules for unknown units…

## Acceptance

- Given an item with unitId `bottle` and amount `1`…

13.2 Example Decision Record

/doc/decisions/ADR-0021-unified-units-display.md

Decision Record (excerpt):

---
id: ADR-0021
status: Accepted
created: 2025-09-05
links:
related_changes: ["GH-456"]
---

# Decision

We standardize UI unit rendering via `UnitDisplay` component and i18n keys…

13.3 Example Contracts Snippets

OpenAPI (excerpt):

openapi: 3.0.3
paths:
  /recipes/search:
    get:
      operationId: searchRecipes
      parameters:
        - name: q
          in: query
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"

AsyncAPI (excerpt):

asyncapi: 2.6.0
channels:
  recipe.created:
    publish:
      message:
        $ref: "#/components/messages/RecipeCreated"

13.4 Example Agent Context Loading

## When implementing an HTTP change

Agents load context per `.opencode/command/*.md`:

- /doc/changes/**/chg-<workItemRef>-spec.md
- /doc/decisions/**
- /doc/spec/api/**
- /doc/contracts/rest/openapi.yaml
- /doc/quality/test-specs/**

14) Tooling & Automation

Current repository note: no scripts/doc-checks.sh or scripts/doc/doc-checks.sh entry point is present at this time.

Until a validator entry point exists

Run git diff --check.
Perform manual checks for front matter, naming, and link/path correctness.
For changed .yaml templates, run YAML parsing checks.

Follow-up scope for future lightweight profile-aware docs checks

Validate required doc/documentation-profile.md fields when profile file is present.
Validate business_docs_enabled is boolean.
Warn when engineering-profile repos introduce doc/business/** content.
Validate decision record prefix naming (ADR/TDR/PDR/BDR/ODR).
Parse .yaml register templates and fail on syntax errors.

Docs site (optional): Use mkdocs + mkdocs-mermaid2-plugin for a searchable site in CI.

15) FAQs

Q: When does a term go to UL vs Glossary?
A: If it names domain model elements/behaviors → UL. If it’s an acronym, tool, or general term → Glossary. When in doubt, add to Glossary and propose an UL entry if it becomes model-relevant.

Q: Should ADRs be everywhere?
A: Only in repos impacted by the decision. Keep one canonical ADR and replicate/link where needed.

Q: Where do I put “how to fix X error”?
A: /doc/ops/troubleshooting/.

Q: Where do I put UX copy prompts?
A: /doc/prompts/. Agent system prompts belong in .opencode/agent/.

Q: Who owns OpenAPI/AsyncAPI?
A: The producer (the service that exposes the API or publishes the event). Consumers import versioned artifacts.

16) Invariants & Style Guide

Write in present tense for Spec (it describes current truth).
One concern per doc; keep files short; link out liberally.
Prefer mermaid/PUML sources for diagrams; commit generated images.
Always cross-link Change ↔ ADR ↔ Spec ↔ Contracts via front-matter links.*.
Docs update is part of the PR; code without docs is not done.

16a) Rollback Guidance for Profile-Aware Documentation Updates

If profile-aware behavior proves unsafe before release:

Revert profile-specific handbook additions and template index additions in one docs-only revert.
Remove newly added business templates/register templates from index references.
Keep the existing engineering defaults and unified decision-record model intact.

If only validation wording is incorrect, update/revert the validation subsection without removing the profile model.

17) Appendix: Template Index

Core ADOS templates

doc/templates/change-spec-template.md
doc/templates/decision-record-template.md
doc/templates/feature-spec-template.md
doc/templates/test-spec-template.md
doc/templates/test-plan-template.md
doc/templates/implementation-plan-template.md
doc/templates/north-star-template.md
doc/templates/pr-instructions-template.md

Documentation profile contract template

doc/templates/documentation-profile-template.md

Profile-aware business/product strategy templates (optional; enabled business docs only)

doc/templates/business-north-star-template.md
doc/templates/business-model-template.md
doc/templates/strategic-assumptions-template.md
doc/templates/ideal-customer-profile-template.md
doc/templates/persona-template.md
doc/templates/jobs-to-be-done-template.md
doc/templates/customer-problem-template.md
doc/templates/product-roadmap-template.md
doc/templates/business-experiment-template.md
doc/templates/business-validation-plan-template.md
doc/templates/north-star-metric-template.md
doc/templates/content-strategy-template.md
doc/templates/sales-strategy-template.md
doc/templates/customer-success-strategy-template.md

YAML register templates (optional)

doc/templates/product-roadmap-register-template.yaml
doc/templates/experiment-register-template.yaml
doc/templates/metric-catalog-template.yaml
doc/templates/content-calendar-template.yaml

(Keep these shared and versioned; use only templates allowed by repository profile.)

18) Inception Artifact Catalog

Project inception produces the knowledge base that AI delivery agents operate against. This section is the discoverability surface for the inception artifact catalog and the conditional matrix. For the complete, human-executable process, see the Project Inception guide.

Always-produced (all projects)

This is a condensed quick-reference. The Project Inception guide holds the complete artifact catalog, including testing strategy, CI baseline, dev-environment guide, NFRs, repo analysis, and tribal knowledge.

Artifact	Template
Inception state	`inception-state-template.yaml`
Material inventory	`material-inventory-template.md`
North star	`north-star-template.md`
Roadmap	`roadmap-engineering-template.md`
Tech stack	`tech-stack-template.md`
Architecture overview	`architecture-overview-template.md`
Glossary	`glossary-template.md`
Documentation profile	`documentation-profile-template.md`
Inception summary	`inception-summary-template.md`

(ADOS framework files — AGENTS.md, .ai/agent/*-instructions.md, the documentation handbook, and the templates set — are generated/installed by @bootstrapper, not hand-authored at inception.)

Conditional artifacts matrix

Phase 0 detects project characteristics and activates the appropriate subset of conditional artifacts. Use the five project-type columns to decide which apply.

Artifact	CLI/API only	Library	Web app new	Web app legacy	Business repo
OST	❌	❌	If discovery done	If discovery done	✅
Personas / JTBD	❌	❌	✅	✅	✅
User journeys	❌	❌	✅	✅	❌
Screen inventory	❌	❌	✅	✅	❌
UX guidance	❌	❌	✅	✅	❌
Repo analysis	❌	❌	❌	✅	❌
Tribal knowledge	❌	❌	❌	✅	❌
Project PRD	❌	❌	Optional	Optional	Optional
Assumption register	✅	✅	✅	✅	✅
Risk register	Optional	Optional	✅	✅	Optional

Conditional templates: opportunity-solution-tree-template.md, persona-jtbd-template.md, user-journey-template.md, screen-inventory-template.md, ux-guidance-template.md, ubiquitous-language-template.md, repo-analysis-template.md, project-prd-template.md, assumption-register-template.md, risk-register-template.md.

`doc/inception/` Workspace

Inception work is staged under doc/inception/:

doc/inception/
├── README.md          # workspace purpose + structure + lifecycle
├── inputs/            # user-provided materials (NOT agent-produced)
├── meetings/          # inception meeting notes
└── analysis/          # agent intermediate analysis (inventory, assumptions, risks, repo analysis, tribal knowledge)

Lifecycle: staged at Phase 0, populated through Phase 7, retained as the project's inception record. Templates live under doc/templates/; instances (inception-state.yaml, inception-summary.md, and the analysis files) are written into this workspace only when a project runs inception.

Forward pointer

Run inception end to end with the Project Inception guide.

FilesExpand file tree

documentation-handbook.md

Latest commit

History