SpecWeave
The AI Development Framework That Can Run for Hours Autonomously.
Ship features while you sleep. /sw:auto executes tasks, runs tests, fixes failures, and syncs to GitHub/JIRA — completely hands-off. Mobile apps, microservices, multi-repo architectures — one framework handles it all.
# Requires Node.js 20.12.0+ (we recommend Node.js 22 LTS)
npm install -g specweave
New in v1.0.100: Auto mode now shows live labels in your terminal — see exactly what SpecWeave is doing:
[Planning],[Implementing],[Testing],[Fixing]. Hours of autonomous execution with full visibility.
The Problem With AI Coding Tools
Every AI coding tool promises productivity. But after the chat ends:
| What Happens | The Cost |
|---|---|
| Specs disappear into chat history | No traceability for audits |
| Architecture decisions forgotten | Repeated debates, inconsistent code |
| Tests? "We'll add them later" | Regressions, production bugs |
| JIRA/GitHub manually updated | Stale tickets, wrong priorities |
| Onboarding: "Ask John, he knows" | Knowledge silos, bus factor |
The real problem: AI generates code, but code without context is technical debt waiting to happen.
SpecWeave: AI That Works While You Sleep
/sw:increment "Add OAuth authentication" # Creates spec + plan + tasks
/sw:auto # Autonomous execution for HOURS
# ↑ Watch live: [Planning] → [Implementing] → [Testing] → [Fixing] → [Done]
What happens during /sw:auto:
[08:23:41] [Planning] Analyzing T-003: Implement refresh token rotation
[08:24:12] [Implementing] Writing src/auth/token-manager.ts (127 lines)
[08:25:33] [Testing] Running npm test -- token-manager.test.ts
[08:25:47] [Fixing] Test failed: Expected 401, got 403. Adjusting...
[08:26:15] [Testing] Re-running tests... PASSED
[08:26:18] [Syncing] Updating tasks.md, pushing to GitHub
[08:26:22] [Done] T-003 complete. Moving to T-004...
Or step-by-step control:
/sw:do # Execute one task at a time
/sw:done 0001 # Validates: tests pass, docs updated
Every feature creates three permanent files:
.specweave/increments/0001-oauth/
├── spec.md <- WHAT: User stories, acceptance criteria
├── plan.md <- HOW: Architecture decisions, tech choices
└── tasks.md <- DO: Implementation tasks with embedded tests
After 6 months: Search "OAuth" -> find exact decisions, who approved, why it was built that way.
Why SpecWeave vs BMAD, SpecKit, Cursor Rules?
| Capability | BMAD | SpecKit | Cursor Rules | SpecWeave |
|---|---|---|---|---|
| Maturity | Alpha (v6) | Stable | Built-in | Production (v1.0.100) |
| Autonomous Work | Manual steps required | One-shot generation | Per-request only | Hours unattended |
| Live Status | None | None | None | Terminal labels |
| Multi-Repo | Single repo | Single repo | Single repo | Coordinate N repos |
| Mobile Apps | No agents | No agents | No agents | React Native/Expo |
| External Sync | None | None | None | GitHub/JIRA/ADO |
| Brownfield | Limited | Greenfield only | Any | 10-year legacy? Fine. |
| Quality Gates | Not built-in | None | None | 3-gate validation |
| Living Docs | Manual | Snapshot | None | Auto-update |
| Self-Learning | None | None | None | Reflects on mistakes |
| Dogfooding | Unknown | Unknown | N/A | 140+ self-built features |
The math: SpecKit output = ONE SpecWeave increment. SpecWeave = N increments + lifecycle + sync + hooks + hours of autonomous execution.
Proof: Built With SpecWeave
This framework builds itself. Every feature, bug fix, and release — all spec-driven.
| Metric | Value |
|---|---|
| Features shipped | 140+ with full specs |
| Living docs | Auto-update on every task |
| DORA metrics | Live tracking |
| Test coverage | 60%+ enforced |
Quick Start
Prerequisites
Node.js 20.12.0 or higher is required (we recommend Node.js 22 LTS).
# Check your version
node --version
# If below v20.12.0, upgrade using nvm:
nvm install 22 && nvm use 22 && nvm alias default 22
Getting
SyntaxError: Unexpected token 'with'? Your Node.js is too old. See upgrade instructions.
Installation
npm install -g specweave
cd your-project
specweave init .
Then in Claude Code:
/sw:increment "Add dark mode" # AI creates spec + plan + tasks
/sw:auto # Ship while you sleep (hours of autonomous work)
Or step-by-step:
/sw:do # Execute tasks one at a time
/sw:done 0001 # Quality-validated completion
Troubleshooting - if commands/skills stop working:
specweave refresh-marketplace # Reinstall all plugins from GitHub
specweave update-instructions # Regenerate CLAUDE.md
Key Features
Autonomous Execution (v2.9)
Run for hours without intervention. See exactly what's happening:
/sw:auto # Start autonomous mode
/sw:auto-status # Check progress anytime
/sw:cancel-auto # Emergency stop (rarely needed)
What you see in terminal:
[Planning]- Analyzing task requirements[Implementing]- Writing code[Testing]- Running test suites[Fixing]- Auto-correcting failures[Syncing]- Updating docs and external tools[Done]- Task complete, moving to next
External Tool Integration
| Platform | Capabilities |
|---|---|
| GitHub Issues | Create, update, close, progress sync |
| JIRA | Epic/Story hierarchy, bidirectional sync |
| Azure DevOps | Work items, area paths, status sync |
/sw:sync-progress # Push updates to all connected tools
Works With ANY AI Tool
SpecWeave is structure, not AI magic. spec.md and tasks.md are just markdown.
- Sarah uses Claude. Mike uses GPT-4. Alex uses Copilot.
- Everyone works on the same specs, same tasks, same acceptance criteria.
- Claude Code gets the best experience (slash commands, hooks, skills). But any AI can participate.
Living Documentation
Documentation updates on lifecycle events — not on every edit, but when it matters:
| Event | What Updates |
|---|---|
increment.done | Marked complete, living docs synced |
user-story.completed | Status refreshed, external tools updated |
increment.reopened | Restored from archive |
Quality Gates
Three gates before any increment closes:
- Tasks: All marked complete
- Tests: 60%+ coverage (configurable)
- Documentation: Living docs updated
Token Efficiency
70%+ context reduction:
- Progressive plugin loading
- Skills auto-activate on keywords
- Context optimizer removes irrelevant specs
Commands
| Command | Purpose |
|---|---|
/sw:increment "feature" | Create spec + plan + tasks |
/sw:auto | Ship while you sleep - hours of autonomous work |
/sw:auto-status | Check autonomous session progress |
/sw:do | Execute one task at a time |
/sw:done 0001 | Close with quality validation |
/sw:sync-progress | Push to GitHub/JIRA/ADO |
/sw:cancel-auto | Stop autonomous session |
Works On Everything
| Scenario | What You Do |
|---|---|
| 10-year legacy codebase | specweave init . -> brownfield analysis detects doc gaps |
| Weekend MVP | specweave init . -> /sw:increment "Build auth" |
| 50-team enterprise | specweave init . -> /sw:enable-multiproject -> maps to JIRA/ADO |
Requirements
- Node.js 20.12.0+ (we recommend Node.js 22 LTS) — upgrade guide
- Any AI coding tool: Claude Code, Cursor, Windsurf, Cline, Aider, etc.
- Git repository
Why Node.js 20.12.0+? SpecWeave uses modern JavaScript features (ES2022 Import Attributes) that require Node.js 20.12.0 or higher. If you see
SyntaxError: Unexpected token 'with', you need to upgrade Node.js.
Community
Documentation | Discord | YouTube | GitHub Issues