AI Agent Integration Guide

Complete guide for integrating AI agents with TaskMaster’s autonomous TDD workflow system.

Overview

TaskMaster provides a complete TDD workflow orchestration system that enables AI agents to autonomously implement features following strict Test-Driven Development practices. The system manages workflow state, git operations, test validation, and progress tracking.

Key Features

TDD State Machine: Enforces RED → GREEN → COMMIT cycle
Git Integration: Automated branch creation, commits with metadata
Test Validation: Ensures RED phase has failures, GREEN phase passes
Progress Tracking: Subtask completion, attempt counting, error logging
State Persistence: Automatic workflow state management
Dual Interface: CLI commands and MCP tools for flexibility

Architecture

┌─────────────────────────────────────────────────────┐
│                   AI Agent                          │
│  (Claude Code, Custom Agent, etc.)                  │
└─────────────┬───────────────────────────────────────┘
              │
              │ Uses CLI or MCP
              │
┌─────────────▼───────────────────────────────────────┐
│            TaskMaster Interface                      │
│  ┌──────────────┐         ┌──────────────┐         │
│  │ CLI Commands │         │  MCP Tools   │         │
│  └──────┬───────┘         └──────┬───────┘         │
└─────────┼────────────────────────┼─────────────────┘
          │                        │
┌─────────▼────────────────────────▼─────────────────┐
│         WorkflowOrchestrator (Core)                 │
│  ┌─────────────────────────────────────────────┐   │
│  │  State Machine: RED → GREEN → COMMIT        │   │
│  └─────────────────────────────────────────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │GitAdapter│  │TestResult│  │CommitMessage │    │
│  │          │  │Validator │  │Generator     │    │
│  └──────────┘  └──────────┘  └──────────────┘    │
└────────────────────────────────────────────────────┘
          │
          │ Persists to
          │
┌─────────▼───────────────────────────────────────────┐
│  .taskmaster/workflow-state.json                     │
└──────────────────────────────────────────────────────┘

Component Responsibilities

WorkflowOrchestrator

Manages TDD state machine transitions
Tracks current subtask and progress
Enforces workflow rules and validations
Emits events for state changes

GitAdapter

Creates and manages workflow branches
Stages files and creates commits
Validates git repository state
Provides safety checks (clean working tree, etc.)

TestResultValidator

Validates RED phase has test failures
Validates GREEN phase has all tests passing
Parses test results from various formats

CommitMessageGenerator

Generates conventional commit messages
Embeds workflow metadata (subtask ID, phase, etc.)
Follows project commit conventions

Getting Started

Prerequisites

TaskMaster initialized project with subtasks
Git repository with clean working tree
Test framework configured (vitest, jest, etc.)

Quick Start

# 1. Initialize workflow for a task
tm autopilot start 7

# 2. Check what to do next
tm autopilot next

# 3. Write failing test (RED phase)
# ... create test file ...

# 4. Run tests and complete RED phase
tm autopilot complete --results '{"total":1,"passed":0,"failed":1,"skipped":0}'

# 5. Implement code to pass tests (GREEN phase)
# ... write implementation ...

# 6. Run tests and complete GREEN phase
tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}'

# 7. Commit changes
tm autopilot commit

# 8. Repeat for next subtask (automatically advanced)
tm autopilot next

CLI Commands

All commands support --json flag for machine-readable output.

`tm autopilot start <taskId>`

Initialize a new TDD workflow for a task. Options:

--max-attempts <number>: Maximum attempts per subtask (default: 3)
--force: Force start even if workflow exists
--project-root <path>: Project root directory
--json: Output JSON

Example:

tm autopilot start 7 --max-attempts 5 --json

JSON Output:

{
  "success": true,
  "message": "Workflow started for task 7",
  "taskId": "7",
  "branchName": "task-7",
  "phase": "SUBTASK_LOOP",
  "tddPhase": "RED",
  "progress": {
    "completed": 0,
    "total": 5,
    "percentage": 0
  },
  "currentSubtask": {
    "id": "1",
    "title": "Implement start command",
    "status": "in-progress",
    "attempts": 0
  },
  "nextAction": "generate_test"
}

`tm autopilot resume`

Resume a previously started workflow from saved state. Example:

tm autopilot resume --json

`tm autopilot next`

Get the next action to perform with detailed context. JSON Output:

