<p align="center"><img src="https://spec-weave.com/img/logo.svg?v=079fbdd1" width="96" height="96" alt="SpecWeave logo" /></p>
<h1 align="center">SpecWeave</h1>
<p align="center">
<strong>Change agents. Keep the thread.</strong><br/>
Intent-first development: settle what you want before the code, hand the work between Claude, Codex, Grok and any other tool in two words, and close it with evidence.
</p>
<p align="center">
<a href="https://www.npmjs.com/package/specweave"><img src="https://img.shields.io/npm/v/specweave?color=brightgreen" alt="npm" /></a>
<img src="https://img.shields.io/badge/skills-7%20core%20%2B%204%20optional-8B5CF6" alt="7 core + 4 optional skills" />
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT" /></a>
<a href="https://discord.gg/UYg4BGJ65V"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
</p>
<br/>
## Install
```bash
npm install -g specweave # Node.js 20.12.0+
cd your-project
specweave init .
```
`init` writes `AGENTS.md` (read by Codex, Grok, Cursor, Gemini and Copilot), a two-line `CLAUDE.md` that imports it, and the skills for Claude Code and Codex. Nothing else runs in the background.
## SpecWithCode: the free workspace on top
[SpecWithCode](https://spec-weave.com/code/) is a desktop app built on SpecWeave. Describe the work once and a coordinator splits it across Claude Code, Codex, Grok or Cursor workers on your own machines, with the spec, evidence and handoff in git. It is free for every developer and team: no markup, no token resale, no seat fee to run agents on your own machines. Early access, for Apple silicon Macs, Windows 10 and 11, and Linux. [Download SpecWithCode](https://spec-weave.com/code/download/) ยท [Pricing](https://spec-weave.com/pricing)
## Keep your repositories where they are
An existing workspace can register nested, sibling or external checkouts without moving files or initializing a second planning root:
```bash
specweave --workspace ./planning get ../existing-api --dry-run --json
specweave --workspace ./planning get ../existing-api --json
```
`--workspace` selects planning authority; `SPECWEAVE_WORKSPACE` carries that context to hooks. Existing IDs and child plans stay intact. [Workspace adoption](https://spec-weave.com/docs/guides/workspace-adoption) explains previews, identity, permissions and migration limits.
## Out of tokens? Say "hand off"
```text
you (in Claude, account 1): hand off
you (in Codex, or account 2): pick up
```
That is the whole handoff. "Hand off" runs `specweave handoff`: it releases your task claims, records why you stopped, and pushes your branch plus a snapshot of your uncommitted edits. "Pick up" runs `specweave pickup` in any other tool, account, machine or cloud session (a Claude Code Projects thread, a Codex cloud task): it brings that work into the checkout and prints the next task with its acceptance criteria. Nothing to copy, no paths to paste.
Running out mid-task? `specweave auto-handoff on`, once per machine, makes it automatic: when a session reaches 90% of your plan's 5-hour or weekly limit, it hands off by itself and tells you to say "pick up" elsewhere. Claude Code reads the limit through its status line (your own status line keeps working) and Codex through a Stop hook. Under the threshold it costs no tokens. `--at 85` changes the threshold and `off` undoes every change.
`specweave report` writes an HTML timeline of who did what on an increment (tools, sessions, handoffs, pickups, test evidence), straight from the ledger.
## The loop
| # | Say or run | What happens |
|---|---|---|
| 1 | "pick up" ยท `specweave pickup` | The open increment, the next task with its acceptance criteria, claims held by others, branch state, notes and project memory, in one read. |
| 2 | `/sw:increment` ยท `specweave create-increment "<title>"` | One `spec.md`: Problem, Scope, Acceptance Criteria, Approach and the Tasks. |
| 3 | `/sw:do` ยท `specweave task claim T-01` โ `task done T-01 --run "<test>"` | Work a task. `done` refuses a failing test and stores the evidence in the ledger. |
| 4 | `specweave verify` ยท `/sw:review` ยท `specweave review` | Runs your test, lint and build; a fresh-context review cites `path:line`, and `specweave review` hands the diff to another model family. |
| 5 | `/sw:done` ยท `specweave complete <id>` | Closes on a green verify. Acceptance criteria are met when their tasks are done; nobody ticks boxes. |
| 6 | "hand off" ยท `specweave handoff` | Stop anywhere; the next tool picks up. |
An increment is one folder, `.specweave/increments/NNNN-slug/`, with one file you read (`spec.md`) and one the CLI appends to (`ledger.jsonl`). Increments from 2.x with a `tasks.md` keep working unchanged.
Set `"git": { "autoCommitIncrement": true }` in `.specweave/config.json` and `task claim|done|skip|block|release`, `create-increment` and `handoff` commit that increment's `spec.md`, `ledger.jsonl` and `metadata.json` as `NNNN: done T-02` and the like, through a pathspec, so the plan and its claims reach your other machines. Evidence and reports are never staged. `autoPushIncrement` also pushes, fast-forward only, when nothing but those commits is unpushed; `--no-commit` skips one command. See [configuration](https://spec-weave.com/docs/reference/configuration#git).
## Works the way Claude Code Projects work
| Claude Code Projects | SpecWeave |
|---|---|
| A thread: one session, one branch, one PR | One increment |
| The thread's checklist | The `## Tasks` of that increment's `spec.md`, state in `ledger.jsonl` |
| Project memory (`MEMORY.md` + one file per fact) | `.specweave/memory/`, same format, committed, so every tool and account sees it |
| Threads passing notes | `specweave note "<text>"` on another increment |
Project memory in claude.ai stays with one account. `.specweave/memory/` travels with the code, so Codex, Grok and a second Claude subscription start from the same decisions.
## Seven core skills, four optional
The CLI is the product and runs in any tool or in CI. The skills expose it to coding agents: the plugin answers to `/sw:<name>` in Claude Code and `$sw:<name>` in Codex, and project copies named `sw-<name>` live in `.claude/skills/` (for Projects threads, where plugins do not load) and `.agents/skills/` (Codex, Grok). [Run a skill](https://spec-weave.com/docs/reference/skills#run-a-skill) lists the syntax for each tool.
Core, in every project:
| Skill | Use it for |
|-------|------------|
| `increment` | Settle your decisions, then plan the work as one `spec.md`. |
| `grill-me` | An interview in rounds, each question with a recommended answer, recorded under `## Decisions` (after Matt Pocock's grilling). |
| `do` | Claim a task, implement it, close it with evidence; also unattended, or in parallel lanes. |
| `auto` | The unattended run of `do`, started by you, until the tasks run out. |
| `review` | Adversarial review by a fresh context or another model family; findings cite `path:line`. |
| `done` | Verify, review, `specweave complete`. |
| `handoff` | "Hand off" and "pick up". |
Optional, installed per project when enabled or detected (in Claude Code they are `/sw-glossary` and so on):
| Skill | Use it for | Detected by |
|-------|------------|-------------|
| `glossary` | `GLOSSARY.md`: each domain term across business, data, code and UI, with words to avoid. | a `GLOSSARY.md` or `GLOSSARY-MAP.md` |
| `sync` | GitHub, Jira and Azure DevOps, only when you run it. | a configured tracker |
| `project` | Shared goals, artifacts and briefs across tools. | `.specweave/project/hub.json` |
| `jev` | Closed-set decisions in about 250 ms via Jev. | `jev.enabled` |
```bash
specweave skills enable glossary # turn optional skills on (list, disable)
specweave glossary check --strict # avoided words and stale names; exit 1 for CI
specweave review # another model family reviews the diff; exit 0 ship, 3 fix first
```
`brainstorm` and `team` are retired: the Decide step is in `increment`, the full interview is `grill-me`, and parallel agents are `do`'s Parallel lanes. `specweave update` removes SpecWeave's own copies of retired skills.
## Upgrade to 3.0
```bash
npm i -g specweave@3
specweave update
```
`specweave update` rewrites `AGENTS.md` into the lean form, turns `CLAUDE.md` into an import of it, keeps your own sections, and backs up the old files under `.specweave/backups/`. Existing increments need no migration. The **[3.0.0 changelog](https://github.com/anton-abyzov/specweave/blob/develop/CHANGELOG.md#300---2026-09-25)** lists what changed and what was removed. To have sessions hand off by themselves near the usage limit, run `specweave auto-handoff on` once.
<br/>
## Built With SpecWeave
Examples from the maintainer's portfolio. These are usage examples, not controlled productivity measurements.
| App | Platform | What It Does |
|-----|----------|-------------|
| [**EasyChamp**](https://easychamp.com) | Web (GCP) | Enterprise sports league management. 20+ microservices, ML video analytics. 4 years in production. |
| [**SketchMate**](https://apps.apple.com/app/sketchmate-ai-draw-game/id6760250072) | App Store | AI drawing game โ multi-model evaluation judges player art semantically. |
| [**Lulla**](https://apps.apple.com/app/lulla-calm-baby-anywhere/id6756977992) | App Store | Baby sleep app with Apple Watch. ML cry classification (tired/hungry/pain). |
| [**Football 2026**](https://apps.apple.com/app/football-2026-travel/id6757258711) | App Store + Web | World Cup 2026 companion. AI travel planner, live tickets, team stats. |
| [**SkillUp Football**](https://apps.apple.com/app/skillup-football/id6756978002) | App Store | Coaches monetize training via Stripe. Instagram-like feed, scheduling. |
| [**BizZone**](https://apps.apple.com/app/business-zone/id6756091030) | App Store | Student & business events with AI-powered news generation. |
| [**EduFeed**](https://edufeed-jet.vercel.app/) | Web | NotebookLM meets Zoom. Upload videos, get quizzes, flashcards, live rooms. |
| [**JobWeave**](https://jobweave.ai) | Web | AI-powered job search. Smart matching, resume optimization. |
| [**SpecWeave**](https://github.com/anton-abyzov/specweave) | npm | The framework itself. 600+ increments, 538+ releases. |
| [**SpecWeave Umbrella**](https://github.com/anton-abyzov/specweave-umb) | GitHub | Multi-repo orchestration workspace for all repositories. |
| [**vskill**](https://github.com/anton-abyzov/vskill) | npm | Package manager for AI skills. Security scanning, 49 platforms. |
| [**verified-skill.com**](https://verified-skill.com) | Web | Skill marketplace & studio. 105K+ verified skills, eval system. |
[Browse increments on GitHub](https://github.com/anton-abyzov/specweave/tree/develop/.specweave/increments) โ full transparency.
<br/>
## How It Compares
| Capability | Cursor Rules | Copilot Instructions | Windsurf | Cline | Vibe Coding | **SpecWeave** |
|------------|:---:|:---:|:---:|:---:|:---:|:---:|
| Structured specs (Problem, ACs, Approach) | โ | โ | โ | โ | โ | **Yes** |
| One closure gate you can actually see (`verify.json`) | โ | โ | โ | โ | โ | **Yes** |
| Autonomous execution (hours, unattended) | โ | โ | โ | โ | โ | **Yes** |
| Multi-agent teams (parallel, contract-first) | โ | โ | โ | โ | โ | **Yes** |
| Append-only ledger (claims, evidence, no lost work) | โ | โ | โ | โ | โ | **Yes** |
| LSP code intelligence (198x faster) | โ | โ | โ | โ | โ | **Yes** |
| Cross-tool handoff (any vendor, any subscription) | โ | โ | โ | โ | โ | **Yes** |
Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow against these five acceptance criteria, prove the tests pass, review the diff, then close."
<br/>
## Key Features
**Intent first** โ Every feature starts by settling your decisions, then one `spec.md`: Problem, Scope, ACs, Approach, Decisions and Tasks.
**Evidence, not vibes** โ `specweave task done --run "<test>"` refuses a failing command and stores the exit code and output tail in the ledger.
**Multi-agent, any vendor** โ A worktree per agent, claims through `ledger.jsonl`, one closure. Coordination happens only through committed files.
```
โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ
โ Agent 1 (auth) โ Agent 2 (payments)โ Agent 3 (catalog)โ
โ T-01..T-04 โ T-05..T-08 โ T-09..T-12 โ
โ โโโโโโโโโโ 80% โ โโโโโโโโโโ 60% โ โโโโโโโโโโ 40% โ
โโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ
```
**LSP Code Intelligence** โ 198x faster than grep, 0 false positives. Semantic references, definitions, and types.
**7 core skills, 4 optional, one source** โ the same skills for Claude Code, Codex and Grok; see [Seven core skills, four optional](#seven-core-skills-four-optional).
**For developers and teams** โ Compliance audit trails. Brownfield analysis. Multi-repo workspaces.
**Dashboard** โ `specweave dashboard` shows intents, increments and evidence from local files, with no model calls.
**Optional tracker sync** โ `specweave sync push|pull|status|setup`. GitHub is first-class; Jira and Azure DevOps are opt-in. Nothing calls a tracker unless you run sync.
<br/>
## Skills Ecosystem
SpecWeave skills are published and verified at **[verified-skill.com](https://verified-skill.com)**. The [vskill](https://www.npmjs.com/package/vskill) package manager provides:
- **Security scanning** โ 52 attack patterns, SHA-256 pinning, blocklist API
- **49 agent platforms** โ one install deploys to Claude Code, Cursor, Copilot, Windsurf, and 45 more
- **Skill evals** โ unit tests, A/B comparisons, cross-model testing. Skills tested like programs.
- **Visual Skill Studio** โ `vskill eval serve` for benchmarks, comparisons, and history
```bash
npx vskill install remotion-best-practices # Install from registry
npx vskill eval run my-skill # Run eval suite
```
<br/>
## Documentation
**[spec-weave.com](https://spec-weave.com)** โ [SpecWeave 3.0](https://spec-weave.com/docs/guides/specweave-3) ยท [handoff](https://spec-weave.com/docs/guides/cross-tool-handoff) ยท [commands](https://spec-weave.com/docs/reference/commands) ยท [skills](https://spec-weave.com/docs/reference/skills) ยท [configuration](https://spec-weave.com/docs/reference/configuration)
## Contributing
Inside this repo dependency install scripts are disabled (`.npmrc`): run `npm ci`, then `npm run setup` (rebuilds the allowlisted native deps), and `npm run security:scan` before pushing โ see [SECURITY.md](https://github.com/anton-abyzov/specweave/blob/develop/SECURITY.md).
## Community
[Discord](https://discord.gg/UYg4BGJ65V) ยท [YouTube](https://www.youtube.com/@antonabyzov) ยท [GitHub Issues](https://github.com/anton-abyzov/specweave/issues)
## License
MIT โ [github.com/anton-abyzov/specweave](https://github.com/anton-abyzov/specweave)