From 365c52107686cf93ec7e2097a44a9b345106b250 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 17:03:15 +0200 Subject: [PATCH] docs: add docs/README.md as navigation hub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs/ tree had no index — a fresh visitor landing at /docs/ through GitHub's file browser would see just a glossary.md and four subdirectories with no orientation. docs/README.md gives: - Where to start (CLAUDE.md + AGENTS.md links + glossary.md as the "resolve a term" entry point) - The full directory tree annotated with what each path holds - Doc-type table (Glossary / Architecture / ADR / Guide / PRD / Epic-Story-Task) with lifetime expectations - "When to put what where" routing rules (new decisions -> ADR, new how-to -> guide, new term -> glossary, new initiative -> PRD, new diagram -> architecture/-explainer.html) - Conventions section codifying the rules already followed implicitly across the existing docs No content is duplicated — every section either lists or routes to existing files. Adds the missing navigation surface so the docs/ tree is discoverable from any entry point. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e4496d4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,86 @@ +# docs/ + +Documentation hub for the `template-vertical` monorepo. **Start here if you landed at `docs/` directly.** + +For the project entry point, see [`../CLAUDE.md`](../CLAUDE.md) (humans + agents) and [`../AGENTS.md`](../AGENTS.md) (package map + boundary rules). + +--- + +## Resolving terminology + +[`glossary.md`](./glossary.md) — **canonical vocabulary** for every cross-cutting term used in this repo (feature, use case, manifest, conformance, slice, coverage band, dispatch, etc.). When in doubt about what a term means _here_, check the glossary first. + +--- + +## How the documentation is organised + +``` +docs/ +├── glossary.md # canonical vocabulary +├── architecture/ # design + invariants (rarely changes) +│ ├── overview.md # high-level architecture summary +│ ├── vertical-feature-spec.md # canonical feature design spec +│ ├── dependency-flow.md # workspace + import-graph reference +│ ├── template-tiers.md # must-have vs optional core packages +│ ├── agent-first-workflow-and-conformance.md # workflow + 5-gate design +│ ├── data-flow-explainer.html # interactive (single-file) +│ ├── di-explainer.html # interactive (single-file) +│ ├── feature-conformance-explainer.html # interactive (single-file) +│ └── audit-and-compliance-explainer.html # interactive (single-file) +├── decisions/ # ADRs (durable design decisions) +│ └── adr-001..adr-020.md # 20 ADRs, numbered in order accepted +├── guides/ # day-to-day how-to docs +│ ├── runbook.md # ← first time? read this end-to-end +│ ├── conformance-quickref.md +│ ├── coverage.md # 4-layer coverage cookbook (ADR-020) +│ ├── tdd-workflow.md +│ ├── testing-strategy.md +│ ├── adding-a-feature.md # manual path +│ ├── scaffolding-a-feature.md # generator path (preferred) +│ ├── scaffolding-core-package.md +│ ├── scaffolding-core-ui-component.md +│ ├── events-and-jobs.md # requires `gen core-package events` +│ ├── realtime.md # requires `gen core-package realtime` +│ ├── audit-and-compliance.md # requires `gen core-package audit` +│ ├── frontend-work-shape.md +│ └── infrastructure-work-shape.md +└── work/ # local task system (PRD → Epic → Story → Task) + ├── README.md # work-folder layout + PRD lifecycle + ├── _state.json # derived index (orchestrator-managed) + ├── prds/-.prd.md # PRDs + └── /... # one folder per epic +``` + +## Document types + +| Type | Where | Purpose | Lifetime | +| ----------------------- | ------------------------ | ------------------------------------------------ | ---------------------------------------- | +| **Glossary** | `glossary.md` | One sentence per term; flagged ambiguities | Long-lived | +| **Architecture** | `architecture/` | Design invariants, system shape | Long-lived | +| **ADR** | `decisions/adr-NNN-*.md` | Single decision: context → choice → consequences | Long-lived | +| **Guide** | `guides/` | How-to, reference, troubleshooting | Updated as features evolve | +| **PRD** | `work/prds/*.prd.md` | Implementation seed for one epic | `draft → in-review → approved → shipped` | +| **Epic / Story / Task** | `work//...` | Workflow artifacts | Created → in-progress → done | + +## When to put what where + +- **A new architectural decision** (events, audit, instrumentation choices, etc.) → ADR. Number is `001 + max(existing)`. +- **A new how-to** (cookbook, troubleshooting, "how do I do X") → guide. +- **A new vocabulary term** that's cross-cutting → glossary, alphabetically grouped. +- **A new initiative** (multi-task feature work) → PRD seed. The decomposer refuses to run on `draft` — flip to `approved` after human review. `pnpm work prd-ship ` auto-flips to `shipped` on epic completion. +- **A new interactive diagram** → drop a single-file HTML at `architecture/-explainer.html`; cross-link from the other explainers + from `architecture/overview.md`'s Interactive explainers section. + +## See also + +- [`../CLAUDE.md`](../CLAUDE.md) — entry point for agents +- [`../AGENTS.md`](../AGENTS.md) — package map + boundary rules + agent-driven development overview +- [`../README.md`](../README.md) — project-level README + +## Conventions + +- **Markdown over HTML** unless the doc is genuinely interactive (the 4 architecture HTMLs). +- **Reference ADRs by ID** (`ADR-NNN`) rather than path so renames don't break links. +- **Cross-reference paths sparingly** — they rot. Prefer naming the doc (e.g. "see the coverage guide"). +- **Don't duplicate** — if two docs describe the same thing, consolidate or pick a single source of truth and link from the other. +- **Date PRDs + ADRs** in the file name (`YYYY-MM-DD` prefix for PRDs) and in their frontmatter. +- **Each ADR cites at least one related ADR** when extending or building on prior decisions.