TDD Workflow Quick Start

Get started with TaskMaster’s autonomous TDD workflow in 5 minutes.

Prerequisites

TaskMaster initialized project (tm init)
Tasks with subtasks created (tm parse-prd or tm expand)
Git repository with clean working tree
Test framework installed (vitest, jest, mocha, etc.)

1. Start a Workflow

tm autopilot start <taskId>

Example:

$ tm autopilot start 7

✓ Workflow started for task 7
✓ Created branch: task-7
✓ Current phase: RED
✓ Subtask 1/5: Implement start command
→ Next action: Write a failing test

2. The TDD Cycle

RED Phase: Write Failing Test

# Check what to do next
$ tm autopilot next --json
{
  "action": "generate_test",
  "currentSubtask": {
    "id": "1",
    "title": "Implement start command"
  }
}

Write a test that fails:

// tests/start.test.ts
import { describe, it, expect } from 'vitest';
import { StartCommand } from '../src/commands/start';

describe('StartCommand', () => {
  it('should initialize workflow', async () => {
    const command = new StartCommand();
    const result = await command.execute({ taskId: '7' });
    expect(result.success).toBe(true);
  });
});

Run tests:

$ npm test
# ✗ 1 test failed

Complete RED phase:

$ tm autopilot complete --results '{"total":1,"passed":0,"failed":1,"skipped":0}'

✓ RED phase complete
✓ Current phase: GREEN
→ Next action: Implement code to pass tests

GREEN Phase: Implement Feature

Write minimal code to pass:

// src/commands/start.ts
export class StartCommand {
  async execute(options: { taskId: string }) {
    return { success: true };
  }
}

Run tests:

$ npm test
# ✓ 1 test passed

Complete GREEN phase:

$ tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}'

✓ GREEN phase complete
✓ Current phase: COMMIT
→ Next action: Commit changes

COMMIT Phase: Save Progress

$ tm autopilot commit

✓ Created commit: abc123
✓ Message: feat(autopilot): implement start command (Task 7.1)
✓ Advanced to subtask 2/5
✓ Current phase: RED
→ Next action: Write a failing test

3. Continue for All Subtasks

Repeat the RED-GREEN-COMMIT cycle for each subtask until complete.

# Check progress anytime
$ tm autopilot status --json
{
  "taskId": "7",
  "progress": {
    "completed": 1,
    "total": 5,
    "percentage": 20
  },
  "currentSubtask": {
    "id": "2",
    "title": "Implement resume command"
  }
}

4. Complete the Workflow

When all subtasks are done:

$ tm autopilot status --json
{
  "phase": "COMPLETE",
  "progress": {
    "completed": 5,
    "total": 5,
    "percentage": 100
  }
}

Your branch task-7 is ready for review/merge!

Common Patterns

Parse Test Output

Your test runner outputs human-readable format - convert to JSON: Vitest:

Tests  2 failed | 8 passed | 10 total

→ {"total":10,"passed":8,"failed":2,"skipped":0} Jest:

Tests:  2 failed, 8 passed, 10 total

→ {"total":10,"passed":8,"failed":2,"skipped":0}

Handle Errors

Problem: RED phase won’t complete - “no test failures” Solution: Your test isn’t testing new behavior. Make sure it fails:

// Bad - test passes immediately
it('should exist', () => {
  expect(StartCommand).toBeDefined(); // Always passes
});

// Good - test fails until feature exists
it('should initialize workflow', async () => {
  const result = await new StartCommand().execute({ taskId: '7' });
  expect(result.success).toBe(true); // Fails until execute() is implemented
});

Problem: GREEN phase won’t complete - “tests still failing” Solution: Fix your implementation until all tests pass:

# Run tests to see what's failing
$ npm test

# Fix the issue
$ vim src/commands/start.ts

# Verify tests pass
$ npm test

# Try again
$ tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}'

Resume Interrupted Work

# If you interrupted the workflow
$ tm autopilot resume

✓ Workflow resumed
✓ Task 7 - subtask 3/5
✓ Current phase: GREEN
→ Continue from where you left off

JSON Output Mode

All commands support --json for programmatic use:

$ tm autopilot start 7 --json | jq .
{
  "success": true,
  "taskId": "7",
  "branchName": "task-7",
  "phase": "SUBTASK_LOOP",
  "tddPhase": "RED",
  "progress": { ... },
  "currentSubtask": { ... },
  "nextAction": "generate_test"
}

Perfect for:

CI/CD integration
Custom tooling
Automated workflows
Progress monitoring

MCP Integration

For AI agents (Claude Code, etc.), use MCP tools:

// Start workflow
await mcp.call('autopilot_start', {
  taskId: '7',
  projectRoot: '/path/to/project'
});

// Get next action
const next = await mcp.call('autopilot_next', {
  projectRoot: '/path/to/project'
});

// Complete phase
await mcp.call('autopilot_complete_phase', {
  projectRoot: '/path/to/project',
  testResults: { total: 1, passed: 0, failed: 1, skipped: 0 }
});

// Commit
await mcp.call('autopilot_commit', {
  projectRoot: '/path/to/project'
});

See AI Agent Integration Guide for details.

Cheat Sheet

# Start
tm autopilot start <taskId>         # Initialize workflow

# Workflow Control
tm autopilot next                    # What's next?
tm autopilot status                  # Current state
tm autopilot resume                  # Continue interrupted work
tm autopilot abort                   # Cancel and cleanup

# TDD Cycle
tm autopilot complete --results '{...}'   # Advance phase
tm autopilot commit                       # Save progress

# Options
--json                              # Machine-readable output
--project-root <path>               # Specify project location
--force                             # Override safety checks

Next Steps

Read AI Agent Integration Guide for complete documentation
Check Command Reference for all options

Tips

Always let tests fail first - That’s the RED phase
Write minimal code - Just enough to pass
Commit frequently - After each subtask
Use —json - Better for programmatic use
Check status often - Know where you are
Trust the workflow - It enforces TDD rules

Ready to start? Run tm autopilot start <taskId> and begin your TDD journey!

Welcome

Getting Started

Best Practices

Technical Capabilities

AI Providers

TDD Workflow (Autopilot)

TDD Workflow Quick Start

Prerequisites

1. Start a Workflow

2. The TDD Cycle

RED Phase: Write Failing Test

GREEN Phase: Implement Feature

COMMIT Phase: Save Progress

3. Continue for All Subtasks

4. Complete the Workflow

Common Patterns

Parse Test Output

Handle Errors

Resume Interrupted Work

JSON Output Mode

MCP Integration

Cheat Sheet

Next Steps

Tips

​Prerequisites

​1. Start a Workflow

​2. The TDD Cycle

​RED Phase: Write Failing Test

​GREEN Phase: Implement Feature

​COMMIT Phase: Save Progress

​3. Continue for All Subtasks

​4. Complete the Workflow

​Common Patterns

​Parse Test Output

​Handle Errors

​Resume Interrupted Work

​JSON Output Mode

​MCP Integration

​Cheat Sheet

​Next Steps

​Tips

Prerequisites

1. Start a Workflow

2. The TDD Cycle

RED Phase: Write Failing Test

GREEN Phase: Implement Feature

COMMIT Phase: Save Progress

3. Continue for All Subtasks

4. Complete the Workflow

Common Patterns

Parse Test Output

Handle Errors

Resume Interrupted Work

JSON Output Mode

MCP Integration

Cheat Sheet

Next Steps

Tips