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

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 tasks in tasks.md before proceeding.

   TASK_COUNT=$(grep -c "^### T-" .specweave/increments/<id>/tasks.md)
   

   If TASK_COUNT > 25:

   ⚠️ TASK COUNT EXCEEDS SOFT LIMIT
   
   This increment has X tasks (soft limit: 25)
   
   >25 tasks = consider splitting for maintainability (per CLAUDE.md rules)
   
   💡 RECOMMENDED: Split this increment OR execute phase-by-phase:
   
   Option A - Split into separate increments:
   Pattern: 0116-feature/ → Split into:
     • 0116-feature-phase1/ (T-001 to T-008)
     • 0117-feature-phase2/ (T-009 to T-016)
     • 0118-feature-phase3/ (T-017 to T-025)
   
   Option B - Phase-by-phase execution (recommended for 15-25 tasks):
     Execute Phase 1 → validate → continue to Phase 2 → ...
   
   User choice required to proceed.
   

   If TASK_COUNT <= 25: Proceed to next step

6. 🚨 CRITICAL: Validate AC Presence:

   MANDATORY: Run pre-increment-start validation hook to verify spec.md contains ACs.

   Use the Bash tool to run:

   bash plugins/specweave/hooks/pre-increment-start.sh <increment-path>
   # Example: bash plugins/specweave/hooks/pre-increment-start.sh .specweave/increments/0050-feature-name
   

   Expected Output (Success):

   ✅ AC Presence Validation PASSED
      • spec.md contains 39 ACs
      • Matches metadata.json (39 expected)
      • Ready to start implementation
   

   Expected Output (Failure):

   ❌ AC Presence Validation FAILED
      • spec.md contains 0 ACs (expected 39)
      • ACs are REQUIRED for task-AC sync to work
   
   💡 Fix: Run /sw:embed-acs <increment-id>
   

   What to Do After Validation:

   • ✅ If validation passes: Proceed to Step 2
   • ❌ If validation fails: Show error, run

     /sw:embed-acs

     , then retry
   • DO NOT PROCEED without ACs in spec.md (hooks will fail!)

   Why This Matters (ADR-0064):

   • The AC sync hook requires ACs in spec.md to update completion status
   • Without inline ACs, you get 0% AC completion and broken status line
   • Even with external living docs, ACs MUST be embedded in spec.md

Example output:

📂 Loading increment 0001-user-authentication...

✅ Loaded context:
   • spec.md (6 user stories, 15 requirements)
   • plan.md (Architecture: JWT + PostgreSQL)
   • tasks.md (42 tasks, estimated 3-4 weeks)
   • tests.md (12 test cases, 85% coverage)

🎯 Ready to execute!

Step 1.5: Check TDD Mode

Read testMode from metadata.json:

INCREMENT_PATH=".specweave/increments/<id>"
TEST_MODE=$(cat "$INCREMENT_PATH/metadata.json" | jq -r '.testMode // "test-after"')

If TEST_MODE == "TDD", display TDD reminder banner:

┌─────────────────────────────────────────────────────────────┐
│  🔴 TDD MODE ACTIVE                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  This increment uses Test-Driven Development.               │
│                                                             │
│  WORKFLOW:                                                  │
│  1. [RED]      Write failing test FIRST                     │
│  2. [GREEN]    Minimal code to make test pass               │
│  3. [REFACTOR] Improve code, keep tests green               │
│                                                             │
│  ⚠️  GREEN tasks depend on their RED counterpart!           │
│  💡 Tip: Use /sw:tdd-cycle for guided workflow              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

When executing tasks, detect and display current phase:

CURRENT_TASK_TITLE="T-001: [RED] Write failing test for login"

if [[ "$CURRENT_TASK_TITLE" == *"[RED]"* ]]; then
  PHASE="🔴 RED - Writing failing test"
elif [[ "$CURRENT_TASK_TITLE" == *"[GREEN]"* ]]; then
  PHASE="🟢 GREEN - Making test pass"
elif [[ "$CURRENT_TASK_TITLE" == *"[REFACTOR]"* ]]; then
  PHASE="🔵 REFACTOR - Improving code quality"
else
  PHASE=""  # Not a TDD task
fi

if [ -n "$PHASE" ]; then
  echo "Current Phase: $PHASE"
fi

Skip TDD banner if:

• testMode

  is not "TDD"
• Already showed banner in current session

Step 1.5.5: TDD Marker Validation (CRITICAL when TDD mode is enabled)

