What is SpecWeave?
SpecWeave is a small command-line tool and a set of skills that keep AI-assisted software work to engineering standards, and let you switch coding tools without losing your place.
The method is intent-first development, an intent-first take on spec-driven development: the agent settles what you want and how a machine will check it before it writes code. It asks only the decisions that are yours, each with a recommended answer, and records them in the spec.
You describe a change. SpecWeave keeps three things for it in your repository:
- What done means: a short
spec.mdwith the problem, scope, acceptance criteria, approach and tasks. - What actually happened: an append-only
ledger.jsonlrecording who claimed each task, which commit finished it and what test output proved it. - Where you stopped: a handoff with the next step, open questions and your work in progress, pushed where a cloud session can see it.
Because all of it is plain files in git, it works with Claude Code (including Projects threads), Codex, Grok Build, Cursor, GitHub Copilot, Gemini CLI and OpenCode, and across two subscriptions of the same tool.
SpecWithCode is the workspace built on this record (how it works). A SpecWithCode project has a coordinator and workers, each on the coding agent and model you choose, running on your own machines. The CLI works on its own; SpecWithCode is a free app in early access.
The problem it solves
AI coding tools are good at writing code and poor at remembering why. Each one keeps its conversation in its own format and location, and nothing hands it over for you. When you hit a usage limit halfway through a feature, the goal, the decisions and your uncommitted edits sit in that transcript. Another tool on the same machine could dig through those files, but they are long and tool-specific, and on another machine, another account or a cloud session they are not there at all. Claude Code project memory stays with one account, so even a second Claude subscription starts cold.
Without a written definition of done, "it's finished" is whatever the agent says. SpecWeave makes the definition explicit before code is written, and closes the work only when the recorded evidence covers every acceptance criterion.
What you do with it
| You want to | You say, or run |
|---|---|
| Plan a change | "Let's add a resumable checkout", or specweave create-increment "Resumable checkout" |
| Work through it | "Do the next task", or specweave task next and specweave task claim T-01 |
| Prove a task is done | specweave task done T-01 --run "npm test" |
| Stop and continue elsewhere | "Hand off", or specweave handoff |
| Continue in another tool | "Pick up where I left off", or specweave pickup |
| Close with evidence | specweave verify then specweave complete 0042 |
Every step is available as a skill in tools that support skills and as a plain command everywhere else. How it works shows the files and the flow in more detail.
What it is not
- Not a replacement for your coding agent. Your agent writes the code. SpecWeave keeps the record.
- Not a tracker. GitHub Issues, Jira and Azure DevOps stay where your team plans. SpecWeave can push progress to them when you ask, and never touches them on its own.
- Not required for every change. A one-line fix needs no increment. Use one when the work needs acceptance criteria, will span sessions, or may change hands.
Next steps
- Quick start: install, initialize and run the loop once.
- What changed in 3.0: one-file increments, one instruction file, handoff and pickup.
- Handoff and pickup: moving work between tools and accounts.