Commands Overview

SpecWeave provides slash commands for every stage of your development workflow. This page covers the main workflow commands you'll use daily.

No Shortcuts

All commands MUST use the /specweave:* namespace prefix. Shortcuts like /inc, /do, /pause, /resume (without the namespace) conflict with Claude Code's native commands and other repositories.

The Core Workflow

Pro tip: Use /specweave:next instead of /specweave:done — it auto-closes and suggests next work!

1. Planning Commands

`/specweave:increment` - Create New Increment

Most frequently used command - Start every new feature here.

/specweave:increment "User authentication with JWT"
/specweave:increment "Payment processing with Stripe"
/specweave:increment "Real-time notifications"

What it does:

🔍 Detects tech stack automatically
📋 PM-led planning (market research, spec.md, plan)
✅ Auto-generates tasks.md from plan
🧪 Creates test strategy
👥 Strategic agent review (Architect, Security, QA, Tech Lead)

See: ADR (Architecture Decision Records) for design decisions made during planning.

Reference: Command Decision Tree for workflow guidance.

2. Implementation Commands

`/specweave:do` - Execute Tasks

Smart auto-resume - Continue from where you left off.

/specweave:do           # Auto-finds active increment
/specweave:do 0007      # Specific increment

What it does:

🎯 Resumes from last incomplete task
🔊 Plays sound after each task (via hooks)
📝 Updates docs inline (CLAUDE.md, README.md, CHANGELOG)
🔗 Syncs to GitHub (if plugin enabled)
🧪 Runs tests continuously

Key Features:

Cost optimization: Uses Haiku for simple tasks (3x faster, 20x cheaper)
Automatic hooks: Runs after EVERY task completion
Living docs sync: Updates .specweave/docs/ after all tasks complete

3. Quality Assurance Commands

`/specweave:validate` - Rule-Based Validation

120+ checks - Fast, free validation.

/specweave:validate 0007
/specweave:validate 0007 --quality        # Include AI assessment
/specweave:validate 0007 --export         # Export suggestions to tasks.md

What it validates:

✅ Consistency (spec → plan → tasks)
✅ Completeness (all required sections)
✅ Quality (testable criteria, actionable tasks)
✅ Traceability (AC-IDs, ADR references)

`/specweave:qa` - Quality Assessment with Risk Scoring

Comprehensive quality gate - AI-powered assessment with quantitative risk scoring (Probability × Impact).

/specweave:qa 0007                    # Quick mode (default)
/specweave:qa 0007 --pre             # Before starting work
/specweave:qa 0007 --gate            # Before closing increment
/specweave:qa 0007 --export          # Export blockers to tasks.md

7 Quality Dimensions:

Clarity (18% weight)
Testability (22% weight)
Completeness (18% weight)
Feasibility (13% weight)
Maintainability (9% weight)
Edge Cases (9% weight)
Risk Assessment (11% weight)

Quality Gate Decisions:

🟢 PASS - Ready to proceed
🟡 CONCERNS - Should fix before release
🔴 FAIL - Must fix before proceeding

Risk Scoring (Probability × Impact method):

CRITICAL (≥9.0) - Immediate action required
HIGH (6.0-8.9) - Address before release
MEDIUM (3.0-5.9) - Monitor
LOW (<3.0) - Acceptable

`/specweave:check-tests` - Test Coverage Check

/specweave:check-tests 0007

What it checks:

📊 Per-task coverage (unit, integration, E2E)
✅ AC-ID coverage (all acceptance criteria tested)
🎯 Overall coverage vs target (80-90%)
📝 Missing tests and recommendations

4. Completion Commands

`/specweave:next` - Smart Workflow Transition

The flow command - Auto-close current work, suggest next.

/specweave:next

What it does:

🔍 Validates current increment (3 gates: tasks, tests, docs)
🎯 Auto-closes if all gates pass
📊 Runs post-closure quality assessment
💡 Suggests next work (backlog or new feature)

Why use /specweave:next instead of /specweave:done:

`/specweave:done`	`/specweave:next`
Closes increment	Closes AND suggests next
Requires increment ID	Auto-detects active increment
Manual next step	Intelligent recommendations
Single action	Complete workflow transition

Example:

/specweave:next

📊 Checking current increment...
Active: 0007-user-authentication

🔍 PM Validation:
  ✅ Gate 1: All tasks complete (15/15)
  ✅ Gate 2: Tests passing (87% coverage)
  ✅ Gate 3: Docs updated

🎯 Auto-closing increment 0007...
  ✓ Quality score: 87/100 (GOOD)

🎉 Increment 0007 closed!

🎯 Next: 0008-payment-processing (P1, ready to start)
   Run: /specweave:do 0008

`/specweave:done` - Close Increment

PM validation before closing - Ensures quality gates pass.

/specweave:done 0007

What it does:

✅ Validates all tasks complete
✅ Runs /specweave:qa --gate (quality gate check)
✅ PM agent validates completion
✅ Creates completion report
🔗 Closes GitHub issues (if plugin enabled)

