adr-method
/adr-method
Create, resolve, validate, approve, version and verify canonical architecture decision records in docs/adr/. TRIGGER WHEN: the user explicitly asks to record or write down an architecture or technical decision, an interview settles a design, contract or domain decision, a task needs the decisions governing its scope, the user approves, revises or abandons a record, or a reviewed change verifies records or lists their drift. DO NOT TRIGGER WHEN: the user only wants brainstorming or advice without recording a decision, the change needs no decision beyond existing records, or the request is proje
- Author
- acaprino ↗
- Repository
- alfio-claude-plugins ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/adr_tool.py
What it does and when to use it
Create, resolve, validate, approve, version and verify canonical architecture decision records in docs/adr/. TRIGGER WHEN: the user explicitly asks to record or write down an architecture or technical decision, an interview settles a design, contract or domain decision, a task needs the decisions governing its scope, the user approves, revises or abandons a record, or a reviewed change verifies records or lists their drift. DO NOT TRIGGER WHEN: the user only wants brainstorming or advice without recording a decision, the change needs no decision beyond existing records, or the request is proje
Original author description
Create, resolve, validate, approve, version and verify canonical architecture decision records in docs/adr/. TRIGGER WHEN: the user explicitly asks to record or write down an architecture or technical decision, an interview settles a design, contract or domain decision, a task needs the decisions governing its scope, the user approves, revises or abandons a record, or a reviewed change verifies records or lists their drift. DO NOT TRIGGER WHEN: the user only wants brainstorming or advice without recording a decision, the change needs no decision beyond existing records, or the request is proje
How it works
- Load map
- Resolve: what governs this scope
- Propose: the interview's output
- Approve, retire, verify
- Instructions and documentation
SKILL.md preview
---
name: adr-method
description: >
Create, resolve, validate, approve, version and verify canonical architecture decision records in docs/adr/.
TRIGGER WHEN: the user explicitly asks to record or write down an architecture or technical decision, an interview settles a design, contract or domain decision, a task needs the decisions governing its scope, the user approves, revises or abandons a record, or a reviewed change verifies records or lists their drift.
DO NOT TRIGGER WHEN: the user only wants brainstorming or advice without recording a decision, the change needs no decision beyond existing records, or the request is project documentation (use project-knowledge:project-knowledge).
---
# Architecture decision records
Load the skill `work-controller:work-record` for run ownership and authorization.
The helper is `python "${CLAUDE_PLUGIN_ROOT}/skills/adr-method/scripts/adr_tool.py"`;
it writes records and the index atomically and refuses an inconsistent state
first.
## Load map
| Step | Run |
|---|---|
| Any | `validate --project ROOT` before relying on records |
| Before an interview | `resolve --project ROOT --paths P... --modules M... --domains D... --symbols S...` |
| Writing a record or a version | read `references/adr-template.md`; `template`, then `propose` |
| The user approved the text shown | `promote --adr ADR-NNNN --sha HEAD_SHA --expect-digest D` |
| Code reviewed as conforming | `verify --adr ADR-NNNN --sha SHA --expect-digest D` |
| Status, realignment | `validate --project ROOT --sha HEAD_SHA` |
| First use in a project | `init-index --project ROOT` |
## Resolve: what governs this scope
Input: the paths, modules, domains and Codebase Map symbols the task touches.
Output: the `Accepted` version of each matching decision, its `digest` and why
it matches, most specific first. Load the one to three that matter, never the
whole directory.
## Propose: the interview's output
Before alternatives, load `research:science-based-approach` and compose its
automatic checkpoint. Cite research identity, immutable revision and claims with
applicability and limits. Changed sources identify reviews; they never rewrite
or approve Accepted records. Reuse an existing interview checkpoint.
After the interview fixes scope, examples, alternatives and invariants, write
the body and `propose` with title, slug, run identity, `HEAD`, scope lists and
optional `--supersedes`/`--depends-on`. A refusal names the fix; never hand-edit
the index. `propose --revise ADR-NNNN` writes the next `Proposed` version under
that number. `ADR-NNNN` cites the active version; `ADR-NNNN vN` pins one.
Versions: at most one `Accepted` and one `Proposed` version per decision.
## Approve, retire, verify
`Accepted` means the user approved this exact text. Show the record and digest,
then `promote`; previous and superseded versions change in one transaction.
Record `dependents_to_review` with `ask`. Approval authorizes no work or merge.
Unapproved records stay `Proposed`; abandon with
`retire --adr ADR-NNNN --reason TEXT --expect-digest D`; never delete.
A mismatched `--expect-digest` refuses the rewrite: show the record again.
After a review confirms the code conforms, `verify` sets `last_verified_sha`;
approval never verifies. `validate --sha` lists as `drifted` each `Accepted`
record whose governed files changed since, `files: null` when never verified.
## Instructions and documentation
Durable instructions carry the active records for a domain inside the loop
block that `project-knowledge:instructions-method` maintains; guides cite a
record by identity and never restate its examples.
Files in this package (4)
- SKILL.md 4 KB
- SKILL.toml 1 KB
- references/adr-template.md 3 KB
- scripts/adr_tool.py 43 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · acaprino/alfio-claude-plugins | 95 | MIT |
| acaprino/alfio-claude-plugins | 95 | MIT |
| acaprino/alfio-claude-plugins | 95 | MIT |
| acaprino/alfio-claude-plugins | 95 | MIT |
| acaprino/alfio-claude-plugins | 95 | MIT |
| acaprino/alfio-claude-plugins | 95 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version c7257c95cddf (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95adr
[UDS] Create, manage, and track Architecture Decision Records (ADR). Use when: architecture decisions, technology choices, design trade-offs, pattern selection. Not for: decisions that do not change architecture — record them in the spec or commit; ideas not yet formed enough to… - 84adr
Create and manage Architecture Decision Records (ADRs). Use when someone asks to create an ADR, record an architecture decision, scaffold ADR support, or when a significant architectural decision surfaces during conversation. - 100adr
Record, find and respect Architecture Decision Records (ADR, decision record, docs/adr) with the `adr` CLI. Use before changing architecture, adding a dependency, changing a public interface, data format or security control, and whenever a task touches files governed by an ADR. - 100recording-architecture-decisions
Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync after architecture-changing work. - 95adr
Create or review Architecture Decision Records. Use for ADRs, architecture decisions, durable trade-offs, new dependencies, contracts, or patterns. - 90architectural-decision-record
Create, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs, extracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design decision, or updating the status of an…