| name | architecture-decision-records |
| description | Manages the ADR (Architecture Decision Record) registry. Use when recording tech-stack choices, design patterns, or infrastructure decisions with context, alternatives, and rationale. Supports listing, searching, or creating formal ADR documents. |
| context | fork |
| agent | technical-director |
| allowed-tools | Read, Glob, Grep, Write, Bash |
| argument-hint | [title or decision topic] |
| user-invocable | true |
| effort | 4 |
| when_to_use | When needing to make a formal technology decision and record the underlying reasoning in docs/architecture/. |
Architecture Decision Records
Workflow Protocol
- Determine the next ADR number by scanning
docs/architecture/ for existing ADRs.
- Gather context by reading related code and existing ADRs.
- Guide the user through the decision by asking clarifying questions if the title alone is insufficient.
- Generate the ADR following the template below.
- Save the ADR to
docs/architecture/adr-[NNNN]-[slug].md.
- Update the Index Table in
docs/architecture/README.md or docs/technical/DECISIONS.md.
When to write an ADR vs skip
| Write ADR | Skip ADR |
|---|
| New framework/database adoption | Minor version upgrades |
| API design patterns | Bug fixes |
| Security architecture | Implementation details |
| Integration patterns | Routine maintenance |
ADR lifecycle
Proposed → Accepted → Deprecated → Superseded
↓
Rejected
Template (MADR format — use this)
# ADR-NNNN: [Title]
## Status
Accepted | Proposed | Deprecated | Superseded by ADR-XXXX
## Context
[Problem statement, current situation, constraints, scale]
## Decision Drivers
- [Must/Should/Could requirement]
## Considered Options
### Option 1: [Name] — [one-line summary]
Pros: ... | Cons: ...
### Option 2: [Name]
Pros: ... | Cons: ...
## Decision
We will use **[Option N]** because [key rationale].
## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... Mitigation: ...
## Related ADRs
- ADR-XXXX: [relationship]
Quick examples
