Add ADR skill for architecture decision records

README.md

@@ -180,6 +180,7 @@ These replace slash commands. Ask naturally and the skill fires:
 | `devkit:research` | "research X", "compare approaches for", "investigate options" |
 | `devkit:deep-research` | "deep research", "validate this", "make sure this is right", "rigorous analysis" |
 | `devkit:scrape` | "scrape this URL", "fetch content from", "extract from this page" |
+| `devkit:adr` | "create an ADR", "document this decision", "record why we chose X" |
 
 ### Coding Principles
 
@@ -326,7 +327,7 @@ devkit/
 │   ├── audit.md             # Project health audit
 │   ├── repo-map.md          # AST-based symbol index
 │   └── status.md            # Health check
-├── skills/                  # 17 context-activated skills
+├── skills/                  # 18 context-activated skills
 │   ├── executing/SKILL.md   # Principle: methodical execution
 │   ├── clean-code/SKILL.md  # Principle: readability
 │   ├── dry/SKILL.md         # Principle: don't repeat yourself
@@ -342,7 +343,8 @@ devkit/
 │   ├��─ research/SKILL.md    # Auto: "research X"
 │   ├── deep-research/SKILL.md # Auto: "deep research", ACH pipeline
 │   ├── scratchpad/SKILL.md  # Iteration memory protocol
-│   └── scrape/SKILL.md      # Auto: "scrape this URL"
+│   ├── scrape/SKILL.md      # Auto: "scrape this URL"
+│   └── adr/SKILL.md         # Auto: "create an ADR", decision records
 ├── agents/                  # 6 agents
 │   ├── reviewer.md          # Opus, worktree isolation
 │   ├── researcher.md        # Sonnet, worktree isolation

ROADMAP.md

@@ -3,7 +3,7 @@
 ## Implemented
 
 - **23 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping, autoresearch-inspired self-audit, autoloop
-- **17 context-activated skills** — 8 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, deep-research, scrape, autoloop) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad)
+- **18 context-activated skills** — 9 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, deep-research, scrape, autoloop, adr) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad)
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **10 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification, language-aware code review), optimization (RTK token compression)
 - **Graceful degradation** — tri:* commands work with 1-3 agents depending on installed CLIs
@@ -34,6 +34,6 @@ Items below were on the roadmap but determined to be unnecessary — either alre
 | Stop hook redesign | Still fires every turn, but exits early with `approve` when no files are changed — near-instant on clean trees, so the performance concern is moot. Revisit only if it causes measurable latency. |
 | Cost event hooks | Budget enforcement already exists in the Go engine via `overBudget()` + `addCost()` callbacks with hard limits |
 | Execution registry | Step tracking already handled by SQLite via `lib.DB` with status, cost, and timing per step |
-| Preset library | The 15 YAML workflows and 17 skills already serve this purpose |
+| Preset library | The 15 YAML workflows and 18 skills already serve this purpose |
 | Framework-specific review checklists | `lang-review.sh` covers language-level patterns; framework-specific rules are better added per-project via hookify |
 | Conditional hook firing | Hooks already self-filter internally (extension checks, changed-file checks); a generic condition system adds complexity for no current need |

skills/adr/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: adr
+description: Generate Architecture Decision Records — use when asked to document a decision, create an ADR, record why we chose X, or capture architectural rationale.
+---
+
+# ADR — Architecture Decision Record
+
+Capture the *why* behind architectural decisions so future-you (and future-agents) don't reverse them without context.
+
+## Step 1: Gather Context
+
+Identify:
+- What decision was made (or needs to be made)
+- What alternatives were considered
+- What constraints drove the choice
+- What the consequences are
+
+If the user hasn't specified, ask one question: "What decision are you documenting?"
+
+## Step 2: Check Existing ADRs
+
+```bash
+mkdir -p docs/adr
+ls docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1
+```
+
+Add 1 to the highest number found, zero-padded to 4 digits. If no output, the directory is empty — start at `0001`.
+
+## Step 3: Write the ADR
+
+Create `docs/adr/NNNN-short-title.md`:
+
+```markdown
+# NNNN. Short Decision Title
+
+**Date:** YYYY-MM-DD
+**Status:** accepted | proposed | deprecated | superseded by [NNNN]
+
+## Context
+
+What is the issue? What forces are at play? 2-4 sentences max.
+
+## Decision
+
+What did we decide? State it directly. 1-3 sentences.
+
+## Alternatives Considered
+
+- **Alternative A** — why rejected (1 line)
+- **Alternative B** — why rejected (1 line)
+
+## Consequences
+
+What follows from this decision? Both positive and negative. Bullet list.
+```
+
+## Rules
+
+- Keep it short. An ADR is a reference, not an essay. Under 200 words total.
+- One decision per ADR. If there are two decisions, write two ADRs.
+- Use plain language. No jargon that requires context to parse.
+- Status is usually `accepted`. Use `proposed` only if the user hasn't decided yet.
+- Never modify the substantive content of existing ADRs (Context, Decision, Alternatives, Consequences). When superseding, only update the old ADR's Status line to `superseded by [MMMM]`.