diff --git a/README.md b/README.md index 8bf12fc..26fb1d1 100644 --- a/README.md +++ b/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 diff --git a/ROADMAP.md b/ROADMAP.md index cd9e9b1..c1cd853 100644 --- a/ROADMAP.md +++ b/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 | diff --git a/skills/adr/SKILL.md b/skills/adr/SKILL.md new file mode 100644 index 0000000..806781b --- /dev/null +++ b/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]`.