🚨 CRITICAL: When TDD mode is active, verify tasks.md has TDD markers!

This step MUST run BEFORE Step 1.6 enforcement to catch the case where TDD is enabled but tasks were NOT generated with

/sw:increment

Check for TDD markers in tasks.md:

INCREMENT_PATH=".specweave/increments/<id>"
TASKS_FILE="$INCREMENT_PATH/tasks.md"

# Count TDD markers
RED_COUNT=$(grep -c '\[RED\]' "$TASKS_FILE" 2>/dev/null || echo "0")
GREEN_COUNT=$(grep -c '\[GREEN\]' "$TASKS_FILE" 2>/dev/null || echo "0")
REFACTOR_COUNT=$(grep -c '\[REFACTOR\]' "$TASKS_FILE" 2>/dev/null || echo "0")
TOTAL_MARKERS=$((RED_COUNT + GREEN_COUNT + REFACTOR_COUNT))

echo "TDD Markers found: RED=$RED_COUNT, GREEN=$GREEN_COUNT, REFACTOR=$REFACTOR_COUNT"

If TDD mode is enabled BUT no markers found (TOTAL_MARKERS == 0):

function validateTDDMarkers(tasksContent: string, tddMode: string, tddEnforcement: string): void {
  if (tddMode !== 'TDD') return; // Not TDD mode, skip

  const hasRedMarkers = tasksContent.includes('[RED]');
  const hasGreenMarkers = tasksContent.includes('[GREEN]');
  const hasRefactorMarkers = tasksContent.includes('[REFACTOR]');

  if (!hasRedMarkers && !hasGreenMarkers && !hasRefactorMarkers) {
    // TDD mode enabled but NO markers in tasks.md!
    const message = `
⚠️  TDD MODE ENABLED BUT TASKS LACK TDD MARKERS

Your config has TDD mode enabled:
  testing.defaultTestMode: "TDD"

But tasks.md has NO [RED], [GREEN], [REFACTOR] markers.

This means TDD enforcement CANNOT work because:
  • /sw:do checks task markers to enforce order
  • Without markers, enforcement is silently bypassed

CAUSE: Tasks were likely created manually or before TDD was enabled.

FIX OPTIONS:
  1. (Recommended) Regenerate tasks with /sw:increment
     This will create proper RED→GREEN→REFACTOR triplets

  2. Add markers manually to existing tasks:
     ### T-001: [RED] Write failing test for feature X
     ### T-002: [GREEN] Implement feature X to pass test
     ### T-003: [REFACTOR] Clean up feature X code

  3. Disable TDD mode:
     Set testing.defaultTestMode: "test-after" in config.json
`;

    if (tddEnforcement === 'strict') {
      console.error(message);
      console.error('❌ BLOCKED: Cannot proceed without TDD markers in strict mode.');
      console.error('   Fix tasks.md or change tddEnforcement to "warn".');
      throw new Error('TDD_MARKERS_MISSING');
    } else if (tddEnforcement === 'warn') {
      console.warn(message);
      console.warn('⚠️  Proceeding without TDD enforcement (warn mode)...');
    }
    // If tddEnforcement === 'off', silently continue
  }
}

Enforcement behavior:

strict

warn

off

Example output (strict mode, no markers):

❌ TDD MARKER VALIDATION FAILED

TDD mode is enabled (testing.defaultTestMode: "TDD")
But tasks.md has 0 TDD markers:
  • [RED] markers: 0
  • [GREEN] markers: 0
  • [REFACTOR] markers: 0

This means TDD discipline CANNOT be enforced!

💡 To fix, choose one:
   1. /sw:increment "feature-name"  ← Regenerate with TDD tasks
   2. Add [RED]/[GREEN]/[REFACTOR] markers to task titles
   3. Set tddEnforcement: "warn" to proceed anyway

Blocked in strict mode. Fix markers or change enforcement level.

Example output (warn mode, no markers):

⚠️  TDD MARKERS MISSING

TDD mode is enabled but tasks.md lacks [RED]/[GREEN]/[REFACTOR] markers.
TDD enforcement is effectively DISABLED for this increment.

💡 For proper TDD discipline, regenerate tasks: /sw:increment "feature"

Proceeding without enforcement (warn mode)...

When this validation passes:

