Skip to main content

SpecWeave Command Reference - By Priority

Last Updated: 2025-11-14 Version: v0.19.0

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 progresssw:progress
sw:statusShow all increments statussw:status

Reopen Functionality​

CommandDescriptionExample
sw:resumeNEW! Reopen completed worksw:resume 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:resume 0031 --reason "Production bug found"

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

# Reopen user story
sw:resume 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 incrementsw:pause 0031 --reason "Blocked by API"
sw:resumeResume paused incrementsw:resume 0031
sw:nextSmart transition to next worksw:next
sw:statusMove increment to backlogsw:status 0032 --reason "Deprioritized"

Quality & Validation​

CommandDescriptionExample
sw:validateValidate increment structuresw:validate 0031
sw:qaQuality assessment with risk scoringsw:qa 0031
npx vitest runValidate test coveragenpx vitest run 0031

Documentation Sync​

CommandDescriptionExample
sw:sync-docsSync to living docssw:sync-docs update
sw:sync-specsSync specs onlysw:sync-specs 0031
sw:progress-syncSync task completionsw:progress-sync 0031

P2: Advanced Features (Use Monthly)​

Specialized commands for advanced workflows.

Test-Driven Development​

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

Multi-Project Management​

Multi-project mode is enabled during specweave init (when connecting JIRA/ADO with multiple projects) or by manually editing config.json. Project routing is per-increment via the **Project**: field in spec.md user stories.

Archiving & Cleanup​

CommandDescriptionExample
sw:archive-incrementsArchive completed incrementssw:archive-increments
sw:archive-featuresArchive completed featuressw:archive-features FS-031
sw:restore-featureRestore archived featuresw:restore-feature FS-031
sw:abandonAbandon incrementsw:abandon 0031 --reason "Obsolete"

Import & Migration​

CommandDescriptionExample
sw:importImport issues from GitHub/JIRA/ADOsw:import
sw:translateTranslate contentsw:translate ru

Cost Tracking​

CommandDescriptionExample
sw:costsShow AI cost dashboardsw:costs 0031
sw:increment (to update spec)Log scope changessw:increment (to update spec) 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 issuesw-github:create-issue 0031
sw-github:close-issueClose GitHub issuesw-github:close-issue 0031
sw-github:statusCheck sync statussw-github:status 0031
sw-github:cleanup-duplicatesClean duplicate issuessw-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 itemsw-ado:create-workitem 0031
sw-ado:close-workitemClose ADO work itemsw-ado:close-workitem 0031
sw-ado:statusCheck ADO sync statussw-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
/docs:viewLaunch docs server (internal or public)/docs:view or /docs:view --public
/docs:buildBuild static docs site/docs:build
/docs:generateGenerate documentation/docs:generate
/docs:organizeOrganize large doc folders/docs:organize
/docs:healthDocumentation health report/docs:health
/docs:validateValidate documentation/docs:validate

Infrastructure & SRE​

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

ML/AI Workflows​

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

Release Management​

CommandDescriptionExample
sw-release:initInitialize release strategysw-release:init
sw-release:alignAlign versions across repossw-release:align
sw-release:rcManage release candidatessw-release:rc create
sw-release:platformCoordinate platform releasessw-release:platform create

Internal/Debug​

CommandDescriptionExample
sw:revert-wip-limitRevert WIP limit adjustmentsw: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:

"I want to add user authentication"

2. Execute tasks:

"Start implementing"

3. Check progress:

"What's the status?"

4. Close when done:

"We're done, close it"

5. Reopen if issues found:

sw:resume 0031 --reason "Auth broken in prod"

Daily Workflow Example​

Monday - Start New Feature:

"Let's build payment processing"
→ Creates increment 0032, generates spec/plan/tasks

Tuesday-Thursday - Execute Work:

"Start implementing"
→ Smart resume, continues last active increment
Work on tasks, mark [x] as you complete them
"What's the status?"
→ Check: 15/20 tasks (75%)

Friday - Complete or Pause:

"We're done with 0032, finish up"
→ 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:resume 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

New in v0.19.0: 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:resume 0031 --task T-003 --reason "GitHub API rate limit"

User Story-Level (Feature Fix):

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

Increment-Level (Systemic Fix):

sw:resume 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:resume 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:

"Let's build Feature X"

Auto-creates GitHub issue #123 via hook.

2. Execute:

"Start implementing"

Tasks update GitHub checkboxes automatically via hook.

3. Close:

"We're done, close it"

Closes GitHub issue #123.

4. (If needed) Reopen:

sw:resume 0031 --reason "Bug found"
# → Reopens GitHub issue #123

JIRA Workflow​

1. Plan:

"Let's build Feature X"

2. Sync to JIRA:

"Sync to JIRA"

Creates JIRA epic.

3. Execute:

"Start implementing"

4. Close:

"We're done, close it"

5. Sync completion:

"Sync to JIRA"

Transitions JIRA: In Progress to 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 New in v0.19.0: Smart Reopen Functionality ⭐