specweave 3.0.23 → 3.1.0

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

@@ -1,7 +1,7 @@
 ---
-description: Adversarial fresh-context review and risk check of an increment before it ships; every finding cites path:line and is re-verified. Use for "review", "qa", "quality check", "critique this".
+description: Adversarial review of an increment before it ships, by a fresh context or another model family; every finding cites path:line and is re-verified. Use for "review", "qa", "critique this".
 argument-hint: "[increment-id] [--full]"
-version: 3.0.0
+version: 3.1.0
 ---
 <!-- Generated from skills/sw-review/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
@@ -14,8 +14,8 @@ This is also the quality check: its verdict says whether the increment is ready.
 ## Non-negotiables
 
 - **Fresh context.** The session that wrote the code never approves it. Use a new
-  session, or a subagent if your tool supports them. If you wrote this code here and
-  cannot get a fresh context, say so in the report.
+  session, a subagent if your tool supports them, or another model (below). If you
+  wrote this code here and cannot get a fresh context, say so in the report.
 - **Every finding cites `path:line`** and a concrete failure: input or state leads to
   wrong output, a crash, a hang, data loss or a leak. "Consider refactoring" is not one.
 - **Re-verify.** Re-open the lines and, where a test can show it, run one. Drop what
@@ -42,6 +42,24 @@ This is also the quality check: its verdict says whether the increment is ready.
    (`### T-09 Fix empty evidence` + `- AC: AC-02 | Files: ... | Test: ...`) for sw-do, or
    is fixed and re-tested now. Then verify again and close with sw-done.
 
+## Another model
+
+A model reviewing code its own family wrote shares that code's blind spots.
+`specweave review` hands the increment to a reviewer from another family: it reads who
+finished the tasks from the ledger (`claude@mbp` is Claude), runs Codex with GPT-6.1-Sol
+on Claude-written code (Claude Opus on OpenAI-written code), and writes
+`reports/review-codex.md` in the shape below plus a ledger note. Exit 0: ship; 3: fix
+first, or no verdict; 1: no reviewer installed, or it failed.
+
+- Run it when `review.crossModel` is true in `.specweave/config.json`, when the user
+  asks for another model, or when you wrote the code and have no fresh context.
+- `--brief` prints the brief (ACs, tasks and their Files, the diff) to paste into any
+  model by hand; `--reviewer claude`, `--base origin/main` and `--timeout 45` override.
+- `review.reviewer` pins one reviewer; `review.reviewers.<name>.command` adds a CLI that
+  reads the brief on stdin and answers on stdout, or into `{out}` when it names one.
+
+Its findings get the same treatment as yours: re-open each line before acting on it.
+
 ## reports/review.md
 
 ```markdown
@@ -57,6 +75,7 @@ Nits: naming in ledger.ts:31.
 ```
 
 Verdict is `fix first` while any critical or high finding survives, else `ship`.
+`specweave complete` notes a `fix first` verdict in the newest review report.
 
 ## Manual path (no CLI)
 

package/plugins/specweave/skills-catalog.json

@@ -0,0 +1,32 @@
+{
+  "$comment": "The one list of SpecWeave skills. Core skills ship in the sw plugin and in every project. Optional skills install into a project only when listed under skills.enabled in .specweave/config.json, or when their detect rule matches and they are not under skills.disabled. Retired skills are removed from projects on update. scripts/build/generate-skills.mjs copies this file to plugins/specweave/skills-catalog.json.",
+  "core": ["increment", "do", "auto", "done", "review", "handoff"],
+  "optional": [
+    {
+      "name": "grill-me",
+      "summary": "Interview you in rounds until every decision in a plan is settled",
+      "detect": "deep-interview"
+    },
+    {
+      "name": "glossary",
+      "summary": "Build GLOSSARY.md: each domain term across business, data, code and UI",
+      "detect": "glossary-file"
+    },
+    {
+      "name": "sync",
+      "summary": "Push progress to and pull issues from GitHub, Jira or Azure DevOps",
+      "detect": "tracker"
+    },
+    {
+      "name": "project",
+      "summary": "Shared goal, work items and briefs in .specweave/project/hub.json",
+      "detect": "hub"
+    },
+    {
+      "name": "jev",
+      "summary": "Closed-set decisions through Jev (System One)",
+      "detect": "jev"
+    }
+  ],
+  "retired": ["qa", "task", "brainstorm", "team"]
+}

