Skip to main content

SpecWeave Command Reference - By Priority

Last Updated: 2025-11-14

This guide organizes all SpecWeave commands by priority, from essential daily workflow to specialized features.

P0: Critical/Core Workflow (Use Daily)​

These are the essential commands you'll use every day. Master these first!

Increment Planning & Execution​

CommandDescriptionExample
/sw:incrementPlan new increment (PM-led)/sw:increment "User authentication"
/sw:doExecute tasks (smart resume)/sw:do or /sw:do 0031
/sw:doneClose increment (PM validation)/sw:done 0031
/sw:progressCheck current progress/sw:progress
/sw:statusShow all increments status/sw:status

Reopen Functionality​

CommandDescriptionExample
/sw:reopenNEW! Reopen completed work/sw:reopen 0031 --reason "GitHub sync failing"

Smart Detection: Just say "GitHub sync not working" and the skill auto-suggests what to reopen!

Usage:

# Reopen entire increment
/sw:reopen 0031 --reason "Production bug found"

# Reopen specific task
/sw:reopen 0031 --task T-003 --reason "API broken"

# Reopen user story
/sw:reopen 0031 --user-story US-001 --reason "AC not met"

P1: Common Workflow (Use Weekly)​

Commands you'll use regularly but not every day.

State Management​

CommandDescriptionExample
/sw:pausePause active increment/sw:pause 0031 --reason "Blocked by API"
/sw:resumeResume paused increment/sw:resume 0031
/sw:nextSmart transition to next work/sw:next
/sw:backlogMove increment to backlog/sw:backlog 0032 --reason "Deprioritized"

Quality & Validation​

CommandDescriptionExample
/sw:validateValidate increment structure/sw:validate 0031
/sw:qaQuality assessment with risk scoring/sw:qa 0031
/sw:check-testsValidate test coverage/sw:check-tests 0031

Documentation Sync​

CommandDescriptionExample
/sw:sync-docsSync to living docs/sw:sync-docs update
/sw:sync-specsSync specs only/sw:sync-specs 0031
/sw:sync-tasksSync task completion/sw:sync-tasks 0031

P2: Advanced Features (Use Monthly)​

Specialized commands for advanced workflows.

Test-Driven Development​

CommandDescriptionExample
/sw:tdd-cycleFull TDD red-green-refactor/sw:tdd-cycle 0031
/sw:tdd-redWrite failing tests (red phase)/sw:tdd-red 0031
/sw:tdd-greenImplement to pass tests/sw:tdd-green 0031
/sw:tdd-refactorRefactor with test safety/sw:tdd-refactor 0031

Multi-Project Management​

CommandDescriptionExample
/sw:init-multiprojectInitialize multi-project mode/sw:init-multiproject
/sw:switch-projectSwitch active project/sw:switch-project backend

Archiving & Cleanup​

CommandDescriptionExample
/sw:archive-incrementsArchive completed increments/sw:archive-increments
/sw:archive-featuresArchive completed features/sw:archive-features FS-031
/sw:restore-featureRestore archived feature/sw:restore-feature FS-031
/sw:abandonAbandon increment/sw:abandon 0031 --reason "Obsolete"

Import & Migration​

CommandDescriptionExample
/sw:import-docsImport brownfield docs/sw:import-docs ./notion-export
/sw:translateTranslate content/sw:translate ru

Cost Tracking​

CommandDescriptionExample
/sw:costsShow AI cost dashboard/sw:costs 0031
/sw:update-scopeLog scope changes/sw:update-scope 0031

P3: Optional/Specialized (Use Rarely)​

Edge cases and specialized integrations.

GitHub Integration​

CommandDescriptionExample
/sw-github:syncSync increment ↔ GitHub issue (bidirectional)/sw-github:sync 0031
/sw-github:create-issueCreate GitHub issue/sw-github:create-issue 0031
/sw-github:close-issueClose GitHub issue/sw-github:close-issue 0031
/sw-github:statusCheck sync status/sw-github:status 0031
/sw-github:cleanup-duplicatesClean duplicate issues/sw-github:cleanup-duplicates FS-031

