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). --- > `<plugin-root>` names this plugin's directory inside the installed package, the one that holds its `skills/`, `agents/` and `commands/`. The loader substitutes it in every body it registers; in any other file, resolve it once from where that file was loaded. <daodan_host_binding host="opencode"> This binding governs execution of this package and its loaded references. It takes precedence over executable examples written for another host. Use only registered tools and their actual input schema; an example never creates a tool, argument, permission, model alias or nested worker capability. Preserve the generated worker allowlist, dependency closure, scope and delivery contracts. OpenCode V2 binding: repository reads use read/glob/grep, writes use write/edit/patch, shell execution uses shell, network tools are webfetch/websearch, and clarification uses the registered question tool. shell takes command, optional workdir, timeout in milliseconds and background. It does not provide interactive stdin. Persistent capture uses background: true and an explicit noninteractive stop signal. Load skills with skill using id: "<plugin>:<skill>". Dispatch registered roles with subagent using agent: "<owner>:<role>", description and prompt; optional sessionID continues that child, and background: true requests asynchronous completion. Use only roles allowed by the current harness and permissions. A child cannot dispatch nested workers when its permissions or the configured depth deny it. Workflow entries are /<plugin>:<workflow>, registered by the package loader. Inherit the session model; an override requires its authorized, actually available provider/model identity, not another host's short model alias. The loader includes required local providers and registers plugin-declared MCP servers. Qualified foreign providers need a compatible V2 plugin/skill provisioned through this host, never a Claude marketplace command. Check the active registry: registration metadata alone does not prove a connected server or usable tool. Inherit the active session's model and default variant. A source model alias such as sonnet is not a portable override; request a different model only through an explicit adapter mapping to a valid host identity and user authorization. The executing agent and its coordinator own continuation, recovery, verification and delivery. Skills supply knowledge and method instructions; they are not executors or a runtime persistence mechanism. Resolve each component by kind and exact installed identity. A role is dispatched as a worker, a skill loads instructions, and a workflow starts its declared method. Kernel owner-qualified skill references are logical provider identities: resolve them to the actual host registry name and verified installed provider path. Do not invent a registry string by adding an owner's prefix when the host does not use it. Do not load an agent identity as a skill or execute a workflow name as a shell command. Declared required foreign providers remain mandatory. If a required provider or capability (including required MCP access or isolation) is unavailable, stop its dependent phase and report the missing capability. Optional external providers follow the method's declared selection and absence behavior; their absence alone does not block the base workflow. Report any explicitly requested but unavailable provider contribution as unfulfilled and continue independent work. Do not install a different host's plugin or substitute unrelated skills to claim coverage. Shell execution alone does not establish interactive stdin. Before a capture or checkpoint, use an available session-control mechanism. When stdin is unavailable, keep user-driven capture in a supported background process with bounded output and an explicit stop signal controlled by the coordinator after the user's completion message. Close owned browser/process resources on completion or cancellation. Continue working within the current authorization while the requested result is achievable. After a tool error, inspect its cause, correct the relevant input or implementation, retry when justified and verify the outcome; never repeat a failing action blindly. Do not close the turn with a promise or a partial result when an authorized next step can still produce or verify the requested result. Stop only for a documented real impediment, a missing required capability, an unresolved human decision or the caller's stop request. At that boundary, report completed results, remaining work and the concrete prerequisite for continuation; continue any independent work that the blocker does not prevent. A tool's successful exit, a worker stop or an idle session is not the deliverable. Return final text naming observed findings, artifact paths, executed checks and blockers. An empty worker result is missing delivery: inspect or resume that worker when permitted, or record failure. Verify required artifacts and candidate gates before marking the requested outcome complete. This is an execution binding, not a rewrite of source examples. Preserve programming language fences, domain code and host APIs that are the subject of marketplace-ops or agent-sdk-builder. A host-as-subject API is not a tool provided to this session. Compiled binding and static checks do not prove an installed host executed a run. </daodan_host_binding> # Architecture decision records Load the skill `work-controller:work-record` for run ownership and authorization. The helper is `python "<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 9 KB
- SKILL.toml 1 KB
- references/adr-template.md 8 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 7179ce4ea94b (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…