README
SpecWeave
AI-assisted development, under control.
One folder per unit of work. Six commands. An append-only ledger any tool can write to.
Install
npm install -g specweave # Node.js 20.12.0+
cd your-project
specweave init .
The loop
| # | Command | Claude Code skill | What it does |
|---|---|---|---|
| 1 | specweave create-increment "<title>" | /sw:increment | spec.md with Problem, Scope, numbered ACs and an Approach. Approved before any code. |
| 2 | specweave task next → claim → done --run "<test>" | /sw:do | Work the tasks. done refuses a failing test command. |
| 3 | specweave verify | — | Runs your test/lint/build; writes reports/verify.json. |
| 4 | — | /sw:review | Fresh-context adversarial review; every finding cites path:line. |
| 5 | specweave complete <id> | /sw:done | Closes. Blocks only on a green verify.json (or --reason). |
| 6 | specweave handoff | /sw:handoff | A portable one-page doc so any other tool can pick the work up. |
Everything lives in .specweave/increments/NNNN-slug/: spec.md, tasks.md (+ the rendered SW:BOARD), ledger.jsonl, handoff.md, reports/.
The ten skills
The CLI is the product and it runs in any AI tool or in CI. These ten skills are the Claude Code wrappers over it — nothing else ships in the plugin, so nothing goes stale.
| Skill | Use it for |
|---|---|
sw:brainstorm | Framed alternatives, ending in a pick. |
sw:increment | Plan the work: spec.md with ACs, plus tasks.md. |
sw:do | Claim a task, implement it, close it with evidence. |
sw:auto | The same loop, unattended, until the tasks run out. |
sw:team | A worktree per agent, claims arbitrated by the ledger. |
sw:review | Fresh-context adversarial pass; findings cite path:line. |
sw:qa | Risk-scored assessment, blockers, verdict. |
sw:done | Verify, review check, specweave complete. |
sw:sync | GitHub, Jira and Azure DevOps: push, pull, status, setup. |
sw:handoff | A one-page, secret-scrubbed continuation doc. |
Five longer procedures (tdd-cycle, e2e, debug, diagrams, release-expert) live in skills-optional/ and install on demand with vskill.
Upgrade to 2.0
npm i -g specweave@2
specweave update
specweave update is idempotent: it rewrites the managed sections of CLAUDE.md/AGENTS.md while preserving your own, migrates config.json in one pass, writes the .gitignore/.gitattributes entries 2.0 needs, and keeps backups under .specweave/backups/. Then run specweave doctor.
2.0 removed a lot on purpose — the three-report closure pipeline, auto-generated living docs, 34 never-invoked skills, the queued sync mode. See What was removed, and why.
There is no alias routing: a 1.x slug simply has no skill behind it. The old-to-new map —
every removed skill, the skill or CLI command that replaced it, and the ones that moved to
skills-optional/ — is removedIn2_0 in
plugins/specweave/marketplace.json.
Built With SpecWeave
12 production projects shipped in 3 months. 5 in the App Store.
| App | Platform | What It Does |
|---|---|---|
| EasyChamp | Web (GCP) | Enterprise sports league management. 20+ microservices, ML video analytics. 4 years in production. |
| SketchMate | App Store | AI drawing game — multi-model evaluation judges player art semantically. |
| Lulla | App Store | Baby sleep app with Apple Watch. ML cry classification (tired/hungry/pain). |
| Football 2026 | App Store + Web | World Cup 2026 companion. AI travel planner, live tickets, team stats. |
| SkillUp Football | App Store | Coaches monetize training via Stripe. Instagram-like feed, scheduling. |
| BizZone | App Store | Student & business events with AI-powered news generation. |
| EduFeed | Web | NotebookLM meets Zoom. Upload videos, get quizzes, flashcards, live rooms. |
| JobWeave | Web | AI-powered job search. Smart matching, resume optimization. |
| SpecWeave | npm | The framework itself. 600+ increments, 538+ releases. |
| SpecWeave Umbrella | GitHub | Multi-repo orchestration workspace for all repositories. |
| vskill | npm | Package manager for AI skills. Security scanning, 49 platforms. |
| verified-skill.com | Web | Skill marketplace & studio. 105K+ verified skills, eval system. |
Browse increments on GitHub — full transparency.
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 |
| External sync (GitHub / JIRA / ADO) | — | — | — | — | — | 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."
Key Features
Spec-First Planning — Every feature starts as spec.md (Problem, Scope, ACs, Approach) plus tasks.md. Configuration, not prompting.
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.
10 skills, not 51 — see The ten skills above. Plus five standalone skills for non-Claude tools.
External Sync — specweave sync push|pull|status|setup. GitHub is first-class; Jira and Azure DevOps are opt-in.
Enterprise Ready — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.
Dashboard — Built-in web dashboard for increment progress, analytics, cost tracking, and multi-project monitoring.
Skills Ecosystem
SpecWeave skills are published and verified at verified-skill.com. The 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 servefor benchmarks, comparisons, and history
npx vskill install remotion-best-practices # Install from registry
npx vskill eval run my-skill # Run eval suite
Documentation
spec-weave.com — SpecWeave 2.0 · commands · skills · 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.
Community
Discord · YouTube · GitHub Issues