Skip to main content

Commands Overview

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

No Shortcuts

All commands MUST use the /sw:* 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 /sw:auto for autonomous execution (hours of hands-free work!) or /sw:do for manual task-by-task control.

1. Planning​

/sw:increment - Create New Increment​

Start every new feature here - This is your entry point.

/sw:increment "User authentication with JWT"
/sw:increment "Payment processing with Stripe"

What it does:

  • 🔍 Detects tech stack automatically
  • 📋 PM-led planning (spec.md, plan.md, tasks.md)
  • 🧪 Creates test strategy
  • 👥 Strategic agent review (Architect, Security, QA)

2. Execution​

/sw:auto - Autonomous Execution ⭐ FLAGSHIP​

The Power Feature

Ship features while you sleep. Auto mode executes tasks for hours autonomously - implementing code, running tests, self-healing failures, and syncing to GitHub/JIRA.

/sw:auto                  # Start autonomous execution
/sw:auto-status           # Check progress (from another session)
/sw:cancel-auto           # Emergency stop (rarely needed)

What it does:

  • 🔄 Continuous loop: Read task → Implement → Test → Fix → Next
  • 🧪 Test validation: Runs tests after EVERY task
  • 🔧 Self-healing: Analyzes failures, applies fixes (max 3 retries)
  • 📚 Living docs sync: Updates documentation automatically
  • ⏱️ Hours of work: Proven with 2-3 hour sessions

Stop conditions:

  • ✅ All tasks complete + all tests passing
  • 🛑 Max iterations reached (default: 2500)
  • ⏸️ Test failures after 3 retries → pauses for human

Best for: Well-defined tasks, CRUD operations, repetitive work

See: Auto Mode Deep Dive

/sw:do - Manual Task Execution​

Task-by-task control - For exploratory work or complex decisions.

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

What it does:

  • 🎯 Resumes from last incomplete task
  • 🔊 Plays sound after each task
  • 🔗 Syncs to GitHub (if enabled)

Best for: Architecture decisions, debugging, learning codebase

3. Monitoring​

/sw:progress - Check Status​

/sw:progress         # Current increment
/sw:progress 0007    # Specific increment

Shows: Task completion, time tracking, current phase, upcoming tasks.

4. Quality Assurance​

/sw:validate - Quick Validation​

/sw:validate 0007              # 120+ rule-based checks
/sw:validate 0007 --quality    # Include AI assessment

Validates: Consistency, completeness, testability, traceability.

/sw:qa - AI Quality Gate​

/sw:qa 0007 --gate    # Before closing (recommended)

Returns: 🟢 PASS | 🟡 CONCERNS | 🔴 FAIL

5. Completion​

/sw:next - Smart Workflow Transition ⭐ RECOMMENDED​

/sw:next    # Auto-close + suggest next work

What it does: Validates gates → closes increment → suggests next task.

/sw:done - Close Increment​

/sw:done 0007    # Close specific increment

Use /sw:next instead - it does the same thing plus suggests next work.

6. External Sync (Optional)​

For GitHub, JIRA, or Azure DevOps integration:

/sw-github:sync 0007    # Two-way sync with GitHub
/sw-jira:sync 0007      # Two-way sync with JIRA
/sw-ado:sync 0007       # Two-way sync with Azure DevOps

See GitHub Integration for setup.

Quick Reference​

The 5 Essential Commands​

CommandPurposeWhen to Use
/sw:incrementCreate new incrementStarting new feature
/sw:autoAutonomous executionHands-free work (hours)
/sw:doManual executionTask-by-task control
/sw:progressCheck statusMonitoring progress
/sw:nextComplete + suggest nextFinishing work

Auto Mode Commands​

CommandPurpose
/sw:autoStart autonomous execution
/sw:auto-statusCheck progress (from another session)
/sw:cancel-autoEmergency stop (rarely needed)

Quality Commands​

CommandPurpose
/sw:validateQuick rule-based validation
/sw:qa --gateAI quality gate check

State Management​

CommandPurpose
/sw:pausePause active increment
/sw:resumeResume paused work
/sw:statusShow all increments

Example Workflows​

/sw:increment "User authentication"
/sw:auto                  # Let it run for hours
# ... come back later ...
/sw:next                  # Close and see what's next

Manual (For Complex Decisions)​

/sw:increment "Payment integration"
/sw:do                    # Task-by-task with your guidance
/sw:progress              # Check status
/sw:qa --gate             # Quality check
/sw:done 0007             # Close

Best Practices​

1. Choose the Right Mode​

  • Use /sw:auto for: CRUD, repetitive tasks, well-defined specs
  • Use /sw:do for: Architecture decisions, debugging, exploration

2. Validate Before Closing​

/sw:qa --gate    # Quality check before /sw:done

Next Steps​

Philosophy: SpecWeave is designed for autonomous execution. Let /sw:auto do the heavy lifting while you focus on decisions that matter.