`/specweave:sync-docs` - Synchronize Living Documentation

Strategic docs sync - Review before implementation, export learnings after.

/specweave:sync-docs review          # Before implementation (review strategic docs)
/specweave:sync-docs update          # After implementation (update with learnings)

What it syncs:

📚 ADRs (Proposed → Accepted)
🏗️ Architecture diagrams (planned → actual)
📖 API documentation (contracts → endpoints)
📋 Feature lists (planned → completed)

5. Sync & Repository Commands

`/specweave:save` - Save Changes Across Repositories

One command for git operations - Works for single repos and multi-repo umbrella setups.

# Auto-generate commit message
/specweave:save

# With explicit message
/specweave:save "feat: Add user authentication"

# Dry run (preview)
/specweave:save --dry-run

What it does:

📊 Analyzes changes to auto-generate commit message
🔍 Detects all repos (umbrella or single)
⚡ Commits and pushes to all repos with one command
🔧 Sets up remotes if missing

Options:

--dry-run - Preview without executing
--repos <list> - Specific repos only
--yes / -y - Accept auto-message without prompt
--no-push - Commit only, don't push

`/specweave:sync-specs` - Sync Specs to Living Docs

Quick specs-only sync - Updates user stories and features only.

/specweave:sync-specs 0007
/specweave:sync-specs --dry-run

What it syncs:

User stories to .specweave/docs/internal/specs/
Feature documentation
Bidirectional task links

When to use: After making changes to spec.md and wanting quick sync.

`/specweave:sync-progress` - Sync to External Tools

Full external sync - Updates all connected platforms.

/specweave:sync-progress
/specweave:sync-progress 0007

What it syncs:

Living docs (user stories, features)
GitHub Issues (checkboxes, comments)
JIRA (if configured)
Azure DevOps (if configured)

`/specweave:validate-status` - Fix Status Line

Validate and auto-fix status line desync.

/specweave:validate-status

What it checks:

Task count matches frontmatter
Cache matches tasks.md reality
Percentage calculations correct

When to use: Status line shows wrong percentage, after manual edits, after git conflicts.

`/specweave:workflow` - Dashboard View

Complete workflow navigator - Shows phase, status, and next steps.

/specweave:workflow
/specweave:workflow 0007

What it shows:

Current phase (Planning, Implementing, Review, etc.)
Task and AC completion
External tools status
Living docs status
Suggested next actions

6. Monitoring Commands

`/specweave:progress` - Check Increment Progress

/specweave:progress
/specweave:progress 0007

What it shows:

📊 Task completion (15/42 tasks, 36%)
⏱️ Time tracking (1.2 weeks elapsed, 2.1 weeks remaining)
🎯 Current phase and next phase
✅ Recent completions
📝 Upcoming tasks

All Available Commands

Essential Workflow (Use These!)

/specweave:increment - Plan new increment ⭐ START HERE
/specweave:do - Execute tasks ⭐ MAIN WORK
/specweave:next - Smart workflow transition ⭐ FLOW COMMAND (auto-close + suggest next)
/specweave:progress - Check status ⭐ VISIBILITY
/specweave:validate - Quick validation ⭐ PRE-CHECK
/specweave:qa - Quality assessment ⭐ QUALITY GATE
/specweave:check-tests - Test coverage check ⭐ TEST VALIDATION
/specweave:done - Close increment ⭐ FINISH
/specweave:sync-docs - Synchronize living docs ⭐ KEEP DOCS CURRENT
/specweave:sync-specs - Sync specs only ⭐ QUICK SPEC SYNC
/specweave:sync-progress - Sync to external tools ⭐ EXTERNAL SYNC
/specweave:save - Save & push to all repos ⭐ MULTI-REPO GIT
/specweave:workflow - Dashboard view ⭐ NAVIGATION
/specweave:validate-status - Fix status line ⭐ STATUS FIX

Workflow Example: Standard Feature Development

# 1. Plan new feature
/specweave:increment "User authentication"
# → Creates: spec.md, plan.md, tasks.md

# 2. Review docs (optional)
/specweave:sync-docs review
# → Review strategic docs before starting

# 3. Pre-check quality (optional)
/specweave:qa 0007 --pre
# → Pre-implementation quality check

# 4. Implement tasks
/specweave:do 0007
# → Auto-resumes from last task, hooks fire after each completion

# 5. Check progress
/specweave:progress 0007
# → See completion status

# 6. Validate quality
/specweave:qa 0007 --gate
# → Comprehensive quality gate check

# 7. Check test coverage
/specweave:check-tests 0007
# → Validate all AC-IDs are tested

# 8. Close increment
/specweave:done 0007
# → PM validates and closes

# 9. Update living docs
/specweave:sync-docs update
# → Sync learnings to strategic docs

Integration with External Tools

GitHub Issues (via specweave-github plugin)

