3.0 One-file specs, handoff and pickup

Switch tools.
Keep your place.

Software engineering discipline for AI coding, not vibe coding. SpecWeave keeps the spec, the tasks and the proof of done in your repo, so when one tool or subscription runs out, the next one picks up exactly where it stopped.

Start with your project See how it works ↓

npm install -g specweave

MIT licensed. Local first. No account needed.

Works with

Claude CodeClaude Code ProjectsCodexGrok BuildCursorGemini CLIGitHub CopilotOpenCode

AGENTS.md, skills and git ↗

01 / How it works

The work lives in your repo.
Tools come and go.

01 · Write it down once

One file says
what done means.

Each piece of work is a single spec.md: the problem, the scope, acceptance criteria, the approach and the tasks. No second file to keep in sync, and SpecWeave never writes state back into it.

.specweave/increments/0042-checkout-recovery/spec.md

# Keep checkout resumable
## Problem
A customer who leaves checkout loses their choices.
## Acceptance Criteria
- [ ] AC-01: Returning within 24h restores the cart
- [ ] AC-02: A paid order is never restored
## Tasks
### T-01 Save the checkout draft
- AC: AC-01 | Files: src/checkout/draft.ts | Test: npm test -- draft
### T-02 Restore it on return
- AC: AC-01, AC-02 | Files: src/checkout/restore.ts | Test: npm test -- restore

02 · Work one task at a time

Each task arrives
with its criteria.

The CLI gives the agent the next task with the text of the acceptance criteria it covers, its files and its test, so it reads a few lines instead of the whole spec again. A criterion is met when every task that covers it is done.

terminal · Claude Code

$ specweave task next
T-02 Restore it on return
  AC-01: Returning within 24h restores the cart
  AC-02: A paid order is never restored
  Files: src/checkout/restore.ts | Test: npm test -- restore

$ specweave task claim T-02
Claimed T-02 as claude@laptop

$ specweave task done T-02 --run "npm test -- restore"
Done T-02 (2/3)

03 · Hit a limit
Out of tokens?
Hand it off.
Tell your agent to hand off, or run specweave handoff. It releases your task claims, records where you stopped, and pushes your branch and a snapshot of your uncommitted edits to git. Nothing to copy, nothing to paste. With specweave auto-handoff on, Claude Code and Codex do it on their own at 90% of the limit.
terminal · Claude Code
```
$ specweave handoff
Released your claims on T-03 so the next agent can take them.
Pushed feature/checkout-recovery.
Pushed uncommitted edits to wip/feature/checkout-recovery.
```

04 · Continue anywhere

Another tool.
Same place.

In Codex, Grok, Cursor or a second Claude subscription, specweave pickup fetches the handoff, applies your edits, and prints everything the new session needs in one read: the increment, the next task and its criteria, notes and project memory.

terminal · Codex

$ specweave pickup
SpecWeave pickup · you are codex@laptop
Picked up the handoff from claude@laptop.
Increment 0042 "Keep checkout resumable" (active)
Next: T-03 Drop drafts after payment
  AC-02: A paid order is never restored
Notes:
- claude@laptop 5m ago: restore works; expiry not started
Memory (.specweave/memory/MEMORY.md):

.specweave/increments/0042-checkout-recovery/spec.md

# Keep checkout resumable
## Problem
A customer who leaves checkout loses their choices.
## Acceptance Criteria
- [ ] AC-01: Returning within 24h restores the cart
- [ ] AC-02: A paid order is never restored
## Tasks
### T-01 Save the checkout draft
- AC: AC-01 | Files: src/checkout/draft.ts | Test: npm test -- draft
### T-02 Restore it on return
- AC: AC-01, AC-02 | Files: src/checkout/restore.ts | Test: npm test -- restore

terminal · Claude Code

$ specweave task next
T-02 Restore it on return
  AC-01: Returning within 24h restores the cart
  AC-02: A paid order is never restored
  Files: src/checkout/restore.ts | Test: npm test -- restore

$ specweave task claim T-02
Claimed T-02 as claude@laptop

$ specweave task done T-02 --run "npm test -- restore"
Done T-02 (2/3)

terminal · Claude Code

