Architecture Decision Records
ADRs capture significant, hard-to-reverse decisions and the reasoning behind them. They are immutable once Accepted: to change a decision, write a new ADR that supersedes the old one.
Use template.md for new records. Number sequentially.
| ADR | Title | Status |
|---|---|---|
| 0001 | Monorepo layout and package boundaries | Accepted |
| 0002 | Protocol versioning independent of the toolchain | Accepted |
| 0003 | Single source of truth with tool adapters | Accepted |
| 0004 | Ownership model and idempotent sync | Accepted |
| 0005 | Validation via zod with published JSON Schema | Accepted |
| 0006 | Bundled, offline-first template distribution | Accepted |
| 0007 | Specification-first architecture (Specification → Engine → CLI) | Accepted |
| 0008 | Plugin runtime security (trust and sandbox model) | Accepted |
| 0009 | Plugin sandbox mechanism (worker) | Superseded by 0010 |
| 0010 | Plugin sandbox: Node Permission Model subprocess | Accepted |
| 0011 | Bundle plugins at resolve time (multi-file; integrity over the bundle) | Accepted |
When to write an ADR
- Changing a package boundary or dependency direction.
- Changing the protocol's shape or semantics (also requires an RFC — see
../governance.md). - Choosing or replacing a foundational dependency.
- Any decision a future contributor would otherwise reverse without context.