claude-task-master/.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md

# Phase 1: Core Rails - State Machine & Orchestration

## Objective
Build the WorkflowOrchestrator as a state machine that guides AI sessions through TDD workflow, rather than directly executing code.

## Architecture Overview

### Execution Model
The orchestrator acts as a **state manager and guide**, not a code executor:

```
┌─────────────────────────────────────────────────────────────┐
│                    Claude Code (MCP Client)                  │
│  - Queries "what to do next"                                │
│  - Executes work (writes tests, code, runs commands)        │
│  - Reports completion                                        │
└────────────────┬────────────────────────────────────────────┘
                 │ MCP Protocol
                 ▼
┌─────────────────────────────────────────────────────────────┐
│              WorkflowOrchestrator (tm-core)                  │
│  - Maintains state machine (RED → GREEN → COMMIT)           │
│  - Returns work units with context                          │
│  - Validates preconditions                                  │
│  - Records progress                                         │
│  - Persists state for resumability                          │
└─────────────────────────────────────────────────────────────┘
```

### Why This Approach?
1. **Separation of Concerns**: State management separate from code execution
2. **Leverage Existing Tools**: Uses Claude Code's capabilities instead of reimplementing
3. **Human-in-the-Loop**: Easy to inspect state and intervene at any phase
4. **Simpler Implementation**: Orchestrator is pure logic, no AI model integration needed
5. **Flexible Executors**: Any tool (Claude Code, human, other AI) can execute work units

## Core Components

### 1. WorkflowOrchestrator Service
**Location**: `packages/tm-core/src/services/workflow-orchestrator.service.ts`

**Responsibilities**:
- Track current phase (RED/GREEN/COMMIT) per subtask
- Generate work units with context for each phase
- Validate phase completion criteria
- Advance state machine on successful completion
- Handle errors and retry logic
- Persist run state for resumability

**API**:
```typescript
interface WorkflowOrchestrator {
  // Start a new autopilot run
  startRun(taskId: string, options?: RunOptions): Promise<RunContext>;

  // Get next work unit to execute
  getNextWorkUnit(runId: string): Promise<WorkUnit | null>;

  // Report work unit completion
  completeWorkUnit(
    runId: string,
    workUnitId: string,
    result: WorkUnitResult
  ): Promise<void>;

  // Get current run state
  getRunState(runId: string): Promise<RunState>;

  // Pause/resume
  pauseRun(runId: string): Promise<void>;
  resumeRun(runId: string): Promise<void>;
}

interface WorkUnit {
  id: string;                    // Unique work unit ID
  phase: 'RED' | 'GREEN' | 'COMMIT';
  subtaskId: string;             // e.g., "42.1"
  action: string;                // Human-readable description
  context: WorkUnitContext;      // All info needed to execute
  preconditions: Precondition[]; // Checks before execution
}

interface WorkUnitContext {
  taskId: string;
  taskTitle: string;
  subtaskTitle: string;
  subtaskDescription: string;
  dependencies: string[];        // Completed subtask IDs
  testCommand: string;           // e.g., "npm test"

  // Phase-specific context
  redPhase?: {
    testFile: string;            // Where to create test
    testFramework: string;       // e.g., "vitest"
    acceptanceCriteria: string[];
  };

  greenPhase?: {
    testFile: string;            // Test to make pass
    implementationHints: string[];
    expectedFiles: string[];     // Files likely to modify
  };

  commitPhase?: {
    commitMessage: string;       // Pre-generated message
    filesToCommit: string[];     // Files modified in RED+GREEN
  };
}

interface WorkUnitResult {
  success: boolean;
  phase: 'RED' | 'GREEN' | 'COMMIT';

  // RED phase results
  testsCreated?: string[];
  testsFailed?: number;

  // GREEN phase results
  testsPassed?: number;
  filesModified?: string[];
  attempts?: number;

  // COMMIT phase results
  commitSha?: string;

  // Common
  error?: string;
  logs?: string;
}

interface RunState {
  runId: string;
  taskId: string;
  status: 'running' | 'paused' | 'completed' | 'failed';
  currentPhase: 'RED' | 'GREEN' | 'COMMIT';
  currentSubtask: string;
  completedSubtasks: string[];
  failedSubtasks: string[];
  startTime: Date;
  lastUpdateTime: Date;

  // Resumability
  checkpoint: {
    subtaskId: string;
    phase: 'RED' | 'GREEN' | 'COMMIT';
    attemptNumber: number;
  };
}
```

