Architecture Decision Records
ADRs capture the why behind agentcook's structural choices. Each record describes the context, the alternatives we considered, the decision, and the consequences.
The canonical copies live in the repository under docs/adr/ — this page mirrors the index so the same set is discoverable from the docs site.
Index
| # | Title | Topic |
|---|---|---|
| ADR-001 | Multi-package monorepo | Repo structure |
| ADR-002 | LangGraph integration | Agent orchestration |
| ADR-003 | Design tokens | Shared visual primitives |
| ADR-004 | Plugin sandbox | Tool isolation |
| ADR-005 | Observability stack | OTel + Jaeger + Prometheus + Langfuse |
| ADR-006 | Blue/green deployment | Release strategy |
| ADR-007 | Test pyramid | Unit / integration / contract / e2e |
| ADR-008 | API versioning | URL-path /v1, semver, freeze + bump |
| ADR-009 | Parallel frontends | admin (Vue) vs app (React) |
| ADR-010 | Desktop distribution | Electron packaging |
| ADR-011 | Agent memory | Four-layer Identity/Soul/Memory/Diary |
| ADR-012 | Agent harness philosophy | 9-dimension framework |
| ADR-013 | Java business backend | Python ↔ Java boundary |
How to read these
Each ADR follows the Michael Nygard template: Context describes the forces at play, Decision is the chosen option, Consequences are the trade-offs we are now living with.
When a decision changes, we don't edit the old ADR — we add a new one that supersedes it. Status fields at the top indicate proposed, accepted, superseded by ADR-NNN.
Proposing a new ADR
bash
cp docs/adr/ADR-XXX-template.md docs/adr/ADR-014-your-topic.md
# fill in context / decision / consequences
git add docs/adr/ADR-014-your-topic.md
git commit -m "ADR-014: short description"Open a PR — at least one reviewer should sign off before merging.