Implementation Workflow: The /specweave:do Command

The implementation phase is where specs and plans become working code—with SpecWeave handling the tedious parts automatically.

Overview

Duration: Hours to weeks (depending on increment size)

Command: /specweave:do

Magic: Auto-resumes from next incomplete task, updates docs automatically, validates continuously

The /specweave:do Command: Just Works!

/specweave:do

What happens automatically:

Key features:

✅ Smart resume: Picks up where you left off
✅ Auto-doc update: Hooks fire after each task
✅ Progress tracking: Always know what's next
✅ Quality validation: Tests run automatically

Step-by-Step Flow

Step 1: Start Implementation

/specweave:do

CLI output:

📋 Increment: 0012-real-time-chat
📊 Progress: 2/8 tasks (25%)

🔄 Resuming from: T-003 (TypingIndicatorManager)

**AC**: AC-US3-01, AC-US3-02
**Test Plan**: Given user typing → Indicator shown in under 100ms

**Files to create:**
- src/services/chat/TypingIndicatorManager.ts
- tests/unit/typing-indicator.test.ts

**Dependencies**: T-001 (ChatService) ✅

Ready to implement? (Y/n)

Step 2: Implement the Task

TDD approach (optional but recommended):

Example: TDD cycle for TypingIndicatorManager

2a. Write Failing Test

// tests/unit/typing-indicator.test.ts
import { TypingIndicatorManager } from '../../src/services/chat/TypingIndicatorManager';

describe('TypingIndicatorManager', () => {
  it('should send typing indicator within 100ms', async () => {
    const manager = new TypingIndicatorManager();
    const startTime = Date.now();

    await manager.startTyping('chat-123', 'user-456');

    const duration = Date.now() - startTime;
    expect(duration).toBeLessThan(100);
  });

  it('should clear indicator after 3 seconds', async () => {
    const manager = new TypingIndicatorManager();
    const mockCallback = jest.fn();

    manager.on('typingStopped', mockCallback);
    manager.startTyping('chat-123', 'user-456');

    await new Promise(resolve => setTimeout(resolve, 3100));
    expect(mockCallback).toHaveBeenCalled();
  });
});

2b. Run Test (Fails ❌)

npm test
# ❌ Module not found: TypingIndicatorManager

2c. Implement Feature

// src/services/chat/TypingIndicatorManager.ts
export class TypingIndicatorManager {
  private timeouts = new Map<string, NodeJS.Timeout>();
  private eventEmitter = new EventEmitter();

  async startTyping(chatId: string, userId: string): Promise<void> {
    // Clear existing timeout
    this.clearTimeout(chatId);

    // Emit typing event immediately
    this.eventEmitter.emit('typingStarted', { chatId, userId });

    // Set auto-clear timeout (3 seconds)
    const timeout = setTimeout(() => {
      this.stopTyping(chatId, userId);
    }, 3000);

    this.timeouts.set(chatId, timeout);
  }

  stopTyping(chatId: string, userId: string): void {
    this.clearTimeout(chatId);
    this.eventEmitter.emit('typingStopped', { chatId, userId });
  }

  private clearTimeout(chatId: string): void {
    const existing = this.timeouts.get(chatId);
    if (existing) {
      clearTimeout(existing);
      this.timeouts.delete(chatId);
    }
  }

  on(event: string, callback: Function): void {
    this.eventEmitter.on(event, callback);
  }
}

2d. Run Test (Passes ✅)

npm test
# ✅ All tests passing (2/2)

2e. Refactor (Optional)

// Extract timeout duration to constant
const TYPING_TIMEOUT_MS = 3000;

// Add input validation
if (!chatId || !userId) {
  throw new Error('chatId and userId are required');
}

Step 3: Mark Task Complete

# Task automatically marked complete when:
# 1. You signal completion (type "done" or mark in tasks)
# 2. Tests pass
# 3. Code committed

✅ Task T-003 complete!

Post-task hook fires automatically:

Hook actions:

✅ Updates strategy docs (feature status: Implemented)
✅ Updates architecture docs (component details)
✅ Updates ADRs (Proposed → Accepted)
✅ Regenerates C4 diagrams (adds new components)
✅ Commits doc changes with task

Step 4: Continue to Next Task

# SpecWeave automatically shows next task:

✅ T-003 complete!

📋 Next: T-004 (REST API Endpoints)

**AC**: AC-US1-01, AC-US2-01
**Test Plan**: Given chat initiated → Endpoint returns chat ID

Continue? (Y/n)

Step 5: Check Progress Anytime

/specweave:progress

Output:

📊 Increment 0012: Real-Time Chat

