adr

You are managing Architecture Decision Records (ADRs) for this project. ADRs are short Markdown files capturing one decision each — the context, options considered, decision, and consequences. They live in docs/adr/ and are numbered sequentially (0001-..., 0002-...).

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
ADR_DIR="docs/adr"
mkdir -p "$ADR_DIR"

Input

$ARGUMENTS:

• new <title> — create a new ADR with the next sequential number; use the template
• list — list existing ADRs in a table (id, title, status, date)
• supersede <id> <new-title> — mark <id> as superseded and create a new ADR
• index — regenerate docs/adr/README.md from the contents of the directory
• (empty) — show usage

Steps

new <title>

1. Find the next ID:

   NEXT_ID=$(ls "$ADR_DIR"/[0-9][0-9][0-9][0-9]-*.md 2>/dev/null | sed -E 's:.*/([0-9]{4})-.*:\1:' | sort -n | tail -1)
   NEXT_ID=$(printf "%04d" $((10#${NEXT_ID:-0} + 1)))
   

2. Slugify the title: lowercase, spaces → -, strip punctuation
3. Copy the template from ${CLAUDE_PLUGIN_ROOT}/templates/docs/adr/0000-template.md to ${ADR_DIR}/${NEXT_ID}-${SLUG}.md
4. Substitute placeholders in the new file:
   • {{id}} → e.g., 0007
   • {{title}} → the user-provided title
   • {{date}} → YYYY-MM-DD (today)
   • {{status}} → Proposed
5. Open the file path in the response so the user can fill it in
6. Run index to update docs/adr/README.md

list

Read every ${ADR_DIR}/[0-9]*.md and parse the front-matter for id, title, status, date. Print a Markdown table:

| ID   | Title                       | Status      | Date       |
|------|-----------------------------|-------------|------------|
| 0001 | Use Named Credentials       | Accepted    | 2026-02-14 |
| 0002 | Custom Metadata for config  | Accepted    | 2026-03-01 |
| 0003 | Replace ProcessBuilder X    | Superseded by 0007 | 2026-03-08 |

supersede <id> <new-title>

1. Verify ADR <id> exists. Update its status: to Superseded by <next-id>
2. Create a new ADR via new <new-title> with status Accepted (or Proposed)
3. In the new ADR's "Context" section, add a line: "Supersedes ADR-"
4. Re-run index

index

Walk the directory, parse each ADR's front-matter, and write ${ADR_DIR}/README.md:

# Architecture Decision Records

This index is generated by `/argo:adr index`. Edit the source ADRs, not this file.

| ID | Title | Status | Date |
|----|-------|--------|------|
| 0001 | [Use Named Credentials](0001-use-named-credentials.md) | Accepted | 2026-02-14 |
| ...

ADR Template

Lives at ${CLAUDE_PLUGIN_ROOT}/templates/docs/adr/0000-template.md. The skill copies and substitutes; users edit the body.

Rules

• One decision per ADR. If you find yourself writing about two decisions, split them
• Don't delete superseded ADRs. Mark them and link forward — the history is the value
• Keep them short. The point is "future-me can reconstruct the reasoning in 60 seconds." Aim for under one screen
• Link to code, not the other way around. Code references the ADR ("see ADR-0007"), but the ADR is stable and self-contained
• No tracker/jira links as the only context. External links rot — paraphrase the relevant context inline

Consumers

• @architect, @data-architect, @integration-architect — read ADRs before designing to honor prior decisions
• /argo:code-review — flags code that contradicts an ADR (e.g., hardcoded endpoint when ADR-0001 mandated Named Credentials)
• /argo:release-notes — picks up new ADRs since the last release as architecture-change notes