SpecWeave
The AI Development Framework That Can Run for Hours Autonomously
Ship features while you sleep. Mobile apps, microservices, multi-repo architectures — one framework handles it all.
/sw:auto runs for hours autonomously, and you get real-time visual labels showing exactly what's happening! See iteration counts, test status, and stop criteria as your features build themselves.
Learn about Label Visibility → :::
Engineering Metrics (DORA)
SpecWeave builds SpecWeave using SpecWeave. These are real metrics from our own development — 150+ increments and counting!
Live Dashboard | Detailed Report
What Makes SpecWeave Different
Every AI coding tool promises productivity. But after the chat ends:
- Your specs disappear into chat history
- Your architecture decisions are forgotten
- Your tests are never written
- Your GitHub/JIRA stays outdated
- New team members start from zero
SpecWeave is the only framework where AI decisions become permanent, searchable documentation.
See Auto Mode in Action
When /sw:auto runs autonomously, you now see real-time progress labels in your conversation:
╔══════════════════════════════════════════════════════════════╗
║ 🔄 AUTO SESSION CONTINUING ║
║ 🤖 Main Orchestrator ║
╠══════════════════════════════════════════════════════════════╣
║ Why: Work incomplete, continuing... ║
║ Iteration: 42/2500 ║
║ Increment: 0001-user-auth ║
║ Subagents used: 3 ║
╠══════════════════════════════════════════════════════════════╣
║ 🎯 WHEN WILL SESSION STOP? ║
║ ├─ Mode: STANDARD MODE ║
║ └─ Criteria: ALL tasks [x] completed + tests passing ║
║ ✅ Tests: 42 passed, 0 failed ║
╚══════════════════════════════════════════════════════════════╝
No more wondering "is it still working?" — you see exactly what's happening, iteration counts, test status, and stop criteria in real-time.
Learn about autonomous execution →
Permanent = survives chat sessions | Auto-sync = updates automatically after each task
Quick Start (30 Seconds)
npm install -g specweave
cd your-project
specweave init .
Then in Claude Code:
/sw:increment "Add dark mode toggle" # AI creates spec + plan + tasks
/sw:auto # 🚀 Ship while you sleep (hours of autonomous work)
Or step-by-step control:
/sw:do # Execute one task at a time
/sw:done 0001 # Quality-validated completion
Pro tip: Use /sw:next to flow through the entire cycle. One command auto-closes completed work and suggests what's next — review specs/tasks when needed, otherwise just keep clicking "next".
5-15 tasks, 1-3 user stories, completable in 1-3 days. With Claude Opus 4.5, development speed increases 2-3x (some report 5-10x!). Small increments + Opus 4.5 = almost no manual interaction. Just define requirements, run /sw:auto, and review what's done.
If commands/skills stop working after a Claude Code update:
specweave refresh-marketplace # Reinstall all plugins from GitHub
specweave update-instructions # Regenerate CLAUDE.md
Keep files small: Target 600-800 lines max. Files over 1K lines = crash risk. Split large files into modules before adding code.
Full Quickstart Guide → | Real Examples →
Compact Command — VSCode users can now use compact mode to keep Claude Code inside your editor window. Work continuously for hours in the same session without context switching. No more jumping between terminal and editor!
STOP Hooks with Subagents — Stop hooks now work with spawned subagents, enabling autonomous quality gates at every level. SpecWeave's /sw:auto uses this to validate tests and completion criteria automatically.
Learn more: Boris Cherny's autonomous coding demo — 259 PRs, 497 commits, 40,000 lines added in one month without opening an IDE.
The Workflow
What You Get
| Before | After SpecWeave |
|---|---|
| Specs in chat history | Permanent, searchable specs |
| Manual JIRA/GitHub updates | Auto-sync on every task |
| Tests? Maybe later... | Tests embedded in tasks (60%+ enforced) |
| Architecture in your head | ADRs captured automatically |
| "Ask John, he knows" | Living docs, always current |
| Onboarding: 2 weeks | Onboarding: 1 day |
Key Strengths
🚀 Autonomous Execution
Run /sw:auto and watch real-time labels show progress, test results, and stop criteria. Can run for hours autonomously with self-healing when tests fail.
📚 Permanent Knowledge
- Brownfield + Greenfield — Works with existing codebases, not just new projects
- Living Documentation — Specs auto-update after every task via hooks (critical for quality)
- 🧠 Self-Improving Skills — Claude learns from corrections with
/sw:reflect, applies patterns automatically in future sessions - 🪝 Powerful Hooks System — Customize behavior at every phase (start, prompt submit, tool calls, session end)
⚡ Performance & Scale
- 70%+ Token Reduction — Progressive loading, context optimizer, sub-agent isolation
- Multi-Project Mode — Manage multiple repos with shared specs and cross-project sync
- 15+ Specialized Agents — PM, Architect, Tech Lead, QA, Security, DevOps work autonomously
🔄 External Integration
- Auto-Sync — Push specs to GitHub/JIRA/ADO, read status back automatically
- 3-Gate Quality Validation — Tasks, tests (60%+), and docs verified before closing
⚡ Claude Code 2.1.x Optimizations
SpecWeave leverages the latest Claude Code features for maximum performance:
| Feature | Benefit |
|---|---|
context: fork | Heavy skills (PM, Architect) run in isolated sub-agents |
model: opus | Critical decisions use Opus for highest quality |
| Skill-scoped hooks | ~50% fewer hook invocations (fire only when skill active) |
| Agent-type init | Agent-specific startup context and messages |
Learn about Claude Code architecture →
The Three-File Foundation
Every feature generates three permanent files:
.specweave/increments/0001-dark-mode/
├── spec.md <- WHAT: User stories, acceptance criteria, requirements
├── plan.md <- HOW: Architecture, tech decisions, ADRs
└── tasks.md <- DO: Implementation tasks with embedded tests
spec.md (WHAT)
## User Stories
### US-001: Dark Mode Toggle
As a user, I want to toggle dark mode so that I can reduce eye strain at night.
**Acceptance Criteria:**
- [x] AC-US1-01: Toggle switch in settings persists preference
- [x] AC-US1-02: Theme applies to all components instantly
- [ ] AC-US1-03: System preference detected on first visit
tasks.md (DO)
### T-001: Implement Theme Provider
**User Story**: US-001
**Satisfies ACs**: AC-US1-01, AC-US1-02
**Status**: [x] completed
**Embedded Tests** (AC-US1-01):
- test_theme_toggle_persists_to_localstorage
- test_theme_applies_to_all_components
- test_toggle_updates_ui_instantly
Key Features
Autonomous Multi-Agent Orchestration
- PM Agent: User stories, acceptance criteria, market analysis
- Architect Agent: System design, ADRs, tech stack decisions
- Tech Lead Agent: Implementation, code review, best practices
- QA Lead Agent: Test strategy, E2E tests, coverage validation
- Security Agent: Threat modeling, OWASP, vulnerability assessment
- DevOps Agent: IaC, Kubernetes, CI/CD pipelines
Living Documentation & Hooks
Documentation updates after every task via the powerful hybrid hooks system:
- Strategic specs sync to
.specweave/docs/automatically - ADRs captured during architectural decisions
- Runbooks and SLOs generated from operations work
- No manual doc updates — hooks ensure docs are always current
SpecWeave uses a hybrid hook architecture:
- Global hooks (hooks.json): Cross-cutting concerns — SessionStart, UserPromptSubmit, PostToolUse, Stop
- Skill-scoped hooks (frontmatter): Command-specific logic — only fire when that skill is active
Hooks are critical to SpecWeave's quality system. They enable autonomous validation, test execution, and quality gates that make /sw:auto reliable for multi-hour sessions.
Self-Improving AI with Reflect
Correct once, never again. SpecWeave's Reflect system enables Claude to learn from your corrections:
- Pattern Learning: Claude remembers naming conventions, architectural decisions, and code patterns
- Automatic Application: Learned patterns apply in future sessions without reminders
- Centralized Memory: Knowledge stored in
.specweave/memory/*.mdfiles (project and global) - Signal Detection: High-confidence corrections and approvals automatically extracted
- Compounding Knowledge: AI gets smarter over time as it learns your preferences
Enable with /sw:reflect-on for automatic learning, or /sw:reflect to manually capture session learnings.
Quality Gates
Three gates before any increment closes:
- Tasks: All tasks marked complete
- Tests: 60%+ coverage minimum (configurable)
- Documentation: Living docs updated
Token Efficiency
70%+ context reduction through:
- Progressive plugin loading (load only what you need)
- Skills auto-activate based on keywords
- Context optimizer removes irrelevant specs
- Sub-agent parallelization isolates context
External Tool Integration
SpecWeave keeps your project management tools in sync automatically:
| Platform | Capabilities |
|---|---|
| GitHub Issues | Create, update, close, progress sync, checkbox tracking |
| JIRA | Epic/Story hierarchy, status sync, custom fields |
| Azure DevOps | Work items, area paths, status sync |
| Linear | Coming Q1 2026 |
Brownfield & Greenfield
New Projects: Start spec-driven from day one.
Existing Projects:
specweave init .
/sw:import-docs ~/exports/notion --source=notion
Import from Notion, Confluence, GitHub Wiki. AI classifies docs automatically and creates retroactive specifications.
Commands Reference
| Command | Purpose |
|---|---|
/sw:increment "feature" | Plan new increment (PM -> Architect -> Tasks) |
/sw:auto | 🚀 Ship while you sleep - hours of autonomous work |
/sw:do | Execute one task at a time |
/sw:done 0001 | Complete with quality gate validation |
/sw:progress | Show real-time status |
/sw:validate 0001 | Run quality checks |
/sw:sync-progress | Sync to GitHub/JIRA/ADO |
/sw:auto-status | Check autonomous session progress |
/sw:cancel-auto | Stop autonomous session |
/sw:tdd-cycle | Full red-green-refactor workflow |
Requirements
- Node.js 20.12.0+ (we recommend Node.js 22 LTS) — upgrade guide
- Claude Code (VSCode extension or CLI) with Claude Opus 4.5 (recommended) — released Nov 2026
- Git repository
Claude Code is the best AI tool for SpecWeave — native hooks support, task management, and multi-hour autonomous sessions. While SpecWeave works with other AI tools (see md.template instructions), Claude Code + SpecWeave provides the optimal experience with autonomous execution, stop hooks, and quality gates.
If you see SyntaxError: Unexpected token 'with', your Node.js is too old. Run node --version — you need 20.12.0 or higher. See upgrade instructions.
Community
- Documentation - Full guides and tutorials
- Discord - Get help, share tips
- YouTube - Video tutorials
- GitHub Issues - Bug reports and features
Learn Software Engineering with SpecWeave
New to software engineering? The Software Engineering Academy takes you from complete beginner to Fortune 500 enterprise developer:
| Path | Duration | For |
|---|---|---|
| SpecWeave Essentials | 90 min+ | Learn SpecWeave step by step |
| Fundamentals | Varies | Software engineering foundations |
16 SpecWeave lessons + 8 fundamentals modules — from first command to enterprise patterns.
Real-World Proof
SpecWeave isn't theory — it's production-tested across multiple use cases:
| Use Case | Duration | Result |
|---|---|---|
| Mobile App (React Native) | 2.5 hours | 3,200 LOC, 42 tests, full offline sync |
| Microservices (3 repos) | 1.2 hours | Payment webhooks, 67 tests, 3 PRs created |
| Brownfield Docs | 3 hours | 450k LOC analyzed, 127 pages generated |
| Large Refactor | 1.8 hours | 52 files migrated, 186 tests maintained |
Next Steps
🎯 Get Started (5 minutes)
Quick Start Guide → - Install, init, run your first increment
📖 Learn the Fundamentals
- Core Concepts - Understand specs, plans, and tasks
- Autonomous Execution - Ship while you sleep with
/sw:auto - External Sync - Keep GitHub/JIRA/ADO updated
🚀 Advanced Usage
- Multi-Project Setup - Coordinate across microservices
- Self-Improving Skills - Claude learns from your corrections
- Quality Gates - Ensure quality before shipping
🎓 Complete Curriculum
Software Engineering Academy - SpecWeave essentials + software engineering fundamentals
Ready to ship features while you sleep?
npm install -g specweave
cd your-project
specweave init .
# Then in Claude Code: /sw:increment "your feature"
Join the community: