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. Always run /sw:grill before closing!

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

/sw:grill - Code Review (MANDATORY) 🔥​

Required Before Closing

/sw:grill must pass before /sw:done will work. This is enforced automatically.

/sw:grill 0007                # Full review
/sw:grill 0007 security       # Focus on security
/sw:grill 0007 performance    # Focus on performance

What it reviews:

  • 🔒 Security vulnerabilities (OWASP Top 10)
  • ⚡ Performance issues (N+1 queries, complexity)
  • 🎯 Edge cases and error handling
  • 📐 Code quality and maintainability

Issue severities: BLOCKER, CRITICAL, MAJOR, MINOR, SUGGESTION

On PASS: Creates marker file allowing /sw:done to proceed.

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:grill 0007   # Required first!
/sw:done 0007    # Close specific increment

Prerequisite: /sw:grill must pass first.

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
/sw:grillCode review (MANDATORY before close)

State Management​

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

CLI Commands (Terminal)​

CommandPurpose
specweave init .Initialize project
specweave updateFull update: CLI + plugins + instructions (use this first)
specweave update --no-pluginsUpdate without refreshing plugins
specweave refresh-marketplacePlugin-only refresh (see note below)
About refresh-marketplace

Most users should use specweave update. The refresh-marketplace command exists for specific situations:

What it does beyond Claude Code's native auto-update:

  • Fixes hook permissions (chmod +x) — Claude Code doesn't preserve executable bits
  • Manages lazy loading state (router-only installation)
  • Cleans up orphaned cache/skills directories
  • Updates instruction files (CLAUDE.md, AGENTS.md)

When to use it:

  • Hooks stopped working after Claude Code update
  • Skills not activating despite being installed
  • Want to refresh plugins without updating CLI version

Note: You can enable Claude Code's native marketplace auto-update via /plugin → Marketplaces → Enable auto-update. However, this doesn't fix hook permissions or manage SpecWeave-specific state.

Example Workflows​

/sw:increment "User authentication"
/sw:auto                  # Let it run for hours
# ... come back later ...
/sw:grill 0007            # Code review (mandatory!)
/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:grill 0007            # Code review (mandatory!)
/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. Grill and Validate Before Closing​

/sw:qa --gate       # Quality check
/sw:grill 0007      # Code review (mandatory!)
/sw:done 0007       # Now close

Next Steps​

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