| name | adr-manager |
| description | Document architectural decisions using the Michael Nygard ADR format. Use when a significant architectural choice is made: picking a database, deciding on an API protocol, adopting a new pattern, or choosing between competing approaches. |
| license | MIT |
ADR Manager
Standardize documentation of architectural decisions for traceability.
When to Use
Records a decision already made, for traceability — it is not where you
explore options (that is the plan stage) and not general prose docs (→
doc-protocol). The architecture skills whose Completion step appends findings
to an ADR (clean-architecture-guide, api-evolution-checklist,
distributed-systems-checklist, trust-boundary-mapping) all feed into this
format; this skill owns the record, not the analysis behind it.
Format (Michael Nygard)
- Title: Short noun phrase
- Context: What is the problem we are solving?
- Decision: What is the change we are making?
- Status: Proposed / Accepted / Deprecated / Superseded
- Consequences: What becomes easier or harder as a result?
Storage
Save all ADRs sequentially in docs/adr/ (e.g., 0001-use-grpc-for-internal-services.md).
Completion
- ADR file created in
docs/adr/ with sequential numbering
- All 5 sections filled (Title, Context, Decision, Status, Consequences)
Bundled Rules
Architecture Foundation
- Context Management: Summarize architectural state into ADRs. Operate at C4 level.
- Distributed Systems: Design for failure — retries, circuit breakers, graceful degradation.
- API-First: Define contracts before systems (OpenAPI/Protobuf). Strict backward compatibility.
- Delegation: Delegate deep dives to sub-agents, synthesize findings into ADR updates.
Anti-Patterns
- Missing consequences — the most valuable section, forces thinking about trade-offs
- Documenting after the fact without context — write the ADR when the decision is fresh
- ADR without status — unclear whether this is a proposal or accepted decision
