Skip to main content

Commands Reference

This page lists all SpecWeave commands organized by purpose. Every command can be invoked three ways:

  1. Natural language -- just describe what you want (easiest)
  2. Slash command -- sw:name in Claude Code (precise)
  3. Keyword -- type name without prefix in Cursor, Copilot, and other AI tools
Commands vs Skills

Commands are action-oriented (sw:do, sw:done) while Skills provide domain expertise (sw:pm, sw:architect). Both support all three invocation methods.

For domain expertise, see Skills Reference.

Quick Reference Card​

Natural LanguageClaude CodeOther AIPurpose
"let's build X"sw:increment "X"increment "X"Start new work
"ship while I sleep"sw:autoautoRun autonomously (hours!)
"what's the status?"sw:progressprogressCheck status
"review my work"sw:grill 0007grill 0007Code review (MANDATORY)
"what's next?"sw:nextnextComplete and suggest next

1. Planning Commands​

Start new work and create specifications.

Natural LanguageClaude CodeOther AIPurpose
"let's build X", "I want to create X", "add feature X"sw:increment "X"increment "X"Create new increment
"what's in progress?"sw:statusstatusView/manage backlog

sw:increment​

The entry point for all new work.

"I want to build user authentication with JWT"
# With options
sw:increment "Payment processing" --priority high

What happens:

  1. Tech stack detection (React, Node, etc.)
  2. PM-led spec creation (spec.md)
  3. Architecture planning (plan.md)
  4. Task breakdown (tasks.md)
  5. Strategic agent review (Architect, Security, QA)

Output: Creates .specweave/increments/XXXX-feature-name/ with all files.

2. Execution Commands​

Execute tasks and implement features.

Natural LanguageClaude CodeOther AIPurpose
"ship while I sleep", "autonomous mode"sw:autoautoHands-free work (hours)
"start implementing", "execute tasks"sw:dodoManual task execution
"parallel agents"sw:auto-parallelauto-parallelMulti-agent parallel
"check auto progress"sw:auto-statusauto-statusMonitoring
"stop auto mode"sw:cancel-autocancel-autoEmergency stop

sw:auto​

Ship features while you sleep. The flagship command.

"Ship it while I sleep"
sw:auto --tdd     # With TDD enforcement

What it does:

  • Reads next task from tasks.md
  • Implements the code
  • Runs tests
  • If tests fail: analyzes, fixes, retries (max 3)
  • If tests pass: marks complete, moves to next
  • Syncs to GitHub/JIRA (if enabled)
  • Updates living documentation

Stop conditions:

  • All tasks complete + all tests passing
  • Max iterations reached (default: 2500)
  • 3 consecutive test failures → pauses for human

Duration: Proven for 2-3 hour continuous sessions.

sw:do​

Manual task-by-task execution.

"Start implementing the tasks"
sw:do 0007   # Specific increment

When to use:

  • Architecture decisions requiring human judgment
  • Debugging complex issues
  • Learning the codebase
  • Exploratory work

sw:auto-parallel​

Multi-agent parallel execution in isolated git worktrees.

"Build this with parallel agents"

Spawns specialized agents:

  • Frontend Agent (React, Vue)
  • Backend Agent (API, database)
  • Database Agent (migrations, queries)
  • DevOps Agent (CI/CD, infra)
  • QA Agent (tests, validation)

Each works in its own worktree - no merge conflicts during execution.

sw:auto-status​

Check autonomous execution progress from another terminal.

"Check auto mode progress"

Shows: Current task, completion percentage, recent activity, errors.

sw:cancel-auto​

Emergency stop for autonomous execution.

"Stop auto mode"
Use Sparingly

Only use if auto mode is stuck or producing bad results. Normal completion happens automatically.

3. Monitoring Commands​

Track progress and status.

Natural LanguageClaude CodeOther AIPurpose
"what's the status?", "show progress"sw:progressprogressDetailed progress report
"list all increments"sw:statusstatusList all increments
"show background jobs", "check jobs"sw:jobsjobsView background jobs

sw:progress​

Detailed progress for an increment.

"How far along are we?"
sw:progress 0007    # Specific increment

Shows:

  • Task completion (e.g., 12/15 tasks, 80%)
  • Time tracking (started, elapsed)
  • Current phase (planning, implementing, testing)
  • Upcoming tasks
  • Blockers (if any)

sw:status​

Overview of all increments.

sw:status    # List all increments

Shows:

  • Active increments
  • Paused increments
  • Recently completed
  • Abandoned (in _abandoned/)

