specweave 2.3.0 → 3.0.1

package/plugins/specweave/PLUGIN.md

@@ -1,6 +1,8 @@
 # SpecWeave plugin (`sw`)
 
 The Claude Code surface for SpecWeave: **11 skills, 2 default hooks, 1 closer agent**.
+The skills are generated from `skills/sw-<name>/` at the repository root (the one source
+every tool shares); edit them there, never here.
 Everything deterministic lives in the `specweave` CLI; a skill exists only where a
 procedure needs model judgement. There is no `commands/` namespace in 2.0.
 
@@ -8,16 +10,16 @@ procedure needs model judgement. There is no `commands/` namespace in 2.0.
 
 | Skill | What it does |
 |---|---|
-| `sw:increment` | Plan a unit of work → `spec.md` (Problem, Scope, ACs, Approach) + `tasks.md` |
+| `sw:increment` | Plan a unit of work → one `spec.md` (Problem, Scope, ACs, Approach, Tasks) |
 | `sw:do` | Work the increment task by task through the ledger, with evidence per task |
 | `sw:done` | Close it: ledger check → `specweave verify` → optional review → `specweave complete` |
-| `sw:review` | Adversarial fresh-context review; every finding cites `path:line` |
+| `sw:review` | Adversarial fresh-context review and quality check; every finding cites `path:line` |
 | `sw:team` | Several agents on one increment: a worktree each, claims through the ledger |
-| `sw:handoff` | Portable, secret-scrubbed handoff doc so the work continues in any tool |
+| `sw:handoff` | "Hand off" here, "pick up" in any other tool, account or machine |
 | `sw:sync` | GitHub / Jira / ADO: push, pull, status, setup |
 | `sw:auto` | Unattended loop driven by the Stop hook |
 | `sw:brainstorm` | Expand the option space before committing to one |
-| `sw:qa` | Risk-scored quality assessment (`specweave qa`) |
+| `sw:project` | Shared goal, memory, work items and briefs across tools |
 | `sw:jev` | Delegate closed-set decisions to Jev (TypeSafe System One): routing, command safety, screening |
 
 Optional procedures (tdd-cycle, e2e, debug, diagrams, release-expert) are **not** in the
@@ -52,8 +54,6 @@ the marker and the project hook. This is a Claude Code surface only; other tools
 |---|---|
 | `sw:sw-closer` | Runs closure in a fresh context after implementation finishes |
 
-Team lane templates live in `skills/team/agents/` and are loaded by `specweave team`.
-
 ## Requirements
 
 - Claude Code 2.1.0+, Node.js 18+, Git

package/plugins/specweave/marketplace.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://spec-weave.com/schemas/skill-marketplace.v1.json",
   "plugin": "sw",
