From 95dce3bc2a619f9b71468a43e0f5f48d543faefe Mon Sep 17 00:00:00 2001 From: Trong Tran Date: Fri, 19 Jun 2026 16:03:10 +0700 Subject: [PATCH 1/5] Add design doc for sd-docs-writer agent and /sd:adr command --- .../2026-06-19-sd-docs-writer-adr-design.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-19-sd-docs-writer-adr-design.md diff --git a/docs/superpowers/specs/2026-06-19-sd-docs-writer-adr-design.md b/docs/superpowers/specs/2026-06-19-sd-docs-writer-adr-design.md new file mode 100644 index 0000000..1b7b5cc --- /dev/null +++ b/docs/superpowers/specs/2026-06-19-sd-docs-writer-adr-design.md @@ -0,0 +1,83 @@ +# Design: `sd-docs-writer` agent + `/sd:adr` command + +Date: 2026-06-19 +Roadmap item: ROADMAP.md "Planned" - `sd-docs-writer` agent +Status: approved (brainstorming) + +## Problem + +Durable architectural decisions captured in spec artifacts (`03-decisions.md`) never get promoted into +human-facing Architecture Decision Records. The constitution's mutation protocol already points to ADRs +under `.specs/_adr/`, and `/sd:setup` already scaffolds that directory, but nothing authors ADRs and no +agent or command targets them. + +## Goal + +Promote durable spec decisions into numbered ADRs under `.specs/_adr/`, via a new read-mostly agent +driven by a new command. + +## Non-goals + +- Generating or updating human-facing architecture docs (e.g. `docs/architecture.md`) - separate, fuzzier + roadmap item; high risk of clobbering hand-written prose. +- Drafting constitution amendments. The agent never edits `.specs/constitution.md`. +- A new spec template. ADRs are not specs; they live in `.specs/_adr/` with their own MADR-style format. + +## Design + +### New agent: `agents/docs-writer.md` (installs as `sd-docs-writer`) + +- **Frontmatter:** `name: sd-docs-writer`, `color`, `model: sonnet` (ADR drafting is prose synthesis, + matching the architect/reviewer tier), minimal `tools: [Read, Write, Glob, Grep]`, and + `skills: [sd-evidence-citation]` (ADRs must cite the spec/file that drove the decision). +- **Role:** read a spec's decision artifacts (primarily `03-decisions.md`, plus spec context) and draft + ONE ADR. Never edits the constitution, never auto-fixes code, never invents decisions not present in + the source. + +### New command: `commands/adr.md` (`/sd:adr`) + +- **Argument:** `` (e.g. `FEAT-012`) OR a free-text decision title for ad-hoc ADRs with no spec. +- **Phase 0 - bootstrap:** read `CLAUDE.md`, `.specs/constitution.md`, `.claude/project-config.json`, + `.specs/index.md` (same as every command). +- **Phase 1 - resolve source:** locate the spec folder and read `03-decisions.md` (and spec context). For + free-text mode, take the decision from the argument + a short interactive prompt. +- **Phase 2 - number + draft:** scan `.specs/_adr/` for the highest existing `NNNN-` prefix, assign the + next zero-padded number, derive a kebab slug from the decision title, and invoke `sd-docs-writer` to + draft `.specs/_adr/NNNN-.md`. +- **ADR format (MADR-style):** `Status` (proposed / accepted / superseded), `Context`, `Decision`, + `Consequences`, plus a back-link to the source spec ID. Supersession: a new ADR may mark an older one + `superseded by NNNN`, with a reciprocal link recorded on the old ADR. +- **HARD gate:** print the drafted ADR and require explicit approval before writing to disk (engine gate + discipline; silence is not approval). +- **Idempotent:** if an ADR for the same decision already exists, offer update-in-place vs new-number + rather than clobbering. + +### Wiring (the "everywhere" surface) + +Command count 10 -> 11 and agent count 5 -> 6 in: + +- `CLAUDE.md` (repo) - command list, agent list, and the install-target table. +- `commands/setup.md` - Phase 7 report block ("10 workflow commands", "5 specialist agents"). +- `templates/CLAUDE.template.md` - the Workflows table gains a `/sd:adr` row. +- `README.md` - command/agent counts and any command table. +- `docs/architecture.md` - the command -> agent routing tree gains `/sd:adr -> sd-docs-writer`. +- `scripts/validate.ps1` + `scripts/validate.sh` - install-target count assertions (`commands/sd` 11, + `agents/sd` 6). + +No `templates/specs/` addition (ADRs are not specs). + +## Verification + +- `scripts/validate.{ps1,sh}` pass with updated counts (11 commands, 6 agents); ASCII scan, hook-pair + parity, model-alias-only all still green. +- Dry-run install + install -> uninstall round-trip in a sandbox; confirm `commands/sd/adr.md` and + `agents/sd/docs-writer.md` land and are removed cleanly. +- Manual `/sd:adr ` run against a sample `.specs//03-decisions.md`: confirm a numbered ADR + is drafted, the HARD gate fires before writing, and the file lands in `.specs/_adr/`. +- `CHANGELOG.md` gains an `[Unreleased]` entry. + +## Out of scope / follow-ups + +- Architecture-doc generation from accumulated specs. +- A close-gate offer ("draft an ADR from this spec?") inside feature/bug/refactor/perf workflows - a + follow-up once the dedicated command proves out. From af3811a5fb882420b4a3556d8948fb390d939dca Mon Sep 17 00:00:00 2001 From: Trong Tran Date: Fri, 19 Jun 2026 16:08:51 +0700 Subject: [PATCH 2/5] Add implementation plan for sd-docs-writer and /sd:adr --- .../plans/2026-06-19-sd-docs-writer-adr.md | 439 ++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-19-sd-docs-writer-adr.md diff --git a/docs/superpowers/plans/2026-06-19-sd-docs-writer-adr.md b/docs/superpowers/plans/2026-06-19-sd-docs-writer-adr.md new file mode 100644 index 0000000..9056cd0 --- /dev/null +++ b/docs/superpowers/plans/2026-06-19-sd-docs-writer-adr.md @@ -0,0 +1,439 @@ +# `sd-docs-writer` + `/sd:adr` Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add a `sd-docs-writer` agent and a `/sd:adr` command that drafts a numbered, MADR-style Architecture Decision Record under `.specs/_adr/` from a spec's decision artifacts, behind one hard approval gate. + +**Architecture:** Pure prompt-engineering change. A new agent markdown file (`agents/docs-writer.md`) and a new command markdown file (`commands/adr.md`), plus the count/doc wiring that every "Nth command / Nth agent" addition requires across the repo (the same surface the `/sd:release` 10th-command change touched). No application code, no scripts beyond bumping two hardcoded count constants in the validators. + +**Tech Stack:** Markdown with YAML frontmatter (ATX headers, 100-char soft wrap), PowerShell + bash validators. No build system, no unit-test framework. + +## Global Constraints + +- Model fields are aliases only (`sonnet` / `haiku` / `opus` / `inherit`); never full model IDs. `sd-docs-writer` uses `sonnet`. +- Minimal tool allowlists: an agent gets a tool only if its role requires it. +- The namespace is `sd-` (agent `name:`) and `sd/` (install subfolder); assets reference each other by the namespaced name (`sd-docs-writer`), never the bare filename. +- Stack-agnostic: no hardcoded stack commands or language assumptions in the command or agent. +- Gate discipline: hard gates STOP and wait for explicit approval; silence is not approval. +- ADRs are not specs: no `.specs/index.md` lifecycle entry; they live under `.specs/_adr/` with their own numbering. +- Pure ASCII in `*.ps1` files (use `->`, `[OK]`); verify with the repo grep. +- Markdown style: ATX headers, no trailing colon in headers, fenced blocks with language hint, 100-char soft wrap. +- Every PR adds a line under `## [Unreleased]` in `CHANGELOG.md`. +- Verification is `scripts/validate.{ps1,sh}` + install -> uninstall round-trip; there are no unit tests. + +--- + +### Task 1: Create the `sd-docs-writer` agent + +**Files:** +- Create: `agents/docs-writer.md` + +**Interfaces:** +- Consumes (from the `/sd:adr` command in Task 2): `ADR_NUMBER` (zero-padded 4-digit string), `ADR_PATH` (exact target file path), `SPEC_REF` (spec ID or `ad-hoc`), `DECISION_SOURCE` (path to `03-decisions.md` or inline decision text), `SUPERSEDES` (ADR number or `none`), and `DATE` (today, `YYYY-MM-DD`). +- Produces: writes exactly one file at `ADR_PATH` and returns its content. Never assigns its own number; never writes any other file. + +- [ ] **Step 1: Write the agent file** + +Create `agents/docs-writer.md` with exactly this content: + +```markdown +--- +name: sd-docs-writer +color: cyan +description: Authors a single Architecture Decision Record (ADR) from a spec's decision artifacts. Reads 03-decisions.md plus spec context and drafts a MADR-style ADR under .specs/_adr/. Never edits the constitution, never modifies code, never invents decisions. +model: sonnet +tools: Read, Write, Glob, Grep +skills: + - sd-evidence-citation +--- + +You are the docs-writer for specwright. You turn durable decisions captured in spec artifacts into a single human-facing Architecture Decision Record (ADR). You synthesize only what the source says: you never invent a decision, never edit the constitution, and never modify code. + +--- + +## Always do first + +1. Read the `DECISION_SOURCE` the command provides (`03-decisions.md` for a spec, or the inline decision text for ad-hoc mode). +2. Read `CLAUDE.md` and `.specs/constitution.md` for naming and convention context (read-only; never edit them). +3. Use the `ADR_NUMBER` and `ADR_PATH` the command assigns. Never pick or change the number. + +--- + +## Input contract + +The command passes: +- `ADR_NUMBER` - zero-padded 4-digit sequence (e.g. `0007`). +- `ADR_PATH` - exact target file (e.g. `.specs/_adr/0007-cqrs-read-path.md`). +- `SPEC_REF` - source spec ID (e.g. `FEAT-012`) or `ad-hoc`. +- `DECISION_SOURCE` - path to `03-decisions.md` or the inline decision text. +- `SUPERSEDES` - ADR number this one supersedes, or `none`. +- `DATE` - today's date (`YYYY-MM-DD`); never invent a date. + +## Output: one ADR file (MADR-style) + +Write exactly one file at `ADR_PATH` with this structure: + + # ADR : + + - Status: proposed + - Date: <DATE> + - Source spec: <SPEC_REF> + - Supersedes: <ADR number or "none"> + + ## Context + + <Why the decision was needed. Cite the driving spec artifact and any code the decision concerns, using file:line per the sd-evidence-citation skill.> + + ## Decision + + <What was decided, stated as one clear position.> + + ## Consequences + + <Positive, negative, and follow-up consequences. Honest about trade-offs.> + +Rules: +- Status is always `proposed` on a fresh draft - a human accepts it later. +- Every claim about the codebase cites `file:line` (sd-evidence-citation skill). +- Never fabricate a decision, date, or consequence not supported by the source. +- If `DECISION_SOURCE` is empty or absent, STOP and report `no decision content found in <DECISION_SOURCE>` - do not invent an ADR. +- If `SUPERSEDES` is not `none`, state the reciprocal link in your returned summary so the command can update the superseded ADR. + +## Hard limits + +- You write ONLY the one `ADR_PATH` file. You never touch the constitution, code, or other ADRs. +- You never assign or change the ADR number (the command owns numbering). +- You return the drafted ADR content as your final output. +``` + +- [ ] **Step 2: Verify frontmatter shape matches the other agents** + +Run: `grep -nE "^(name|color|model|tools|skills):" agents/docs-writer.md` +Expected: lines for `name: sd-docs-writer`, `color: cyan`, `model: sonnet`, `tools: Read, Write, Glob, Grep`, and `skills:`. + +Run: `grep -c "sd-docs-writer" agents/docs-writer.md` +Expected: at least `1` (the `name:` field). + +- [ ] **Step 3: Commit** + +```bash +git add agents/docs-writer.md +git commit -m "Add sd-docs-writer agent for ADR authoring" +``` + +--- + +### Task 2: Create the `/sd:adr` command + +**Files:** +- Create: `commands/adr.md` + +**Interfaces:** +- Consumes: nothing from Task 1 at author time; at runtime it invokes the `sd-docs-writer` agent by name with the input contract defined in Task 1. +- Produces: the entry point that assigns `ADR_NUMBER`/`ADR_PATH`, gates on approval, and (on `yes`) updates a superseded ADR's status. + +- [ ] **Step 1: Write the command file** + +Create `commands/adr.md` with exactly this content: + +```markdown +--- +description: Author an Architecture Decision Record (ADR) from a spec's decisions via sd-docs-writer. One hard gate before keeping the file. +argument-hint: <spec-ID | "decision title"> +--- + +# /sd:adr + +Promotes a durable decision into a numbered ADR under `.specs/_adr/`. Drives the `sd-docs-writer` agent. + +**Argument:** a spec ID (e.g. `FEAT-012`) whose `03-decisions.md` holds the decision, OR a free-text +decision title for an ad-hoc ADR with no spec. + +--- + +## Phase 0 - Bootstrap + +Read, in order: `CLAUDE.md`, `.specs/constitution.md`, `.claude/project-config.json`, `.specs/index.md`. +If `.specs/` does not exist, abort: "No `.specs/` found - run `/sd:setup` first." + +## Phase 1 - Resolve the decision source + +1. If the argument matches a spec ID in `.specs/index.md`: + - Locate `.specs/<ID>/03-decisions.md`. If it is missing or has no decision content, STOP and ask the + user to supply the decision inline or pick another spec. Never invent decisions. + - Set `SPEC_REF = <ID>` and `DECISION_SOURCE = .specs/<ID>/03-decisions.md`. +2. Otherwise treat the argument as a free-text decision title: + - Set `SPEC_REF = ad-hoc`. If the title alone is insufficient, ask the user once for the Context, + Decision, and Consequences. `DECISION_SOURCE` = the gathered text. + +## Phase 2 - Assign number and slug + +1. Glob `.specs/_adr/` for files matching `^[0-9]{4}-`. Take the highest 4-digit prefix; `ADR_NUMBER` = + that value + 1, zero-padded to 4 digits. If none exist, `ADR_NUMBER = 0001`. +2. Derive `<slug>` = kebab-case of the decision title (lowercase, alphanumerics and hyphens, <= 60 chars). +3. `ADR_PATH = .specs/_adr/<ADR_NUMBER>-<slug>.md`. +4. If the user names an existing ADR this decision replaces, set `SUPERSEDES` to its number; else `none`. +5. Idempotency: if an ADR whose title clearly matches this decision already exists, ask whether to update + it in place or create a new number. Never silently clobber. + +## Phase 3 - Draft via sd-docs-writer + +Invoke the `sd-docs-writer` agent with `ADR_NUMBER`, `ADR_PATH`, `SPEC_REF`, `DECISION_SOURCE`, +`SUPERSEDES`, and today's date as `DATE`. The agent drafts and writes the file, then returns its content. + +## Gate (HARD) - approve before keeping + +Display the drafted ADR in full. STOP and ask: "Keep this ADR at `<ADR_PATH>`? (yes / edit / abort)". +Silence is not approval. +- `yes` -> keep the file. If `SUPERSEDES` is not `none`, edit that ADR's `Status` line to + `superseded by <ADR_NUMBER>` and add a reciprocal "Superseded by" link. +- `edit` -> apply the requested changes (re-invoke the agent or edit directly) and re-display. +- `abort` -> delete the drafted file and report that no ADR was created. + +## Phase 4 - Report + +Print the ADR path, number, status (`proposed`), source spec, and any supersession link. Remind the user +the ADR stays `proposed` until they change its status to `accepted`. + +--- + +## Rules (hard constraints) + +- **Decisions come from the source, never invented.** Empty or absent decision content aborts the command. +- **One hard gate.** Nothing is kept on disk without explicit approval. +- **ADRs are not specs.** No `.specs/index.md` lifecycle entry; ADRs live under `.specs/_adr/` with their + own numbering. +- **The constitution is never edited here.** Amending a rule is a separate `/sd:refactor` or a manual ADR + acceptance step. +``` + +- [ ] **Step 2: Verify the command references the agent by its namespaced name** + +Run: `grep -n "sd-docs-writer" commands/adr.md` +Expected: at least one match (Phase 3 invocation). + +Run: `grep -nE "^(description|argument-hint):" commands/adr.md` +Expected: both frontmatter keys present. + +- [ ] **Step 3: Commit** + +```bash +git add commands/adr.md +git commit -m "Add /sd:adr command driving sd-docs-writer" +``` + +--- + +### Task 3: Wire the 11th-command / 6th-agent counts and docs + +This is the mechanical "bump everywhere" surface. The hard ones (validators) fail CI if missed; the rest +keep docs honest. Append `/sd:adr` as the 11th command and `sd-docs-writer` as the 6th agent in every list. + +**Files:** +- Modify: `scripts/validate.ps1`, `scripts/validate.sh` +- Modify: `CLAUDE.md`, `README.md`, `docs/architecture.md`, `install/README.md`, `CONTRIBUTING.md` +- Modify: `commands/setup.md`, `templates/CLAUDE.template.md` +- Modify: `CHANGELOG.md` + +**Interfaces:** +- Consumes: the agent name `sd-docs-writer` (Task 1) and command `/sd:adr` (Task 2). +- Produces: validator count constants of 11 commands / 6 agents that the Task 4 install round-trip checks. + +- [ ] **Step 1: Bump the validator count constants** + +In `scripts/validate.ps1`, change: + +```powershell +$ExpectedCommands = 10 +$ExpectedAgents = 5 +``` + +to: + +```powershell +$ExpectedCommands = 11 +$ExpectedAgents = 6 +``` + +In `scripts/validate.sh`, change: + +```bash +EXPECTED_COMMANDS=10 +EXPECTED_AGENTS=5 +``` + +to: + +```bash +EXPECTED_COMMANDS=11 +EXPECTED_AGENTS=6 +``` + +- [ ] **Step 2: Update `CLAUDE.md`** + +Change the sandbox comment (line ~21) from `# expect 10 .md files` to `# expect 11 .md files`. + +In the repo-structure table, change the `commands/` row to read `11 slash commands` and append +`` `/sd:adr` `` to the parenthesised command list, and change the `agents/` row to read `6 subagents` +and append `` `sd-docs-writer` `` to its list: + +``` +| `commands/` | `~/.claude/commands/sd/` | 11 slash commands (`/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release`, `/sd:adr`) | +| `agents/` | `~/.claude/agents/sd/` | 6 subagents (`sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer`, `sd-docs-writer`) | +``` + +- [ ] **Step 3: Update `README.md`** + +Change the `**10 slash commands**` cell (line ~29) to `**11 slash commands**` and append `/sd:adr` to the +command list in that cell. + +- [ ] **Step 4: Update `docs/architecture.md`** + +- Line ~13: `commands/sd/ 10 workflow definitions` -> `11 workflow definitions`. +- Line ~14: `agents/sd/ 5 subagent prompt files` -> `6 subagent prompt files`. +- Line ~323: `lists all 10 commands` -> `lists all 11 commands`. +- Agent table (after the `sd-reviewer` row, ~line 94) add: + +``` +| `sd-docs-writer` | sonnet | Read/Write/Glob/Grep + sd-evidence-citation | Authors one MADR-style ADR from a spec's decisions. Writes only the ADR file. | +``` + +- Command -> agent routing block (the fenced list ~lines 108-117): add a line after `/sd:review`: + +``` +/sd:adr -> docs-writer +``` + +- Evidence-citation consumers: in the skills table row for `sd-evidence-citation` (~line 143) add + `sd-docs-writer` to the consumer list, and in the de-duplication prose (~line 134) change + "used by `sd-code-explorer`, `sd-debugger`, and `sd-reviewer`" to + "used by `sd-code-explorer`, `sd-debugger`, `sd-reviewer`, and `sd-docs-writer`". + +- [ ] **Step 5: Update `install/README.md`** + +- Layout tree: `commands/sd/ 10 slash commands` -> `11 slash commands`; + `agents/sd/ 5 subagent definitions` -> `6 subagent definitions`. +- Install table: `commands/` row count `10` -> `11` and append `adr` to its list; + `agents/` row count `5` -> `6` and append `sd-docs-writer` to its list. +- Verify snippets: `# expect 10 .md files` -> `11`; `# expect 5 .md files` -> `6`; + `ls ~/.claude/commands/sd/ # 10 .md files` -> `11`; `ls ~/.claude/agents/sd/ # 5 .md files` -> `6`. +- Total line: `**Total**: 33 files per OS.` -> `**Total**: 35 files per OS.` (commands 10->11, agents 5->6). + +- [ ] **Step 6: Update `CONTRIBUTING.md`** + +- `commands/ # 10 slash commands (markdown with frontmatter)` -> `11 slash commands`. +- `agents/ # 5 subagent definitions (markdown with frontmatter)` -> `6 subagent definitions`. + +- [ ] **Step 7: Update `commands/setup.md` Phase 7 report** + +- ` - ~/.claude/commands/sd/ (10 workflow commands)` -> `(11 workflow commands)`. +- ` - ~/.claude/agents/sd/ (5 specialist agents)` -> `(6 specialist agents)`. + +- [ ] **Step 8: Update `templates/CLAUDE.template.md` workflow table** + +After the `/sd:setup` row (line ~24) add: + +``` +| `/sd:adr <spec-ID>` | Author an ADR from a spec's decisions. | +``` + +- [ ] **Step 9: Add the CHANGELOG entry** + +In `CHANGELOG.md`, under `## [Unreleased]` add an `### Added` bullet (create the `### Added` subheading if +this branch does not already have one): + +```markdown +- `/sd:adr` command (11th) + `sd-docs-writer` agent (6th) - drafts a numbered, MADR-style Architecture + Decision Record under `.specs/_adr/` from a spec's `03-decisions.md` (or an ad-hoc decision), behind one + hard approval gate. The agent (model `sonnet`, tools Read/Write/Glob/Grep, skill `sd-evidence-citation`) + writes only the ADR file and never invents decisions; the command owns numbering and supersession links. + Bumps command count 10 -> 11 and agent count 5 -> 6 across docs and the validators. +``` + +- [ ] **Step 10: Verify no stale counts remain and ASCII is clean** + +Run: `grep -rnE "10 (slash command|workflow command|workflow definition|\.md file)|5 (subagent|specialist agent|\.md file)" CLAUDE.md README.md docs/architecture.md install/README.md CONTRIBUTING.md commands/setup.md` +Expected: no output (every stale `10 commands` / `5 agents` count updated). + +Run: `grep -nP "[^\x00-\x7F]" scripts/validate.ps1` +Expected: no output (validators stay pure ASCII). + +- [ ] **Step 11: Commit** + +```bash +git add scripts/validate.ps1 scripts/validate.sh CLAUDE.md README.md docs/architecture.md install/README.md CONTRIBUTING.md commands/setup.md templates/CLAUDE.template.md CHANGELOG.md +git commit -m "Wire 11th command and 6th agent counts for /sd:adr" +``` + +--- + +### Task 4: Full verification (validate + install round-trip) + +**Files:** none (verification only). + +**Interfaces:** +- Consumes: all prior tasks. +- Produces: green validator and a clean install -> uninstall round-trip proving the new files land and remove. + +- [ ] **Step 1: Run the validator** + +Run (PowerShell): `./scripts/validate.ps1` +Expected: all 6 checks pass; Check 5 reports `commands/sd : 11 file(s)` and `agents/sd : 6 file(s)`; +Check 6 (`[Unreleased]` gate) passes. + +- [ ] **Step 2: Sandbox install and count check** + +Run (PowerShell): + +```powershell +./install/install.ps1 -BasePath C:\temp\sd-adr-test +(Get-ChildItem C:\temp\sd-adr-test\commands\sd\ -Filter *.md).Count # expect 11 +(Get-ChildItem C:\temp\sd-adr-test\agents\sd\ -Filter *.md).Count # expect 6 +Test-Path C:\temp\sd-adr-test\commands\sd\adr.md # expect True +Test-Path C:\temp\sd-adr-test\agents\sd\docs-writer.md # expect True +``` + +Expected: counts 11 and 6; both `Test-Path` results `True`. + +- [ ] **Step 3: Uninstall round-trip and cleanup** + +Run (PowerShell): + +```powershell +./install/uninstall.ps1 -BasePath C:\temp\sd-adr-test -Force +Test-Path C:\temp\sd-adr-test\commands\sd # expect False +Remove-Item -Recurse -Force C:\temp\sd-adr-test +``` + +Expected: `commands/sd` removed (`False`), then the temp tree cleaned up. + +- [ ] **Step 4: No commit** + +Verification only; nothing to commit. If any check failed, return to the owning task and fix. + +--- + +## Self-Review + +**Spec coverage** (against `docs/superpowers/specs/2026-06-19-sd-docs-writer-adr-design.md`): +- New agent `agents/docs-writer.md` (sonnet, Read/Write/Glob/Grep, sd-evidence-citation, drafts one ADR, + never edits constitution/code, never invents) -> Task 1. +- New command `commands/adr.md` (`<spec-ID>` or free-text; Phase 0 bootstrap; resolve source; number + + slug; invoke agent; HARD gate; supersession; idempotent) -> Task 2. +- MADR format (Status/Context/Decision/Consequences + back-link + supersession) -> Task 1 Step 1 output + block; supersession reciprocal write -> Task 2 gate `yes` branch. +- Wiring 10->11 / 5->6 in CLAUDE.md, setup.md, CLAUDE.template.md, README.md, architecture.md routing + + agent table, validators -> Task 3 Steps 1-8; plus install/README.md and CONTRIBUTING.md found during + planning (the design's "everywhere" surface). +- No new spec template -> intentionally absent; noted in constraints. +- Verification (validators with updated counts, install round-trip, CHANGELOG) -> Task 3 Step 9, Task 4. +- No gaps. + +**Placeholder scan:** `<Title>`, `<ADR_NUMBER>`, `<slug>` etc. are literal template tokens inside the ADR +format the agent emits at runtime (intended), not unfilled plan steps. No "TBD"/"handle edge cases"/"similar +to Task N". + +**Type consistency:** the input-contract field names (`ADR_NUMBER`, `ADR_PATH`, `SPEC_REF`, +`DECISION_SOURCE`, `SUPERSEDES`, `DATE`) are identical in Task 1 (consumes/produces), the agent body, and +Task 2 Phase 3 (the invocation). Counts are 11 commands / 6 agents uniformly across Task 3 and Task 4. +Agent name is `sd-docs-writer` and command is `/sd:adr` everywhere. From ce11ed7c667c26eb96f53eb797cac176dbdf46b0 Mon Sep 17 00:00:00 2001 From: Trong Tran <trongtran@developzone.dev> Date: Fri, 19 Jun 2026 16:17:30 +0700 Subject: [PATCH 3/5] Add sd-docs-writer agent for ADR authoring --- agents/docs-writer.md | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 agents/docs-writer.md diff --git a/agents/docs-writer.md b/agents/docs-writer.md new file mode 100644 index 0000000..e842a15 --- /dev/null +++ b/agents/docs-writer.md @@ -0,0 +1,67 @@ +--- +name: sd-docs-writer +color: cyan +description: Authors a single Architecture Decision Record (ADR) from a spec's decision artifacts. Reads 03-decisions.md plus spec context and drafts a MADR-style ADR under .specs/_adr/. Never edits the constitution, never modifies code, never invents decisions. +model: sonnet +tools: Read, Write, Glob, Grep +skills: + - sd-evidence-citation +--- + +You are the docs-writer for specwright. You turn durable decisions captured in spec artifacts into a single human-facing Architecture Decision Record (ADR). You synthesize only what the source says: you never invent a decision, never edit the constitution, and never modify code. + +--- + +## Always do first + +1. Read the `DECISION_SOURCE` the command provides (`03-decisions.md` for a spec, or the inline decision text for ad-hoc mode). +2. Read `CLAUDE.md` and `.specs/constitution.md` for naming and convention context (read-only; never edit them). +3. Use the `ADR_NUMBER` and `ADR_PATH` the command assigns. Never pick or change the number. + +--- + +## Input contract + +The command passes: +- `ADR_NUMBER` - zero-padded 4-digit sequence (e.g. `0007`). +- `ADR_PATH` - exact target file (e.g. `.specs/_adr/0007-cqrs-read-path.md`). +- `SPEC_REF` - source spec ID (e.g. `FEAT-012`) or `ad-hoc`. +- `DECISION_SOURCE` - path to `03-decisions.md` or the inline decision text. +- `SUPERSEDES` - ADR number this one supersedes, or `none`. +- `DATE` - today's date (`YYYY-MM-DD`); never invent a date. + +## Output: one ADR file (MADR-style) + +Write exactly one file at `ADR_PATH` with this structure: + + # ADR <ADR_NUMBER>: <Title> + + - Status: proposed + - Date: <DATE> + - Source spec: <SPEC_REF> + - Supersedes: <ADR number or "none"> + + ## Context + + <Why the decision was needed. Cite the driving spec artifact and any code the decision concerns, using file:line per the sd-evidence-citation skill.> + + ## Decision + + <What was decided, stated as one clear position.> + + ## Consequences + + <Positive, negative, and follow-up consequences. Honest about trade-offs.> + +Rules: +- Status is always `proposed` on a fresh draft - a human accepts it later. +- Every claim about the codebase cites `file:line` (sd-evidence-citation skill). +- Never fabricate a decision, date, or consequence not supported by the source. +- If `DECISION_SOURCE` is empty or absent, STOP and report `no decision content found in <DECISION_SOURCE>` - do not invent an ADR. +- If `SUPERSEDES` is not `none`, state the reciprocal link in your returned summary so the command can update the superseded ADR. + +## Hard limits + +- You write ONLY the one `ADR_PATH` file. You never touch the constitution, code, or other ADRs. +- You never assign or change the ADR number (the command owns numbering). +- You return the drafted ADR content as your final output. From 75a99a27232bebec168577d64dbcdca6bd0a0af3 Mon Sep 17 00:00:00 2001 From: Trong Tran <trongtran@developzone.dev> Date: Fri, 19 Jun 2026 16:23:17 +0700 Subject: [PATCH 4/5] Add /sd:adr command driving sd-docs-writer --- commands/adr.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 commands/adr.md diff --git a/commands/adr.md b/commands/adr.md new file mode 100644 index 0000000..3036955 --- /dev/null +++ b/commands/adr.md @@ -0,0 +1,68 @@ +--- +description: Author an Architecture Decision Record (ADR) from a spec's decisions via sd-docs-writer. One hard gate before keeping the file. +argument-hint: <spec-ID | "decision title"> +--- + +# /sd:adr + +Promotes a durable decision into a numbered ADR under `.specs/_adr/`. Drives the `sd-docs-writer` agent. + +**Argument:** a spec ID (e.g. `FEAT-012`) whose `03-decisions.md` holds the decision, OR a free-text +decision title for an ad-hoc ADR with no spec. + +--- + +## Phase 0 - Bootstrap + +Read, in order: `CLAUDE.md`, `.specs/constitution.md`, `.claude/project-config.json`, `.specs/index.md`. +If `.specs/` does not exist, abort: "No `.specs/` found - run `/sd:setup` first." + +## Phase 1 - Resolve the decision source + +1. If the argument matches a spec ID in `.specs/index.md`: + - Locate `.specs/<ID>/03-decisions.md`. If it is missing or has no decision content, STOP and ask the + user to supply the decision inline or pick another spec. Never invent decisions. + - Set `SPEC_REF = <ID>` and `DECISION_SOURCE = .specs/<ID>/03-decisions.md`. +2. Otherwise treat the argument as a free-text decision title: + - Set `SPEC_REF = ad-hoc`. If the title alone is insufficient, ask the user once for the Context, + Decision, and Consequences. `DECISION_SOURCE` = the gathered text. + +## Phase 2 - Assign number and slug + +1. Glob `.specs/_adr/` for files matching `^[0-9]{4}-`. Take the highest 4-digit prefix; `ADR_NUMBER` = + that value + 1, zero-padded to 4 digits. If none exist, `ADR_NUMBER = 0001`. +2. Derive `<slug>` = kebab-case of the decision title (lowercase, alphanumerics and hyphens, <= 60 chars). +3. `ADR_PATH = .specs/_adr/<ADR_NUMBER>-<slug>.md`. +4. If the user names an existing ADR this decision replaces, set `SUPERSEDES` to its number; else `none`. +5. Idempotency: if an ADR whose title clearly matches this decision already exists, ask whether to update + it in place or create a new number. Never silently clobber. + +## Phase 3 - Draft via sd-docs-writer + +Invoke the `sd-docs-writer` agent with `ADR_NUMBER`, `ADR_PATH`, `SPEC_REF`, `DECISION_SOURCE`, +`SUPERSEDES`, and today's date as `DATE`. The agent drafts and writes the file, then returns its content. + +## Gate (HARD) - approve before keeping + +Display the drafted ADR in full. STOP and ask: "Keep this ADR at `<ADR_PATH>`? (yes / edit / abort)". +Silence is not approval. +- `yes` -> keep the file. If `SUPERSEDES` is not `none`, edit that ADR's `Status` line to + `superseded by <ADR_NUMBER>` and add a reciprocal "Superseded by" link. +- `edit` -> apply the requested changes (re-invoke the agent or edit directly) and re-display. +- `abort` -> delete the drafted file and report that no ADR was created. + +## Phase 4 - Report + +Print the ADR path, number, status (`proposed`), source spec, and any supersession link. Remind the user +the ADR stays `proposed` until they change its status to `accepted`. + +--- + +## Rules (hard constraints) + +- **Decisions come from the source, never invented.** Empty or absent decision content aborts the command. +- **One hard gate.** Nothing is kept on disk without explicit approval. +- **ADRs are not specs.** No `.specs/index.md` lifecycle entry; ADRs live under `.specs/_adr/` with their + own numbering. +- **The constitution is never edited here.** Amending a rule is a separate `/sd:refactor` or a manual ADR + acceptance step. From e4fcdc1c6d69510a4e98daa0bdee707396763917 Mon Sep 17 00:00:00 2001 From: Trong Tran <trongtran@developzone.dev> Date: Fri, 19 Jun 2026 16:29:51 +0700 Subject: [PATCH 5/5] Wire 11th command and 6th agent counts for /sd:adr --- CHANGELOG.md | 5 +++++ CLAUDE.md | 6 +++--- CONTRIBUTING.md | 4 ++-- README.md | 4 ++-- commands/setup.md | 4 ++-- docs/architecture.md | 14 ++++++++------ install/README.md | 18 +++++++++--------- scripts/validate.ps1 | 4 ++-- scripts/validate.sh | 4 ++-- templates/CLAUDE.template.md | 1 + 10 files changed, 36 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bcfd200..d0f3342 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 inside-out `paths.layers` map) into `CLAUDE.md` and `project-config.json`, with a single batch confirmation gate. Facts only - constitution rules are never auto-filled. Adds `paths.layers` to `templates/project-config.template.json`. +- `/sd:adr` command (11th) + `sd-docs-writer` agent (6th) - drafts a numbered, MADR-style Architecture + Decision Record under `.specs/_adr/` from a spec's `03-decisions.md` (or an ad-hoc decision), behind one + hard approval gate. The agent (model `sonnet`, tools Read/Write/Glob/Grep, skill `sd-evidence-citation`) + writes only the ADR file and never invents decisions; the command owns numbering and supersession links. + Bumps command count 10 -> 11 and agent count 5 -> 6 across docs and the validators. --- diff --git a/CLAUDE.md b/CLAUDE.md index 550c5ac..7aff799 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ Note: `templates/CLAUDE.template.md` is the template `/sd:setup` scaffolds into # Sandbox install test (run before any PR touching install/hooks/commands/agents) .\install\install.ps1 -BasePath C:\temp\sd-test -Get-ChildItem C:\temp\sd-test\commands\sd\ # expect 10 .md files +Get-ChildItem C:\temp\sd-test\commands\sd\ # expect 11 .md files .\install\uninstall.ps1 -BasePath C:\temp\sd-test -Force # round-trip: removes the 5 sd\ dirs Remove-Item -Recurse -Force C:\temp\sd-test # cleanup ``` @@ -44,8 +44,8 @@ Every PR adds a line under `## [Unreleased]` in `CHANGELOG.md` (Keep a Changelog | Source | Installs to | Contents | |---|---|---| -| `commands/` | `~/.claude/commands/sd/` | 10 slash commands (`/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release`) | -| `agents/` | `~/.claude/agents/sd/` | 5 subagents (`sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer`) | +| `commands/` | `~/.claude/commands/sd/` | 11 slash commands (`/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release`, `/sd:adr`) | +| `agents/` | `~/.claude/agents/sd/` | 6 subagents (`sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer`, `sd-docs-writer`) | | `hooks/powershell/` + `hooks/bash/` | `~/.claude/hooks/sd/` | 3 hooks × 2 platforms (`prompt-router`, `spec-gate`, `subagent-retro`) | | `templates/` | `~/.claude/templates/sd/` | 4 setup templates + 5 spec templates in `specs/` | | `skills/` | `~/.claude/skills/sd/` | 6 rule packs, one folder per skill with `SKILL.md` | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a907996..3ad1363 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,8 +40,8 @@ per-file-type guidelines, and how to test changes locally. ``` specwright/ - commands/ # 10 slash commands (markdown with frontmatter) - agents/ # 5 subagent definitions (markdown with frontmatter) + commands/ # 11 slash commands (markdown with frontmatter) + agents/ # 6 subagent definitions (markdown with frontmatter) hooks/ powershell/ # 3 PowerShell hooks bash/ # 3 bash hooks (parity with PowerShell) diff --git a/README.md b/README.md index 7379328..65225af 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ The system is **stack-agnostic**. Agents read `CLAUDE.md` and `constitution.md` | Capability | What you get | |---|---| -| **10 slash commands** | `/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release` | -| **5 specialized subagents** | `sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer` | +| **11 slash commands** | `/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release`, `/sd:adr` | +| **6 specialized subagents** | `sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer`, `sd-docs-writer` | | **3 cross-platform hooks** | `prompt-router`, `spec-gate`, `subagent-retro` (PowerShell + bash) | | **9 templates** | 4 setup templates + 5 spec templates (feature / bug / refactor / perf / rca) | | **6 reusable skills** | `sd-severity-taxonomy`, `sd-hypothesis-tree`, `sd-atomic-task-format`, `sd-evidence-citation`, `sd-spec-templates`, `sd-pattern-discipline` | diff --git a/commands/setup.md b/commands/setup.md index 74c08c5..8cab09b 100644 --- a/commands/setup.md +++ b/commands/setup.md @@ -213,8 +213,8 @@ Setup complete. Generated: - .claude/settings.json (hooks: prompt-router, spec-gate, subagent-retro) Installed engine paths: - - ~/.claude/commands/sd/ (10 workflow commands) - - ~/.claude/agents/sd/ (5 specialist agents) + - ~/.claude/commands/sd/ (11 workflow commands) + - ~/.claude/agents/sd/ (6 specialist agents) - ~/.claude/hooks/sd/ (3 hooks) - ~/.claude/templates/sd/ (templates) - ~/.claude/skills/sd/ (6 skills: severity-taxonomy, hypothesis-tree, atomic-task-format, evidence-citation, spec-templates, pattern-discipline) diff --git a/docs/architecture.md b/docs/architecture.md index d4dcc12..6b19b2a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -10,8 +10,8 @@ specwright is a thin layer on top of Claude Code that enforces spec-driven devel +--------------------------------------------------------------------+ | Layer 1 - USER scope (~/.claude/, installed once) | | | -| commands/sd/ 10 workflow definitions | -| agents/sd/ 5 subagent prompt files | +| commands/sd/ 11 workflow definitions | +| agents/sd/ 6 subagent prompt files | | hooks/sd/ 3 cross-platform hook scripts | | templates/sd/ 4 setup + 5 spec templates | | skills/sd/ 6 reusable rule packs (referenced by agents) | @@ -92,6 +92,7 @@ Each subagent has a focused role, a minimal tool allowlist, and a model assignme | `sd-debugger` | sonnet | Read/Grep/Glob/Bash + sequential-thinking + GitNexus + MSSQL (SELECT only) + Tavily + Context7 | Hypothesis-tree investigation. Distinguishes proximate vs root cause. | | `sd-implementer` | haiku | Read/Write/Edit/MultiEdit/Grep/Glob/Bash + Context7 | Executes ONE atomic task with scope discipline. | | `sd-reviewer` | sonnet | Read/Grep/Glob + sequential-thinking + GitNexus | Severity-tagged review (🔴 BLOCK / 🟠 WARN / 🟡 SUGGEST / 🟢 PASS). Cannot write. | +| `sd-docs-writer` | sonnet | Read/Write/Glob/Grep + sd-evidence-citation | Authors one MADR-style ADR from a spec's decisions. Writes only the ADR file. | **Tool allowlists are minimal by design.** The reviewer cannot fix code because it has no write tools. The explorer cannot suggest fixes for the same reason. This is enforced by the engine, not by prose discipline alone. @@ -112,6 +113,7 @@ fan-out each command performs (left to right = invocation order; `(xN)` = once p /sd:rca -> spec-architect -> debugger (enumerate / verify) [no code change - output IS the spec] /sd:explore -> code-explorer /sd:review -> reviewer +/sd:adr -> docs-writer /sd:spec -> (none - pure file ops on .specs/) /sd:setup -> (none - scaffolds CLAUDE.md / .specs/ / .claude/) /sd:release -> (none - pure file ops; mirrors /sd:spec) @@ -131,16 +133,16 @@ Skills are markdown rule packs that agents reference from their frontmatter. The The split exists for three reasons: -1. **De-duplication.** `sd-evidence-citation` is used by `sd-code-explorer`, `sd-debugger`, and `sd-reviewer`. Without skills, the same `file:line` citation rule would be copy-pasted into three agent files and drift over time. With skills, it lives in one place. +1. **De-duplication.** `sd-evidence-citation` is used by `sd-code-explorer`, `sd-debugger`, `sd-reviewer`, and `sd-docs-writer`. Without skills, the same `file:line` citation rule would be copy-pasted into four agent files and drift over time. With skills, it lives in one place. 2. **Smaller agent bodies.** The reviewer prompt no longer carries the full severity taxonomy inline; it points at `sd-severity-taxonomy`. Body size goes down; lookup discipline stays the same. -3. **Auditability.** A reader can open one `SKILL.md` and see exactly what rules every agent follows for that concern — without grepping across 5 agent files. +3. **Auditability.** A reader can open one `SKILL.md` and see exactly what rules every agent follows for that concern — without grepping across 6 agent files. | Skill | Used by | Purpose | |---|---|---| | `sd-severity-taxonomy` | `sd-reviewer` | Severity levels + per-severity rules + mandatory output markdown. | | `sd-hypothesis-tree` | `sd-debugger` | Enumerate / verify protocol, the 5 mental models, score formula `(L × I) / C`, proximate-vs-root ladder. | | `sd-atomic-task-format` | `sd-spec-architect`, `sd-implementer` | The task block (9 required fields + `Pattern refs`) + canonical enums (`Step type`, `Complexity`, `Reversibility`). | -| `sd-evidence-citation` | `sd-code-explorer`, `sd-debugger`, `sd-reviewer` | `file:line` discipline, snippet length, evidence taxonomy, grouping. | +| `sd-evidence-citation` | `sd-code-explorer`, `sd-debugger`, `sd-reviewer`, `sd-docs-writer` | `file:line` discipline, snippet length, evidence taxonomy, grouping. | | `sd-spec-templates` | `sd-spec-architect` | Per-template authoring rules; which cross-phase fields to leave empty. | | `sd-pattern-discipline` | `sd-spec-architect`, `sd-implementer`, `sd-reviewer` | Pattern discovery and adherence: precedent sampling, `Pattern refs` authoring/following, conformance review. | @@ -320,7 +322,7 @@ Every command, agent, and (conceptually) namespaced asset uses the `sd:` prefix: The prefix exists for three reasons: 1. **Collision avoidance.** A project may have its own `/feature` or `/review` slash command. `sd:` carves out a namespace. -2. **Discoverability.** Typing `/sd:` in Claude Code lists all 10 commands. The namespace is its own table of contents. +2. **Discoverability.** Typing `/sd:` in Claude Code lists all 11 commands. The namespace is its own table of contents. 3. **Removability.** Uninstalling the engine removes everything under `sd/` subfolders, leaving the rest of `~/.claude/` intact. --- diff --git a/install/README.md b/install/README.md index b17f870..3a376f1 100644 --- a/install/README.md +++ b/install/README.md @@ -4,8 +4,8 @@ The installer copies the engine (commands, agents, hooks, templates) into a Clau ``` <base>/ -├── commands/sd/ 10 slash commands -├── agents/sd/ 5 subagent definitions +├── commands/sd/ 11 slash commands +├── agents/sd/ 6 subagent definitions ├── hooks/sd/ 3 hook scripts (.ps1 on Windows, .sh on Unix) ├── templates/sd/ 9 templates (4 setup + 5 spec) └── skills/sd/ 6 skills (one folder per skill with SKILL.md) @@ -46,14 +46,14 @@ Default base is `$HOME/.claude` (Unix) or `$env:USERPROFILE\.claude` (Windows). | Source (in repo) | Target (under `<base>/`) | Files | Notes | |---|---|---|---| -| `commands/` | `commands/sd/` | 10 | `feature`, `bug`, `rca`, `refactor`, `perf`, `spec`, `explore`, `review`, `setup`, `release` | -| `agents/` | `agents/sd/` | 5 | `sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer` | +| `commands/` | `commands/sd/` | 11 | `feature`, `bug`, `rca`, `refactor`, `perf`, `spec`, `explore`, `review`, `setup`, `release`, `adr` | +| `agents/` | `agents/sd/` | 6 | `sd-spec-architect`, `sd-code-explorer`, `sd-debugger`, `sd-implementer`, `sd-reviewer`, `sd-docs-writer` | | `hooks/powershell/` (Windows installer) | `hooks/sd/` | 3 | `prompt-router.ps1`, `spec-gate.ps1`, `subagent-retro.ps1` | | `hooks/bash/` (Unix installer) | `hooks/sd/` | 3 | `prompt-router.sh`, `spec-gate.sh`, `subagent-retro.sh` (chmod +x applied) | | `templates/` | `templates/sd/` | 4 + 5 | Setup templates + `specs/` subfolder with 5 spec templates | | `skills/` | `skills/sd/` | 6 | One folder per skill, each with a `SKILL.md` | -**Total**: 33 files per OS. +**Total**: 35 files per OS. --- @@ -81,16 +81,16 @@ After install, check the target directories: **Windows:** ```powershell -Get-ChildItem $env:USERPROFILE\.claude\commands\sd\ # expect 10 .md files -Get-ChildItem $env:USERPROFILE\.claude\agents\sd\ # expect 5 .md files +Get-ChildItem $env:USERPROFILE\.claude\commands\sd\ # expect 11 .md files +Get-ChildItem $env:USERPROFILE\.claude\agents\sd\ # expect 6 .md files Get-ChildItem $env:USERPROFILE\.claude\hooks\sd\ # expect 3 .ps1 files Get-ChildItem $env:USERPROFILE\.claude\templates\sd\ # expect 4 files + specs\ folder ``` **Unix:** ```bash -ls ~/.claude/commands/sd/ # 10 .md files -ls ~/.claude/agents/sd/ # 5 .md files +ls ~/.claude/commands/sd/ # 11 .md files +ls ~/.claude/agents/sd/ # 6 .md files ls ~/.claude/hooks/sd/ # 3 .sh files (executable) ls -l ~/.claude/hooks/sd/ # confirm +x bits set ls ~/.claude/templates/sd/ # 4 files + specs/ folder diff --git a/scripts/validate.ps1 b/scripts/validate.ps1 index ee9f18b..fbf166c 100644 --- a/scripts/validate.ps1 +++ b/scripts/validate.ps1 @@ -32,8 +32,8 @@ $repoRoot = Split-Path -Parent $scriptDir # ---- expected install-target counts ---------------------------------------- # One platform's hooks land per install (PowerShell hooks here), so 3 not 6. -$ExpectedCommands = 10 -$ExpectedAgents = 5 +$ExpectedCommands = 11 +$ExpectedAgents = 6 $ExpectedSkills = 6 $ExpectedHooks = 3 $ExpectedTemplates = 9 diff --git a/scripts/validate.sh b/scripts/validate.sh index 0a2ad4e..9f7d5e3 100755 --- a/scripts/validate.sh +++ b/scripts/validate.sh @@ -19,8 +19,8 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" repo_root="$(cd "$script_dir/.." && pwd)" # One platform's hooks land per install (bash hooks here), so 3 not 6. -EXPECTED_COMMANDS=10 -EXPECTED_AGENTS=5 +EXPECTED_COMMANDS=11 +EXPECTED_AGENTS=6 EXPECTED_SKILLS=6 EXPECTED_HOOKS=3 EXPECTED_TEMPLATES=9 diff --git a/templates/CLAUDE.template.md b/templates/CLAUDE.template.md index 16b679e..e2c49d6 100644 --- a/templates/CLAUDE.template.md +++ b/templates/CLAUDE.template.md @@ -22,6 +22,7 @@ | `/sd:explore <query>` | Read-only code navigation. | | `/sd:review <target>` | Standalone compliance review. | | `/sd:setup` | Idempotent project scaffold. | +| `/sd:adr <spec-ID>` | Author an ADR from a spec's decisions. | ## Stack