Skip to content
Skills Library
Programming · Writing

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

Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Load map
  2. Resolve: what governs this scope
  3. Propose: the interview's output
  4. Approve, retire, verify
  5. Instructions and documentation
Original SKILL.md headings · 61 lines, 409 words
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

RepositoryScoreLicence
This page · acaprino/alfio-claude-plugins95MIT
acaprino/alfio-claude-plugins95MIT
acaprino/alfio-claude-plugins95MIT
acaprino/alfio-claude-plugins95MIT
acaprino/alfio-claude-plugins95MIT
acaprino/alfio-claude-plugins95MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.