Architecture Decision Records (ADRs)

Manage architectural decisions as structured markdown documents in docs/adr/.

Alongside superpowers

Decisions land mid-flow: superpowers:brainstorming gets one accepted, an execution task uncovers one. Write the ADR the moment the choice is accepted, then continue the task. Before designing in an area — and before briefing a subagent into it — read docs/adr/INDEX.md and the records it names: accepted ADRs are constraints on the options, and they carry the why the next agent inherits.

Directory Structure

docs/adr/
├── INDEX.md                                          # Index with TOC (read this first)
├── ADR-001-nats-jetstream-instead-of-kafka.md      # Individual ADR
├── ADR-002-embedded-nats-server.md
└── ...

If docs/adr/ does not exist yet, create it with an INDEX.md carrying the TOC header below before writing the first ADR. Every project has decisions worth logging; the first one seeds the log.