Progress: 3/8 tasks (37%)

✅ Completed:
  - T-001: ChatService ✅
  - T-002: MessageRepository ✅
  - T-003: TypingIndicatorManager ✅

🔄 Current:
  - T-004: REST API Endpoints [in_progress]

⏳ Pending:
  - T-005: Frontend Chat Component
  - T-006: Redis Pub/Sub Integration
  - T-007: Reconnection Handling
  - T-008: Documentation + E2E Tests

📈 Test Coverage: 91% (target: 88%)
⏱️  Estimated Remaining: 2-3 days

Implementation Patterns

Pattern 1: Straight-Through Execution

Goal: Complete all tasks without stopping

/specweave:do
# Implement T-001 ✅
# Implement T-002 ✅
# Implement T-003 ✅
# ...
# Implement T-008 ✅

# Result: Increment complete in one session

Best for: Small increments (3-6 tasks), focus time available

Pattern 2: Incremental Progress

Goal: Work in short bursts, pause/resume

# Day 1 morning (2 hours)
/specweave:do
# Complete T-001, T-002 ✅

# Day 1 afternoon (meeting)
# Work paused automatically

# Day 2 morning (3 hours)
/specweave:do  # Auto-resumes from T-003!
# Complete T-003, T-004, T-005 ✅

# Day 3 (finish up)
/specweave:do
# Complete T-006, T-007, T-008 ✅

Best for: Medium/large increments, interrupted workflow

Pattern 3: Parallel Work (Teams)

Goal: Multiple developers work on different tasks

# Developer A
/specweave:do --task T-001
# Works on ChatService

# Developer B
/specweave:do --task T-003
# Works on TypingIndicatorManager (independent)

# Developer C
/specweave:do --task T-005
# Works on Frontend (independent)

# Tasks sync when complete
# No merge conflicts (separate files)

Best for: Large increments, team projects

Handling Challenges

Challenge 1: Test Failures

Problem: Tests fail, can't complete task

npm test
# ❌ FAIL: typing indicator timeout not working

Solution:

# 1. Debug the issue
npm test -- --watch

# 2. Fix the code
vim src/services/chat/TypingIndicatorManager.ts

# 3. Re-run tests
npm test
# ✅ PASS: All tests passing

# 4. Mark task complete
# Hook fires, docs update

Don't:

❌ Skip tests ("I'll fix it later")
❌ Mark task complete with failing tests
❌ Comment out failing tests

Do:

✅ Fix the issue before moving on
✅ Ask for help if stuck
✅ Refine test if it's checking wrong behavior

Challenge 2: Scope Creep

Problem: During implementation, you realize more work is needed

Example:

While implementing ChatService, you discover:
- Need rate limiting (not in spec)
- Need connection pooling (not in spec)
- Need admin monitoring dashboard (not in spec)

Solution:

# 1. Evaluate criticality
# - Is it required for MVP? (P1)
# - Or nice-to-have? (P2/P3)

# 2a. If P1 (must-have):
/specweave:update-scope "Added rate limiting (required for security)"
# Updates spec.md, plan.md, tasks.md
# Regenerates with new tasks

# 2b. If P2/P3 (nice-to-have):
# Document in "Future Enhancements" section
# Create new increment for next iteration
/specweave:increment "0013-chat-admin-dashboard"

Challenge 3: Blocked by Dependencies

Problem: Can't complete task due to external dependency

Example:

T-006: Redis Pub/Sub Integration
Blocked: Redis server not available in dev environment

Solution:

# Option 1: Pause task, work on independent task
/specweave:do --skip T-006
# Works on T-007 instead (independent)

# Option 2: Use mock/stub temporarily
# Create Redis mock for tests
# Document TODO: Replace with real Redis

# Option 3: Pause entire increment
/specweave:pause 0012 --reason="Waiting for Redis setup"
# Resume later when unblocked

Challenge 4: Unforeseen Complexity

Problem: Task is way more complex than estimated

Example:

T-003: TypingIndicatorManager
Estimated: 2 hours
Actual: 8 hours (race conditions, debouncing issues)

Solution:

# 1. Break down into subtasks (if possible)
# T-003a: Basic typing detection
# T-003b: Debouncing logic
# T-003c: Race condition handling

# 2. Document learnings in completion report
/specweave:update-scope "T-003 complexity: race conditions in WebSocket events"

# 3. Adjust estimates for remaining tasks

# 4. Complete the task (don't cut corners)
# Better to take time and do it right

Best Practices

✅ DO