-  "description": "Skill catalog for the specweave plugin. The plugin version is tracked in .claude-plugin/plugin.json (stamped from package.json); this file only lists what ships.",
+  "description": "Skill catalog for the specweave plugin. The skills are generated from skills/sw-<name>/ (scripts/build/generate-skills.mjs); the plugin version is tracked in .claude-plugin/plugin.json.",
   "skills": [
     {
       "name": "sw:increment",
       "path": "skills/increment/SKILL.md",
-      "description": "Plan a unit of work: spec.md with Problem, Scope, numbered ACs and an Approach, plus tasks.md definitions.",
+      "description": "Plan a unit of work: one spec.md with Problem, Scope, numbered ACs, Approach and Tasks.",
       "deprecated": false
     },
     {
@@ -18,13 +18,13 @@
     {
       "name": "sw:done",
       "path": "skills/done/SKILL.md",
-      "description": "Close an increment: ledger check, specweave verify, optional review, specweave complete.",
+      "description": "Close an increment: board check, specweave verify, fresh-context review, specweave complete.",
       "deprecated": false
     },
     {
       "name": "sw:review",
       "path": "skills/review/SKILL.md",
-      "description": "Adversarial fresh-context review; every finding cites path:line and is re-verified. Replaces grill, code-reviewer and judge-llm.",
+      "description": "Adversarial fresh-context review and quality check; every finding cites path:line and is re-verified. Replaces qa, grill, code-reviewer and judge-llm.",
       "deprecated": false
     },
     {
@@ -36,7 +36,7 @@
     {
       "name": "sw:handoff",
       "path": "skills/handoff/SKILL.md",
-      "description": "Portable, secret-scrubbed handoff doc so the work continues in any AI tool or on any machine.",
+      "description": "\"Hand off\" in one tool, \"pick up\" in any other tool, account or machine: specweave handoff and specweave pickup.",
       "deprecated": false
     },
     {
@@ -48,7 +48,7 @@
     {
       "name": "sw:auto",
       "path": "skills/auto/SKILL.md",
-      "description": "Unattended execution driven by the Stop hook until every task is done.",
+      "description": "Run an increment unattended until every task is done, then verify and close.",
       "deprecated": false
     },
     {
@@ -57,12 +57,6 @@
       "description": "Expand the option space before committing to one, ending in a pick handed to sw:increment.",
       "deprecated": false
     },
-    {
-      "name": "sw:qa",
-      "path": "skills/qa/SKILL.md",
-      "description": "Risk-scored quality assessment via specweave qa: verdict, blockers, optional export to tasks.md.",
-      "deprecated": false
-    },
     {
       "name": "sw:jev",
       "path": "skills/jev/SKILL.md",
@@ -73,7 +67,7 @@
       "name": "sw:project",
       "path": "skills/project/SKILL.md",
       "deprecated": false,
-      "description": "Coordinate code, research and content projects with shared context, artifacts and portable worker briefs."
+      "description": "Shared goal, memory, work items, artifacts and briefs, portable across AI tools and accounts."
     }
   ],
   "optionalSkills": {
@@ -99,17 +93,17 @@
       "sw:plan": "sw:increment",
       "sw:pm": "sw:increment",
       "sw:architect": "sw:increment",
-      "sw:validate": "sw:qa",
+      "sw:validate": "sw:review",
       "sw:close-all": "specweave complete --all",
       "sw:progress": "specweave status",
-      "sw:analytics": "specweave analytics",
+      "sw:analytics": "specweave dashboard",
       "sw:help": "specweave help",
       "sw:get": "specweave get",
       "sw:umbrella": "specweave init --umbrella",
       "sw:npm": "skills-optional/release-expert",
       "sw:pr": "specweave link-pr",
-      "sw:sync-docs": "specweave docs sync",
-      "sw:living-docs": "specweave sync-living-docs",
+      "sw:sync-docs": "specweave sync push",
+      "sw:living-docs": "specweave sync push",
       "sw:progress-sync": "sw:sync",
       "sw:import": "sw:sync",
       "sw:github-sync": "sw:sync",
@@ -130,5 +124,13 @@
       "sw:skill-gen": "vskill skill-creator",
       "sw:skill-refine": "vskill skill-creator"
     }
+  },
+  "removedIn3_0": {
+    "note": "Removed in 3.0. Use the replacement; there is no alias routing.",
+    "map": {
+      "sw:qa": "sw:review",
+      "sw:task": "sw:do",
+      "sw-task": "sw-do"
+    }
   }
 }

package/plugins/specweave/skills/auto/SKILL.md

@@ -1,65 +1,48 @@
 ---
-disable-model-invocation: true
-description: Run an increment unattended - the Stop hook feeds you back into the loop until every task is done. Use when saying "auto mode", "run until done", or "ship this while I sleep".
-version: 2.0.0
-argument-hint: "[increment-ids...] [--dry-run|--reset|--all-backlog]"
+description: Run a SpecWeave increment unattended until every task is done, then verify and close. Use for "auto mode", "run until done", "ship this while I sleep".
+argument-hint: "[increment-ids...] [--dry-run|--reset]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-auto/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Auto Mode
+# sw-auto: run until done
 
-Unattended execution. `specweave auto` writes a session file; the plugin's **Stop**
-hook reads it after every turn and either blocks (with what remains) or lets the
-session end. There is no daemon and no background process — the loop is the hook.
+Auto mode is the sw-do loop without stopping to ask. The bar does not drop: claim
+before editing, a passing test for every `done`, verify before closing.
 
-## Start / inspect / stop
+## Start
 
-| Intent | Command |
-|---|---|
-| Start on specific increments | `specweave auto 0042 0043` |
-| Start on whatever is active | `specweave auto` |
-| Preview without activating | `specweave auto --dry-run` |
-| Clear stale session state | `specweave auto --reset` |
-| Progress of the running session | `specweave auto-status [--json]` |
-| Stop it (emergency) | `specweave cancel-auto [--force]` |
+1. The spec has no open questions and every task has `Files` and a `Test`. If not,
+   fix the spec first.
+2. `specweave auto 0042` records the session (`--dry-run` previews it, `--reset` clears
+   stale state). In a tool that runs SpecWeave's Stop hook (Claude Code with the `sw`
+   plugin) the hook hands you the remaining work after every turn until nothing is
+   left. In any other tool, nothing feeds you back: keep looping yourself.
+3. `specweave auto-status` shows progress; `specweave cancel-auto` stops it.
 