• TDD mode not enabled → Skip (no validation needed)
• TDD mode enabled + markers found → Pass (proceed to Step 1.6)
• TDD mode enabled + no markers + strict → Block (user must fix)
• TDD mode enabled + no markers + warn → Warn and proceed
• TDD mode enabled + no markers + off → Silent pass

Step 1.6: TDD Enforcement (MANDATORY when TDD mode is enabled)

🚨 CRITICAL: When TDD mode is active, enforce RED→GREEN→REFACTOR order!

Read enforcement level from config.json:

CONFIG_PATH=".specweave/config.json"
TDD_ENFORCEMENT=$(cat "$CONFIG_PATH" | jq -r '.testing.tddEnforcement // "warn"')
# Values: "strict" (blocks), "warn" (allows but warns), "off" (no checks)

Before marking ANY task as complete, check TDD discipline:

function checkTDDViolation(currentTask: Task, allTasks: Task[]): TDDViolation | null {
  // Only check if task has TDD phase marker
  const phase = extractPhase(currentTask.title); // [RED], [GREEN], [REFACTOR]
  if (!phase) return null;

  // Find related tasks in the same triplet (e.g., T-001, T-002, T-003)
  const tripletBase = Math.floor((currentTask.number - 1) / 3) * 3 + 1;

  if (phase === 'GREEN') {
    // GREEN requires RED to be completed first
    const redTask = allTasks.find(t =>
      t.number === tripletBase && t.title.includes('[RED]')
    );
    if (redTask && redTask.status !== 'completed') {
      return {
        type: 'GREEN_BEFORE_RED',
        message: `Cannot complete GREEN task (${currentTask.id}) before RED task (${redTask.id})`,
        redTaskId: redTask.id,
      };
    }
  }

  if (phase === 'REFACTOR') {
    // REFACTOR requires GREEN to be completed first
    const greenTask = allTasks.find(t =>
      t.number === tripletBase + 1 && t.title.includes('[GREEN]')
    );
    if (greenTask && greenTask.status !== 'completed') {
      return {
        type: 'REFACTOR_BEFORE_GREEN',
        message: `Cannot complete REFACTOR task (${currentTask.id}) before GREEN task (${greenTask.id})`,
        greenTaskId: greenTask.id,
      };
    }
  }

  return null; // No violation
}

Enforcement behavior based on level:

strict

warn

off

Example output (strict mode):

❌ TDD ENFORCEMENT BLOCKED

You attempted to complete: T-002: [GREEN] Implement login handler
But its RED counterpart is not done: T-001: [RED] Write login test

TDD DISCIPLINE REQUIRES:
  1. 🔴 RED - Write failing test FIRST
  2. 🟢 GREEN - Then implement to pass
  3. 🔵 REFACTOR - Then improve code

💡 Complete T-001 first, then come back to T-002.
   Or disable strict enforcement: Set tddEnforcement: "warn" in config.json

Example output (warn mode):

⚠️  TDD DISCIPLINE WARNING

Completing T-002 [GREEN] before T-001 [RED] violates TDD discipline.

TDD works best when you:
  1. Write the failing test first (RED)
  2. Then implement just enough to pass (GREEN)

Proceeding anyway... (set tddEnforcement: "strict" to block)

When to check:

• ✅ Before marking any [GREEN] or [REFACTOR] task complete
• ❌ Skip check for [RED] tasks (they can be completed freely)
• ❌ Skip check for non-TDD tasks (no phase marker)

Step 2: Smart Resume - Find Next Incomplete Task

🎯 CRITICAL: Auto-resume functionality - no need to remember which task you were on!

1. Parse tasks.md:

   • Scan all tasks in order
   • Check completion status (

     [x]

     = complete,

     [ ]

     = incomplete)
   • Extract model hints (⚡ haiku, 🧠 sonnet, 💎 opus)
   • Find first incomplete task

2. Determine starting point:

   • If all tasks complete → Show completion message
   • If tasks incomplete → Resume from first incomplete task
   • If no tasks started → Start from T001

3. Show resume context with model optimization:

   📊 Resume Context:
   
   Completed: 3/12 tasks (25%)
   ├─ [✅] T001: ⚡ haiku - Setup auth module (P1) [saved $0.14]
   ├─ [✅] T002: ⚡ haiku - Create user model (P1) [saved $0.14]
   ├─ [✅] T003: 💎 opus - Implement JWT tokens (P1)
   └─ [⏳] T004: ⚡ haiku - Add password hashing (P1) ← RESUMING HERE
   
   Remaining: 9 tasks (estimated 2 weeks)
   Cost savings so far: $0.28 (67% cheaper than all-Opus)
   

