File size: 5,118 Bytes
5dd1bb4 9e64e71 5dd1bb4 9e64e71 5dd1bb4 9e64e71 5dd1bb4 9e64e71 5dd1bb4 9e64e71 5dd1bb4 9e64e71 5dd1bb4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | # 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 |
|