-## How the loop actually ends
+## Each turn
 
-The Stop handler decides each turn, in this order (any error → the session is released,
-never trapped):
+1. `specweave task next` → `specweave task claim T-NN` → implement inside its `Files` →
+   commit `0042: ...` → `specweave task done T-NN --run "<Test>"`.
+2. A failing test is fixed in the next turn, never marked done.
+3. Genuinely blocked (missing secret, ambiguous spec, external dependency):
+   `specweave task block T-NN --reason "<what is missing>"` and move on. Blocked tasks
+   still count as work left: when only blocked tasks remain, run `specweave cancel-auto`
+   and tell the user what each one needs, instead of looping until the turn limit.
+4. Nothing claimable left: run sw-done (verify, review, complete).
 
-1. No `auto-mode.json`, or `active !== true` → session over.
-2. Session file older than `auto.maxSessionAge` (default 7200 s) → released.
-3. Turn count above `auto.maxTurns` (default 20) → safety stop.
-4. `stop_hook_active` and no progress for 3 consecutive turns → loop guard releases it.
-5. No increment left to work on → released.
-6. Zero pending tasks and every AC satisfied → blocks once with
-   `all_complete_needs_closure` — that is your cue to close.
-7. Otherwise → blocks with `<P> task(s) / <A> AC(s) remain` and you keep going.
+## Running out of budget
 
-So: **you never decide to keep looping.** You do the next task, stop, and the hook
-either returns you or lets you go.
+Before the session ends for tokens or time: `specweave handoff --reason "auto: out of
+tokens"`. The next session, in any tool or account, says "pick up" and continues.
 
-## What you do inside the loop
+## Manual path (no CLI)
 
-1. `specweave task next <id>` → `task claim` → implement inside the task's `Files` →
-   commit `<id>: …` → `specweave task done T-NN <id> --run "<Test>"`. Same loop as `sw:do`.
-2. Test fails → fix it in the next turn. Never mark a task done without a passing run.
-3. Genuinely blocked (missing secret, ambiguous spec, external dependency) →
-   `specweave task block T-NN <id> --note "<what is missing>"` and stop. Blocked tasks do
-   not count as remaining work, so the loop ends instead of thrashing.
-4. On `all_complete_needs_closure`: `specweave verify <id>`, then `sw:done <id>`.
+Without the CLI there is no hook and no session file: follow the manual path of sw-do
+in a loop until every task in spec.md has a `done` or `skip` line, then sw-done.
 
 ## Rules
 
-- **Never edit `.specweave/state/auto-mode.json` or `.stop-auto-turns` by hand.**
-  `specweave auto --reset` is the supported way to clear them.
-- Do not start auto mode on an increment whose spec has open questions — resolve them first.
-- Auto mode does not lower the bar: same claim-before-edit, same evidence for `task done`.
-- If the hook is not installed (plugin not loaded), `specweave auto` still writes the session
-  but nothing feeds you back — say so rather than pretending to loop.
-- One auto session per project. Check `specweave auto-status` before starting another.
-
-## Resources
-
-- `specweave auto --help`, `specweave auto-status --help`
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#auto)
+- Never edit `.specweave/state/auto-mode.json` by hand; `specweave auto --reset` clears it.
+- One auto session per project; check `specweave auto-status` before starting another.
+- Never widen a task's `Files` or weaken a test to keep the loop moving.

package/plugins/specweave/skills/brainstorm/SKILL.md

