Skip to main content

Getting Started with SpecWeave

From zero to shipping in 5 minutes.

SpecWeave is the AI development framework that doesn't lose your work. Every AI decision becomes permanent, searchable documentation.

What You Can Build​

SpecWeave has been used to ship production applications in weeks, not months:

ApplicationTypeResult
Mobile AppsReact Native + ExpoiOS & Android builds with offline sync
Web PlatformsNext.js + SupabaseFull-stack with auth, payments, real-time
APIsNode.js + PostgreSQLOpenAPI specs, Postman collections auto-generated
InfrastructureTerraform + K8sIaC with GitOps, monitoring dashboards
ML SystemsPython + MLOpsTraining pipelines, model deployment
MicroservicesMulti-repo20+ services with cross-repo coordination

Real-World Examples​

"5 production apps in ONE MONTH — not 10x faster, 100x faster."

AppDescriptionTech Stack
SkillUpFootball coaching platform with Stripe monetizationReact Native, Cloudflare Workers
EduFeedAI learning platform (NotebookLM-style)Next.js, Supabase, LLM integration
WC26World Cup 2026 companion with AI travel plannerMobile + Web, real-time data
LullaBaby cry classifier with Apple WatchSwift, Core ML, Cloudflare R2
EasyChampSports league platform with 20+ microservicesGCP, ArgoCD GitOps, ML video analytics

Quick Start (5 Minutes)​

1. Install SpecWeave​

npm install -g specweave

Requirements: Node.js 20.12.0+ (we recommend Node.js 22 LTS)

2. Initialize Your Project​

cd your-project
specweave init .

Answer the prompts — SpecWeave auto-detects your tech stack and configures accordingly.

3. Create Your First Feature​

In Claude Code (or your AI tool):

/sw:increment "Add user authentication with OAuth"

SpecWeave creates three permanent files:

  • spec.md — WHAT (user stories, acceptance criteria)
  • plan.md — HOW (architecture, ADRs)
  • tasks.md — DO (implementation tasks with tests)

4. Build It​

Option A: Ship While You Sleep

/sw:auto

Autonomous execution for hours. Real-time progress labels show iteration count, test status, stop criteria.

Option B: Step-by-Step Control

/sw:do          # Execute one task
/sw:progress    # Check status
/sw:done 0001   # Complete with validation

5. Quality Gates​

Before closing, SpecWeave validates:

  • All tasks complete
  • 60%+ test coverage (configurable)
  • Living docs updated

What Makes SpecWeave Different​

BeforeAfter SpecWeave
Specs in chat historyPermanent, searchable specs
Manual JIRA/GitHub updatesAuto-sync on every task
Tests? Maybe later...Tests embedded in tasks (60%+ enforced)
Architecture in your headADRs captured automatically
"Ask John, he knows"Living docs, always current
Onboarding: 2 weeksOnboarding: 1 day

Platform Support​

SpecWeave works everywhere:

PlatformSupport
macOSFull support (primary development)
LinuxFull support
WindowsFull support (WSL recommended for best experience)

AI Tool Compatibility​

ToolIntegration Level
Claude CodeNative (hooks, skills, agents)
CursorVia CLAUDE.md instructions
WindsurfVia CLAUDE.md instructions
GitHub CopilotVia CLAUDE.md instructions
Any AI IDEVia specweave generate --template=md

Best Experience: Claude Code provides the deepest integration with native hooks, skills, and autonomous execution. Other tools work via instruction files.

Choose Your Path​

Your GoalNext Step
Quick hands-onYour First Increment
Understand conceptsWhat is an Increment?
Full curriculumSpecWeave Essentials
Existing codebaseBrownfield Projects
External toolsGitHub/JIRA/ADO Integration

Troubleshooting​

Node.js Version Error​

If you see SyntaxError: Unexpected token 'with':

node --version  # Must be 20.12.0+

Upgrade instructions

Commands Not Working​

After Claude Code updates:

specweave update      # Full update: CLI + instructions + config + plugins

Then restart Claude Code.

Community​

Ready? → Create Your First Increment