package/plugins/specweave/skills-optional/glossary/SKILL.md

@@ -0,0 +1,90 @@
+---
+description: Build the shared language - interview the user term by term and write GLOSSARY.md with what each term means in the business, the data, the code and the UI. Use for "glossary", "ubiquitous language".
+argument-hint: "[term...] [--check]"
+version: 1.0.0
+---
+<!-- Generated from skills/sw-glossary/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
+
+# sw-glossary: one word for one thing, everywhere
+
+Domain-driven design's ubiquitous language: an Order should be an Order when the
+client talks about it, in the database, in the code and on the screen. When the words
+drift ("purchase" table, `Order` type, "basket" button), agents spend tokens decoding
+jargon, name new code inconsistently and build the wrong thing. A short glossary fixes
+that for every session after it. Run this at a project's start, when a new domain area
+arrives, or whenever one word means two things or two words mean one.
+
+## GLOSSARY.md
+
+One file at the repository root. A repo with several bounded contexts keeps a
+`GLOSSARY-MAP.md` at the root that links one `GLOSSARY.md` per context; follow it.
+Create the file when the first term settles, never empty.
+
+```markdown
+# Glossary
+
+A shop that sells refurbished laptops to small businesses.
+
+## Ordering
+
+### Order
+A customer's request to buy one or more products, placed at checkout and paid once.
+- Avoid: purchase, basket, transaction
+- Data: `orders` table; its lines in `order_lines`
+- Code: `Order` in `src/orders/order.ts`; `POST /orders`
+- UI: "Order", "My orders"
+- Rules: never deleted; cancelling sets the status to cancelled
+```
+
+- The definition says what the thing **is**, in the client's words, in one or two
+  sentences. No implementation detail there.
+- `Avoid` lists the synonyms nobody should use for it. Be opinionated: one term wins.
+- `Data`, `Code` and `UI` say where the term lives at each level. Put table, column,
+  type and file names in backticks so `specweave glossary check` can find them. Leave
+  out a level the term does not have.
+- `Rules` (optional) holds the invariants the business states about it.
+- Only terms specific to this domain. Timeouts, caches and retries are not glossary
+  terms even if the code uses them everywhere.
+- Group terms under `##` headings when clusters appear; a flat list is fine.
+
+## The interview
+
+1. **Harvest.** Read the README, the schema or migrations, the models and types, the
+   routes and the UI strings. List the nouns that recur, and every mismatch: one
+   concept with several names (`purchases` table, `Order` type, "Basket" label) and
+   one name with several meanings ("account" as login and as billing account).
+2. **Ask in rounds**, as sw-grill-me does: a few terms per round, each question with
+   your recommended answer, worded so "yes" accepts it. "The table is `purchases`, the
+   type is `Order`, the button says Basket. Call all three an Order?" Use your tool's
+   structured question tool when it has one.
+3. **Sharpen with scenarios.** "A customer pays for 3 items and one ships late: one
+   Order or two?" Invent the edge case that forces a boundary.
+4. **Check the code.** When the user says how something works, read the code. If it
+   disagrees ("the code cancels whole Orders; you said a single line can be
+   cancelled"), say so and settle which one is right.
+5. **Write each term as it settles**, not in a batch at the end.
+6. **Drift is work, not an edit.** Where the code or data uses an avoided word, do not
+   rename silently. List it for the user, and plan the renames as an increment
+   (sw-increment): a table rename is a migration and the user's call.
+
+## Using it
+
+- Every skill writes specs, names, commits and replies in the glossary's terms.
+- `specweave glossary check` lists avoided words used as identifiers in tracked files
+  and backticked `Data` or `Code` names that no longer exist, with `file:line`.
+  `--strict` exits 1 when it finds any, for CI. `--json` for tools.
+- A new term or a changed meaning comes back here, or into sw-grill-me's interview.
+
+## Configuration
+
+`specweave skills enable glossary` installs this skill. A `GLOSSARY.md` or
+`GLOSSARY-MAP.md` at the root installs it too, and adds a short "Shared language"
+section to AGENTS.md on the next `specweave update`.
+
+## Manual path (no CLI)
+
+Write GLOSSARY.md by hand in the format above. Without the check, search the code for
+each avoided word yourself (`git grep -n -i -w purchase`) and read the hits.
+
+Adapted from mattpocock/skills `domain-modeling` (MIT, Copyright (c) 2026 Matt Pocock);
+see `references/credits.md`.

package/plugins/specweave/skills-optional/glossary/references/credits.md

@@ -0,0 +1,33 @@
+# Credits
+
+sw-glossary adapts [mattpocock/skills](https://github.com/mattpocock/skills)
+`skills/engineering/domain-modeling` (MIT): the GLOSSARY.md and GLOSSARY-MAP.md layout,
+`_Avoid_` synonyms, definitions that say what a term is, challenging terms against the
+glossary and the code, and edge-case scenarios that force a boundary. The Data, Code,
+UI and Rules levels and `specweave glossary check` are SpecWeave's.
+
+## mattpocock/skills
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+## Permission notice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/specweave/skills-optional/grill-me/SKILL.md

@@ -0,0 +1,99 @@
+---
+description: Interview the user relentlessly, in rounds, until every decision in a plan is settled; facts are your job, decisions are theirs. Use for "grill me", "interview me", "stress-test this plan".
+argument-hint: "[topic or increment-id]"
+version: 1.0.0
+---
+<!-- Generated from skills/sw-grill-me/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
+
+# sw-grill-me: settle every decision before building
+
+No one knows exactly what they want. The gap between the user and the agent is where
+wrong builds come from, and a model never closes it alone: it fills the gaps with
+guesses. This skill walks the plan's decision tree with the user until nothing is left
+silently assumed. Use it at a project's start, before a change whose shape is unclear,
+or whenever the user asks to be grilled. A clear, small request does not need it.
+
+## How it runs
+
+1. **Read first.** The code the plan touches, `.specweave/config.json`, the open
+   increment's spec.md (`specweave task list`) and `GLOSSARY.md` if it exists. Draft
+   the problem, the scope and the approach yourself.
+2. **Map the tree.** List every open decision and what it depends on. Probe the
+   things users forget: scope and non-goals; users and flows; the data and the words
+   for it; integrations, installs, accounts and keys; failures and edge cases;
+   security and privacy; performance and scale; rollout and migration; how a machine
+   will check that it works.
+3. **Facts are yours.** Anything the code, docs, config or a quick command can answer,
+   look up (in a subagent if your tool has them). Never ask the user what you could
+   find. A lookup still running blocks only the questions that depend on it.
+4. **Ask in rounds.** Each round asks the whole frontier: every decision whose
+   prerequisites are already settled. Number the questions; give each one clause on
+   why it matters and your recommended answer, worded so "yes" accepts it. A question
+   that depends on another one in the same round waits for the next round.
+5. **Recompute** after every answer: settled decisions unlock new ones, and some
+   answers make others moot. Then ask the next round.
+6. **Stop** when the frontier is empty and the user confirms you share one picture.
+   "Enough" or "your call" stops early: every decision left gets your recommendation
+   as a stated default.
+
+Plain text, one round per message:
+
+```text
+Q1 Auth provider: who signs users in? Changes the data model and pricing.
+   Recommended: Clerk, since the app already uses its React components.
+Q2 Rate limits: per API key or per IP? NAT users share IPs.
+   Recommended: per API key.
+```
+
+If your tool has a structured question tool (as Claude Code and Codex do), ask the
+round through it so apps such as SpecWithCode show a card: up to 4 questions per card,
+header `Q1 Auth`, your recommendation first, free answers allowed, multi-select only
+for "which of these services or installs". Split a larger frontier over several cards.
+Never ask for a secret in a question: name the env var or use the app's secret request.
+
+## The words (when GLOSSARY.md exists)
+
+- When the user uses a term that conflicts with the glossary, say so at once: "The
+  glossary says an Order is one checkout; you mean one shipment. Which is it?"
+- When a word is fuzzy ("account" for both the login and the billing account), propose
+  one precise term each.
+- Test a boundary with a concrete scenario: "A customer pays for 3 items and one ships
+  late: one Order or two?"
+- When the user states how something works, check the code agrees and surface any
+  contradiction.
+- Write each settled term into `GLOSSARY.md` as sw-glossary describes, when it settles.
+
+## Record
+
+In the increment's spec.md, under `## Decisions` (before spec.md exists, hold them
+until sw-increment creates it with `specweave create-increment`):
+
+```markdown
+## Decisions
+### Asked
+- D-01 Auth provider? → Clerk (user). Changes the data model and pricing.
+### Defaulted (change any before sw-do)
+- D-04 Rate-limit store → in-memory, Redis later (reversible).
+### Open
+- none
+```
+
+Apply every answer to Scope, the acceptance criteria and Approach, replacing any text
+it contradicts. Keep a Decision line only when a later change could contradict it:
+hard to reverse, surprising without context, or a real trade-off. Everything else is
+just applied. Do not build until the user confirms; sw-do refuses to run unattended
+while `### Open` has entries.
+
+## Configuration
+
+`specweave skills enable grill-me` installs this skill; `planning.deepInterview: deep`
+in `.specweave/config.json` installs it too and makes sw-increment run it for every
+new increment. `critical` (the default) keeps sw-increment to at most 5 questions.
+
+## Manual path (no CLI)
+
+Nothing here needs the CLI: read the files by hand, ask in rounds, and write the
+decisions into spec.md yourself.
+
+Adapted from mattpocock/skills `grilling` and `domain-modeling` (MIT, Copyright (c) 2026
+Matt Pocock); see `references/credits.md`.

package/plugins/specweave/{skills/brainstorm → skills-optional/grill-me}/references/credits.md

@@ -1,12 +1,12 @@
 # Credits
 
-The Decide part of sw-brainstorm adapts ideas from these MIT-licensed projects. Their
+sw-grill-me, sw-glossary and the Decide step of sw-increment adapt ideas from these MIT-licensed projects. Their
 copyright and permission notices are kept below, as the MIT license requires.
 
 | Project | What we adapted |
 |---|---|
-| [obra/superpowers](https://github.com/obra/superpowers) `skills/brainstorming` | One question at a time; sorting questions into answered, my call and theirs; "a default they never heard is one they couldn't reject"; asking for a description before offering options |
-| [mattpocock/skills](https://github.com/mattpocock/skills) `skills/productivity/grilling` | Facts are the agent's job, decisions are the user's; a recommended answer for every question; walking the decision tree until shared understanding ("grill me") |
+| [obra/superpowers](https://github.com/obra/superpowers) `skills/brainstorming` | Sorting questions into answered, my call and theirs; "a default they never heard is one they couldn't reject" |
+| [mattpocock/skills](https://github.com/mattpocock/skills) `skills/productivity/grilling`, `skills/engineering/domain-modeling` | Facts are the agent's job, decisions are the user's; rounds over the frontier of the decision tree, each question with a recommended answer worded so "yes" accepts it ("grill me"); the GLOSSARY.md with _Avoid_ words; challenging terms against the glossary and the code; the three-part test for recording a decision |
 | [github/spec-kit](https://github.com/github/spec-kit) `templates/commands/clarify.md` | The coverage categories, ranking by impact times uncertainty, the 5-question cap, multiple choice with a recommended option, and writing each answer back into the spec |
 
 ## obra/superpowers

package/src/templates/AGENTS.md.template

@@ -8,7 +8,7 @@ This project uses SpecWeave. Plan increments in `.specweave/increments/NNNN-slug
 ## The loop
 
 1. `specweave pickup`: applies the latest handoff and prints the open increment, next task and ACs, other claims, branch state, notes and project memory.
-2. New work needing ACs or handoff: `specweave create-increment "title"`, then fill spec.md. First ask the user only their critical decisions, one at a time with a recommended answer, and record them under `## Decisions` (sw-brainstorm). If an open increment owns the files, add ACs and tasks there. Small fixes need no increment.
+2. New work needing ACs or handoff: `specweave create-increment "title"`, then fill spec.md. First ask the user only their critical decisions, one at a time with a recommended answer, and record them under `## Decisions` (sw-increment). If an open increment owns the files, add ACs and tasks there. Small fixes need no increment.
 3. `specweave task claim T-NN`, edit only that task's Files, commit as `NNNN: what changed`, then `specweave task done T-NN --run "<its Test>"`.
 4. `specweave verify`, a review in a fresh session for anything that ships, then `specweave complete NNNN`.
 5. Before stopping or switching tools/accounts: `specweave handoff --reason "<why>"`.
@@ -33,6 +33,12 @@ Tasks in spec.md: `### T-01 Title`, then `- AC: AC-01 | Files: src/a.ts, tests/e
 Umbrella project: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
 <!-- /SECTION -->
 
+<!-- SECTION:glossary when="glossary" -->
+## Shared language
+
+`GLOSSARY.md` defines this project's domain terms and what each means in the business, the data, the code and the UI. Use its words in specs, names, commits and replies; never a word a term lists under Avoid. `specweave glossary check` lists drift. A new term or a changed meaning goes into the glossary first (sw-glossary).
+<!-- /SECTION -->
+
 <!-- SECTION:hub when="hub" -->
 ## Project hub
 

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

@@ -1,100 +0,0 @@
----
-description: Widen options, then settle the user's critical decisions one question at a time, each with a recommended answer, before the spec. Use for "brainstorm", "what are our options", "grill me".
-argument-hint: "<topic> [--depth quick|standard|deep] [--decide off|critical|deep]"
-version: 3.1.0
----
-<!-- Generated from skills/sw-brainstorm/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
-
-# sw-brainstorm: options, then decisions
-
-Two parts, used alone or in order. **Options** picks which thing to build. **Decide**
-settles the calls only the user can make. sw-increment runs Decide as its own step.
-Neither replaces the spec.
-
-## Options
-
-| Depth | Options | Output |
-|---|---|---|
-| `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 |
-
-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.
-
-Contested decisions: run three lenses over the same options, advocate (strongest case),
-critic (how each fails in production), pragmatist (what ships this week). In parallel if
-your tool supports subagents, otherwise three labelled passes. Merge.
-
-## Decide
-
-Mode comes from `--decide`, else `planning.deepInterview` in `.specweave/config.json`:
-`off` skips, `critical` (also when unset) asks at most 5, `deep` has no cap. "Grill me",
-"interview me" or "think hard" means `deep` for this run; "just build it" means `off`.
-
-1. **Think first.** Read the code the change touches, project config and any draft.
-   Draft Problem, Scope and Approach yourself, then list every open decision across:
-   scope and non-goals; users and flows; data model; integrations, installs, accounts
-   and keys; failures and edge cases; security and privacy; performance and scale;
-   rollout and migration; how we will know it works.
-2. **Triage.** *Fact*: look it up (code, docs, a subagent if your tool has them), never
-   ask. *My call*: reversible or low impact, so pick a default. *Theirs*: hard to
-   reverse, costly, or taste. Only "theirs" reaches the user.
-3. **Ask, one question at a time.** Rank "theirs" by impact times uncertainty and ask
-   the top one, wait, then the next: an answer often settles or changes the rest.
-   `critical` stops after 5; a clear request asks nothing and says so. Each question
-   gets one clause on why it matters and 2 to 4 options, the first your recommendation
-   marked "(Recommended)" with its trade-off, plus a free answer. "Yes" accepts the
-   recommendation; "your call" accepts it for every question left.
-4. **Deep ("grill me").** Walk the decision tree: after each answer, ask what it
-   unlocks, until no "theirs" remains and the user agrees you share one picture. No cap,
-   still one question at a time with a recommendation. "Enough" stops it; whatever is
-   left gets a default. Optional extra for longer grilling sessions:
-   `npx vskill@latest install mattpocock/skills/grilling`.
-5. **Record** in spec.md under `## Decisions`, then apply each answer to Scope, ACs and
-   Approach, replacing any text it contradicts. Before spec.md exists, hold them and
-   write them when sw-increment creates it.
-
-```markdown
-## Decisions
-### Asked
-- D-01 Auth provider? → Clerk (user). Changes the data model and pricing.
-### Defaulted (change any before sw-do)
-- D-04 Rate-limit store → in-memory, Redis later (reversible).
-### Open
-- none
-```
-
-**Question cards.** If your tool has a structured question tool (Claude Code's
-ask-user-question tool, Codex `request_user_input`), ask through it so apps such as
-SpecWithCode show a card: header `D-01 Auth`, the recommended option first, custom
-answers allowed, multi-select only for "which of these services or installs". Without
-one, write `D-01 <question>` with numbered options and `Recommended: <option>`. Never
-ask for a secret in a question; use the app's secret request or name the env var.
-
-Rules: facts are your job, decisions are the user's. A default the user never saw is
-one they could not reject, so list every default. When the user has no shape for the
-idea yet, ask them to describe it before offering options; options steer.
-
-## Hand off
-
-`specweave create-increment "<the pick>"` (sw-increment), paste the rejected
-alternatives into Approach and the decisions into `## Decisions`. If the user already
-knows what they want, skip Options and say why. sw-auto will not start while
-`### Open` has entries.
-
-## Manual path (no CLI)
-
-Nothing here needs the CLI: read `.specweave/config.json` by hand and create the
-increment folder as sw-increment describes.
-
-Decide adapts ideas from obra/superpowers `brainstorming`, mattpocock/skills
-`grilling` and GitHub Spec Kit `/clarify` (all MIT); see `references/credits.md`.

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

@@ -1,70 +0,0 @@
----
-description: Run one SpecWeave increment with several agents in parallel - any tool or account, a worktree each, claims through the ledger, one close. Use for "team", "parallel agents", 3+ disjoint lanes.
-argument-hint: "[increment-id]"
-version: 3.0.0
----
-<!-- Generated from skills/sw-team/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
-
-# sw-team: several agents, one increment
-
-Agents can be Claude Code, Codex, Cursor, Grok, another account or a person. They
-coordinate only through committed files: spec.md (tasks), `ledger.jsonl` (claims and
-evidence) and handoffs. No message bus is needed; your tool's subagents or agent teams
-are an accelerator, never a requirement.
-
-## You are the lead
-
-You split, start, watch, merge and close. You do not implement. Fan out only with three
-or more disjoint lanes or 15+ tasks; otherwise use sw-do.
-
-## 1. Split
-
-1. `Files` is the ownership unit. Two tasks that touch one file cannot run in parallel:
-   merge them, or put `**Dependencies**: T-01` under the later one. Shared contracts
-   (types, schema, migrations) go in an early task the others depend on.
-2. Group tasks into lanes with disjoint `Files`: 2 to 5 lanes, one agent each.
-3. `specweave task list 0042` shows every task open. Commit spec.md.
-
-## 2. Start each agent
-
-One worktree and branch per agent:
-`git worktree add ../0042-api -b inc/0042-api`. Then give that agent (a subagent, a
-terminal in the worktree, another tool or account) this brief:
-
-```text
-You are agent "api" on increment 0042 in ../0042-api (branch inc/0042-api).
-Your tasks: T-01, T-02. Run the sw-do loop (`specweave task next 0042`, claim, ...)
-on your tasks only. Edit only their Files. Commit as "0042: ...". `task done --run`
-needs exit 0. When done or blocked: `specweave task release --all-mine`,
-`specweave note "api: <done | blocked: why>" 0042`, commit and push your branch.
-```
-
-Set `SPECWEAVE_AGENT=api` in that agent's environment so its claims are distinct.
-In Claude Code, `specweave team` opens agent-team panes for the same setup.
-
-## 3. Watch cheaply
-
-Poll `specweave task list 0042` instead of chatting. `blocked` rows are your queue:
-unblock (supply the secret, split the task, decide) and tell only that agent. A claim
-older than 2 hours with no progress is stale; a replacement agent claims it with
-`specweave task claim T-NN --force`. Agents' notes show in `specweave pickup --no-apply`.
-Lane agents do not use `specweave handoff`: it moves the one shared handoff pointer.
-
-## 4. Merge and close
-
-1. Merge the lane branches in dependency order. `ledger.jsonl` conflicts resolve by
-   keeping every line from both sides.
-2. `specweave verify 0042` on the merged tree; red becomes a fix task for one agent.
-3. sw-review on the merged diff, then `specweave complete 0042`. Only the lead closes.
-4. `git worktree remove ../0042-api` for each lane.
-
-## Manual path (no CLI)
-
-Same split and brief; each agent appends its own `claim`, `done` and `release` lines to
-`ledger.jsonl` as in sw-do's manual path, plus a `note` line as in sw-handoff's.
-
-## Anti-patterns
-
-- An agent editing outside its tasks' `Files`. Add a task instead.
-- One increment per agent: you lose the single ledger and the single verify.
-- The lead implementing "just this small piece", or closing while a claim is live.