{
  "action": "generate_test",
  "actionDescription": "Write a failing test for the current subtask",
  "phase": "SUBTASK_LOOP",
  "tddPhase": "RED",
  "taskId": "7",
  "branchName": "task-7",
  "progress": {
    "completed": 0,
    "total": 5,
    "current": 1,
    "percentage": 0
  },
  "currentSubtask": {
    "id": "1",
    "title": "Implement start command",
    "status": "in-progress",
    "attempts": 0,
    "maxAttempts": 3
  },
  "expectedFiles": ["test file"],
  "context": {
    "canProceed": false,
    "errors": []
  }
}

`tm autopilot status`

Get comprehensive workflow progress and state information. Example:

tm autopilot status --json

`tm autopilot complete`

Complete the current TDD phase with test result validation. Options:

--results <json>: Test results JSON string

Example:

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

Validation Rules:

RED Phase: Must have at least one failing test
GREEN Phase: All tests must pass (failed === 0)

`tm autopilot commit`

Create a git commit with enhanced message generation. Options:

--message <text>: Custom commit message (optional)
--files <paths...>: Specific files to stage (optional)

Example:

tm autopilot commit --json

`tm autopilot abort`

Abort the workflow and clean up state (preserves git branch and code). Example:

tm autopilot abort --force --json

MCP Tools

MCP tools provide the same functionality as CLI commands for programmatic integration.

`autopilot_start`

Parameters:

{
  taskId: string;          // Required: Task ID (e.g., "7", "2.3")
  projectRoot: string;     // Required: Absolute path to project
  tag?: string;            // Optional: Tag context
  maxAttempts?: number;    // Optional: Default 3
  force?: boolean;         // Optional: Default false
}

Returns:

{
  success: boolean;
  message: string;
  taskId: string;
  branchName: string;
  phase: WorkflowPhase;
  tddPhase: TDDPhase;
  progress: {
    completed: number;
    total: number;
    percentage: number;
  };
  currentSubtask: SubtaskInfo | null;
  nextAction: string;
}

`autopilot_resume`

Parameters:

{
  projectRoot: string;  // Required: Absolute path to project
}

`autopilot_next`

Parameters:

{
  projectRoot: string;  // Required: Absolute path to project
}

Returns:

{
  action: string;              // 'generate_test' | 'implement_code' | 'commit_changes'
  actionDescription: string;
  phase: WorkflowPhase;
  tddPhase: TDDPhase;
  taskId: string;
  branchName: string;
  progress: ProgressInfo;
  currentSubtask: SubtaskInfo | null;
  expectedFiles: string[];
  context: {
    canProceed: boolean;
    errors: string[];
  };
}

`autopilot_status`

Parameters:

{
  projectRoot: string;  // Required: Absolute path to project
}

Returns:

{
  taskId: string;
  branchName: string;
  phase: WorkflowPhase;
  tddPhase: TDDPhase;
  progress: ProgressInfo;
  currentSubtask: SubtaskInfo | null;
  subtasks: SubtaskInfo[];
  errors: string[];
  metadata: Record<string, any>;
  canProceed: boolean;
}

`autopilot_complete_phase`

Parameters:

{
  projectRoot: string;  // Required: Absolute path to project
  testResults: {
    total: number;      // Required: Total tests
    passed: number;     // Required: Passing tests
    failed: number;     // Required: Failing tests
    skipped?: number;   // Optional: Skipped tests
  };
}

`autopilot_commit`

Parameters:

{
  projectRoot: string;     // Required: Absolute path to project
  files?: string[];        // Optional: Files to stage
  customMessage?: string;  // Optional: Custom commit message
}

`autopilot_abort`

Parameters:

{
  projectRoot: string;  // Required: Absolute path to project
}

Workflow Phases

Phase Diagram

PREFLIGHT → BRANCH_SETUP → SUBTASK_LOOP → FINALIZE → COMPLETE
                                   ↓
                          RED → GREEN → COMMIT
                           ↑              ↓
                           └──────────────┘
                             (Next Subtask)

Phase Descriptions

PREFLIGHT

Validate task has subtasks
Check git repository state
Verify preconditions

BRANCH_SETUP

Create workflow branch: task-{taskId}
Checkout new branch
Initialize workflow context

SUBTASK_LOOP

RED Phase: Write failing tests
- Action: generate_test
- Validation: At least one test must fail
- Files: Test files
GREEN Phase: Implement code
- Action: implement_code
- Validation: All tests must pass
- Files: Implementation files
COMMIT Phase: Create commit
- Action: commit_changes
- Auto-generates commit message
- Advances to next subtask

FINALIZE

All subtasks complete
Workflow ready for review/merge

COMPLETE

Workflow finished
State can be cleaned up

Responsibility Matrix

