melodic-software Repository context. Gather first
Collect these with individual Bash calls, one command per call, never combined into a single invocation:
- Current branch,
git branch --show-current - Working tree status (empty = clean),
git status --porcelain | head -10
The pipe is the bound and belongs in the command. A read-time cap ("read only the first 10 entries") bounds nothing: the Bash tool returns the command's complete output into context before there is anything to decide about.
Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git.
Variables
Arguments: $ARGUMENTS
Purpose
Record one architecture decision into whatever ADR convention the repository already has. The convention is discovered and followed, never prescribed: this skill owns discovery, the next identifier, the record shape, and the single write. Where no convention exists it reports what it searched, offers common shapes, and defers to the human rather than inventing one.
Input contract
The decision comes from $ARGUMENTS and the conversation. A file path the user names is read
verbatim. This skill never reads design-threads.md, PLAN.md, or any other planning artifact on
its own; those formats belong to the planning capability, and callers pass the decision and its
rationale in the invocation text. When context, decision, or consequences are missing, ask for them.
Never invent them.
Admission test (advisory)
A decision earns a record when ALL three hold: it is hard to reverse, it is surprising without context (a future reader would wonder why it was done this way), and it is the result of a real trade-off (genuine alternatives existed and one was picked for stated reasons).
When the decision plainly fails the test, say so once and offer to skip. The human's call wins: if they still want the record, write it.
Step 1. Discover the convention
Read ${CLAUDE_PLUGIN_ROOT}/reference/adr-discovery.md
and walk its ladder from the working area up to the repository root, first hit wins.
Emit one paragraph naming the directory, the numbering scheme, the template source (or that there is none), and any duplicates or shape disagreement observed. That paragraph is the evidence for everything Step 2 does.
Step 2a. Convention found
- Derive the next identifier: highest existing plus one, preserving the observed zero-pad width and separator. A date-prefixed scheme uses today's date in the observed format. Done when the identifier is one no existing filename already carries.
- Derive the filename in the observed form (identifier, separator, kebab-case title, extension). Done when it is indistinguishable in form from the records already there.
- Derive the section set from the template source; absent a template, from the newest records. Done when every heading in the set is one the observed shape uses.
- Re-read the target directory immediately before writing, confirming no record has appeared since Step 1 that would change the identifier.
- Write exactly one file, and report its path. Done when
git status --porcelainshows that one new path and nothing else.
Do not create, rename, or renumber any other file. Report duplicates and leave them where they are.
Step 2b. No convention
- List the rungs searched, so the human can see the search was real and where it stopped.
- Offer two or three common shapes, each naming a directory, a numbering scheme, and a minimal section set.
- Point at the upstream catalog URL below so the human can read templates and pick one.
- Stop. Write nothing: no directory, no file, no placeholder. Done when the report is delivered and
git status --porcelainis exactly what it was before the invocation.
When the human chooses in the same session, create only what they chose (the directory plus the first record) and nothing else.
Upstream template catalog
Templates for the human to read, cited by URL:
https://github.com/joelparkerhenderson/architecture-decision-record.
License: CC BY-NC-SA 4.0 (https://creativecommons.org/licenses/by-nc-sa/4.0/).
- Claim: README-authored content in that repository is licensed CC BY-NC-SA 4.0; the bundled templates carry their own licenses, stated per template.
- Basis:
https://raw.githubusercontent.com/joelparkerhenderson/architecture-decision-record/main/LICENSE.md. - As of: 2026-09-06.
- Recheck trigger: that
LICENSE.mdchanges, or the repository moves.
Rule beside it: catalog templates are cited for the human to read, never pasted into this skill, into the reference file, or into a record. When asked to paste one, decline, name the URL and the license, and offer the repository's own observed shape instead.
What this skill does NOT do
- Supersession workflows. Marking a record superseded, and the bookkeeping around it
- Index generation. README tables,
index.md, or any catalog of records - Status lifecycle beyond what the convention already defines
- Migrating existing records to a different template or numbering scheme
- Prescribing a convention to a repository that has none
- Reading planning artifacts. Callers pass the decision in; this skill does not open them
Composition
| When | Then | How |
|---|---|---|
| An interview resolves a decision that earns a record | Invoked from /planning:interview when that plugin is installed |
The caller passes the decision and its rationale; the gate lives at the caller |
| A design handoff lists ADR candidates | Invoked from /planning:design-handoff when that plugin is installed |
One invocation per candidate; the offer never blocks the handoff |
| A scan needs to read existing records | /architecture:improve reads the same ladder |
Both skills load the plugin's shared discovery reference; neither carries a second copy |
Gotchas
Failure modes this skill runs into, each stated as the rule it implies.
- Duplicate identifiers exist in real repositories. Two records can share a number. Pick highest plus one, report the duplicate, and never renumber: renumbering breaks every inbound link, and the duplicate is a fact about the repository's history rather than an error to fix here.
- Records disagree in shape. Where the newest few records use different heading sets, follow the newest and say so in the report. Silently averaging the shapes produces a record matching nothing.
- A subtree-local ADR directory found before the root one wins. The ladder walks up from the working area, so a nearer directory is the answer. Name both in the report, so the human can redirect when the root one was intended.
- A convention declared in
CLAUDE.mdpointing at a directory that does not exist yet. Declared beats observed: create the record at the declared path and state in the report that the directory was created because the declaration named it.