@@ -1,58 +1,49 @@
 ---
-description: Expand the solution space before committing - framed options compared on stated criteria, ending in a pick. Use when saying "brainstorm", "ideate", or "what are our options".
-version: 2.0.0
+description: Widen the options before committing - framed options compared on stated criteria, ending in a pick that becomes an increment. Use for "brainstorm", "ideate", "what are our options".
 argument-hint: "<topic> [--depth quick|standard|deep]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-brainstorm/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Brainstorm
+# sw-brainstorm: diverge, converge, pick
 
-Diverge, then converge, then hand the winner to `sw:increment`. This never replaces
-the spec — it decides *which* thing to spec.
+Decides which thing to spec; it never replaces the spec. Hand the winner to sw-increment.
 
 ## Depth
 
 | Depth | Options | Output |
 |---|---|---|
-| `quick` (default for a narrow question) | 3 | a table + a pick, in the conversation |
-| `standard` | 4–5 | table + trade-offs + `reports/brainstorm.md` if an increment exists |
-| `deep` | 5–7, incl. one "do nothing" and one contrarian | written doc + rejected alternatives + risks |
+| `quick` (default for a narrow question) | 3 | a table and a pick, in the conversation |
+| `standard` | 4 to 5 | table, trade-offs, `reports/brainstorm.md` if an increment exists |
+| `deep` | 5 to 7, including "do nothing" and one contrarian | written doc, rejected alternatives, risks |
 
 ## Steps
 
-1. **Frame.** One sentence: the decision to be made, and what would make an answer good.
-   Write down 3–5 **criteria** up front (cost, time-to-ship, blast radius, reversibility,
-   who maintains it). Choosing criteria after seeing the options is how bias sneaks in.
-2. **Diverge.** Generate the options *before* judging any of them. Force variety:
-   - the obvious one (do the thing directly);
-   - the cheap one (what buys 80% for 20%);
-   - the buy-instead-of-build one;
-   - the do-nothing / defer one, with what it costs;
-   - one that inverts an assumption everyone is making.
-   Name each option in 3–6 words.
-3. **Converge.** One table: option × criteria, with a one-line "kills it if" per option.
-   Then a short paragraph per surviving option: how it works, what it costs, what breaks.
-4. **Pick.** State the recommendation, the runner-up, and the one fact that would flip
-   the decision. If the honest answer is "we need data first", say that and name the
-   experiment.
-5. **Hand off.** `sw:increment "<the picked option>"`. Paste the rejected alternatives into
-   the new spec's **Approach** section — that is where they earn their keep.
+1. **Frame.** One sentence: the decision and what makes an answer good. Write 3 to 5
+   criteria first (cost, time to ship, blast radius, reversibility, who maintains it).
+   Choosing criteria after seeing the options is how bias gets in.
+2. **Diverge.** Generate before judging, and force variety: the obvious one, the cheap
+   one (80% for 20%), buy instead of build, do nothing or defer (with its cost), and one
+   that inverts an assumption everyone makes. Name each in 3 to 6 words.
+3. **Converge.** One table, option by criteria, with a "kills it if" per option. Then a
+   short paragraph per survivor: how it works, what it costs, what breaks.
+4. **Pick.** The recommendation, the runner-up, and the one fact that would flip it. If
+   the honest answer is "we need data", name the experiment.
+5. **Hand off.** `specweave create-increment "<the pick>"` (sw-increment) and paste the
+   rejected alternatives into its Approach section.
+
+## Contested decisions
+
+Run three lenses over the same options: advocate (strongest case for), critic (how each
+fails in production), pragmatist (what ships this week). If your tool supports
+subagents, run them in parallel; otherwise do three labelled passes in sequence. Merge.
 
 ## Rules
 
-- Never grade an option while still generating options.
-- Every option gets the same amount of scrutiny; do not build a straw man to justify the favourite.
+- Never grade an option while still generating options; give each the same scrutiny.
 - Tables and short paragraphs, not essays.
-- Persist the doc only when there is an increment to hold it
-  (`.specweave/increments/<id>/reports/brainstorm.md`); otherwise keep it in the conversation.
-- If the user already knows what they want, skip to `sw:increment` and say why.
+- If the user already knows what they want, skip to sw-increment and say why.
 