4. Quality Commands​

Validate quality before completion.

Natural LanguageClaude CodeOther AIPurpose
"check quality", "validate it"sw:validatevalidateRule-based validation (120+ checks)
"quality check", "assess quality"sw:qaqaAI quality assessment
"review my work", "critique the code"sw:grillgrillImplementation audit

sw:validate​

Fast rule-based validation.

"Validate the increment"
sw:validate 0007 --quality    # Include AI assessment

Checks:

  • Spec consistency (AC-IDs match)
  • Task completeness
  • Traceability (tasks → specs)
  • File structure

sw:qa​

AI-powered quality gate using LLM-as-Judge pattern.

"Assess the quality of this increment"
sw:qa 0007 --pre    # Pre-implementation check

Returns: 🟢 PASS | 🟡 CONCERNS | 🔴 FAIL

Evaluates 7 dimensions:

  1. Clarity (18%)
  2. Testability (22%)
  3. Completeness (18%)
  4. Feasibility (13%)
  5. Maintainability (9%)
  6. Edge Cases (9%)
  7. Risk (11%) - BMAD P×I scoring

sw:grill​

Comprehensive implementation audit.

"Review my implementation for issues"
sw:grill src/auth           # Specific module
sw:grill --focus security   # Focus area
sw:grill --full             # Maximum depth

Uses parallel subagents to audit:

  • Structure and organization
  • Code quality patterns
  • Consistency across codebase
  • Documentation completeness
  • Dependency health
  • Test coverage
  • Security vulnerabilities

5. Completion Commands​

Finish work and move on.

Natural LanguageClaude CodeOther AIPurpose
"what's next?"sw:nextnextComplete + suggest next (recommended)
"we're done", "close it", "finish up"sw:donedoneClose increment

sw:next​

Smart workflow transition. (Recommended)

"What should I work on next?"

What it does:

  1. Validates quality gates
  2. Closes increment (moves to _archive/)
  3. Suggests next work (from backlog or new)

sw:done​

Close specific increment.

"We're done with this increment"

Prerequisites:

  • sw:grill must pass first (creates marker file)

Validations:

  • All P1 tasks must be complete
  • Tests must pass
  • Acceptance criteria must be met
  • Grill marker file exists
Grill Required

sw:done is BLOCKED if sw:grill hasn't passed. Run sw:grill 0007 first.

Use sw:next

sw:next does everything sw:done does, plus suggests what to work on next.

6. State Management Commands​

Control increment lifecycle.

Natural LanguageClaude CodeOther AIPurpose
"pause this", "put on hold"sw:pause 0007pause 0007Pause increment
"resume work", "continue where we left off"sw:resume 0007resume 0007Resume paused / reopen completed
"abandon this", "cancel increment"sw:abandon 0007abandon 0007Abandon increment
"restore the abandoned increment"sw:restore 0007restore 0007Restore abandoned
"archive the increment"sw:archive 0007archive 0007Manual archive

sw:pause​

Pause active increment.

"Pause this work for now"

Moves to _paused/ folder. Resume with sw:resume.

sw:resume​

Resume paused increment.

"Resume where we left off"

sw:abandon​

Abandon increment (soft delete).

"Cancel this increment"

Can be restored with sw:restore.

7. External Sync Commands​

Integrate with GitHub, JIRA, Azure DevOps.

CommandPluginPurpose
sw-github:syncsw-githubSync to GitHub Issues
sw-jira:syncsw-jiraSync to JIRA
sw-ado:syncsw-adoSync to Azure DevOps

sw-github:sync​

Two-way sync with GitHub Issues.

sw-github:sync 0007              # Sync increment
sw-github:sync 0007 --dry-run    # Preview changes

Maps:

  • Feature → GitHub Milestone
  • User Story → GitHub Issue
  • Task → Issue checkbox

Requires: gh CLI authenticated, config enabled.

sw-jira:sync​

Bidirectional JIRA sync.

sw-jira:sync 0007    # Sync to JIRA

Maps:

  • Feature → JIRA Epic
  • User Story → JIRA Story
  • Task → Sub-task

sw-ado:sync​

Azure DevOps sync.

sw-ado:sync 0007    # Sync to Azure DevOps

8. Documentation Commands​

Sync and manage documentation.

Natural LanguageClaude CodeOther AIPurpose
"update the docs", "sync documentation"sw:sync-docssync-docsSync living docs
"sync specs"sw:sync-specssync-specsSync specs only
"import issues"sw:importimportImport external issues
"load auth context"sw:docs authdocs authLoad project context