Clear division of responsibilities between AI Agent and TaskMaster.

Responsibility	AI Agent	TaskMaster
Workflow Orchestration		✓
Start/resume workflow	Call CLI/MCP	Execute & validate
Track workflow state	Read state	Persist state
Manage TDD phases	Request transitions	Enforce transitions
Validate phase completion		✓ (RED must fail, GREEN must pass)
Test Management
Write test code	✓
Run tests	✓
Parse test output	✓
Report test results	Provide JSON	Validate results
Implementation
Write implementation code	✓
Ensure tests pass	✓
Follow TDD cycle	✓ (guided by TaskMaster)	Enforce rules
Git Operations
Create workflow branch	Request	✓ Execute
Stage files	Request (optional)	✓ Execute
Generate commit messages		✓
Create commits	Request	✓ Execute
Progress Tracking
Query progress	Call status	✓ Provide data
Advance subtasks		✓ (automatic on commit)
Count attempts		✓
Log activity		✓

AI Agent Responsibilities

Read and understand subtask requirements
Write test code that validates the requirement
Run test suite using project’s test command
Parse test output into JSON format
Report results to TaskMaster for validation
Write implementation to satisfy tests
Request commits when GREEN phase complete
Handle errors and retry within attempt limits

TaskMaster Responsibilities

Manage workflow state machine
Enforce TDD rules (RED must fail, GREEN must pass)
Track progress (completed, current, attempts)
Create git commits with enhanced messages
Manage git branches and repository safety
Validate transitions between phases
Persist state for resumability
Generate reports and activity logs

Examples

Complete TDD Cycle Example

1. Start Workflow

$ tm autopilot start 7 --json

{
  "success": true,
  "taskId": "7",
  "branchName": "task-7",
  "tddPhase": "RED",
  "currentSubtask": {
    "id": "1",
    "title": "Implement start command",
    "status": "in-progress"
  },
  "nextAction": "generate_test"
}

2. Get Next Action

$ tm autopilot next --json

{
  "action": "generate_test",
  "actionDescription": "Write a failing test for the current subtask",
  "tddPhase": "RED",
  "currentSubtask": {
    "id": "1",
    "title": "Implement start command"
  }
}

3. Write Failing Test

AI Agent creates tests/start.test.ts:

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

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

4. Run Tests (Should Fail)

$ npm test
# Output: 1 test failed (expected)

Parse output to JSON:

{
  "total": 1,
  "passed": 0,
  "failed": 1,
  "skipped": 0
}

5. Complete RED Phase

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

{
  "success": true,
  "message": "Completed RED phase",
  "previousPhase": "RED",
  "currentPhase": "GREEN",
  "nextAction": "implement_code"
}

6. Implement Code

AI Agent creates src/commands/start.ts:

export class StartCommand {
  async execute(options: { taskId: string }) {
    // Implementation that makes test pass
    return {
      success: true,
      branchName: `task-${options.taskId}`
    };
  }
}

7. Run Tests (Should Pass)

$ npm test
# Output: 1 test passed

Parse output:

{
  "total": 1,
  "passed": 1,
  "failed": 0,
  "skipped": 0
}

8. Complete GREEN Phase

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

{
  "success": true,
  "previousPhase": "GREEN",
  "currentPhase": "COMMIT",
  "nextAction": "commit_changes"
}

9. Commit Changes

$ tm autopilot commit --json

{
  "success": true,
  "commit": {
    "hash": "abc123",
    "message": "feat(autopilot): implement start command (Task 7.1)\n\n..."
  },
  "subtaskCompleted": "1",
  "currentSubtask": {
    "id": "2",
    "title": "Implement resume command"
  },
  "nextAction": "generate_test"
}

MCP Integration Example

// AI Agent using MCP tools

async function implementTask(taskId: string) {
  // Start workflow
  const start = await mcp.call('autopilot_start', {
    taskId,
    projectRoot: '/path/to/project'
  });

  console.log(`Started task ${start.taskId} on branch ${start.branchName}`);

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

    console.log(`Next action: ${next.action}`);

    if (next.action === 'generate_test') {
      // AI generates test
      const testCode = await generateTest(next.currentSubtask);
      await writeFile(testCode);

      // Run tests
      const results = await runTests();

      // Complete RED phase
      await mcp.call('autopilot_complete_phase', {
        projectRoot: '/path/to/project',
        testResults: results
      });

    } else if (next.action === 'implement_code') {
      // AI generates implementation
      const implCode = await generateImplementation(next.currentSubtask);
      await writeFile(implCode);

      // Run tests
      const results = await runTests();

      // Complete GREEN phase
      await mcp.call('autopilot_complete_phase', {
        projectRoot: '/path/to/project',
        testResults: results
      });

    } else if (next.action === 'commit_changes') {
      // Commit
      const commit = await mcp.call('autopilot_commit', {
        projectRoot: '/path/to/project'
      });

      console.log(`Committed: ${commit.commit.hash}`);

      if (commit.isComplete) {
        console.log('Task complete!');
        break;
      }
    }
  }
}