Follow TDD (Red → Green → Refactor)
Commit frequently (after each task or logical unit)
Run tests before marking complete
Update docs as you go (hooks help, but review)
Ask for clarification if spec unclear
Take breaks (Pomodoro: 25 min work, 5 min break)

❌ DON'T

Don't skip tests ("I'll add them later" = never)
Don't work on multiple tasks simultaneously (focus!)
Don't bypass hooks (use /specweave:do, not raw git)
Don't ignore failing tests (fix before moving on)
Don't gold-plate (stick to spec, no bonus features)

Quality Checks During Implementation

SpecWeave runs automatic checks:

Automatic validations:

✅ Test suite runs (all pass)
✅ Coverage target met (per task)
✅ Linting passes (ESLint, Prettier)
✅ Type checking (TypeScript)
✅ Security scan (npm audit)

Commit Strategy

Per-task commits (recommended):

# After completing T-003
git add .
git commit -m "feat(chat): implement typing indicator manager

- Add TypingIndicatorManager with auto-clear timeout
- Debounce keystrokes to prevent spam
- Test coverage: 92% (target: 90%)
- AC-US3-01, AC-US3-02 validated

Task: T-003
Increment: 0012-real-time-chat"

Benefits:

Clear history (one task = one commit)
Easy rollback (revert specific task)
Traceability (task → commit → code)

Interactive Example

Let's walk through implementing T-003 completely:

$ /specweave:do

📋 Increment: 0012-real-time-chat
🔄 Next: T-003 (TypingIndicatorManager)

**Test Plan**: Given user typing → Indicator shown in under 100ms → Clears after 3s

Create tests first (TDD mode)? (Y/n): y

✅ Created: tests/unit/typing-indicator.test.ts (2 tests)

$ npm test
❌ FAIL: Module not found (expected)

Implement the feature now...

$ vim src/services/chat/TypingIndicatorManager.ts
# ... write code ...

$ npm test
✅ PASS: All tests passing (2/2)
✅ Coverage: 92% (target: 90%)

$ git add .
$ git commit -m "feat(chat): implement typing indicator manager..."

🔄 Post-task hook running...
  ✅ Updated living docs (strategy/chat)
  ✅ Updated architecture (hld-chat)
  ✅ Regenerated diagrams (chat-components.mmd)
  ✅ Committed doc changes

✅ T-003 complete! (3/8 tasks done)

📋 Next: T-004 (REST API Endpoints)

Continue? (Y/n):

Summary

Command: /specweave:do (just works!)
Auto-resume: Picks up where you left off
Auto-docs: Hooks update living docs
Quality: Tests + linting + coverage checks
Progress: /specweave:progress anytime
Flexibility: Pause/resume, skip tasks, work in parallel

Next Steps

Implementation complete? Move to validation:

/specweave:validate 0012

Learn more:

Related:

Overview​

The /specweave:do Command: Just Works!​

Step-by-Step Flow​

Step 1: Start Implementation​

Step 2: Implement the Task​

2a. Write Failing Test​

2b. Run Test (Fails ❌)​

2c. Implement Feature​

2d. Run Test (Passes ✅)​

2e. Refactor (Optional)​

Step 3: Mark Task Complete​

Step 4: Continue to Next Task​

Step 5: Check Progress Anytime​

Implementation Patterns​

Pattern 1: Straight-Through Execution​

Pattern 2: Incremental Progress​

Pattern 3: Parallel Work (Teams)​

Handling Challenges​

Challenge 1: Test Failures​

Challenge 2: Scope Creep​

Challenge 3: Blocked by Dependencies​

Challenge 4: Unforeseen Complexity​

Best Practices​

✅ DO​

❌ DON'T​

Quality Checks During Implementation​

Commit Strategy​

Interactive Example​

Summary​

Next Steps​

Overview

The /specweave:do Command: Just Works!

Step-by-Step Flow

Step 1: Start Implementation

Step 2: Implement the Task

2a. Write Failing Test

2b. Run Test (Fails ❌)

2c. Implement Feature

2d. Run Test (Passes ✅)

2e. Refactor (Optional)

Step 3: Mark Task Complete

Step 4: Continue to Next Task

Step 5: Check Progress Anytime

Implementation Patterns

Pattern 1: Straight-Through Execution

Pattern 2: Incremental Progress

Pattern 3: Parallel Work (Teams)

Handling Challenges

Challenge 1: Test Failures

Challenge 2: Scope Creep

Challenge 3: Blocked by Dependencies

Challenge 4: Unforeseen Complexity

Best Practices

✅ DO

❌ DON'T

Quality Checks During Implementation

Commit Strategy

Interactive Example

Summary

Next Steps