ADR
Skill
Workflow and Bun CLI for drafting, superseding, linking, and validating Architecture Decision Records.
By Vedang Manerikar · git:github.com/vedang/pi-adr · View source
What it does
ADR pairs an agent skill with a deterministic CLI (adr-tools.ts) so architecture decisions stay consistent as a codebase evolves. The skill guides the agent through discovering existing ADRs, surfacing assumptions with the user, comparing real alternatives, and drafting a clean record.
Instead of hand-editing filenames and status headers, the agent uses the CLI to allocate the next sequence number, create new records, update reciprocal 'Supersedes / Superseded by' links across files, generate summary reports, and validate every ADR in the directory.
When to reach for it
Invocation: Loaded automatically when discussing ADRs or architectural decisions, or invoked via /skill:adr.
- Recording a new architectural choice
- Surface constraints and rejected alternatives, then create a numbered ADR in docs/adr/.
- Revising an older decision
- Supersede the prior ADR and automatically wire reciprocal links between the old and new records.
What it adds
- A four-step ADR authoring workflow (discover, clarify, draft, verify) plus templates and quality checklists.
- A Bun CLI (init, list, new, link, supersede, report, validate) that respects .adr-dir and docs/adr conventions.
Commands: /skill:adr
How it fits
- Shaping Skills — Captures the enduring architectural decisions that emerge during shaping.
- Modularity Skills — Records the rationale behind module boundaries and contract designs.
Good to know
- Requires Bun on PATH to run the companion adr-tools.ts helper script.
Source and setup
- Loaded via
git:github.com/vedang/pi-adr- Attribution
- By Vedang Manerikar