314 lines
6.5 KiB
Plaintext
314 lines
6.5 KiB
Plaintext
---
|
|
title: "TDD Workflow Quick Start"
|
|
description: "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
|
|
tm autopilot start <taskId>
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
$ 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
|
|
# 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
|
|
// 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
|
|
$ npm test
|
|
# ✗ 1 test failed
|
|
```
|
|
|
|
Complete RED phase:
|
|
```bash
|
|
$ 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
|
|
// src/commands/start.ts
|
|
export class StartCommand {
|
|
async execute(options: { taskId: string }) {
|
|
return { success: true };
|
|
}
|
|
}
|
|
```
|
|
|
|
Run tests:
|
|
```bash
|
|
$ npm test
|
|
# ✓ 1 test passed
|
|
```
|
|
|
|
Complete GREEN phase:
|
|
```bash
|
|
$ 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
|
|
$ 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
|
|
# 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
|
|
$ 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
|
|
// 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
|
|
# 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
|
|
# 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
|
|
$ 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
|
|
// 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
|
|
# 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!
|