$ specweave handoff
Released your claims on T-03 so the next agent can take them.
Pushed feature/checkout-recovery.
Pushed uncommitted edits to wip/feature/checkout-recovery.

terminal · Codex

$ specweave pickup
SpecWeave pickup · you are codex@laptop
Picked up the handoff from claude@laptop.
Increment 0042 "Keep checkout resumable" (active)
Next: T-03 Drop drafts after payment
  AC-02: A paid order is never restored
Notes:
- claude@laptop 5m ago: restore works; expiry not started
Memory (.specweave/memory/MEMORY.md):

02 / Parallel work

One thread.
One increment.

A Claude Code Projects thread works on one branch and opens one pull request. So does an increment. SpecWeave maps the two, and keeps everything that matters in git, where every tool and every account can read it.

How threads map to increments ↗

In a Claude Code ProjectIn SpecWeave 3.0

A projectAGENTS.md and the project goal

Project memory.specweave/memory/, committed with the code

A threadOne increment: one branch, one pull request

The thread checklistThe Tasks section of that spec.md

A note to another threadA note in the other increment's ledger

03 / Leaner by default

Less to read.
Every session.

Every token an agent spends rereading bookkeeping is a token it does not spend on your code. 3.0 removes the duplicates and hands the agent only what the current task needs.

~800tokens

One instruction file, AGENTS.mdWas about 3,300 across CLAUDE.md and AGENTS.md

1file

Per incrementWas spec.md, tasks.md and often plan.md

1read

To resume in a new toolWas 4 to 5 files the next tool had to find

11skills

One source for every toolWas 12 plugin skills and 6 portable ones that drifted

04 / See the work

What matters,
at a glance.

See what is moving, what is waiting and what is actually verified. Open an intent to find its spec and the work behind it.

Product workspace / Work

Illustrative workspace

4 intents1 in progress1 ready for reviewLocal files · no model calls

Backlog1

In progress1

Review1

Done1

Inside this intentKeep checkout resumable

The next agent gets the same acceptance criteria, completed task evidence, and next action.

Explore the work model

Example data above. Your dashboard reads your project. Open it with specweave dashboard.

05 / Fit your team

Your tracker.
On your terms.

Keep GitHub, Jira or Azure DevOps where your team plans. In 3.0, changing an increment's status no longer creates or closes issues. SpecWeave touches a tracker only when you push to it.

Explore optional integrations ↗

GitHubIssues and pull requests JiraOpt-in, pushed when you choose Azure DevOpsOpt-in, pushed when you choose

06 / In practice

Built with SpecWeave.

Products where we use the workflow to plan changes, track delivery and carry work between sessions and subscriptions.

Sports platforms

The companion project

Better skills. Less baggage.

Find focused expertise, inspect its source and evaluate whether it helps your workflow.

Explore Verified Skills ↗

Your next session can start here

Keep building.
Whatever you build with.

Get started ↗What's new in 3.0

Switch tools.
Keep your place.

The work lives in your repo.
Tools come and go.

One file says
what done means.

Each task arrives
with its criteria.

Out of tokens?
Hand it off.

Another tool.
Same place.

One thread.
One increment.

Less to read.
Every session.

What matters,
at a glance.

Your tracker.
On your terms.

Built with SpecWeave.

EasyChamp

JobWeave

Verified Skills

Better skills. Less baggage.

Keep building.
Whatever you build with.

Switch tools.Keep your place.

The work lives in your repo.Tools come and go.

One file sayswhat done means.

Each task arriveswith its criteria.

Out of tokens?Hand it off.

Another tool.Same place.

One thread.One increment.

Less to read.Every session.

What matters,at a glance.

Your tracker.On your terms.

Built with SpecWeave.

EasyChamp ↗

JobWeave ↗

Verified Skills ↗

Better skills. Less baggage.

Keep building.Whatever you build with.

Switch tools.
Keep your place.

The work lives in your repo.
Tools come and go.

One file says
what done means.

Each task arrives
with its criteria.

Out of tokens?
Hand it off.

Another tool.
Same place.

One thread.
One increment.

Less to read.
Every session.

What matters,
at a glance.

Your tracker.
On your terms.

EasyChamp

JobWeave

Verified Skills

Keep building.
Whatever you build with.