| # Docs |
|
|
| This directory is the system-of-record for durable project knowledge. |
|
|
| ## Quick Links |
|
|
| | Category | Index | Type | Purpose | |
| |----------|-------|------|---------| |
| | **Guides** | [guides/README.md](guides/README.md) | how-to | Practical step-by-step procedures | |
| | **Design** | [design-docs/index.md](design-docs/index.md) | explanation | Feature design, ADRs, decision rationale | |
| | **ADR Template** | [design-docs/decisions/0001-template.md](design-docs/decisions/0001-template.md) | reference | Decision record template | |
| | **Core Beliefs** | [design-docs/core-beliefs.md](design-docs/core-beliefs.md) | explanation | Agent-first operating principles | |
| | **Discovery** | [discovery/index.md](discovery/index.md) | explanation | Validate ideas and capture taste | |
| | **Delivery Specs** | [delivery-specs/index.md](delivery-specs/index.md) | reference | Engineering handoff specs | |
| | **Exec Plans** | [exec-plans/README.md](exec-plans/README.md) | how-to | Complex multi-step work tracking | |
| | **Tech Debt** | [exec-plans/tech-debt-tracker.md](exec-plans/tech-debt-tracker.md) | how-to | Known debt and cleanup opportunities | |
| | **Exploration** | [exploration/README.md](exploration/README.md) | exploration | Ideas, research, scratchpad | |
| | **Learnings** | [learnings/README.md](learnings/README.md) | reference | Durable patterns from completed work | |
| | **Archived Learnings** | [learnings/archived/README.md](learnings/archived/README.md) | reference | Overflow learnings archive | |
| | **References** | [references/README.md](references/README.md) | reference | External docs for agent context | |
|
|
| ## Learnings by Category |
|
|
| | Category | File | |
| |----------|------| |
| | Architecture | [learnings/architecture.md](learnings/architecture.md) | |
| | Conventions | [learnings/conventions.md](learnings/conventions.md) | |
| | Gotchas | [learnings/gotchas.md](learnings/gotchas.md) | |
| | Integrations | [learnings/integrations.md](learnings/integrations.md) | |
| | Security | [learnings/security.md](learnings/security.md) | |
| | Testing | [learnings/testing.md](learnings/testing.md) | |
| | Workflow | [learnings/workflow.md](learnings/workflow.md) | |
|
|
| ## System Docs |
|
|
| - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md) |
| - Operations: [RUNBOOK.md](RUNBOOK.md) |
| - Taxonomy: [DOCS_TAXONOMY.md](DOCS_TAXONOMY.md) |
| - Quality: [QUALITY_SCORE.md](QUALITY_SCORE.md) |
| - Feature Slicing: [FEATURE_SLICING.md](FEATURE_SLICING.md) |
| - Contract: [DOCS_CONTRACT.json](DOCS_CONTRACT.json) |
|
|
| ## Directory Structure |
|
|
| ``` |
| docs/ |
| ├── README.md # This file (index) |
| ├── ARCHITECTURE.md # System design overview [reference] |
| ├── RUNBOOK.md # Operations guide [how-to] |
| ├── DOCS_TAXONOMY.md # Where to put new docs [reference] |
| ├── QUALITY_SCORE.md # Domain quality grades [reference] |
| ├── FEATURE_SLICING.md # Feature slicing strategy [reference] |
| ├── DOCS_CONTRACT.json # Validation config [reference] |
| ├── guides/ # How-to guides [how-to] |
| │ └── README.md # Guide index |
| ├── design-docs/ # Decision rationale [explanation] |
| │ ├── index.md # Design docs catalogue |
| │ ├── core-beliefs.md # Agent-first principles |
| │ └── decisions/ # Architectural Decision Records |
| ├── discovery/ # Idea validation [explanation] |
| │ └── index.md # Discovery index |
| ├── delivery-specs/ # Engineering handoff [reference] |
| │ └── index.md # Delivery specs index |
| ├── exec-plans/ # Work tracking [how-to] |
| │ ├── README.md # Exec plans index |
| │ └── tech-debt-tracker.md # Technical debt |
| ├── exploration/ # Ideas, scratchpad [exploration] |
| │ └── README.md # Exploration index |
| ├── learnings/ # Durable patterns [reference] |
| │ ├── README.md # Learnings index |
| │ ├── architecture.md # Architecture learnings |
| │ ├── conventions.md # Convention learnings |
| │ ├── gotchas.md # Gotcha learnings |
| │ ├── integrations.md # Integration learnings |
| │ ├── security.md # Security learnings |
| │ ├── testing.md # Testing learnings |
| │ ├── workflow.md # Workflow learnings |
| │ └── archived/ # Overflow archive |
| │ └── README.md # Archive policy |
| └── references/ # External docs [reference] |
| └── README.md # External docs for agent context |
| ``` |
|
|
| ## Adding Documentation |
|
|
| | If you need... | Create in... | Type | |
| |----------------|--------------|------| |
| | Step-by-step procedure | `docs/guides/<topic>.md` | how-to | |
| | Design for a feature | `docs/design-docs/<feature>.md` | explanation | |
| | External library docs | `docs/references/<library>-llms.txt` | reference | |
|
|
