SpecWeave
The AI Development Framework That Doesn't Lose Your Work
Engineering Metrics (DORA)
SpecWeave builds SpecWeave using SpecWeave. These are real metrics from our own development.
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.
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:
/specweave:increment "Add dark mode toggle" # AI creates spec + plan + tasks
/specweave:do # Autonomous implementation
/specweave:done 0001 # Quality-validated completion
Pro tip: Use /specweave: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 /specweave:do, and review what's done.
Keep files small: Target 600-800 lines max. Files over 1K lines = crash risk. Split large files into modules before adding code.
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
- Brownfield + Greenfield — Works with existing codebases, not just new projects
- 70%+ Token Reduction — Progressive loading, context optimizer, sub-agent isolation
- Multi-Project Mode — Manage multiple repos with shared specs and cross-project sync
- External Tool Sync — Push specs to GitHub/JIRA/ADO, read status back automatically
- 3-Gate Quality Validation — Tasks, tests (60%+), and docs verified before closing
- 15+ Specialized Agents — PM, Architect, Tech Lead, QA, Security, DevOps work autonomously
- Living Documentation — Specs auto-update after every task via hooks
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
Documentation updates after every task via hooks:
- Strategic specs sync to
.specweave/docs/ - ADRs captured automatically
- Runbooks and SLOs generated
- No manual doc updates ever
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 .
/specweave:import-docs ~/exports/notion --source=notion
Import from Notion, Confluence, GitHub Wiki. AI classifies docs automatically and creates retroactive specifications.
Commands Reference
| Command | Purpose |
|---|---|
/specweave:increment "feature" | Plan new increment (PM -> Architect -> Tasks) |
/specweave:do | Execute all tasks autonomously |
/specweave:done 0001 | Complete with quality gate validation |
/specweave:progress | Show real-time status |
/specweave:validate 0001 | Run quality checks |
/specweave:sync-progress | Sync to GitHub/JIRA/ADO |
/specweave:tdd-cycle | Full red-green-refactor workflow |
Requirements
- Node.js 20+
- Claude Code with Claude Opus 4.5 (recommended) — released Nov 2025
- Git repository
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 |
|---|---|---|
| Quick Start | 2 hours | Experienced devs wanting SpecWeave |
| Beginner | 4 weeks | New to software engineering |
| Full-Stack | 10 weeks | Building complete web apps |
| Enterprise | 16 weeks | Fortune 500-ready skills |
14 parts, 44 modules — from single-file scripts to microservices with CI/CD.
Next Steps
- Quickstart Guide - Get running in 30 seconds
- Core Concepts - Understand the fundamentals
- Key Features - Deep dive into capabilities
- Philosophy - Why spec-driven development
- Academy - Complete software engineering curriculum
Stop losing your AI work. Start building permanent knowledge.
npm install -g specweave