Do Increment

Implementation Execution: Following spec.md and plan.md to execute the increment work.

You are helping the user implement a SpecWeave increment by executing tasks from tasks.md with automatic documentation updates after EVERY task completion.

Usage

# Auto-resumes from last incomplete task
/sw:do <increment-id>

# Or let it find active increment automatically
/sw:do

# Override model selection for all tasks (advanced)
/sw:do <increment-id> --model haiku
/sw:do <increment-id> --model sonnet
/sw:do <increment-id> --model opus

Arguments

• <increment-id>: Optional. Increment ID (e.g., "001", "0001", "1", "0042")

  • If omitted, MUST auto-select best candidate (see Step 0.5 below)
  • Smart resume: Automatically starts from next incomplete task

• --model <tier>: Optional. Override model selection for all tasks

  • haiku: Fast, cheap execution (simple mechanical tasks)
  • sonnet: Legacy option (rarely needed)
  • opus: Maximum quality (default for all complex tasks)
  • If omitted, uses model hints from tasks.md (recommended)

Workflow

Step 0.5: Smart Increment Auto-Selection (MANDATORY when no ID provided)

🎯 CRITICAL: When user runs /sw:do without increment ID, you MUST auto-select the best candidate.

DO NOT ask the user for an increment ID. DO NOT fail with "increment ID required". Instead:

1. Scan for candidates in this priority order:

   # Priority 1: in-progress (resume work)
   IN_PROGRESS=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "in-progress"' {} \; 2>/dev/null | head -1)
   
   # Priority 2: planned (start next work)
   PLANNED=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "planned"' {} \; 2>/dev/null | head -1)
   
   # Priority 3: ready_for_review with incomplete tasks (needs finishing)
   READY=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "ready_for_review"' {} \; 2>/dev/null)
   
   # Priority 4: backlog with tasks (can start)
   BACKLOG=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "backlog"' {} \; 2>/dev/null)
   

2. For each candidate, check if it has incomplete tasks:

   # Count incomplete tasks in tasks.md (supports multiple formats)
   # Format 1: List items "- [ ] Task"
   INCOMPLETE=$(grep -c '^\- \[ \]' "$INCREMENT_PATH/tasks.md" 2>/dev/null || echo "0")
   # Format 2: Status field "**Status**: [ ] pending"
   INCOMPLETE_STATUS=$(grep -c '\*\*Status\*\*: \[ \]' "$INCREMENT_PATH/tasks.md" 2>/dev/null || echo "0")
   # Total incomplete = sum of all formats
   TOTAL_INCOMPLETE=$((INCOMPLETE + INCOMPLETE_STATUS))
   

3. Select the best candidate:

   • If in-progress increment exists → use it
   • Else if planned increment exists → use it
   • Else if ready_for_review with incomplete tasks → use it
   • Else if backlog increment exists with incomplete tasks → use it (and change status to in-progress)

4. If candidate found, display selection and continue:

   🎯 Auto-selected increment: 0162-lsp-skill-integration
   
   Status: backlog → in-progress (auto-promoted)
   Tasks: 0/28 completed (0%)
   Priority: P1
   Type: refactor
   
   Proceeding with execution...
   

5. If NO candidates found (all done), show insights and ask user:

   ✅ All increments completed!
   
   📊 Quick Status:
   ┌─────────────────────────────────────────────────────────────┐
   │  Active: 0 | Backlog: 0 | Completed: 47 | Archived: 125    │
   │  Last completed: 0167-comprehensive-code-review (2 days ago) │
   └─────────────────────────────────────────────────────────────┘
   
   🔮 Recent completions:
      • 0175-plugin-session-restart-warning (completed 1 day ago)
      • 0174-router-brain-orchestrator (ready_for_review)
      • 0167-comprehensive-code-review (ready_for_review)
   
   💡 What would you like to do?
   
   Options:
     A) Create new increment: /sw:increment "feature name"
     B) Close ready_for_review: /sw:done 0174
     C) Resume from backlog: /sw:resume 0162
     D) View full status: /sw:status
   
   Your choice? [A/B/C/D or type feature name]: _
   

Why This Matters:

• Users shouldn't need to remember increment IDs
• /sw:do should "just work" like /sw:auto
• Smart selection saves context switches

Step 0: Self-Awareness Check

🎯 OPTIONAL BUT RECOMMENDED: Check if running in SpecWeave repository itself.

This step is particularly useful when implementing SpecWeave features vs user projects, as it provides context for:

• Understanding if changes affect the framework
• Being careful with breaking changes
• Considering backward compatibility

import { detectSpecWeaveRepository } from './src/utils/repository-detector.js';

const repoInfo = detectSpecWeaveRepository(process.cwd());

if (repoInfo.isSpecWeaveRepo) {
  console.log('ℹ️  Working on SpecWeave framework increment');
  console.log(`   Confidence: ${repoInfo.confidence}`);
  console.log('');
  console.log('   💡 Reminders:');
  console.log('      • Test changes don\'t break existing user projects');
  console.log('      • Consider backward compatibility');
  console.log('      • Update CLAUDE.md if workflow changes');
  console.log('');
}

When to Show This:

• On first task execution for the increment
• Skip on subsequent tasks (user already knows context)

Why This Helps: Contributors working on SpecWeave itself need different mindset than users building apps:

• Framework changes affect ALL users
• Breaking changes need deprecation warnings
• Documentation updates are critical

Step 1: Load Context

Prerequisite: Increment ID is now available (either from user input or auto-selected in Step 0.5).

1. Find increment directory:

   • Normalize increment ID:
     • If ID contains dash (e.g., "0153-feature-name"), extract numeric portion before first dash → "0153"
     • Convert to 4-digit format (e.g., "1" → "0001", "153" → "0153")
     • Both formats work: /sw:do 0153 or /sw:do 0153-feature-name
   • Find matching directory: .specweave/increments/0001-*/ (matches by prefix)
   • Verify increment exists

2. Load specification and plan:

   • Read spec.md - Understand WHAT and WHY
   • Read plan.md - Understand HOW
   • Read tasks.md - Understand implementation steps
   • Read tests.md - Understand test strategy

3. 🔄 Load Living Docs Context:

   Optional but recommended: Load relevant living documentation context.

   # Extract topic keywords from spec.md title/user stories
   TOPIC=$(grep -m1 "^#" spec.md | sed 's/# //' | tr '[:upper:]' '[:lower:]')
   
   # Check if related living docs exist
   LIVING_DOCS_ROOT=".specweave/docs/internal"
   RELATED_DOCS=$(find "$LIVING_DOCS_ROOT" -name "*${TOPIC}*" -o -name "*${KEYWORD}*" 2>/dev/null)
   

   If related living docs found:

   • Read relevant ADRs from .specweave/docs/internal/architecture/adr/
   • Read relevant specs from .specweave/docs/internal/specs/
   • Read relevant architecture docs from .specweave/docs/internal/architecture/

   Why This Helps:

   • Ensures implementation follows established patterns
   • Avoids contradicting existing ADRs
   • Provides historical context for design decisions
   • References related features for consistency

   Example output:

   📚 Living Docs Context Loaded:
      • ADR-0023: Database Connection Pooling (relevant)
      • spec-005: User Management (related feature)
      • architecture/auth-flow.md (pattern to follow)
   

   Skip if: Living docs don't exist or no relevant docs found

4. Verify readiness:

   • Check status is "planned" (not already in-progress or completed)
   • Check no blocking dependencies
   • Check tasks.md has tasks to execute

5. 🚨 CRITICAL: Task Count Validation (CRASH PREVENTION!):

   MANDATORY: Count task