do

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:

```bash # 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) ```

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

``bash # 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)) ``

1. Select the best candidate:
2. If in-progress increment exists → use it
3. Else if planned increment exists → use it
4. Else if ready_for_review with incomplete tasks → use it
5. Else if backlog increment exists with incomplete tasks → use it (and change status to in-progress)

1. 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... ```

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

1. Load specification and plan:
2. Read spec.md - Understand WHAT and WHY
3. Read plan.md - Understand HOW
4. Read tasks.md - Understand implementation steps
5. Read tests.md - Understand test strategy

1. 🔄 Load Living Docs Context:

Optional but recommended: Load relevant living documentation context.

```bash # 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

1. Verify readiness:
2. Check status is "planned" (not already in-progress or completed)
3. Check no blocking dependencies
4. Check tasks.md has tasks to execute

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

MANDATORY: Count task