specweave 1.0.592 → 2.0.0

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

@@ -1,59 +1,41 @@
 ---
-name: sw/handoff
-description: Write a portable, secret-scrubbed work handoff doc so you can continue this work in any AI tool. Use when saying "handoff", "running out of tokens", "switch to Codex/OpenCode/Gemini/Cursor", "continue elsewhere", or "continue on another machine".
-version: 1.0.0
+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]"
 ---
 
 # Work Handoff (Cross-Tool)
 
-No AI coding tool can read another's transcript — each locks its session in a proprietary `.jsonl`, SQLite DB, or encrypted `.pb`. The only portable thing is a **self-contained handoff document**. This skill assembles SpecWeave's durable on-disk state (active increment, task/AC progress, decisions, ambient rules) plus a full diff of your uncommitted edits into one document that any other tool can read to pick up exactly where you left off.
+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.
 
-This skill is the Claude Code surface of the cross-tool handoff feature. It is intentionally thin: the deterministic engine is the `specweave handoff` CLI subcommand. The same engine backs the PreCompact auto-handoff hook and the vskill `handoff` skill that carries this capability to other tools — so a handoff written here is continuable in Codex/OpenCode/Gemini/Cursor unchanged.
+## Steps
 
-## When to use
-
-- Low on subscription tokens — hand off and continue in another tool's free or separate quota.
-- Want a durable artifact in case the session dies at context exhaustion.
-- Moving to another machine — use `--inline` so the full doc travels inside the paste-prompt.
-
-## Workflow
-
-1. **Run the CLI**, forwarding any short context the agent can supply cheaply:
+1. **Release your claims** (rule 5): `specweave task release --all-mine`.
+2. **Write the doc**, adding only what the files cannot know:
 
    ```bash
-   specweave handoff [incrementId] [--reason ...] [--summary ...] [--next ...] [--gotcha ...] [--decision ...] [--inline]
+   specweave handoff [incrementId] [--reason "…"] [--summary "…"] [--next "…"] [--gotcha "…"] [--decision "…"] [--inline]
    ```
 
-   - No `incrementId` + exactly one active increment → it is used automatically.
-   - No active increment → a git + short-interview handoff is written (still portable).
-   - 2+ active increments + no `incrementId` → CLI errors listing candidate ids; re-run with the chosen id.
-
-2. **Surface the CLI output verbatim, in order** (do not reorder or paraphrase):
-   1. absolute doc path as plain text (first), 2. clickable markdown link, 3. `.diff` path,
-   4. fenced copy-paste resume prompt, 5. per-tool "find your source session" tips.
-
-3. **Respect the safety defaults**: the doc + diff are secret-scrubbed and gitignored by default; scrubbing is heuristic (review before sharing); nothing is committed.
-
-## Doc format (single source of truth)
+   - 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.
 
-The doc is rendered by `handoff-doc-format.ts` and has these sections, in this order, ending with the `Doc format v1` footer marker:
+## What is written
 
-1. **Where I Left Off** — reason, summary, active increment id + status, current/next task.
-2. **Done / Pending** — task counts + %, AC counts, AC/task drift from `acSyncEvents`.
-3. **Key Decisions & Gotchas** — decisions from `plan.md` + agent-supplied, plus ambient rules (test mode, coverage target, WIP limit) from `config.json`.
-4. **Files Touched** — `git status --porcelain` + `git diff --stat` inline; the full uncommitted diff is in the sibling `.diff` file; an UNCOMMITTED warning when the tree is dirty.
-5. **Exact Next Steps** — the explicit next step or the next pending task.
-6. **How To Resume** — per-tool resume matrix (Claude `claude -r <uuid>`, Codex `codex resume <uuid>` / `--last`, OpenCode `opencode -s <id>`, Gemini `/chat resume <tag>`, Antigravity Agent Manager, Aider `aider --restore-chat-history`) + the instruction to STOP and ask for a paste if the doc path is missing on the current machine.
-7. **Redaction** — per-pattern secret-scrub counts + the heuristic disclaimer.
+- `.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.
 
-## Doc placement
+## Resuming from a handoff
 
-- **SpecWeave**: `.specweave/increments/{id}/reports/handoff.md` + a stable copy at `.specweave/state/handoff-latest.md` (with `handoff-latest.diff`).
-- **Non-SpecWeave**: `.handoff/HANDOFF.md` + `.handoff/handoff.diff`, with a self-created `.handoff/.gitignore` containing `*`.
+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.
 
 ## Related
 
-- `sw:progress` — status without writing a handoff.
-- vskill `handoff` skill — the self-contained cross-tool version for Codex/OpenCode/Gemini/Cursor (no SpecWeave required).
-- `docs/guides/cross-tool-handoff.md` — the cross-tool matrix and full reference.
+- `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.