fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add docs/README.md as navigation hub

Browse Source 
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/<name>-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) <noreply@anthropic.com>
This commit is contained in:
Danijel Martinek
2026-05-13 17:03:15 +02:00
parent 7b238e401c
commit 365c521076
1 changed files with 86 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/README.md Normal file
View File

@@ -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/<date>-<slug>.prd.md # PRDs
└── <epic-slug>/... # 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/<epic>/...` | 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 <id>` auto-flips to `shipped` on epic completion.
- **A new interactive diagram** → drop a single-file HTML at `architecture/<name>-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.