Why smart resume?

• ✅ No manual tracking needed
• ✅ Seamlessly continue after breaks
• ✅ Prevents duplicate work
• ✅ Shows progress at a glance
• ✅ Cost optimization through smart model selection

Step 3: Update Status to In-Progress (if needed)

If status is "planned", update

spec.md

---
increment: 0001-user-authentication
status: in-progress      # ← Changed from "planned"
started: 2025-10-28      # ← Start date
---

If already "in-progress", keep existing metadata.

Step 4: Execute Tasks Sequentially

For each task in tasks.md:

1. Read task details:

   • Task ID (T001, T002, etc.)
   • Model hint (⚡ haiku, 🧠 sonnet, 💎 opus)
   • Description
   • Acceptance criteria
   • File paths affected
   • Implementation notes

2. Select execution model:

   • Use model from task hint (recommended, optimizes cost/speed)
   • OR use

     --model

     override if specified by user
   • Show selected model and reasoning

3. Execute task:

   • Follow plan.md architecture
   • Implement using detected tech stack
   • Write clean, maintainable code
   • Add inline documentation
   • Track cost savings when using Haiku

4. Mark task complete in tasks.md:

   • Change

     [ ]

     →

     [x]

   • Add completion timestamp
   • Note any deviations from plan

5. 🔥 CRITICAL: After EVERY task completion:

   Step A: Hook executes automatically (via .claude/hooks.json):

   • 🔊 Plays completion sound (Glass.aiff on macOS)
   • 📝 Shows reminder message
   • ✅ This happens automatically when you mark task complete

   Step B: Update GitHub Issue (if GitHub plugin enabled):

   • Close task GitHub issue (#43, #44, etc.)
   • Check off task in epic issue
   • Post completion comment with stats:
     • Files modified (+lines/-lines)
     • Tests passing
     • Actual vs estimated duration
     • Brief summary of changes
     • Next task
   • Update epic progress (X/Y tasks completed, Z%)
   • Add 'in-progress' label to epic (if first task)

   Example GitHub sync:

   🔗 Syncing to GitHub...
      ✓ Closed task issue #43
      ✓ Checked off [T-001] in epic #42
      ✓ Posted completion comment
      ✓ Updated epic progress: 7/48 tasks (15%)
   

   Step C: Update project documentation inline:

   • Update CLAUDE.md if task added:
     • New commands or CLI flags
     • New file structure
     • New configuration options
     • New skills or agents
   • Update README.md if task added:
     • User-facing features
     • Installation steps
     • Usage examples
     • API changes
   • Update CHANGELOG.md if task added:
     • Public API changes
     • Breaking changes
     • New features
   • Update API docs if task is API-related (only if

     apiDocs.enabled

     in config):
     • New endpoint → Update openapi.yaml (or regenerate from decorators)
     • On increment close → Generate postman-collection.json from OpenAPI

   Step D: Continue to next task:

   • Do NOT call

     /sw:sync-docs

     yet (wait until all tasks complete)
   • Move to next incomplete task

Example task execution:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK T001: Create User model (PostgreSQL)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Task details:
   • File: src/models/User.ts
   • Model: ⚡ haiku (clear instructions, specific file path)
   • Description: Create User model with Prisma
   • Acceptance: Model has id, email, passwordHash, createdAt fields

⚡ Executing with Haiku (3x faster, ~$0.0025 vs $0.15 Opus)...
   ✓ Created src/models/User.ts
   ✓ Added Prisma schema definition
   ✓ Generated migration file
   ✓ Added inline documentation

✅ Task T001 completed
💰 Cost savings: $0.1475 (98% cheaper than Opus)

🔊 [Glass.aiff plays automatically via hook]
🔔 Task completed! Remember to update documentation...

🔗 Syncing to GitHub (if enabled):
   ✓ Closed task issue #43
   ✓ Checked off [T-001] in epic #42
   ✓ Posted completion comment to #43
   ✓ Updated epic #42 progress: 1/42 tasks (2%)

📝 Updating project documentation:
   ✓ Updated CLAUDE.md (added User model to schema reference)
   ✓ Updated README.md (added database section with example)
   ✓ No CHANGELOG.md update needed (internal model)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Progress: 1/42 tasks (2%) | Cost savings so far: $0.05 | Estimated remaining: 3.9 weeks

Moving to next task...

Step 4: Handle Blockers

If a task cannot be completed:

1. Document blocker:

   • Add to tasks.md as note
   • Explain reason (missing dependency, unclear requirement, etc.)

2. Ask user for clarification:

   • Present blocker clearly
   • Offer solutions or alternatives
   • Wait for user decision

3. Continue or pause:

   • Skip to next task if blocker is non-blocking
   • Pause if blocker is critical

Example blocker:

⚠️ Blocker on Task T012: "Add email verification"

Issue: Email service provider not specified in plan.md

Options:
  A) Use SendGrid (recommended, $15/month)
  B) Use AWS SES (cheaper, $1/1000 emails)
  C) Use SMTP (self-hosted, free but complex)
  D) Skip for now, add as new task later

