ADR
Skill
Guides creation and maintenance of architecture decision records, with a bundled Bun CLI for deterministic filenames, links, reports, and validation.
What it does
ADR guides creation and maintenance of architecture decision records while preserving the context, decision, consequences, status, and links that future maintainers need.
A bundled Bun CLI handles deterministic ADR initialization, filenames, creation, supersession links, navigation, reports, and validation.
When to reach for it
Invocation: Ask to create, review, update, supersede, list, validate, summarize, or report on Architecture Decision Records.
- An architectural choice needs durable rationale
- Capture one decision with value-neutral context and explicit consequences.
- A newer decision replaces or qualifies an earlier record
- Preserve the old record and add explicit supersession or relationship links.
- An ADR log has drifted or needs an overview
- Validate its structure or generate a list, table of contents, or graph.
What it adds
- A repository-aware workflow that respects an existing ADR-directory marker before the conventional architecture-record directory and asks before establishing a new location.
- Deterministic helpers for fragile file and link operations, while leaving architectural reasoning to the agent and user.
How it fits
No related catalog surfaces are recorded.
Common questions
- Does superseding a decision delete the old record?
- No. The writing rules preserve superseded and rejected decisions so their rationale remains part of repository history.
- Can the helper CLI decide architecture on its own?
- No. It performs deterministic repository operations and checks structure; humans and agents still supply and review the context, decision, and consequences.
It’s working if
- Each new ADR captures one decision and follows the repository's existing numbering and status conventions.
- Supersession and relationship links are reciprocal and old rationale remains available.
- Validation reports no structural, numbering, date, status, or link errors.
Source and setup
Provenance
- Project
- Pi ADR
- Origin
- Vedang Manerikar
- Current maintainer
- Vedang Manerikar
- Relationship
- original
- Installed source
git:github.com/vedang/pi-adr- Source path
- View source (
skills/adr/SKILL.md) - Compatibility
- Agent Skills
- Bun
- Markdown ADR repositories
- License publication scope
- Independently written factual summary and source link only; no source reuse permission asserted.
- Reviewed revision
8f10418d7fbec46c3a75e6f54b2b8a3be26d4958- Catalog revision
e0c035a297462c519315abfa1af31a1ed3bd9eef
Setup notes
- Created and maintained by Vedang Manerikar; the installed Vedang locator now resolves to the canonical Unravel Team repository.
- Helper commands require Bun and should run from the project whose ADR paths they manage.
- The pinned repository declares no public source license. This catalog provides independently written factual notes and a source link, not permission to reuse source code or documentation.
- Behavior claims were reviewed against the installed commit rather than a moving branch.