-## Multi-perspective variant
+## Manual path (no CLI)
 
-For a genuinely contested decision, run three lenses over the same option set — advocate
-(strongest case for), critic (how each fails in production), pragmatist (what ships this
-week) — and merge. In Claude Code these can be parallel subagents (`sw:team` in brainstorm
-mode); in other tools, do the three passes in sequence and label them.
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#brainstorm)
+Nothing here needs the CLI; create the increment folder by hand as sw-increment describes.

package/plugins/specweave/skills/do/SKILL.md

@@ -1,56 +1,73 @@
 ---
-description: Work an increment task by task through the ledger: task next, claim, implement, commit, task done with evidence. Use when saying "implement", "start working", or "continue increment".
-version: 2.0.0
-argument-hint: "<increment-id>"
+description: Work a SpecWeave increment task by task - claim, implement inside the task's Files, test, commit, done with evidence - then verify and close. Use for "implement", "continue", "keep going".
+argument-hint: "[increment-id]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-do/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Do Increment
+# sw-do: work an increment to done
 
-Work an increment task by task through the ledger. State lives in
-`.specweave/increments/<id>/ledger.jsonl` (append-only); `tasks.md` holds the
-definitions. Never hand-edit status lines — `specweave task done` renders them.
+Tasks are defined in spec.md under `## Tasks`; their state lives only in the
+increment's `ledger.jsonl`, which the CLI appends to. Never write state into spec.md.
 
-## Usage
+## Start
 
-```
-sw:do [<increment-id>]     # id optional when exactly one increment is active
-```
+`specweave pickup` applies any handoff pushed from another tool or account, then prints
+the open increment, the next task with its acceptance criteria, claims other agents
+hold, and notes left for you. No increment yet? Run sw-increment first.
 
-## Loop (repeat until `task next` returns nothing)
+## The loop
 