Your choice? [A/B/C/D]: _

Step 5: Run Tests Continuously

After completing tasks that affect testable functionality:

1. Run relevant tests:

   • Unit tests for the module
   • Integration tests if applicable
   • Show pass/fail status

2. If tests fail:

   • Show error details
   • Fix immediately
   • Re-run tests
   • Continue only when tests pass

Example test run:

🧪 Running tests for auth module...

  ✓ User model validation
  ✓ Password hashing
  ✗ JWT token generation (FAILED)
    Expected token to expire in 24h, got 1h

🔧 Fixing test failure...
   • Updated JWT expiry config in plan.md
   • Fixed token generation in src/auth/jwt.ts

Re-running tests...

  ✓ JWT token generation

✅ All tests passing (3/3)

Step 6: Progress Tracking

Show progress regularly:

📊 Increment Progress: 0001-user-authentication

Tasks completed: 15/42 (36%)
Time elapsed: 1.2 weeks
Estimated remaining: 2.1 weeks
On track: ✅ Yes

Current phase: Backend Implementation
Next phase: Frontend Integration

Recent completions:
  ✓ T012: Add email verification (2h ago)
  ✓ T013: Implement password reset (1h ago)
  ✓ T014: Add rate limiting (30m ago)

Up next:
  [ ] T015: Create login API endpoint
  [ ] T016: Add JWT middleware

Step 7: Completion Check

When all tasks marked complete:

🎉 All tasks completed!

✅ Tasks: 42/42 (100%)
⏱️  Time taken: 3.2 weeks (vs estimated 3-4 weeks)

🔊 [Playing celebration sound...]

📝 Now syncing implementation learnings to living docs...

CRITICAL: Now run

/sw:sync-docs update

/sw:sync-docs update

This will:

• Update ADRs with implementation details (Proposed → Accepted)
• Update API documentation with actual endpoints
• Update architecture diagrams with actual system
• Update feature lists with completed features
• May prompt for conflict resolution if needed

After

/sw:sync-docs update

✅ Living documentation synchronized!

Next steps:
1. Run full test suite: npm test
2. Validate increment: /sw:validate 0001 --quality
3. Close increment: /sw:done 0001 (PM validates before closing)

Hook Integration (CRITICAL!)

Post-Task Completion Hook runs after EVERY task via

.claude/hooks.json

Configuration

File:

.claude/hooks.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "TodoWrite",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/post-task-completion.sh"
          }
        ]
      }
    ]
  }
}

Hook Script:

.claude/hooks/post-task-completion.sh

#!/bin/bash
# Plays completion sound and outputs reminder JSON
# Output: {"continue": true, "systemMessage": "Task completed! Update docs..."}

Hook Behavior

After EVERY task completion (via TodoWrite):

1. Play sound synchronously:

   • macOS: Glass.aiff via

     afplay

   • Linux: complete.oga via

     paplay

   • Windows: chimes.wav via PowerShell
   • Sound plays BEFORE Claude continues

2. Show reminder:

   • JSON systemMessage displayed to user
   • Reminds to update CLAUDE.md, README.md inline

3. Log completion:

   • Appends to

     .specweave/logs/tasks.log

Documentation Updates (Manual)

After each task, Claude should manually update:

• CLAUDE.md: New commands, file structure, config options, skills, agents
• README.md: User-facing features, installation, usage, API changes
• CHANGELOG.md: Public API changes, breaking changes, new features

