create-adr

Create Architecture Decision Record

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh create-adr !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-agents.sh

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.

Decisions directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh decisions

You are tasked with guiding the user through creating an architecture decision record (ADR) — a concise document capturing a significant architectural decision, its context, the options considered, and the consequences.

Initial Setup

When this command is invoked:

1. Check if parameters were provided:

• If a topic/description was provided, proceed directly to context gathering
• If --supersedes ADR-NNNN was provided, note the supersession target
• If no parameters provided, respond with:

I'll help you create an architecture decision record. Please provide:
1. The topic or decision to document (e.g., "use PostgreSQL for user data")
2. Any relevant context or constraints

You can also specify if this supersedes an existing ADR:
`/accelerator:create-adr use Redis for caching --supersedes ADR-0003`

Then wait for the user's input.

Process Steps

Step 1: Determine ADR Number

1. Run the companion script to get the next ADR number:

${CLAUDE_PLUGIN_ROOT}/skills/decisions/scripts/adr-next-number.sh

2. If --supersedes ADR-NNNN was specified:
   • Find the target ADR file by matching {decisions directory}/ADR-NNNN-*.md
   • Verify exactly one file matches the glob pattern (error if zero or multiple matches)
   • Read the target ADR's status using the companion script:

     ${CLAUDE_PLUGIN_ROOT}/skills/decisions/scripts/adr-read-status.sh <resolved-path>
     

   • Verify the target ADR is in accepted status (only accepted ADRs can be superseded). This is an early-fail check to avoid wasted effort — the status will be re-verified before writing in Step 4.
   • If not accepted, inform the user and ask how to proceed

Step 2: Gather Context

1. Spawn agents to gather relevant context (in parallel):

• Use {documents locator agent} to find related research, plans, and existing ADRs in the configured document directories
• Use {codebase locator agent} to find relevant code related to the decision topic

2. Read any directly mentioned files fully

3. Present gathered context and ask clarifying questions:

Based on my research, here's what I found relevant to this decision:

**Related documents:**
- [list of relevant meta documents]

**Related code:**
- [list of relevant code areas]

**Existing ADRs on related topics:**
- [list of related ADRs, if any]

Before I draft the ADR, I'd like to understand:
1. What forces or constraints are driving this decision?
2. What alternatives have you considered?
3. Are there specific tradeoffs you want to highlight?

If context gathering finds nothing relevant (e.g., first ADR in a new project), skip the context sections and present:

No existing documents or ADRs found related to this topic. I'll draft the ADR
based on the information you provide.

Before I draft, I'd like to understand:
1. What forces or constraints are driving this decision?
2. What alternatives have you considered?
3. Are there specific tradeoffs you want to highlight?

Wait for user input before proceeding.

Step 3: Draft the ADR