# Create GitHub issue from increment
/specweave-github:specweave-github-create-issue 0007

# Sync progress to GitHub
/specweave-github:specweave-github-sync 0007

# Close GitHub issue when done
/specweave-github:specweave-github-close-issue 0007

Automatic sync: When GitHub plugin enabled, /specweave:do and /specweave:done automatically sync to GitHub.

Best Practices

1. Follow the Core Flow

Always use the standard workflow for best results:

/specweave:increment - Plan (START HERE)
/specweave:do - Implement (MAIN WORK)
/specweave:progress - Check status (VISIBILITY)
/specweave:qa - Validate quality (QUALITY GATE)
/specweave:done - Close (FINISH)
/specweave:sync-docs - Update docs (KEEP CURRENT)

2. Validate Early and Often

# Before starting work
/specweave:qa 0007 --pre

# Before closing
/specweave:qa 0007 --gate

3. Check Test Coverage

# Always validate tests before closing
/specweave:check-tests 0007

4. Keep Living Docs Current

# After completing increment
/specweave:sync-docs update

Configuration

All commands respect .specweave/config.json:

{
  "limits": {
    "maxActiveIncrements": 1,
    "hardCap": 2
  },
  "validation": {
    "quality_judge": {
      "enabled": true,
      "always_run": false
    }
  },
  "language": "en",
  "translation": {
    "enabled": true,
    "autoTranslateInternalDocs": true
  }
}

Glossary Links

Understanding SpecWeave terminology (see full glossary):

ADR - Architecture Decision Records
RFC - Request for Comments (specification format)
API - Application Programming Interface
E2E - End-to-End Testing
Node.js - JavaScript runtime
REST - RESTful API pattern
GraphQL - Query language for APIs
Microservices - Distributed architecture pattern
IaC - Infrastructure as Code

SpecWeave-Specific Terms:

Increments - Work units in SpecWeave
spec.md - Specification file format
plan.md - Architecture plan format
tasks.md - Task tracking format
PM Agent - Product Manager agent
Architect Agent - System design agent
Quality Gate - Validation checkpoints
WIP Limits - Work-in-progress limits

View full glossary →

Next Steps

Getting Started: Quick Start Guide
Workflow Guide: Complete Development Workflow
Quality Gates: Quality Assurance Guide
GitHub Integration: GitHub Sync Guide

Philosophy:

SpecWeave commands are designed for intelligent automation. The system detects intent, suggests actions, and handles workflow management - you focus on building.

The Core Workflow​

1. Planning Commands​

/specweave:increment - Create New Increment​

2. Implementation Commands​

/specweave:do - Execute Tasks​

3. Quality Assurance Commands​

/specweave:validate - Rule-Based Validation​

/specweave:qa - Quality Assessment with Risk Scoring​

/specweave:check-tests - Test Coverage Check​

4. Completion Commands​

/specweave:next - Smart Workflow Transition​

/specweave:done - Close Increment​

/specweave:sync-docs - Synchronize Living Documentation​

5. Sync & Repository Commands​

/specweave:save - Save Changes Across Repositories​

/specweave:sync-specs - Sync Specs to Living Docs​

/specweave:sync-progress - Sync to External Tools​

/specweave:validate-status - Fix Status Line​

/specweave:workflow - Dashboard View​

6. Monitoring Commands​

/specweave:progress - Check Increment Progress​

All Available Commands​

Essential Workflow (Use These!)​

Workflow Example: Standard Feature Development​

Integration with External Tools​

GitHub Issues (via specweave-github plugin)​

Best Practices​

1. Follow the Core Flow​

2. Validate Early and Often​

3. Check Test Coverage​

4. Keep Living Docs Current​

Configuration​

Glossary Links​

Next Steps​

The Core Workflow

1. Planning Commands

`/specweave:increment` - Create New Increment

2. Implementation Commands

`/specweave:do` - Execute Tasks

3. Quality Assurance Commands

`/specweave:validate` - Rule-Based Validation

`/specweave:qa` - Quality Assessment with Risk Scoring

`/specweave:check-tests` - Test Coverage Check

4. Completion Commands

`/specweave:next` - Smart Workflow Transition

`/specweave:done` - Close Increment

`/specweave:sync-docs` - Synchronize Living Documentation

5. Sync & Repository Commands

`/specweave:save` - Save Changes Across Repositories

`/specweave:sync-specs` - Sync Specs to Living Docs

`/specweave:sync-progress` - Sync to External Tools

`/specweave:validate-status` - Fix Status Line

`/specweave:workflow` - Dashboard View

6. Monitoring Commands

`/specweave:progress` - Check Increment Progress

All Available Commands

Essential Workflow (Use These!)

Workflow Example: Standard Feature Development

Integration with External Tools

GitHub Issues (via specweave-github plugin)

Best Practices

1. Follow the Core Flow

2. Validate Early and Often

3. Check Test Coverage

4. Keep Living Docs Current

Configuration

Glossary Links

Next Steps