specweave 2.2.3 → 3.0.0

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`.

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

@@ -1,41 +1,75 @@
 ---
-disable-model-invocation: true
-description: Write a portable, secret-scrubbed handoff doc so this work can continue in any AI tool or on any machine. Use when saying "handoff", "running out of tokens", or "continue elsewhere".
-version: 2.0.0
-argument-hint: "[incrementId] [--reason ...] [--summary ...] [--next ...] [--gotcha ...] [--decision ...] [--inline]"
+description: Hand work to another tool, account or machine and pick it up there, in two words. Use when the user says "hand off", "out of tokens", "switching accounts", "pick up" or "continue".
+argument-hint: "[--reason \"...\"] [--next \"...\"]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-handoff/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Work Handoff (Cross-Tool)
+# sw-handoff: "hand off" here, "pick up" there
 
-No tool can read another's transcript. The portable thing is a ≤1-page
-`handoff.md` next to the increment, built from durable state (ledger fold,
-spec ACs, decisions, git diff) — any agent from any vendor resumes from it.
+The user should never have to copy a prompt. Two words each way.
 
-## Steps
+## Hand off
 
-1. **Release your claims** (rule 5): `specweave task release --all-mine`.
-2. **Write the doc**, adding only what the files cannot know:
+When the user says "hand off", "handoff", "I'm out of tokens", "switching to Codex" or
+"switching accounts", run:
 
-   ```bash
-   specweave handoff [incrementId] [--reason "…"] [--summary "…"] [--next "…"] [--gotcha "…"] [--decision "…"] [--inline]
-   ```
+```bash
+specweave handoff --reason "<their words>"
+```
 
-   - id optional when exactly one increment is `active`; 2+ active → the CLI lists candidates, re-run with one.
-   - `--inline` embeds the full body in the paste prompt (moving machines).
-   - No SpecWeave workspace / no active increment → a git + notes handoff still gets written.
-3. **Surface the CLI output verbatim**: doc path first, then the `.diff` path, then the fenced paste prompt.
+It releases your task claims, records the handoff in the ledger, writes `handoff.md`
+next to the increment, pushes the branch, and pushes a snapshot of your uncommitted
+edits to the `specweave-handoff` branch (and `wip/<branch>`). Your working tree,
+index and branch are untouched. Relay its two or three lines as they are, then tell
+the user: say "pick up" in the other tool.
 
-## What is written
+Add `--next "<exact next step>"`, `--gotcha "..."` or `--decision "..."` only for what
+the files cannot tell the next agent. No Git remote and another machine:
+`--inline` prints a prompt to paste instead. `--no-push` keeps it local.
 
-- `.specweave/increments/<id>/handoff.md` (+ `handoff.diff` with the full uncommitted diff) — the single location; `.specweave/state/handoff-latest.txt` points at it.
-- Sections: **Where I left off · Done / Pending (ledger table) · Decisions · Files touched · Next steps · Resume**, ending with the `Doc format v2` marker. Header line = agent id, branch @ sha, uncommitted count, redaction count, active claims. The doc format is specified once, in the standalone `sw-handoff` skill (`skills/sw-handoff/SKILL.md`) — read it there when writing or checking a handoff by hand.
-- Secrets are scrubbed heuristically — review before sharing. Nothing is committed for you; commit `handoff.md` if the next agent works from another clone.
+To hand off by itself, the user runs `specweave auto-handoff on` once (Claude Code and
+Codex, on their own machine; not in cloud sessions). A session then hands off at 90% of
+the 5-hour or weekly limit (`--at <percent>` to change it); `auto-handoff status` shows
+the current usage. When its Stop hook asks you to hand off, run the handoff it names.
 
-## Resuming from a handoff
+Claude Code also warns the model itself near and at the 5-hour limit, with a note that
+starts "[Usage limit approaching" or "[Usage limit reached". Treat that note as the
+handoff moment: finish the current edit, run `specweave handoff --reason "usage limit"`
+(one command; it needs no summary from you) and stop.
 
-Read `handoff.md` → `specweave task next <id>` → claim → go. If the path does not exist on this machine, ask for the doc to be pasted; do not improvise context.
+## Pick up
 
-## Related
+When the user says "pick up", "pick up here", "continue" or "continue from the other
+account", run `specweave pickup`. It fetches the last handoff, moves this branch
+forward to it and applies the handed-off edits (only on a clean tree), then prints the
+increment, the next task with its acceptance criteria and any notes. If it reports
+uncommitted changes or a diverged branch, do what it says; never discard the user's
+edits. Then continue with sw-do.
 
-- `specweave status` — where things stand, without writing a handoff. PreCompact hook writes the same doc automatically.
-- `skills/sw-handoff/SKILL.md` — the standalone, CLI-less version (vskill: `npx vskill install anton-abyzov/specweave/sw-handoff`) and the single source of truth for the document format.
+## Notes and the record
+
+- `specweave note "<text>"` leaves a message for whoever works on the increment next.
+- `specweave report` writes an HTML timeline of who did what: tools, sessions,
+  handoffs, pickups, evidence.
+
+## Manual path (no CLI)
+
+1. Release each task you hold by appending a line to its `ledger.jsonl`:
+   `{"t":"T-03","e":"release","by":"codex@mbp","at":"2026-09-02T12:00:00Z"}`, and a note
+   for the next agent: `{"t":"*","e":"note","by":"codex@mbp","at":"2026-09-02T12:00:00Z","note":"T-03 half done, see handoff.md"}`.
+   In PowerShell append with `[IO.File]::AppendAllText` and UTF-8 without a BOM, never `>>`.
+2. Write `.specweave/increments/<id>/handoff.md` (UTF-8, no BOM) with these sections in
+   this order: `## Where I left off`, `## Done / Pending`, `## Decisions`,
+   `## Files touched`, `## Next steps`, `## Resume`, and a last line
+   `<!-- Doc format v2 -->`. Scrub tokens, keys and passwords from it first.
+3. Commit the work in progress and push the branch:
+
+```bash
+git add -A
+git commit -m "0042: work in progress (handoff)"
+git push -u origin HEAD
+```
+
+To pick up by hand: `git fetch origin`, check out that branch, read its `handoff.md`,
+and continue at the first task in spec.md with no `done` line in the ledger.