Note: Epic/Feature/User Story syncing happens automatically via living docs sync (triggered by /sw:done). The /sync command is for increments only.

JIRA Integration​

CommandDescriptionExample
/sw-jira:syncSync increment ↔ JIRA epic (bidirectional)/sw-jira:sync 0031

Note: Epic/Feature/User Story syncing happens automatically via living docs sync (triggered by /sw:done). The /sync command is for increments only.

Azure DevOps Integration​

CommandDescriptionExample
/sw-ado:syncSync increment ↔ ADO work item (bidirectional)/sw-ado:sync 0031
/sw-ado:create-workitemCreate ADO work item/sw-ado:create-workitem 0031
/sw-ado:close-workitemClose ADO work item/sw-ado:close-workitem 0031
/sw-ado:statusCheck ADO sync status/sw-ado:status 0031

Note: Epic/Feature/User Story syncing happens automatically via living docs sync (triggered by /sw:done). The /sync command is for increments only.

Documentation​

CommandDescriptionExample
/sw-docs:viewLaunch docs server (internal or public)/sw-docs:view or /sw-docs:view --public
/sw-docs:buildBuild static docs site/sw-docs:build
/sw-docs:generateGenerate documentation/sw-docs:generate
/sw-docs:organizeOrganize large doc folders/sw-docs:organize
/sw-docs:healthDocumentation health report/sw-docs:health
/sw-docs:validateValidate documentation/sw-docs:validate

Infrastructure & SRE​

CommandDescriptionExample
/sw-infra:monitor-setupSetup monitoring/sw-infra:monitor-setup
/sw-infra:slo-implementImplement SLOs/sw-infra:slo-implement

ML/AI Workflows​

CommandDescriptionExample
/sw-ml:pipelineDesign ML pipeline/sw-ml:pipeline
/sw-ml:evaluateEvaluate ML model/sw-ml:evaluate
/sw-ml:explainModel explainability/sw-ml:explain
/sw-ml:deployDeploy ML model/sw-ml:deploy

Release Management​

CommandDescriptionExample
/sw-release:initInitialize release strategy/sw-release:init
/sw-release:alignAlign versions across repos/sw-release:align
/sw-release:rcManage release candidates/sw-release:rc create
/sw-release:platformCoordinate platform releases/sw-release:platform create

Internal/Debug​

CommandDescriptionExample
/sw:revert-wip-limitRevert WIP limit adjustment/sw:revert-wip-limit
/swCommand reference/help/sw

Quick Start Guide - Essential 5 Commands​

If you're new to SpecWeave, start with these 5 commands:

# 1. Plan new work
/sw:increment "Add user authentication"

# 2. Execute tasks
/sw:do

# 3. Check progress
/sw:progress

# 4. Close when done
/sw:done 0031

# 5. (NEW!) Reopen if issues found
/sw:reopen 0031 --reason "Auth broken in prod"

Daily Workflow Example​

Monday - Start New Feature:

/sw:increment "Implement payment processing"
# → Creates increment 0032, generates spec/plan/tasks

Tuesday-Thursday - Execute Work:

/sw:do
# → Smart resume, continues last active increment
# Work on tasks, mark [x] as you complete them

/sw:progress
# → Check: 15/20 tasks (75%)

Friday - Complete or Pause:

/sw:done 0032
# → PM validates, syncs to living docs, closes increment

# OR if blocked:
/sw:pause 0032 --reason "Waiting for API access"

Next Week - Resume or Reopen:

# Resume paused work
/sw:resume 0032

# OR reopen if issues found
/sw:reopen 0032 --reason "Payment gateway timeout"

Command Priority Matrix​

PriorityFrequencyLearn First?Examples
P0Daily✅ YESincrement, do, done, progress, reopen
P1Weekly✅ YESpause, resume, validate, sync-docs
P2Monthly⚠️ LATERtdd-cycle, archive, translate
P3Rarely❌ OPTIONALGitHub sync, JIRA sync, ML pipelines