Error Handling

Common Errors and Solutions

Workflow Already Exists

Error:

{
  "error": "Workflow already in progress",
  "suggestion": "Use autopilot_resume to continue the existing workflow"
}

Solution:

# Resume existing workflow
tm autopilot resume

# OR force start new workflow
tm autopilot start 7 --force

RED Phase Validation Failed

Error:

{
  "error": "RED phase validation failed",
  "reason": "At least one test must be failing in RED phase",
  "actual": { "passed": 10, "failed": 0 },
  "suggestion": "Ensure you have written a failing test before proceeding"
}

Solution: The test isn’t actually testing the new feature. Write a test that validates the new behavior that doesn’t exist yet.

GREEN Phase Validation Failed

Error:

{
  "error": "GREEN phase validation failed",
  "reason": "All tests must pass in GREEN phase",
  "actual": { "passed": 9, "failed": 1 },
  "suggestion": "Fix the implementation to make all tests pass"
}

Solution: Implementation isn’t complete. Debug failing test and fix implementation.

No Staged Changes

Error:

{
  "error": "No staged changes to commit",
  "suggestion": "Make code changes before committing"
}

Solution: Ensure you’ve actually created/modified files before committing.

Git Working Tree Not Clean

Error:

{
  "error": "Git validation failed: working tree not clean",
  "suggestion": "Commit or stash changes before starting workflow"
}

Solution:

git status
git add . && git commit -m "chore: save work"
# Then start workflow

Error Recovery Patterns

Retry Pattern

async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts: number = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      console.log(`Attempt ${attempt} failed, retrying...`);
      await sleep(1000 * attempt); // Exponential backoff
    }
  }
  throw new Error('Should not reach here');
}

// Usage
const results = await withRetry(async () => {
  const output = await runTests();
  return parseTestResults(output);
});

Graceful Degradation

async function completePhase(projectRoot: string, results: TestResults) {
  try {
    return await mcp.call('autopilot_complete_phase', {
      projectRoot,
      testResults: results
    });
  } catch (error) {
    console.error('Phase completion failed:', error);

    // Log error for debugging
    await logError(error);

    // Attempt manual recovery
    console.log('Attempting manual state recovery...');
    const status = await mcp.call('autopilot_status', { projectRoot });
    console.log('Current state:', status);

    // Provide user guidance
    console.log('Manual intervention required:');
    console.log('1. Check test results are correct');
    console.log('2. Verify current phase allows transition');
    console.log('3. Run: tm autopilot status');

    throw error;
  }
}

Troubleshooting

Workflow State Issues

Problem: State file corrupted or inconsistent Solution:

# Check state file
cat .taskmaster/workflow-state.json

# If corrupted, abort and restart
tm autopilot abort --force
tm autopilot start 7

Test Results Parsing

Problem: Test output format not recognized Solution: Ensure test results JSON has required fields:

{
  "total": 10,    // Required
  "passed": 8,    // Required
  "failed": 2,    // Required
  "skipped": 0    // Optional
}

Branch Conflicts

Problem: Workflow branch already exists Solution:

# Check branches
git branch

# Delete old workflow branch if safe
git branch -D task-7

# Start workflow again
tm autopilot start 7

Permission Issues

Problem: Cannot write to .taskmaster directory Solution:

# Check directory permissions
ls -la .taskmaster/

# Fix permissions
chmod -R u+w .taskmaster/

State Persistence Failures

Problem: State not saving between commands Solution:

# Check file system permissions
ls -la .taskmaster/workflow-state.json

# Verify state is being written
tm autopilot status --json | jq .

# If all else fails, reinstall
rm -rf .taskmaster/
tm init

Working with AI Agents

Example prompts for AI agents (Claude Code, Cursor, etc.) to use the TDD workflow.

Starting a Task

I want to implement Task 7 using TDD workflow. Please:
Start the autopilot workflow
Show me the first subtask to implement
Begin the RED-GREEN-COMMIT cycle

RED Phase - Writing Failing Tests