-1. **Pick**: `specweave task next <id>` — prints the first open task whose deps are done and whose `Files` are not held by another agent. If several increments are active, pass the id.
-2. **Claim**: `specweave task claim T-NN <id>`. Exit 3 = someone else owns it (pick another), 4 = its Files overlap a live claim, 6 = deps not done. Never edit before claiming.
-3. **Read**: the task's `AC:` ids in spec.md and its `Files:`; open plan.md (or spec.md Approach) only for that scope.
-4. **Implement** inside the task's `Files` only. Need another file → claim the task that owns it, or add a task (`### T-NN Title` + `- AC: … | Files: … | Test: …`).
-5. **Commit** with the increment id in the subject: `git commit -m "<id>: <what>"`.
-6. **Done with evidence**: `specweave task done T-NN <id> --run "<Test command>"` (uses the task's `Test:` when `--run` is omitted). Exit 5 = the command failed → task stays open; fix and re-run. No `Test:` → `--evidence "<sha + what you ran>"`. Never claim completion without a fresh, passing run.
-7. **Stuck?** `specweave task block T-NN <id> --reason "<what is missing>"`; not needed? `specweave task skip T-NN <id> --reason "<why>"` (terminal).
-8. Go to 1.
+1. `specweave task next` prints the next claimable task with its AC text.
+2. `specweave task claim T-03`. Exit 3: someone holds it; 4: its Files overlap a live
+   claim; 6: its dependencies are not done. Pick another. Never edit before claiming.
+3. Implement inside that task's `Files` only. Need another file? Claim the task that
+   owns it, or add a task to spec.md `## Tasks`.
+4. Run the task's `Test`. Red means fix it; never skip, weaken or delete a test.
+5. Commit with the increment id first: `git commit -m "0042: fold the ledger"`.
+6. `specweave task done T-03 --run "npm test -- ledger"`. Exit 5: the command failed and
+   the task stays open. No `Test`? `--evidence "<sha> + what you checked"`.
+7. Stuck: `specweave task block T-03 --reason "<what is missing>"`. Not needed:
+   `specweave task skip T-03 --reason "<why>"`. Then back to 1.
 
-## Rules
+Commands take the increment id last (`specweave task next 0042`) when more than one
+increment is active. `specweave task list` shows the whole board.
+
+## Finish without asking
 
-- One agent per worktree when 2+ agents share the increment; branch name contains the increment id.
-- Append only: never edit or delete ledger lines, never touch another task's state line.
-- If a claim older than 2h (config `tasks.leaseHours`) has no `done`, it is stale — `task next` offers it again; `task claim --force` takes it over.
-- Stopping for any reason: `specweave task release --all-mine` then `sw:handoff`.
-- No CLI? Append the line yourself: `echo '{"t":"T-01","e":"claim","by":"<agent>","at":"<ISO>"}' >> ledger.jsonl` (PowerShell: `[IO.File]::AppendAllText`). `by` = `SPECWEAVE_AGENT` or `<tool>@<host>`.
+When `task next` has nothing left, run sw-done: verify, review, complete.
+"All tasks are done, should I close?" is the anti-pattern.
 
-## Increment selection (no id given)
+## Stopping early
 
-- Exactly one `metadata.json` with `status: active` → use it.
-- Several → `specweave task list` errors listing candidates; ask which, or take the one named in the auto-mode context / stop-hook feedback.
-- None active but exactly one `planned` → the CLI uses it, and `task claim` starts it (`planned → active`). `specweave start <id>` does it explicitly.
-- None at all → `sw:increment` first.
+Out of tokens, switching tool or account: `specweave handoff --reason "<why>"` (sw-handoff).
 
-## Finish (mandatory, never stop to ask)
+## Manual path (no CLI)
 
-When `task next` says nothing is claimable and every task is done or skipped:
+Read the tasks from spec.md and the state from `ledger.jsonl`: the next task is the lowest
+T-id nobody holds whose Files no live claim holds. Append one JSON object per line, keys
+in this order, UTF-8, LF:
 
-1. `specweave verify <id>` → `reports/verify.json` (project test/lint/build + AC table + ledger).
-2. Invoke `Skill({ skill: "sw:done" })` with the id. It runs the optional review and `specweave complete`.
+```bash
+L=.specweave/increments/0042-ledger-fold/ledger.jsonl
+printf '%s\n' '{"t":"T-01","e":"claim","by":"codex@mbp","at":"2026-09-02T10:00:00Z"}' >> "$L"
+```
+
+```powershell
+$L = '.specweave\increments\0042-ledger-fold\ledger.jsonl'
+$line = '{"t":"T-01","e":"done","by":"codex@win","at":"2026-09-02T11:30:00Z","evidence":"npm test -- ledger exit 0 / a1b2c3d"}'
+[IO.File]::AppendAllText($L, $line + "`n", [Text.UTF8Encoding]::new($false))
+```
 
-Anti-pattern: "All tasks are complete. Should I close?" — close it.
+PowerShell never uses `>>` here: it writes UTF-16 and every other tool fails to read it.
+Events: `claim`, `done` (needs `evidence`), `release`, `block` and `skip` (both need
+`note`), for example
+`{"t":"T-02","e":"skip","by":"codex@mbp","at":"2026-09-02T12:00:00Z","note":"covered by T-01"}`.
+`by` is `SPECWEAVE_AGENT` if set, else `<tool>@<host>`.
 
-## Resources
+## Rules
 
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#do)
+- A claim older than 2 hours with no `done` is stale and may be taken over.
+- Append only: never edit, reorder or delete a ledger line. On a merge conflict in
+  `ledger.jsonl` keep every line from both sides.
+- Several agents on one increment: one worktree and branch each (sw-team).

package/plugins/specweave/skills/done/SKILL.md

@@ -1,41 +1,48 @@
 ---
-disable-model-invocation: true
-description: Close an increment: ledger check, specweave verify, optional review, then specweave complete. Use when all tasks are done and saying "close increment", "we are done", or "finish up".
-version: 2.0.0
-argument-hint: "<increment-id> [--reason <text>]"
+description: Close a SpecWeave increment - every task done or skipped, specweave verify green, a fresh-context review, then specweave complete. Use for "close it", "we are done", "finish up".
+argument-hint: "[increment-id] [--reason \"...\"]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-done/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Close Increment
+# sw-done: close an increment
 
-Closure = **verify → optional review → `specweave complete`**. The only hard
-gate is `reports/verify.json` with `ok: true`. Grill / judge / rubric reports
-are optional evidence and never block.
-
-## Usage
-
-```
-sw:done <increment-id>                    # normal closure
-sw:done <increment-id> --reason "<why>"   # close without a green verify (recorded as metadata.closeReason)
-```
+Closing is verify, review, complete. The one hard gate is a passing
+`reports/verify.json`; everything else is evidence.
 
 ## Steps
 
-1. **Ledger check**: `specweave task list <id>`. Every task must be `done` or `skipped`. Open/claimed tasks → go back to `sw:do` (or `task skip … --reason "<why>"`). Release your own claims: `specweave task release --all-mine`.
-2. **Verify**: `specweave verify <id>`. Runs `testing.commands` from config (else `npm run test|lint|build`, `cargo test`, `pytest`, `go test ./...`), writes `reports/verify.md` + `reports/verify.json`. Non-zero exit → fix, re-run. Do not proceed on red without a `--reason` from the user.
-3. **Review (recommended for anything user-facing, optional otherwise)**: invoke `Skill({ skill: "sw:review" })` — fresh context, adversarial, findings cite `path:line`, written to `reports/review.md`. Fix critical/high findings, re-run step 2 if code changed.
-4. **Docs touched?** If the increment changed commands, config, or user-facing behaviour, update README/CHANGELOG/CLAUDE.md `## Commands` in the same commit. Living docs sync only if `livingDocs` is enabled in config (`specweave docs sync <id>`).
-5. **Complete**: `Bash({ command: "specweave complete <id> --yes" })`. The CLI refuses when `verify.json` is missing or not ok unless `--reason "<text>"` is given; it prints a notice when `reports/review.md` is absent; it sets `status: completed` and syncs GitHub/Jira/ADO when configured. **Never edit `metadata.json` status by hand.**
-6. **Handoff**: if work continues elsewhere (follow-ups, another increment), `sw:handoff`.
-
-Report in one paragraph: verify result, review verdict (or "skipped"), commit sha(s), anything deferred.
+1. **Board.** `specweave task list`: every task must be `done` or `skipped`. Anything
+   open goes back to sw-do, or `specweave task skip T-04 --reason "<why>"`.
+2. **Verify.** `specweave verify` runs the project's test, lint and build commands
+   (config `testing.commands`, else detected), checks every acceptance criterion
+   against the ledger (an AC is met when all its tasks are done) and writes
+   `reports/verify.md` and `reports/verify.json`. Red: fix and re-run. Do not tick
+   AC boxes; they are derived.
+3. **Review.** For anything that ships, run sw-review in a fresh context. Fix critical
+   and high findings, then verify again.
+4. **Docs.** If commands, config or user-facing behaviour changed, update README,
+   CHANGELOG and the `## Commands` table in AGENTS.md in the same branch.
+5. **Complete.** `specweave complete 0042`. It refuses without a passing verify unless
+   the user gives a reason: `specweave complete 0042 --reason "<why>"`.
+6. **Ship.** Push the branch and open the PR the way this repository ships;
+   `specweave report` writes an HTML timeline to attach as evidence.
+
+Report in one paragraph: verify result, review verdict (or "skipped"), commits,
+anything deferred.
+
+## Manual path (no CLI)
+
+Check every task in spec.md has a `done` or `skip` line in `ledger.jsonl`. Run the
+project's test, lint and build commands yourself and put their real output in
+`reports/verify.md`. Then set `"status": "completed"` in `metadata.json`, the one state
+change the manual path makes by hand.
 
 ## Rules
 
-- Never ask "should I close?" — closure follows automatically when tasks are done; the user can re-open.
-- `--skip-validation` exists for emergencies only; prefer `--reason` so the reason is recorded.
-- Multi-agent sessions (`sw:team`): only the lead runs `sw:done`, after every agent has released and handed off.
-- Failed sync after completion: `specweave sync push <id>` retries; closure itself already succeeded.
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#done)
+- Never ask "should I close?" when the tasks are done; close, and the user can reopen.
+- Never edit `metadata.json` status while the CLI is available.
+- Several agents on one increment: only the lead closes, after every agent has handed
+  off or released its claims.
+- Completing never calls GitHub, Jira or Azure DevOps unless close-on-complete is set;
+  a failed sync afterwards is retried with `specweave sync push`.