feat: Phase 1 - Complete TDD Workflow Automation System (#1289)
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Ralph Khreish
944
apps/docs/tdd-workflow/ai-agent-integration.mdx
Normal file
944
apps/docs/tdd-workflow/ai-agent-integration.mdx
Normal file
@@ -0,0 +1,944 @@
|
||||
---
|
||||
title: "AI Agent Integration Guide"
|
||||
description: "Complete guide for integrating AI agents with TaskMaster's autonomous TDD workflow system"
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
1. TaskMaster initialized project with subtasks
|
||||
2. Git repository with clean working tree
|
||||
3. Test framework configured (vitest, jest, etc.)
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
tm autopilot start 7 --max-attempts 5 --json
|
||||
```
|
||||
|
||||
**JSON Output:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```bash
|
||||
tm autopilot resume --json
|
||||
```
|
||||
|
||||
### `tm autopilot next`
|
||||
|
||||
Get the next action to perform with detailed context.
|
||||
|
||||
**JSON Output:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```bash
|
||||
tm autopilot status --json
|
||||
```
|
||||
|
||||
### `tm autopilot complete`
|
||||
|
||||
Complete the current TDD phase with test result validation.
|
||||
|
||||
**Options:**
|
||||
- `--results <json>`: Test results JSON string
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
tm autopilot commit --json
|
||||
```
|
||||
|
||||
### `tm autopilot abort`
|
||||
|
||||
Abort the workflow and clean up state (preserves git branch and code).
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
tm autopilot abort --force --json
|
||||
```
|
||||
|
||||
## MCP Tools
|
||||
|
||||
MCP tools provide the same functionality as CLI commands for programmatic integration.
|
||||
|
||||
### `autopilot_start`
|
||||
|
||||
**Parameters:**
|
||||
```typescript
|
||||
{
|
||||
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:**
|
||||
```typescript
|
||||
{
|
||||
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:**
|
||||
```typescript
|
||||
{
|
||||
projectRoot: string; // Required: Absolute path to project
|
||||
}
|
||||
```
|
||||
|
||||
### `autopilot_next`
|
||||
|
||||
**Parameters:**
|
||||
```typescript
|
||||
{
|
||||
projectRoot: string; // Required: Absolute path to project
|
||||
}
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
```typescript
|
||||
{
|
||||
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:**
|
||||
```typescript
|
||||
{
|
||||
projectRoot: string; // Required: Absolute path to project
|
||||
}
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
```typescript
|
||||
{
|
||||
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:**
|
||||
```typescript
|
||||
{
|
||||
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:**
|
||||
```typescript
|
||||
{
|
||||
projectRoot: string; // Required: Absolute path to project
|
||||
files?: string[]; // Optional: Files to stage
|
||||
customMessage?: string; // Optional: Custom commit message
|
||||
}
|
||||
```
|
||||
|
||||
### `autopilot_abort`
|
||||
|
||||
**Parameters:**
|
||||
```typescript
|
||||
{
|
||||
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
|
||||
|
||||
1. **Read and understand subtask requirements**
|
||||
2. **Write test code** that validates the requirement
|
||||
3. **Run test suite** using project's test command
|
||||
4. **Parse test output** into JSON format
|
||||
5. **Report results** to TaskMaster for validation
|
||||
6. **Write implementation** to satisfy tests
|
||||
7. **Request commits** when GREEN phase complete
|
||||
8. **Handle errors** and retry within attempt limits
|
||||
|
||||
### TaskMaster Responsibilities
|
||||
|
||||
1. **Manage workflow state machine**
|
||||
2. **Enforce TDD rules** (RED must fail, GREEN must pass)
|
||||
3. **Track progress** (completed, current, attempts)
|
||||
4. **Create git commits** with enhanced messages
|
||||
5. **Manage git branches** and repository safety
|
||||
6. **Validate transitions** between phases
|
||||
7. **Persist state** for resumability
|
||||
8. **Generate reports** and activity logs
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete TDD Cycle Example
|
||||
|
||||
#### 1. Start Workflow
|
||||
|
||||
```bash
|
||||
$ tm autopilot start 7 --json
|
||||
```
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
$ tm autopilot next --json
|
||||
```
|
||||
|
||||
```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`:
|
||||
|
||||
```typescript
|
||||
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)
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
# Output: 1 test failed (expected)
|
||||
```
|
||||
|
||||
Parse output to JSON:
|
||||
```json
|
||||
{
|
||||
"total": 1,
|
||||
"passed": 0,
|
||||
"failed": 1,
|
||||
"skipped": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Complete RED Phase
|
||||
|
||||
```bash
|
||||
$ tm autopilot complete --results '{"total":1,"passed":0,"failed":1,"skipped":0}' --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Completed RED phase",
|
||||
"previousPhase": "RED",
|
||||
"currentPhase": "GREEN",
|
||||
"nextAction": "implement_code"
|
||||
}
|
||||
```
|
||||
|
||||
#### 6. Implement Code
|
||||
|
||||
AI Agent creates `src/commands/start.ts`:
|
||||
|
||||
```typescript
|
||||
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)
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
# Output: 1 test passed
|
||||
```
|
||||
|
||||
Parse output:
|
||||
```json
|
||||
{
|
||||
"total": 1,
|
||||
"passed": 1,
|
||||
"failed": 0,
|
||||
"skipped": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 8. Complete GREEN Phase
|
||||
|
||||
```bash
|
||||
$ tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}' --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"previousPhase": "GREEN",
|
||||
"currentPhase": "COMMIT",
|
||||
"nextAction": "commit_changes"
|
||||
}
|
||||
```
|
||||
|
||||
#### 9. Commit Changes
|
||||
|
||||
```bash
|
||||
$ tm autopilot commit --json
|
||||
```
|
||||
|
||||
```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
|
||||
|
||||
```typescript
|
||||
// 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:**
|
||||
```json
|
||||
{
|
||||
"error": "Workflow already in progress",
|
||||
"suggestion": "Use autopilot_resume to continue the existing workflow"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Resume existing workflow
|
||||
tm autopilot resume
|
||||
|
||||
# OR force start new workflow
|
||||
tm autopilot start 7 --force
|
||||
```
|
||||
|
||||
#### RED Phase Validation Failed
|
||||
|
||||
**Error:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"error": "Git validation failed: working tree not clean",
|
||||
"suggestion": "Commit or stash changes before starting workflow"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
git status
|
||||
git add . && git commit -m "chore: save work"
|
||||
# Then start workflow
|
||||
```
|
||||
|
||||
### Error Recovery Patterns
|
||||
|
||||
#### Retry Pattern
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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:**
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"total": 10, // Required
|
||||
"passed": 8, // Required
|
||||
"failed": 2, // Required
|
||||
"skipped": 0 // Optional
|
||||
}
|
||||
```
|
||||
|
||||
### Branch Conflicts
|
||||
|
||||
**Problem:** Workflow branch already exists
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Check directory permissions
|
||||
ls -la .taskmaster/
|
||||
|
||||
# Fix permissions
|
||||
chmod -R u+w .taskmaster/
|
||||
```
|
||||
|
||||
### State Persistence Failures
|
||||
|
||||
**Problem:** State not saving between commands
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Command Reference](./command-reference.mdx) - Complete CLI command documentation
|
||||
- [MCP Provider Guide](./mcp-provider-guide.mdx) - MCP integration details
|
||||
- [Task Structure](./task-structure.mdx) - Understanding TaskMaster's task system
|
||||
- [Configuration](./configuration.mdx) - Project configuration options
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or contributions:
|
||||
- GitHub Issues: https://github.com/eyaltoledano/claude-task-master/issues
|
||||
- Documentation: https://docs.task-master.dev
|
||||
315
apps/docs/tdd-workflow/quickstart.mdx
Normal file
315
apps/docs/tdd-workflow/quickstart.mdx
Normal file
@@ -0,0 +1,315 @@
|
||||
---
|
||||
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
|
||||
- See [Example Prompts](./templates/example-prompts.mdx) for AI agent patterns
|
||||
- Check [Command Reference](./command-reference.mdx) for all options
|
||||
- Review [CLAUDE.md Template](./templates/CLAUDE.md.template) for AI integration
|
||||
|
||||
## 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!
|
||||
388
apps/docs/tdd-workflow/templates/claude-template.mdx
Normal file
388
apps/docs/tdd-workflow/templates/claude-template.mdx
Normal file
@@ -0,0 +1,388 @@
|
||||
---
|
||||
title: "CLAUDE.md Template"
|
||||
description: "Ready-to-use CLAUDE.md template for AI agent integration with TDD workflow"
|
||||
---
|
||||
|
||||
This file provides integration instructions for AI agents (like Claude Code) to work with TaskMaster's autonomous TDD workflow system.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Start workflow
|
||||
tm autopilot start <taskId>
|
||||
|
||||
# Get next action
|
||||
tm autopilot next --json
|
||||
|
||||
# Complete phase with test results
|
||||
tm autopilot complete --results '{"total":N,"passed":N,"failed":N,"skipped":N}'
|
||||
|
||||
# Commit changes
|
||||
tm autopilot commit
|
||||
|
||||
# Check status
|
||||
tm autopilot status --json
|
||||
|
||||
# Abort workflow
|
||||
tm autopilot abort
|
||||
```
|
||||
|
||||
## Integration Pattern
|
||||
|
||||
### 1. Start Task
|
||||
|
||||
Before implementing a task:
|
||||
|
||||
```bash
|
||||
tm autopilot start {TASK_ID}
|
||||
```
|
||||
|
||||
This creates a workflow branch and initializes the TDD state machine.
|
||||
|
||||
### 2. Follow TDD Cycle
|
||||
|
||||
For each subtask, repeat this cycle:
|
||||
|
||||
#### RED Phase - Write Failing Test
|
||||
|
||||
1. Check next action:
|
||||
```bash
|
||||
tm autopilot next --json
|
||||
```
|
||||
|
||||
2. Write a test that **fails** because the feature doesn't exist yet
|
||||
|
||||
3. Run tests and report results:
|
||||
```bash
|
||||
npm test # or appropriate test command
|
||||
tm autopilot complete --results '{TEST_RESULTS_JSON}'
|
||||
```
|
||||
|
||||
**Important:** RED phase MUST have at least one failing test.
|
||||
|
||||
#### GREEN Phase - Implement Feature
|
||||
|
||||
1. Check next action confirms GREEN phase
|
||||
|
||||
2. Write minimal implementation to make tests pass
|
||||
|
||||
3. Run tests and report results:
|
||||
```bash
|
||||
npm test
|
||||
tm autopilot complete --results '{TEST_RESULTS_JSON}'
|
||||
```
|
||||
|
||||
**Important:** GREEN phase MUST have all tests passing (failed === 0).
|
||||
|
||||
#### COMMIT Phase - Save Progress
|
||||
|
||||
1. Review changes:
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
```
|
||||
|
||||
2. Commit (auto-generates message with metadata):
|
||||
```bash
|
||||
tm autopilot commit
|
||||
```
|
||||
|
||||
3. Workflow automatically advances to next subtask
|
||||
|
||||
### 3. Monitor Progress
|
||||
|
||||
```bash
|
||||
# Check overall progress
|
||||
tm autopilot status --json
|
||||
|
||||
# See what's next
|
||||
tm autopilot next --json
|
||||
```
|
||||
|
||||
### 4. Handle Completion
|
||||
|
||||
When all subtasks are done:
|
||||
- Workflow enters COMPLETE phase
|
||||
- Branch remains for review/merge
|
||||
- State can be cleaned up
|
||||
|
||||
## Example Session
|
||||
|
||||
```bash
|
||||
# Start task with 3 subtasks
|
||||
$ tm autopilot start 7
|
||||
✓ Workflow started for task 7
|
||||
✓ Created branch: task-7
|
||||
✓ Phase: RED
|
||||
✓ Next: generate_test for subtask 7.1
|
||||
|
||||
# Write failing test for subtask 7.1
|
||||
$ cat > tests/feature.test.ts
|
||||
# ... write test ...
|
||||
|
||||
$ npm test
|
||||
# 1 test, 0 passed, 1 failed
|
||||
|
||||
$ tm autopilot complete --results '{"total":1,"passed":0,"failed":1,"skipped":0}'
|
||||
✓ RED phase complete
|
||||
✓ Phase: GREEN
|
||||
✓ Next: implement_code
|
||||
|
||||
# Write implementation
|
||||
$ cat > src/feature.ts
|
||||
# ... write code ...
|
||||
|
||||
$ npm test
|
||||
# 1 test, 1 passed, 0 failed
|
||||
|
||||
$ tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}'
|
||||
✓ GREEN phase complete
|
||||
✓ Phase: COMMIT
|
||||
✓ Next: commit_changes
|
||||
|
||||
$ tm autopilot commit
|
||||
✓ Created commit: abc123
|
||||
✓ Message: feat(feature): implement feature (Task 7.1)
|
||||
✓ Advanced to subtask 7.2
|
||||
✓ Phase: RED
|
||||
✓ Next: generate_test
|
||||
|
||||
# Repeat for subtasks 7.2 and 7.3...
|
||||
```
|
||||
|
||||
## Test Result Format
|
||||
|
||||
Always provide test results in this JSON format:
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 10, // Total number of tests
|
||||
"passed": 8, // Number of passing tests
|
||||
"failed": 2, // Number of failing tests
|
||||
"skipped": 0 // Number of skipped tests (optional)
|
||||
}
|
||||
```
|
||||
|
||||
### Parsing Test Output
|
||||
|
||||
Common test frameworks output that needs parsing:
|
||||
|
||||
**Vitest:**
|
||||
```
|
||||
Test Files 1 passed (1)
|
||||
Tests 10 passed | 2 failed (12)
|
||||
```
|
||||
→ `{"total":12,"passed":10,"failed":2,"skipped":0}`
|
||||
|
||||
**Jest:**
|
||||
```
|
||||
Tests: 2 failed, 10 passed, 12 total
|
||||
```
|
||||
→ `{"total":12,"passed":10,"failed":2,"skipped":0}`
|
||||
|
||||
**Mocha:**
|
||||
```
|
||||
12 passing
|
||||
2 failing
|
||||
```
|
||||
→ `{"total":14,"passed":12,"failed":2,"skipped":0}`
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. RED Phase Won't Complete**
|
||||
- Error: "RED phase validation failed: no test failures"
|
||||
- Solution: Your test isn't actually testing new behavior. Write a test that fails.
|
||||
|
||||
**2. GREEN Phase Won't Complete**
|
||||
- Error: "GREEN phase validation failed: tests still failing"
|
||||
- Solution: Implementation incomplete. Debug and fix failing tests.
|
||||
|
||||
**3. Workflow Already Exists**
|
||||
- Error: "Workflow already in progress"
|
||||
- Solution: Run `tm autopilot resume` or `tm autopilot abort --force` then restart
|
||||
|
||||
**4. No Staged Changes**
|
||||
- Error: "No staged changes to commit"
|
||||
- Solution: Ensure you've actually created/modified files
|
||||
|
||||
### Recovery
|
||||
|
||||
If workflow gets stuck:
|
||||
|
||||
```bash
|
||||
# Check current state
|
||||
tm autopilot status --json
|
||||
|
||||
# If corrupted, abort and restart
|
||||
tm autopilot abort --force
|
||||
tm autopilot start {TASK_ID}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. One Feature Per Test Cycle
|
||||
|
||||
Each RED-GREEN-COMMIT cycle should implement exactly one small feature or behavior.
|
||||
|
||||
**Good:**
|
||||
- RED: Test that `getUser()` returns user object
|
||||
- GREEN: Implement `getUser()` to return user
|
||||
- COMMIT: One commit for getUser feature
|
||||
|
||||
**Bad:**
|
||||
- RED: Test multiple features at once
|
||||
- GREEN: Implement entire module
|
||||
- COMMIT: Massive commit with unrelated changes
|
||||
|
||||
### 2. Meaningful Test Names
|
||||
|
||||
Tests should clearly describe what they're validating:
|
||||
|
||||
```typescript
|
||||
// Good
|
||||
it('should return 404 when user not found', async () => {
|
||||
const result = await getUser('nonexistent');
|
||||
expect(result.status).toBe(404);
|
||||
});
|
||||
|
||||
// Bad
|
||||
it('test 1', () => {
|
||||
// what does this test?
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Minimal Implementation
|
||||
|
||||
In GREEN phase, write just enough code to pass the test:
|
||||
|
||||
```typescript
|
||||
// Good - minimal implementation
|
||||
function getUser(id: string) {
|
||||
if (id === 'nonexistent') {
|
||||
return { status: 404 };
|
||||
}
|
||||
return { status: 200, data: users[id] };
|
||||
}
|
||||
|
||||
// Bad - over-engineering
|
||||
function getUser(id: string) {
|
||||
// Adds caching, validation, logging, etc. that isn't tested
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Keep Tests Fast
|
||||
|
||||
Fast tests mean fast feedback:
|
||||
- Avoid network calls (use mocks)
|
||||
- Avoid file system operations (use in-memory)
|
||||
- Avoid waiting/sleeping
|
||||
|
||||
### 5. Commit Message Quality
|
||||
|
||||
Let TaskMaster generate commit messages - they include:
|
||||
- Conventional commit format (feat, fix, refactor, etc.)
|
||||
- Subtask context and ID
|
||||
- Workflow metadata
|
||||
- Co-authorship attribution
|
||||
|
||||
## MCP Integration (Advanced)
|
||||
|
||||
For programmatic integration, use MCP tools instead of CLI:
|
||||
|
||||
```typescript
|
||||
import { MCPClient } from '@modelcontextprotocol/sdk';
|
||||
|
||||
const client = new MCPClient();
|
||||
|
||||
// Start workflow
|
||||
const start = await client.call('autopilot_start', {
|
||||
taskId: '7',
|
||||
projectRoot: '/path/to/project'
|
||||
});
|
||||
|
||||
// Get next action
|
||||
const next = await client.call('autopilot_next', {
|
||||
projectRoot: '/path/to/project'
|
||||
});
|
||||
|
||||
// Complete phase
|
||||
const complete = await client.call('autopilot_complete_phase', {
|
||||
projectRoot: '/path/to/project',
|
||||
testResults: { total: 1, passed: 0, failed: 1, skipped: 0 }
|
||||
});
|
||||
|
||||
// Commit
|
||||
const commit = await client.call('autopilot_commit', {
|
||||
projectRoot: '/path/to/project'
|
||||
});
|
||||
```
|
||||
|
||||
See [AI Agent Integration Guide](../ai-agent-integration.mdx) for complete MCP documentation.
|
||||
|
||||
## Workflow State Files
|
||||
|
||||
TaskMaster persists workflow state to `.taskmaster/workflow-state.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": "SUBTASK_LOOP",
|
||||
"context": {
|
||||
"taskId": "7",
|
||||
"subtasks": [...],
|
||||
"currentSubtaskIndex": 0,
|
||||
"currentTDDPhase": "RED",
|
||||
"branchName": "task-7",
|
||||
"errors": [],
|
||||
"metadata": {
|
||||
"startedAt": "2025-01-10T..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** Never manually edit this file. Use CLI/MCP tools only.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── .taskmaster/
|
||||
│ ├── workflow-state.json # Current workflow state
|
||||
│ ├── tasks/
|
||||
│ │ └── tasks.json # Task definitions
|
||||
│ └── docs/
|
||||
│ └── prd.txt # Product requirements
|
||||
├── src/ # Implementation files
|
||||
├── tests/ # Test files
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [AI Agent Integration Guide](../ai-agent-integration.mdx) - Complete integration documentation
|
||||
- [Command Reference](../command-reference.mdx) - All CLI commands
|
||||
- [Task Structure](../task-structure.mdx) - Understanding tasks and subtasks
|
||||
- [MCP Provider Guide](../mcp-provider-guide.mdx) - MCP integration details
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Q: Workflow won't start**
|
||||
A: Check that task has subtasks (`tm show <taskId>`) and git working tree is clean
|
||||
|
||||
**Q: Can't complete RED phase**
|
||||
A: Verify at least one test is actually failing (not skipped, not passing)
|
||||
|
||||
**Q: Can't complete GREEN phase**
|
||||
A: Verify ALL tests pass (zero failures)
|
||||
|
||||
**Q: Commit fails**
|
||||
A: Check that you've made changes and they're staged (or stageable)
|
||||
|
||||
**Q: State seems wrong**
|
||||
A: Check `.taskmaster/workflow-state.json` or run `tm autopilot status`
|
||||
|
||||
---
|
||||
|
||||
**For detailed documentation, see:** [AI Agent Integration Guide](../ai-agent-integration.mdx)
|
||||
478
apps/docs/tdd-workflow/templates/example-prompts.mdx
Normal file
478
apps/docs/tdd-workflow/templates/example-prompts.mdx
Normal file
@@ -0,0 +1,478 @@
|
||||
---
|
||||
title: "Example Prompts"
|
||||
description: "Collection of effective prompts for AI agents working with TaskMaster's TDD workflow system"
|
||||
---
|
||||
|
||||
Collection of effective prompts for AI agents working with TaskMaster's TDD workflow system.
|
||||
|
||||
## Getting Started Prompts
|
||||
|
||||
### Start a Task
|
||||
|
||||
```
|
||||
I want to implement Task 7 using TDD workflow. Please:
|
||||
1. Start the autopilot workflow
|
||||
2. Show me the first subtask to implement
|
||||
3. Begin the RED-GREEN-COMMIT cycle
|
||||
```
|
||||
|
||||
### Resume Work
|
||||
|
||||
```
|
||||
I have an in-progress workflow. Please:
|
||||
1. Resume the autopilot workflow
|
||||
2. Show current status and progress
|
||||
3. Continue from where we left off
|
||||
```
|
||||
|
||||
### Understanding Current State
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Test Generation Prompts
|
||||
|
||||
### Basic Test Generation
|
||||
|
||||
```
|
||||
We're in RED phase for subtask "{SUBTASK_TITLE}". Please:
|
||||
1. Read the subtask requirements
|
||||
2. Write a comprehensive test that validates the behavior
|
||||
3. The test MUST fail because the feature doesn't exist yet
|
||||
4. Use the project's testing framework (vitest/jest/etc)
|
||||
5. Follow the project's test file conventions
|
||||
```
|
||||
|
||||
### Test for Specific Feature
|
||||
|
||||
```
|
||||
For subtask: "Implement user authentication endpoint"
|
||||
|
||||
Write a failing test that:
|
||||
1. Tests POST /api/auth/login
|
||||
2. Validates request body (email, password)
|
||||
3. Checks response format and status codes
|
||||
4. Uses proper mocking for database calls
|
||||
5. Follows security best practices
|
||||
```
|
||||
|
||||
### Edge Case Testing
|
||||
|
||||
```
|
||||
The basic happy path test is passing. Now write additional tests for:
|
||||
1. Error cases (invalid input, missing fields)
|
||||
2. Edge cases (empty strings, null values, etc.)
|
||||
3. Security concerns (SQL injection, XSS)
|
||||
4. Performance expectations (timeout, rate limits)
|
||||
|
||||
Each test should initially fail.
|
||||
```
|
||||
|
||||
### Test Refactoring
|
||||
|
||||
```
|
||||
Our tests are passing but could be improved. Please:
|
||||
1. Review existing tests for duplication
|
||||
2. Extract common setup into beforeEach/fixtures
|
||||
3. Improve test descriptions for clarity
|
||||
4. Add missing edge cases
|
||||
5. Ensure all new tests fail first (RED phase)
|
||||
```
|
||||
|
||||
## Implementation Prompts
|
||||
|
||||
### Basic Implementation
|
||||
|
||||
```
|
||||
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 features not tested
|
||||
3. Follow the project's code style and patterns
|
||||
4. Ensure the implementation is clean and readable
|
||||
```
|
||||
|
||||
### Implementation with Constraints
|
||||
|
||||
```
|
||||
Implement the feature to pass the test, but:
|
||||
- Use TypeScript with strict type checking
|
||||
- Follow SOLID principles
|
||||
- Keep functions under 20 lines
|
||||
- Use dependency injection where appropriate
|
||||
- Add JSDoc comments for public APIs
|
||||
```
|
||||
|
||||
### Fix Failing Tests
|
||||
|
||||
```
|
||||
GREEN phase validation failed - {N} tests still failing.
|
||||
|
||||
Please:
|
||||
1. Review the failing test output
|
||||
2. Identify what's not working
|
||||
3. Fix the implementation to pass all tests
|
||||
4. Don't modify tests to make them pass
|
||||
5. Explain what was wrong
|
||||
```
|
||||
|
||||
### Refactor Implementation
|
||||
|
||||
```
|
||||
Tests are passing but code quality needs improvement:
|
||||
1. Extract repeated logic into functions
|
||||
2. Improve variable names
|
||||
3. Add error handling
|
||||
4. Optimize performance if needed
|
||||
5. Ensure tests still pass after refactoring
|
||||
```
|
||||
|
||||
## Debugging Prompts
|
||||
|
||||
### Test Output Parsing
|
||||
|
||||
```
|
||||
Here's the test output:
|
||||
{PASTE_TEST_OUTPUT}
|
||||
|
||||
Please parse this into the required JSON format:
|
||||
{
|
||||
"total": N,
|
||||
"passed": N,
|
||||
"failed": N,
|
||||
"skipped": N
|
||||
}
|
||||
|
||||
Then complete the current phase.
|
||||
```
|
||||
|
||||
### Workflow Stuck
|
||||
|
||||
```
|
||||
The workflow seems stuck. Please:
|
||||
1. Check the current workflow status
|
||||
2. Identify the issue
|
||||
3. If corrupted, abort and restart
|
||||
4. Explain what went wrong and how to prevent it
|
||||
```
|
||||
|
||||
### Phase Validation Failing
|
||||
|
||||
```
|
||||
I'm getting: "RED phase validation failed: no test failures"
|
||||
|
||||
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
|
||||
4. Explain what makes a good failing test
|
||||
```
|
||||
|
||||
### Git Issues
|
||||
|
||||
```
|
||||
Getting git errors when trying to start workflow:
|
||||
{PASTE_ERROR}
|
||||
|
||||
Please:
|
||||
1. Diagnose the git issue
|
||||
2. Provide commands to fix it
|
||||
3. Restart the workflow once fixed
|
||||
```
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Parallel Test Generation
|
||||
|
||||
```
|
||||
We have 3 subtasks to implement. For efficiency:
|
||||
1. Read all 3 subtask descriptions
|
||||
2. Plan the test structure for each
|
||||
3. Identify shared test utilities needed
|
||||
4. Generate tests for subtask 1 (they should fail)
|
||||
5. Once we complete 1, move to 2, then 3
|
||||
```
|
||||
|
||||
### Integration Test Strategy
|
||||
|
||||
```
|
||||
This subtask requires integration testing. Please:
|
||||
1. Set up test database/environment
|
||||
2. Write integration tests that exercise the full stack
|
||||
3. Use proper cleanup in afterEach
|
||||
4. Mock external services (APIs, third-party)
|
||||
5. Ensure tests are deterministic and fast
|
||||
```
|
||||
|
||||
### Test-Driven Refactoring
|
||||
|
||||
```
|
||||
We need to refactor {MODULE_NAME} but keep behavior unchanged:
|
||||
1. First, write comprehensive tests for current behavior
|
||||
2. Ensure all tests pass (document current state)
|
||||
3. Refactor the implementation
|
||||
4. Verify all tests still pass
|
||||
5. Commit the refactoring
|
||||
```
|
||||
|
||||
### Complex Feature Implementation
|
||||
|
||||
```
|
||||
Subtask: "{COMPLEX_SUBTASK}"
|
||||
|
||||
This is complex. Let's break it down:
|
||||
1. Identify the core functionality to test
|
||||
2. Write tests for the simplest version
|
||||
3. Implement minimal working code
|
||||
4. Commit that cycle
|
||||
5. Then iteratively add more tests for additional features
|
||||
6. Each iteration is a RED-GREEN-COMMIT cycle
|
||||
```
|
||||
|
||||
### Performance Testing
|
||||
|
||||
```
|
||||
Write performance tests for {FEATURE}:
|
||||
1. Measure baseline performance (current state)
|
||||
2. Write test that fails if operation takes > {N}ms
|
||||
3. Implement optimizations to pass the test
|
||||
4. Document performance improvements
|
||||
5. Consider edge cases (large inputs, concurrent requests)
|
||||
```
|
||||
|
||||
### Security Testing
|
||||
|
||||
```
|
||||
Write security-focused tests for {FEATURE}:
|
||||
1. Test input validation (injection attacks)
|
||||
2. Test authentication/authorization
|
||||
3. Test data sanitization
|
||||
4. Test rate limiting
|
||||
5. Document security assumptions
|
||||
|
||||
Each test should initially fail and demonstrate the vulnerability.
|
||||
```
|
||||
|
||||
## Workflow Automation Patterns
|
||||
|
||||
### Full Autonomous Mode
|
||||
|
||||
```
|
||||
Implement Task {TASK_ID} completely autonomously:
|
||||
1. Start the workflow
|
||||
2. For each subtask:
|
||||
a. Read requirements
|
||||
b. Write failing tests
|
||||
c. Implement to pass tests
|
||||
d. Commit changes
|
||||
3. Continue until all subtasks complete
|
||||
4. Report final status
|
||||
|
||||
Rules:
|
||||
- Never skip the RED phase
|
||||
- Always verify tests fail first
|
||||
- Implement minimal working code
|
||||
- Commit after each subtask
|
||||
- Handle errors gracefully with retries
|
||||
```
|
||||
|
||||
### Supervised Mode
|
||||
|
||||
```
|
||||
Work on Task {TASK_ID} with human oversight:
|
||||
1. Start workflow and show plan
|
||||
2. For each subtask:
|
||||
a. Show test plan, wait for approval
|
||||
b. Write and run tests, show results
|
||||
c. Show implementation plan, wait for approval
|
||||
d. Implement and verify
|
||||
e. Show commit message, wait for approval
|
||||
3. Request feedback between subtasks
|
||||
```
|
||||
|
||||
### Review Mode
|
||||
|
||||
```
|
||||
Review the current workflow state:
|
||||
1. Show all completed subtasks and their commits
|
||||
2. Identify remaining subtasks
|
||||
3. Check test coverage
|
||||
4. Verify git history is clean
|
||||
5. Recommend next steps
|
||||
```
|
||||
|
||||
## Error Recovery Patterns
|
||||
|
||||
### Retry with Learning
|
||||
|
||||
```
|
||||
The {PHASE} phase failed {N} times. Please:
|
||||
1. Review all previous attempts
|
||||
2. Identify the pattern of failures
|
||||
3. Propose a different approach
|
||||
4. Explain why this approach should work
|
||||
5. Implement with the new approach
|
||||
```
|
||||
|
||||
### Escalate to Human
|
||||
|
||||
```
|
||||
After {MAX_ATTEMPTS} attempts, unable to complete {SUBTASK}.
|
||||
|
||||
Please:
|
||||
1. Document what was tried
|
||||
2. Explain what's not working
|
||||
3. Provide relevant code and test output
|
||||
4. Suggest where human expertise is needed
|
||||
5. Save current state for manual intervention
|
||||
```
|
||||
|
||||
### Reset and Restart
|
||||
|
||||
```
|
||||
Workflow is in an inconsistent state. Please:
|
||||
1. Save any valuable work
|
||||
2. Abort the current workflow
|
||||
3. Explain what went wrong
|
||||
4. Propose a better approach
|
||||
5. Restart with improved strategy
|
||||
```
|
||||
|
||||
## Example Complete Session
|
||||
|
||||
```
|
||||
I need to implement Task 7 which has 5 subtasks. Please work autonomously with these preferences:
|
||||
|
||||
1. Testing Framework: vitest
|
||||
2. Code Style: TypeScript strict mode, functional style preferred
|
||||
3. Commit Style: Conventional commits with detailed messages
|
||||
4. Review: Show me status after each subtask completion
|
||||
|
||||
Workflow:
|
||||
1. Start autopilot for task 7
|
||||
2. For each subtask (7.1 through 7.5):
|
||||
- RED: Write comprehensive failing tests
|
||||
- GREEN: Implement minimal code to pass
|
||||
- COMMIT: Auto-generate commit and advance
|
||||
3. Final: Show summary of all commits and changes
|
||||
|
||||
Error Handling:
|
||||
- If phase validation fails, explain why and retry
|
||||
- If tests are flaky, identify and fix
|
||||
- If stuck after 3 attempts, ask for help
|
||||
|
||||
Let's begin!
|
||||
```
|
||||
|
||||
## Tips for Effective Prompts
|
||||
|
||||
### 1. Be Specific About Context
|
||||
|
||||
**Good:**
|
||||
```
|
||||
For the UserAuthenticationService in src/services/auth.ts,
|
||||
write tests for the login method using vitest.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
Write tests for authentication.
|
||||
```
|
||||
|
||||
### 2. Specify Success Criteria
|
||||
|
||||
**Good:**
|
||||
```
|
||||
Tests should cover:
|
||||
1. Successful login with valid credentials
|
||||
2. Failed login with invalid password
|
||||
3. Account lockout after 5 failures
|
||||
4. Rate limiting (max 10 attempts/minute)
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
Test login functionality.
|
||||
```
|
||||
|
||||
### 3. Request Explanations
|
||||
|
||||
**Good:**
|
||||
```
|
||||
Implement the feature and explain:
|
||||
1. Why this approach was chosen
|
||||
2. What edge cases are handled
|
||||
3. What assumptions were made
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
Just implement it.
|
||||
```
|
||||
|
||||
### 4. Include Project Context
|
||||
|
||||
**Good:**
|
||||
```
|
||||
Following the existing pattern in src/models/,
|
||||
create a User model that:
|
||||
- Extends BaseModel
|
||||
- Uses Zod for validation
|
||||
- Includes proper TypeScript types
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
Create a user model.
|
||||
```
|
||||
|
||||
## Troubleshooting Prompts
|
||||
|
||||
### When Tests Won't Fail
|
||||
|
||||
```
|
||||
My test is passing when it should fail. Please:
|
||||
1. Review the test code
|
||||
2. Identify why it's passing
|
||||
3. Check if implementation already exists
|
||||
4. Rewrite test to actually test new behavior
|
||||
5. Verify it fails this time
|
||||
```
|
||||
|
||||
### When Implementation is Incomplete
|
||||
|
||||
```
|
||||
Tests are still failing after implementation. Please:
|
||||
1. Show me the failing test output
|
||||
2. Review the implementation
|
||||
3. Identify what's missing
|
||||
4. Fix the implementation
|
||||
5. Verify all tests pass
|
||||
```
|
||||
|
||||
### When Workflow Won't Advance
|
||||
|
||||
```
|
||||
Can't complete the phase. Getting error: {ERROR}
|
||||
|
||||
Please:
|
||||
1. Check workflow status
|
||||
2. Verify test results format is correct
|
||||
3. Check if phase validation requirements are met
|
||||
4. If needed, show me how to manually fix state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [AI Agent Integration Guide](../ai-agent-integration.mdx)
|
||||
- [CLAUDE.md Template](./CLAUDE.md.template)
|
||||
- [Command Reference](../command-reference.mdx)
|
||||
- [Testing Best Practices](./testing-best-practices.mdx)
|
||||
Reference in New Issue
Block a user