We're in RED phase for subtask "{SUBTASK_TITLE}". Please:
Read the subtask requirements
Write a test that validates the behavior
The test MUST fail because the feature doesn't exist yet
Run the tests and report results to complete the RED phase

GREEN Phase - Implementing

We're in GREEN phase. The test is failing with: {ERROR_MESSAGE}

Please:
1. Implement the minimal code to make this test pass
2. Don't over-engineer or add untested features
3. Run tests and report results to complete the GREEN phase

Handling Errors

The RED phase validation failed - no test failures detected.

Please:
1. Review the test I just wrote
2. Identify why it's not actually testing new behavior
3. Rewrite the test to properly fail until the feature is implemented

GREEN phase validation failed - {N} tests still failing.

Please:
1. Review the failing test output
2. Fix the implementation to pass all tests
3. Try completing the GREEN phase again

Checking Progress

What's the current state of the workflow? Please show:
- Which subtask we're on
- Current TDD phase (RED/GREEN/COMMIT)
- Progress percentage
- Next action required

Resuming Work

I have an in-progress workflow. Please:
Resume the autopilot workflow
Show current status
Continue from where we left off

Additional Resources

Command Reference - Complete CLI command documentation
MCP Provider Guide - MCP integration details
Task Structure - Understanding TaskMaster’s task system
Configuration - Project configuration options

Welcome

Getting Started

Best Practices

Technical Capabilities

TDD Workflow (Autopilot)

​Overview

​Key Features

​Architecture

​Component Responsibilities

​Getting Started

​Prerequisites

​Quick Start

​CLI Commands

​tm autopilot start <taskId>

​tm autopilot resume

​tm autopilot next

​tm autopilot status

​tm autopilot complete

​tm autopilot commit

​tm autopilot abort

​MCP Tools

​autopilot_start

​autopilot_resume

​autopilot_next

​autopilot_status

​autopilot_complete_phase

​autopilot_commit

​autopilot_abort

​Workflow Phases

​Phase Diagram

​Phase Descriptions

​Responsibility Matrix

​AI Agent Responsibilities

​TaskMaster Responsibilities

​Examples

​Complete TDD Cycle Example

​1. Start Workflow

​2. Get Next Action

​3. Write Failing Test

​4. Run Tests (Should Fail)

​5. Complete RED Phase

​6. Implement Code

​7. Run Tests (Should Pass)

​8. Complete GREEN Phase

​9. Commit Changes

​MCP Integration Example

​Error Handling

​Common Errors and Solutions

​Workflow Already Exists

​RED Phase Validation Failed

​GREEN Phase Validation Failed

​No Staged Changes

​Git Working Tree Not Clean

​Error Recovery Patterns

​Retry Pattern

​Graceful Degradation

​Troubleshooting

​Workflow State Issues

​Test Results Parsing

​Branch Conflicts

​Permission Issues

​State Persistence Failures

​Working with AI Agents

​Starting a Task

​RED Phase - Writing Failing Tests

​GREEN Phase - Implementing

​Handling Errors

​Checking Progress

​Resuming Work

​Additional Resources

Overview

Key Features

Architecture

Component Responsibilities

Getting Started

Prerequisites

Quick Start

CLI Commands

`tm autopilot start <taskId>`

`tm autopilot resume`

`tm autopilot next`

`tm autopilot status`

`tm autopilot complete`

`tm autopilot commit`

`tm autopilot abort`

MCP Tools

`autopilot_start`

`autopilot_resume`

`autopilot_next`

`autopilot_status`

`autopilot_complete_phase`

`autopilot_commit`

`autopilot_abort`

Workflow Phases

Phase Diagram

Phase Descriptions

Responsibility Matrix

AI Agent Responsibilities

TaskMaster Responsibilities

Examples

Complete TDD Cycle Example

1. Start Workflow

2. Get Next Action

3. Write Failing Test

4. Run Tests (Should Fail)

5. Complete RED Phase

6. Implement Code

7. Run Tests (Should Pass)

8. Complete GREEN Phase

9. Commit Changes

MCP Integration Example

Error Handling

Common Errors and Solutions

Workflow Already Exists

RED Phase Validation Failed

GREEN Phase Validation Failed

No Staged Changes

Git Working Tree Not Clean

Error Recovery Patterns

Retry Pattern

Graceful Degradation

Troubleshooting

Workflow State Issues

Test Results Parsing

Branch Conflicts

Permission Issues

State Persistence Failures

Working with AI Agents

Starting a Task

RED Phase - Writing Failing Tests

GREEN Phase - Implementing

Handling Errors

Checking Progress

Resuming Work

Additional Resources