### 2. State Machine Logic

**Phase Transitions**:
```
START → RED(subtask 1) → GREEN(subtask 1) → COMMIT(subtask 1)
                                               ↓
                        RED(subtask 2) ← ─ ─ ─ ┘
                             ↓
                        GREEN(subtask 2)
                             ↓
                        COMMIT(subtask 2)
                             ↓
                           (repeat for remaining subtasks)
                             ↓
                        FINALIZE → END
```

**Phase Rules**:
- **RED**: Can only transition to GREEN if tests created and failing
- **GREEN**: Can only transition to COMMIT if tests passing (attempt < maxAttempts)
- **COMMIT**: Can only transition to next RED if commit successful
- **FINALIZE**: Can only start if all subtasks completed

**Preconditions**:
- RED: No uncommitted changes (or staged from previous GREEN that failed)
- GREEN: RED phase complete, tests exist and are failing
- COMMIT: GREEN phase complete, all tests passing, coverage meets threshold

### 3. MCP Integration

**New MCP Tools** (expose WorkflowOrchestrator via MCP):
```typescript
// Start an autopilot run
mcp__task_master_ai__autopilot_start(taskId: string, dryRun?: boolean)

// Get next work unit
mcp__task_master_ai__autopilot_next_work_unit(runId: string)

// Complete current work unit
mcp__task_master_ai__autopilot_complete_work_unit(
  runId: string,
  workUnitId: string,
  result: WorkUnitResult
)

// Get run state
mcp__task_master_ai__autopilot_get_state(runId: string)

// Pause/resume
mcp__task_master_ai__autopilot_pause(runId: string)
mcp__task_master_ai__autopilot_resume(runId: string)
```

### 4. Git/Test Adapters

**GitAdapter** (`packages/tm-core/src/services/git-adapter.service.ts`):
- Check working tree status
- Validate branch state
- Read git config (user, remote, default branch)
- **Does NOT execute** git commands (that's executor's job)

**TestAdapter** (`packages/tm-core/src/services/test-adapter.service.ts`):
- Detect test framework from package.json
- Parse test output (failures, passes, coverage)
- Validate coverage thresholds
- **Does NOT run** tests (that's executor's job)

### 5. Run State Persistence

**Storage Location**: `.taskmaster/reports/runs/<runId>/`

**Files**:
- `state.json` - Current run state (for resumability)
- `log.jsonl` - Event stream (timestamped work unit completions)
- `manifest.json` - Run metadata
- `work-units.json` - All work units generated for this run

**Example `state.json`**:
```json
{
  "runId": "2025-01-15-142033",
  "taskId": "42",
  "status": "paused",
  "currentPhase": "GREEN",
  "currentSubtask": "42.2",
  "completedSubtasks": ["42.1"],
  "failedSubtasks": [],
  "checkpoint": {
    "subtaskId": "42.2",
    "phase": "GREEN",
    "attemptNumber": 2
  },
  "startTime": "2025-01-15T14:20:33Z",
  "lastUpdateTime": "2025-01-15T14:35:12Z"
}
```

## Implementation Plan

### Step 1: WorkflowOrchestrator Skeleton
- [ ] Create `workflow-orchestrator.service.ts` with interfaces
- [ ] Implement state machine logic (phase transitions)
- [ ] Add run state persistence (state.json, log.jsonl)
- [ ] Write unit tests for state machine