1. Gather metadata by running ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-derive-metadata.sh. Run the bare path directly as an executable; never prefix it with bash/sh/env (a wrapper prefix escapes the skill's allowed-tools permission and forces an unnecessary prompt).

2. Draft the ADR using the template below and present it to the user for review:

Here's my draft ADR. Please review and let me know if you'd like any changes
before I write it to disk:

[draft content]

Wait for user approval or revision requests before writing.

3. Iterate on the draft based on user feedback. Only proceed to writing when the user approves.

Step 4: Write the ADR

1. Create the configured decisions directory if it doesn't exist

2. Populate frontmatter: before writing the artifact file, substitute the unified base fields into the template's frontmatter block, using the metadata captured in Step 3.

   1. The Current Date/Time (UTC): value from artifact-derive-metadata.sh is the source for date: and last_updated:. Repository identity is not part of the ADR provenance bundle (ADRs are not code-state-anchored).

   2. Substitute every field below with the indicated value:

      • type: ← adr
      • id: ← the ADR identifier ADR-NNNN from Step 1, always quoted as a YAML string (e.g. id: "ADR-0042")
      • title: ← the ADR title (without the ADR-NNNN: prefix)
      • date: ← the Current Date/Time (UTC): value
      • author: ← the author resolved per the standard chain (config → VCS user → prompt)
      • producer: ← create-adr
      • status: ← proposed
      • last_updated: ← the same Current Date/Time (UTC): value
      • last_updated_by: ← the same value resolved for author
      • schema_version: ← 1 (bare integer)

      Optional linkage / decision-maker keys are omit-by-default: the template shows each as ""/[], but write a key into the artifact only when it has a value, and omit it entirely otherwise (do not carry the empty placeholder through).

      • parent: ← the owning work item as a typed-linkage ref ("work-item:NNNN"). Fill when the ADR is owned by a work item; otherwise omit the key.
      • supersedes: ← a YAML list of typed-linkage refs of the form "adr:ADR-NNNN" to the ADR(s) this one replaces. Fill when this ADR supersedes another; otherwise omit the key.
      • relates_to: ← list of typed-linkage refs to loosely related ADRs (["adr:ADR-NNNN", ...]). Fill when related decisions are explicit; otherwise omit the key.
      • decision_makers: ← a YAML list of the people who agreed to the decision. Fill when decision-makers are captured; otherwise omit the key.

3. Write the ADR to: {decisions directory}/ADR-NNNN-description.md where NNNN is the number from Step 1 and description is a kebab-case summary

4. If this supersedes an existing ADR:

   • Read the superseded ADR's current status to confirm it's accepted
   • Update ONLY the superseded ADR's frontmatter:
     • Change status: accepted to status: superseded
     • Add superseded_by: ADR-MMMM (where MMMM is the new ADR number)
   • Do NOT modify any other content in the superseded ADR
   • Append the new ADR's typed-linkage ref to the new ADR's supersedes: list (e.g. ["adr:ADR-0017"])

5. Present the result:

ADR created: `{decisions directory}/ADR-NNNN-description.md`
Status: proposed

[If supersession]: Updated ADR-XXXX status to "superseded"

Next steps:
- Review and refine while in "proposed" status
- When ready, use `/accelerator:review-adr` to accept or reject

ADR Template

Use this exact template structure when generating ADRs:

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-template.sh adr

Quality Guidelines

When drafting ADRs, follow these principles:

• Concise: One to two pages maximum. Match length to problem complexity.
• Assertive: Use active voice ("We will...", "We chose...")
• Balanced: Include genuine pros AND cons. Avoid the "Fairy Tale" pattern (only pros, no cons)
• Honest options: Only include options that were genuinely considered. Avoid "Dummy Alternatives" (non-viable options to make preferred choice look good)
• Focused: Each ADR captures ONE decision. If you find multiple decisions, suggest creating separate ADRs.
• Context-rich: Explain WHY, not just WHAT. Future readers need to understand the forces at play.

Anti-Patterns to Avoid

• Fairy Tale: Only listing positive consequences
• Dummy Alternative: Including obviously non-viable options
• Mega-ADR: Multi-page documents crammed with implementation detail
• Blueprint in Disguise: Reads like a cookbook, not a decision journal
• Missing context: Decision without the forces that drove it

Important Notes

• New ADRs ALWAYS start with status proposed
• ADR numbers are NEVER reused — always increment from the highest existing
• File naming is ADR-NNNN-description.md (e.g., ADR-0001-use-jujutsu.md)
• Only modify existing ADRs to update status fields during supersession
• Cross-reference related documents in the References section
• Use {documents locator agent} and {codebase locator agent} agents for context, not deep file reads in the main context
• Dual status fields: The template includes status in both YAML frontmatter (status: proposed) and the body (**Status**: Proposed). The frontmatter is the authoritative source of truth — adr-read-status.sh reads only frontmatter. The body line is for human readability. When updating status, ALWAYS update both locations.
• Before writing a new ADR file, verify the target path does not already exist to prevent accidental overwrites from concurrent invocations

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh create-adr