> ## Documentation Index
> Fetch the complete documentation index at: https://docs.task-master.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TDD Workflow Quick Start

> Get started with TaskMaster's autonomous TDD workflow in 5 minutes

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

```bash theme={null}
tm autopilot start <taskId>
```

Example:

```bash theme={null}
$ 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

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

Write a test that fails:

```typescript theme={null}
// 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:

```bash theme={null}
$ npm test
# ✗ 1 test failed
```

Complete RED phase:

```bash theme={null}
$ 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:

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

Run tests:

```bash theme={null}
$ npm test
# ✓ 1 test passed
```

Complete GREEN phase:

```bash theme={null}
$ 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

```bash theme={null}
$ 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.

```bash theme={null}
# 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:

```bash theme={null}
$ 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:

```typescript theme={null}
// 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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
$ 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:

```typescript theme={null}
// 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](./ai-agent-integration.mdx) for details.

## Cheat Sheet

```bash theme={null}
# 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](./ai-agent-integration.mdx) for complete documentation
* Check [Command Reference](/command-reference) for all options

## 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!