Design Docs
This directory contains design documentation for architectural decisions — the WHY behind technical choices.
Core Beliefs
See core-beliefs.md for agent-first operating principles.
Decisions (ADRs)
Architectural Decision Records are stored in decisions/.
| ADR | Title | Status |
|---|---|---|
| 0001 | ADR Template | Template |
Feature Design Docs
| Feature | Status | Date | Reversibility |
|---|---|---|---|
| None yet |
Creating Design Docs
Use the design-doc skill for structured decision documentation:
skill({ name: "design-doc" })
The skill guides you through:
- Context — What's the situation? What triggered this?
- Decision Drivers — Constraints, preferences, quality attributes
- Options Analysis — At least 2 options with pros/cons
- Decision — Choice + rationale + consequences + reversibility
- Implementation Guidance — Key interfaces, boundaries
When to Create a Design Doc
CREATE when:
- Making an architectural choice with multiple valid options
- Introducing a new pattern or abstraction
- Choosing between technologies, libraries, or approaches
- A decision will affect multiple features
SKIP when:
- Following an existing established pattern
- The decision is trivial or easily reversed
- A simple code comment would suffice
Integration with Autocode
The autocode-implementation-planner skill automatically reads linked design docs:
- Uses constraints as hard requirements
- Respects the chosen interfaces
- Stays within the defined boundaries
- Notes reversibility for future refactoring