Skip to main content

SpecWeave 3.0: switch tools, keep your place

· 3 min read
Anton Abyzov
Anton Abyzov
Creator of SpecWeave

You are halfway through a feature and the usage limit hits. The goal, the decisions and your uncommitted edits are sitting in a session no other tool can read. SpecWeave 3.0 is built around that moment.

Hand off in one command, pick up in one read​

specweave handoff      # in the tool you are leaving
specweave pickup       # in the next one

handoff releases your task claims, records why you stopped and what comes next, and pushes your branch and a snapshot of your uncommitted edits, so a Claude Code Projects thread, a Codex cloud task, another machine or another account can see them. pickup fetches that handoff, applies your edits and prints the increment, the next task with the text of its acceptance criteria, the branch state, the last handoff and any notes, all in one read. In a tool with SpecWeave's skills you can just say "hand off" and "pick up".

It works between Claude Code, Codex, Grok Build, Cursor, Copilot, Gemini CLI and OpenCode, and between two subscriptions of the same tool, because everything is in git.

Less for the agent to read​

  • An increment is one file. spec.md holds the problem, scope, acceptance criteria, approach and tasks. tasks.md is gone for new increments, and state lives only in an append-only ledger.
  • One instruction file. AGENTS.md is about 760 tokens and every tool reads it. CLAUDE.md imports it instead of repeating it; in 2.x the two together were about 3,300 tokens.
  • One task at a time. task next prints the task with its criteria, so the agent stops rereading the whole spec for every task. A criterion is met when the tasks covering it are done, so nobody ticks boxes by hand.

Claude Code Projects​

A Projects thread works on one branch and opens one pull request, which is exactly an increment. So 3.0 maps them one to one: the thread's checklist is the increment's task list, threads leave each other notes in the ledger, and a committed .specweave/memory/ folder in the same format as project memory carries decisions to another account or another tool.

Nothing behind your back​

Starting, pausing or resuming an increment no longer calls GitHub, Jira or Azure DevOps, and issues are only created by specweave sync push. A third of the code, which nothing reached, is gone, along with the commands nobody called.

Upgrade​

npm install -g specweave@latest
specweave update

Existing increments keep working. What changed in 3.0 has the full list, and Handoff and pickup the details.