Smart Reopen​

Breaking News: COMPLETED is no longer terminal! You can now reopen work when issues are discovered.

Auto-Detection Feature​

Just report the issue naturally:

"The GitHub sync isn't working"

The smart-reopen-detector skill will:

  1. 🔍 Scan recent work (active + 7 days completed)
  2. 🎯 Find related items (keyword matching + relevance scoring)
  3. 💡 Suggest exact reopen command

Three Reopen Levels​

Task-Level (Surgical Fix):

/sw:reopen 0031 --task T-003 --reason "GitHub API rate limit"

User Story-Level (Feature Fix):

/sw:reopen 0031 --user-story US-001 --reason "AC not met"

Increment-Level (Systemic Fix):

/sw:reopen 0031 --reason "Multiple issues in production"

WIP Limits Respected​

Reopening respects WIP limits:

⚠️  WIP LIMIT WARNING:
   Current: 2/2 features active
   Reopening will EXCEED limit!

Options:
1. Pause: /sw:pause 0030
2. Force: /sw:reopen 0031 --force --reason "Production critical"

Tips & Best Practices​

Do's ✅​

  • Use /sw:increment for ALL new work (even small fixes)
  • Check /sw:progress frequently
  • Always provide --reason for pause/reopen/abandon
  • Use /sw:validate before closing
  • Leverage smart reopen for production issues

Don'ts ❌​

  • Don't skip /sw:done (breaks living docs sync)
  • Don't exceed WIP limits without good reason
  • Don't reopen old increments (>7 days) without investigation
  • Don't abuse --force flag
  • Don't create new increments for simple fixes (use reopen!)

Command Aliases (Deprecated)​

⚠️ IMPORTANT: Do NOT use shortcuts! They conflict with Claude Code native commands.

❌ Never use:

  • /inc → Use /sw:increment
  • /do → Use /sw:do
  • /done → Use /sw:done

✅ Always use full names:

  • /sw:increment
  • /sw:do
  • /sw:done

Integration Workflows​

GitHub Workflow​

# 1. Plan
/sw:increment "Feature X"

# 2. Auto-create GitHub issue (via hook)
# → Creates issue #123 automatically

# 3. Execute
/sw:do

# 4. Tasks update GitHub (via hook)
# → Checkboxes update automatically

# 5. Close
/sw:done 0031
# → Closes GitHub issue #123

# 6. (If needed) Reopen
/sw:reopen 0031 --reason "Bug found"
# → Reopens GitHub issue #123

JIRA Workflow​

# 1. Plan
/sw:increment "Feature X"

# 2. Sync to JIRA
/sw-jira:sync 0031
# → Creates JIRA epic

# 3. Execute
/sw:do

# 4. Close
/sw:done 0031

# 5. Sync completion
/sw-jira:sync 0031
# → Transitions JIRA: In Progress → Done

Troubleshooting​

"Command not found":

  • Ensure plugin installed: /plugin list --installed
  • Restart Claude Code
  • Check marketplace: claude plugin marketplace list

"WIP limit exceeded":

  • Check status: /sw:status
  • Pause another: /sw:pause 0030 --reason "..."
  • Or force: --force flag

"Cannot reopen: status is active":

  • Increment already active, no need to reopen
  • Just continue work: /sw:do

"Smart reopen not suggesting anything":

  • Check if work is >7 days old
  • Try manual command with increment ID
  • Verify skill is loaded: skill activates on keywords
  • Full Command List: plugins/specweave/commands/sw.md
  • Quick Start: .specweave/docs/public/guides/getting-started.md
  • Workflow Guide: .specweave/docs/internal/delivery/guides/increment-lifecycle.md
  • Reopen Architecture: .specweave/docs/internal/architecture/adr/0033-smart-reopen-functionality.md

Last Updated: 2025-11-14 Total Commands: 62 across 10 plugins