sw:sync-docs​

Synchronize living documentation.

"Update the documentation"

Syncs: ADRs, specs, runbooks to external systems.

sw:docs​

Load relevant project context.

sw:docs auth        # Load auth-related docs
sw:docs database    # Load DB architecture

9. Utility Commands​

Maintenance and diagnostics.

Natural LanguageClaude CodeOther AIPurpose
"save my work"sw:savesaveGit commit current work
"fix duplicate IDs"sw:fix-duplicatesfix-duplicatesFix ID collisions
"check hooks"sw:check-hookscheck-hooksVerify hook setup
"review learnings"sw:reflectreflectReview learnings
"show analytics"sw:analyticsanalyticsUsage analytics

sw:save​

Commit current work with proper message.

sw:save    # Git add + commit

Scans for nested repositories and commits each appropriately.

sw:fix-duplicates​

Fix increment ID collisions.

sw:fix-duplicates    # Scan and fix

10. TDD Commands​

Test-Driven Development workflow.

Natural LanguageClaude CodeOther AITDD Phase
"write failing tests first"sw:tdd-redtdd-redRED
"make the tests pass"sw:tdd-greentdd-greenGREEN
"refactor the code"sw:tdd-refactortdd-refactorREFACTOR
"TDD", "test-driven development"sw:tdd-cycletdd-cycleAll

sw:tdd-cycle​

Complete TDD workflow.

"Let's do test-driven development"

Enforces:

  1. Write failing test first
  2. Verify test fails for right reason
  3. Write minimal code to pass
  4. Verify test passes
  5. Refactor without breaking tests

CLI Commands (Terminal)​

Commands run directly in terminal (not slash commands).

CommandPurpose
specweave init .Initialize project
specweave updateFull update (CLI + plugins + instructions)
specweave refresh-pluginsPlugin-only refresh
specweave lsp refs SymbolFind references (LSP workaround)
specweave lsp def SymbolGo to definition

specweave init​

Initialize SpecWeave in a project.

specweave init .              # Current directory
specweave init ./my-project   # Specific directory

Creates .specweave/ folder with config and initial increment.

specweave update​

Update everything.

specweave update              # Full update
specweave update --no-plugins # Skip plugin refresh

Updates: CLI version, plugins, CLAUDE.md instructions.

specweave refresh-plugins​

Refresh skills/plugins for all AI tools.

specweave refresh-plugins          # Refresh core plugin
specweave refresh-plugins --all    # All plugins
specweave refresh-plugins --force  # Force re-copy even if unchanged

Copies skills to tool-specific directories based on the configured adapter. For non-Claude tools (OpenCode, Cursor, Copilot, etc.), SKILL.md frontmatter is automatically normalized:

  • name: ensured (derived from skill directory name)
  • description: ensured (extracted from body if missing)
  • Claude-specific fields (hooks, model, allowed-tools, etc.) stripped

This ensures non-Claude tools can discover and invoke skills correctly.

specweave lsp​

Code navigation (workaround for Claude Code v2.1.0+ LSP bug).

specweave lsp refs MyFunction       # Find references
specweave lsp def MyClass           # Go to definition
specweave lsp hover file.ts 42 10   # Type at position

Command Cheat Sheet​

Daily Workflow​

StepNatural LanguageClaude CodeOther AI
Start new feature"Build a user dashboard"sw:increment "Add user dashboard"increment "Add user dashboard"
Autonomous execution"Ship while I sleep"sw:autoauto
Check progress"How far along?"sw:auto-statusauto-status
Complete and move on"What's next?"sw:nextnext

Quality Check Before Release​

StepNatural LanguageClaude CodeOther AI
Quick validation"Validate it"sw:validate 0007validate 0007
AI quality gate"Assess quality"sw:qa 0007 --gateqa 0007 --gate
Deep code audit"Review the code"sw:grill 0007grill 0007

Sync to External Tools​

PlatformClaude CodeOther AI
GitHubsw-github:sync 0007github-sync 0007
JIRAsw-jira:sync 0007jira-sync 0007
Azure DevOpssw-ado:sync 0007ado-sync 0007

State Management​

ActionNatural LanguageClaude CodeOther AI
Pause"Put this on hold"sw:pause 0007pause 0007
Resume"Continue working"sw:resume 0007resume 0007
Abandon"Cancel this"sw:abandon 0007abandon 0007
Restore"Bring it back"sw:restore 0007restore 0007

Next Steps​