Living docs sync (via

/sw:sync-docs update

• Only after ALL tasks complete
• Updates

  .specweave/docs/

  with implementation learnings
• Updates ADRs from Proposed → Accepted
• Updates architecture diagrams with actual system

Examples

Example 1: Execute Complete Increment

/sw:do 0001

Output:

📂 Loading increment 0001-user-authentication...

✅ Context loaded (spec.md, plan.md, tasks.md, tests.md)

🔨 Starting execution (42 tasks)...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task T001: Create User model
✅ Completed | 🪝 Docs updated
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[... continues for all 42 tasks ...]

🎉 All tasks completed (42/42)

Next: /sw:validate 0001 --quality

Example 2: Execute with Blocker

/sw:do 0002

Output:

📂 Loading increment 0002-payment-processing...

🔨 Executing tasks...

Task T005: Integrate Stripe payment
⚠️ Blocker: Stripe API key not in .env

Options:
  A) Add API key now (provide test key)
  B) Skip for now, add as separate task
  C) Use mock payment provider

Your choice? [A/B/C]: _

Example 3: Execute with Test Failure

/sw:do 0003

Output:

📂 Loading increment 0003-reporting-dashboard...

Task T008: Add CSV export
✅ Completed

🧪 Running tests...
  ✗ CSV export test failed
    Expected: 1000 rows
    Got: 999 rows (off-by-one error)

🔧 Fixing test failure...
   • Fixed loop boundary in src/reports/csv.ts

✅ Tests now passing (12/12)

🪝 Docs updated

Next task: T009

Error Handling

Increment Not Found

❌ Error: Increment 0001 not found

Available increments:
  • 0002-core-enhancements (planned)
  • 0003-payment-processing (in-progress)

Usage: /sw:do <increment-id>

Increment Not Planned

❌ Error: Cannot execute increment 0001 (status: backlog)

Increment must be "planned" before execution.

Run: /sw:increment "User authentication" to plan this increment first.

No Tasks to Execute

⚠️ Warning: No tasks found in tasks.md

This usually means:
  1. Tasks weren't auto-generated from plan.md
  2. Tasks.md is empty or missing

Options:
  1. Re-plan increment: /sw:increment 0001 (regenerate tasks)
  2. Add tasks manually: Edit .specweave/increments/0001-name/tasks.md

Related Commands

• /increment

  : Plan increment (creates spec.md, plan.md, tasks.md)

• /validate

  : Validate quality before executing

• /specweave done

  : Close increment (PM validates completion)

• /list-increments

  : List all increments with status

Related Skills

• context-loader

  : Loads relevant context (70% token reduction)

• nodejs-backend

  : Node.js implementation knowledge

• python-backend

  : Python implementation knowledge

• nextjs

  : Next.js implementation knowledge

• frontend

  : React/Vue/Angular implementation knowledge

🔐 Auto-Execute with Credentials (MANDATORY)

When executing deployment tasks, ALWAYS follow auto-execute rules:

The Golden Rule

❌ FORBIDDEN: "Next Steps: Run wrangler deploy"
❌ FORBIDDEN: "Execute the schema in Supabase SQL Editor"
❌ FORBIDDEN: "Set secret via: wrangler secret put..."

✅ REQUIRED: Execute commands DIRECTLY using available credentials

Before Any Deployment Task

# Always check for credentials FIRST (presence only - never display values!):
grep -qE "SUPABASE|DATABASE_URL|CF_|AWS_|HETZNER" .env 2>/dev/null && echo "Credentials found in .env"
wrangler whoami 2>/dev/null
aws sts get-caller-identity 2>/dev/null
gh auth status 2>/dev/null

Auto-Execute Decision

Example: Supabase Migration Task

If DATABASE_URL exists in .env:

source .env
psql "$DATABASE_URL" -f src/db/schema.sql
echo "✅ Schema applied successfully"

If DATABASE_URL missing:

🔐 **Credential Required**

I need your Supabase database URL to execute the migration.

**Please paste your DATABASE_URL:**
[I will save to .env and execute automatically]

See:

plugins/specweave/skills/auto-execute/SKILL.md

Why "/do" instead of "/do"?

Universal applicability: SpecWeave isn't just for software engineering!

• Software projects: Writing code, tests, documentation
• Writing projects: Chapters, articles, research papers
• Design projects: Mockups, prototypes, design systems
• Business projects: Reports, analyses, presentations
• Creative projects: Scripts, storyboards, content

"/do" works for any domain - it's about executing the planned work, whatever that work may be.

Important: This command is designed for continuous execution. It's normal to run

/sw:do

Best Practice: Always run

/sw:validate 0001 --quality

/sw:done