Skip to main content
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

​
Tips

  1. Always let tests fail first - That’s the RED phase
  2. Write minimal code - Just enough to pass
  3. Commit frequently - After each subtask
  4. Use —json - Better for programmatic use
  5. Check status often - Know where you are
  6. Trust the workflow - It enforces TDD rules
Ready to start? Run tm autopilot start <taskId> and begin your TDD journey!
⌘I