### Step 2: Work Unit Generation
- [ ] Implement `getNextWorkUnit()` with context assembly
- [ ] Generate RED phase work units (test file paths, criteria)
- [ ] Generate GREEN phase work units (implementation hints)
- [ ] Generate COMMIT phase work units (commit messages)

### Step 3: Git/Test Adapters
- [ ] Create GitAdapter for status checks only
- [ ] Create TestAdapter for output parsing only
- [ ] Add precondition validation using adapters
- [ ] Write adapter unit tests

### Step 4: MCP Integration
- [ ] Add MCP tool definitions in `packages/mcp-server/src/tools/`
- [ ] Wire up WorkflowOrchestrator to MCP tools
- [ ] Test MCP tools via Claude Code
- [ ] Document MCP workflow in CLAUDE.md

### Step 5: CLI Integration
- [ ] Update `autopilot.command.ts` to call WorkflowOrchestrator
- [ ] Add `--interactive` mode that shows work units and waits for completion
- [ ] Add `--resume` flag to continue paused runs
- [ ] Test end-to-end flow

### Step 6: Integration Testing
- [ ] Create test task with 2-3 subtasks
- [ ] Run autopilot start → get work unit → complete → repeat
- [ ] Verify state persistence and resumability
- [ ] Test failure scenarios (test failures, git issues)

## Success Criteria
- [ ] WorkflowOrchestrator can generate work units for all phases
- [ ] MCP tools allow Claude Code to query and complete work units
- [ ] State persists correctly between work unit completions
- [ ] Run can be paused and resumed from checkpoint
- [ ] Adapters validate preconditions without executing commands
- [ ] End-to-end: Claude Code can complete a simple task via work units

## Out of Scope (Phase 1)
- Actual git operations (branch creation, commits) - executor handles this
- Actual test execution - executor handles this
- PR creation - deferred to Phase 2
- TUI interface - deferred to Phase 3
- Coverage enforcement - deferred to Phase 2

## Example Usage Flow

```bash
# Terminal 1: Claude Code session
$ claude

# In Claude Code (via MCP):
> Start autopilot for task 42
[Calls mcp__task_master_ai__autopilot_start(42)]
→ Run started: run-2025-01-15-142033

> Get next work unit
[Calls mcp__task_master_ai__autopilot_next_work_unit(run-2025-01-15-142033)]
→ Work unit: RED phase for subtask 42.1
→ Action: Generate failing tests for metrics schema
→ Test file: src/__tests__/schema.test.js
→ Framework: vitest

> [Claude Code creates test file, runs tests]

> Complete work unit
[Calls mcp__task_master_ai__autopilot_complete_work_unit(
  run-2025-01-15-142033,
  workUnit-42.1-RED,
  { success: true, testsCreated: ['src/__tests__/schema.test.js'], testsFailed: 3 }
)]
→ Work unit completed. State saved.

> Get next work unit
[Calls mcp__task_master_ai__autopilot_next_work_unit(run-2025-01-15-142033)]
→ Work unit: GREEN phase for subtask 42.1
→ Action: Implement code to pass failing tests
→ Test file: src/__tests__/schema.test.js
→ Expected implementation: src/schema.js

> [Claude Code implements schema.js, runs tests, confirms all pass]

> Complete work unit
[...]
→ Work unit completed. Ready for COMMIT.

> Get next work unit
[...]
→ Work unit: COMMIT phase for subtask 42.1
→ Commit message: "feat(metrics): add metrics schema (task 42.1)"
→ Files to commit: src/__tests__/schema.test.js, src/schema.js

> [Claude Code stages files and commits]

> Complete work unit
[...]
→ Subtask 42.1 complete! Moving to 42.2...
```

## Dependencies
- Existing TaskService (task loading, status updates)
- Existing PreflightChecker (environment validation)
- Existing TaskLoaderService (dependency ordering)
- MCP server infrastructure

## Estimated Effort
7-10 days

## Next Phase
Phase 2 will add:
- PR creation via gh CLI
- Coverage enforcement
- Enhanced error recovery
- Full resumability testing