adr

Architecture Decision Records

You are creating or managing Architecture Decision Records (ADRs) for this project.

Red Flags - STOP if you're

• Creating an ADR without understanding the decision context
• Documenting trivial decisions that don't warrant an ADR (e.g., variable naming)
• Writing an ADR after the fact without capturing the original reasoning
• Listing alternatives without genuine pros/cons analysis
• Skipping the "Consequences" section (the most valuable part)
• Not checking existing ADRs for conflicts or superseded decisions

ADRs capture WHY, not just WHAT. Every decision needs alternatives considered.

Pre-Check

1. Verify Draft is initialized:

ls draft/ 2>/dev/null

If draft/ doesn't exist:

• Tell user: "Project not initialized. Run /draft:init first."
• Stop here.

1. Check for existing ADR directory:

ls draft/adrs/ 2>/dev/null

If draft/adrs/ doesn't exist, create it:

mkdir -p draft/adrs

Step 1: Parse Arguments

Check for arguments:

• /draft:adr — Interactive mode: ask about the decision
• /draft:adr "decision title" — Create ADR with given title
• /draft:adr list — List all existing ADRs
• /draft:adr supersede <number> — Mark an ADR as superseded

List Mode

If argument is list:

1. Prefer the deterministic adr-index.sh wrapper for the listing — it returns a structured JSON {adrs:[{id,title,date,status,path,related_tracks}]} derived from each ADR's frontmatter. Resolve via the canonical tool resolver (see core/shared/tool-resolver.md):

   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
   if [ -x "$DRAFT_TOOLS/adr-index.sh" ]; then
     bash "$DRAFT_TOOLS/adr-index.sh" --root draft/adrs
   else
     ls draft/adrs/ # fallback: enumerate files manually
   fi