github/claude-task-master

Fork 0

mirror of https://github.com/eyaltoledano/claude-task-master.git synced 2026-04-03 08:19:14 -06:00

Phase 0: TDD Autopilot Dry-Run Foundation #31

New issue

Closed

opened 2025-10-14 15:38:54 -06:00 by navan · 0 comments

navan commented

2025-10-14 15:38:54 -06:00

Owner

Originally created by @Crunchyman-ralph on 10/7/2025

🎯 Overview

Implements Phase 0 of the autonomous TDD workflow system - a complete dry-run foundation with orchestration architecture for future execution.

This PR delivers a working tm autopilot <taskId> --dry-run command that validates the environment, analyzes tasks, and displays a complete execution plan without making any changes.

✨ What's New

🏗️ Core Services (`tm-core`)

PreflightChecker (`packages/tm-core/src/services/preflight-checker.service.ts`)

Validates environment prerequisites before autopilot execution:

✅ Test command detection from package.json
✅ Git working tree status validation
✅ Required tools availability (git, gh, node, npm)
✅ Default branch detection

TaskLoaderService (`packages/tm-core/src/services/task-loader.service.ts`)

Comprehensive task validation and dependency analysis:

✅ Task existence and structure validation
✅ Subtask dependency analysis with circular dependency detection
✅ Execution order calculation via topological sort
✅ Helpful expansion suggestions for tasks without subtasks

🖥️ CLI Command

Autopilot Command (`apps/cli/src/commands/autopilot.command.ts`)

New command: tm autopilot <taskId> [options]

Options:

--dry-run - Show execution plan without performing actions
--format <text|json> - Output format (default: text)
--project <path> - Project root directory

Features:

Displays complete execution plan with preflight checks
Shows subtasks in dependency order
Previews RED/GREEN/COMMIT phases per subtask
Clean error handling with actionable suggestions
Registered in CLI command registry

📚 Architecture Documentation

Phase 0 Completion (`.taskmaster/docs/tdd-workflow-phase-0-spike.md`)

✅ Marked as complete with implementation reference

Orchestration Model Clarification (`.taskmaster/docs/autonomous-tdd-git-workflow.md`)

Added "Execution Model" section clarifying the orchestration approach:

Orchestrator Role (tm-core):

Maintains state machine tracking TDD phases per subtask
Returns "work units" describing what to do next
Validates preconditions (tests pass, git clean, etc.)
Records progress and persists for resumability

Executor Role (Claude Code/AI via MCP):

Queries orchestrator for next work unit
Executes work (writes tests, code, runs commands)
Reports results back to orchestrator
Handles all file operations and tool invocations

Why This Architecture?

✅ Leverages existing AI capabilities (no code generation in orchestrator)
✅ Clean separation: state management vs execution
✅ Human-in-the-loop: easy to inspect and intervene
✅ Simpler implementation: orchestrator is pure logic
✅ Flexible: any executor (Claude Code, human, other AI) can execute

Phase 1 Roadmap (`.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md`)

New comprehensive specification for next phase:

Detailed WorkflowOrchestrator state machine design
MCP integration plan with new tool definitions
API specifications (getNextWorkUnit, completeWorkUnit, getRunState)
Implementation checklist with 6 clear steps
Example usage flows showing Claude Code interaction

🚀 Example Usage

# Dry-run autopilot for task 42
$ tm autopilot 42 --dry-run

Autopilot Plan for Task #42 [analytics]: User metrics tracking
─────────────────────────────────────────────────────────────

Preflight Checks:
  ✓ Working tree is clean
  ✓ Test command detected: npm test
  ✓ Tools available: git, gh, node, npm
  ✓ Current branch: main (will create new branch)
  ✓ Task has 3 subtasks ready to execute

Branch & Tag:
  → Will create branch: analytics/task-42-user-metrics
  → Will set active tag: analytics

Execution Plan (3 subtasks):

  1. Subtask 42.1: Add metrics schema
     RED:    Generate tests → src/__tests__/schema.test.js
     GREEN:  Implement code → src/schema.js
     COMMIT: "feat(metrics): add metrics schema (task 42.1)"

  2. Subtask 42.2: Add collection endpoint [depends on 42.1]
     RED:    Generate tests → src/api/__tests__/metrics.test.js
     GREEN:  Implement code → src/api/metrics.js
     COMMIT: "feat(metrics): add collection endpoint (task 42.2)"

  3. Subtask 42.3: Add dashboard widget [depends on 42.2]
     RED:    Generate tests → src/components/__tests__/MetricsWidget.test.jsx
     GREEN:  Implement code → src/components/MetricsWidget.jsx
     COMMIT: "feat(metrics): add dashboard widget (task 42.3)"

Finalization:
  → Run full test suite with coverage (threshold: 80%)
  → Push branch to origin (will confirm)
  → Create PR targeting main

Run without --dry-run to execute.

🔧 Technical Details

Preflight Validation

The PreflightChecker runs 4 comprehensive checks:

Test Command - Validates package.json has a test script
Git Working Tree - Ensures clean state (no uncommitted changes)
Required Tools - Verifies git, gh, node, npm availability
Default Branch - Detects repository default branch

Task Validation

The TaskLoaderService performs multi-step validation:

Task Existence - Loads from TaskMaster state
Status Check - Rejects completed/cancelled tasks
Subtask Presence - Ensures task has been expanded
Structure Validation - Verifies subtask fields (title, description)
Dependency Analysis - Detects circular and missing dependencies
Execution Order - Topological sort for safe execution sequence

Error Handling

Comprehensive error types with actionable suggestions:

task_not_found → suggests using task-master list
task_completed → suggests choosing different task
no_subtasks → suggests task-master expand --id=<id>
circular_dependencies → shows dependency chain
missing_dependencies → lists invalid references
invalid_structure → suggests re-expansion

🎨 Architecture Highlights

State Machine Design

Phase transitions follow strict rules:

START → RED → GREEN → COMMIT → (next subtask RED) → ... → FINALIZE → END

Preconditions:

RED: Clean git state (or staged from failed GREEN)
GREEN: Tests exist and are failing
COMMIT: All tests passing, coverage meets threshold

Work Unit API (Phase 1)

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
}

MCP Integration (Phase 1)

New tools to be added:

mcp__task_master_ai__autopilot_start(taskId, dryRun?)
mcp__task_master_ai__autopilot_next_work_unit(runId)
mcp__task_master_ai__autopilot_complete_work_unit(runId, workUnitId, result)
mcp__task_master_ai__autopilot_get_state(runId)
mcp__task_master_ai__autopilot_pause/resume(runId)

📦 Files Changed

New Files

apps/cli/src/commands/autopilot.command.ts (425 lines)
packages/tm-core/src/services/preflight-checker.service.ts (317 lines)
packages/tm-core/src/services/task-loader.service.ts (390 lines)
.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md (500+ lines)

Modified Files

apps/cli/src/command-registry.ts - Added autopilot command
apps/cli/src/index.ts - Exported AutopilotCommand
packages/tm-core/src/services/index.ts - Exported new services
.taskmaster/docs/autonomous-tdd-git-workflow.md - Added execution model section
.taskmaster/docs/tdd-workflow-phase-0-spike.md - Marked complete
.taskmaster/tasks/tasks.json - Updated task statuses

✅ Success Criteria Met

tm autopilot <taskId> --dry-run command functional
Preflight checks detect environment issues
Task loading integrates with TaskMaster state
Dependency resolution handles circular references
Execution order respects dependencies
Dry-run shows complete execution plan
No actual git operations or file modifications in dry-run
Clean error messages with actionable suggestions
Architecture documentation complete for Phase 1

🚫 Out of Scope (Phase 0)

The following are intentionally deferred to Phase 1:

❌ Actual test generation
❌ Actual code implementation
❌ Git operations (branch creation, commits, push)
❌ PR creation
❌ Test execution
❌ WorkflowOrchestrator implementation
❌ MCP tool integration

🔜 Next Steps (Phase 1)

Phase 1 will implement the WorkflowOrchestrator state machine:

WorkflowOrchestrator Service - State machine with work unit generation
Git/Test Adapters - Status checks and validation (no execution)
MCP Integration - Expose work unit API to Claude Code
CLI Integration - Interactive mode showing work units
State Persistence - Run state in .taskmaster/reports/runs/
Integration Testing - End-to-end with Claude Code via MCP

See .taskmaster/docs/tdd-workflow-phase-1-orchestrator.md for detailed roadmap.

🧪 Testing

Manual Testing Performed

Dry-run with task having 1 subtask
Dry-run with multiple subtasks
Dry-run with subtask dependencies
Error handling: task without subtasks
Error handling: dirty git working tree
Error handling: missing tools
Build verification: npm run build successful

Automated Tests

Unit tests for state machine logic (Phase 1)
Integration tests for MCP tools (Phase 1)

📝 Migration Notes

No breaking changes - This is purely additive:

New command: tm autopilot
New services in @tm/core
All existing functionality unchanged

🤝 Review Focus

Please review:

Architecture Decision: Orchestration model (state machine) vs direct execution
PreflightChecker: Are the checks comprehensive enough?
TaskLoaderService: Dependency resolution logic (circular detection)
Error Messages: Are suggestions actionable and helpful?
Phase 1 Roadmap: Does the WorkflowOrchestrator design make sense?

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- New "autopilot" CLI to run tasks autonomously with preflight checks, task validation, dry‑run and JSON/text output.
- Exposed preflight, task-loading and Git helper utilities for CLI and programmatic use.
- Safer worktree creation script with clearer guidance and upstream handling.
Documentation
- Expanded autonomous TDD workflow docs: overview, Phase 0 status, Phase 1 orchestrator, execution model and roadmap.
Chores
- Updated state/metadata, minor config reformatting, and removal of an auto-review base-branches setting.

*Originally created by @Crunchyman-ralph on 10/7/2025* ## 🎯 Overview Implements **Phase 0** of the autonomous TDD workflow system - a complete dry-run foundation with orchestration architecture for future execution. This PR delivers a working `tm autopilot <taskId> --dry-run` command that validates the environment, analyzes tasks, and displays a complete execution plan without making any changes. --- ## ✨ What's New ### 🏗️ Core Services (`tm-core`) #### **PreflightChecker** (`packages/tm-core/src/services/preflight-checker.service.ts`) Validates environment prerequisites before autopilot execution: - ✅ Test command detection from `package.json` - ✅ Git working tree status validation - ✅ Required tools availability (`git`, `gh`, `node`, `npm`) - ✅ Default branch detection #### **TaskLoaderService** (`packages/tm-core/src/services/task-loader.service.ts`) Comprehensive task validation and dependency analysis: - ✅ Task existence and structure validation - ✅ Subtask dependency analysis with **circular dependency detection** - ✅ Execution order calculation via **topological sort** - ✅ Helpful expansion suggestions for tasks without subtasks ### 🖥️ CLI Command #### **Autopilot Command** (`apps/cli/src/commands/autopilot.command.ts`) New command: `tm autopilot <taskId> [options]` **Options**: - `--dry-run` - Show execution plan without performing actions - `--format <text|json>` - Output format (default: text) - `--project <path>` - Project root directory **Features**: - Displays complete execution plan with preflight checks - Shows subtasks in dependency order - Previews RED/GREEN/COMMIT phases per subtask - Clean error handling with actionable suggestions - Registered in CLI command registry ### 📚 Architecture Documentation #### **Phase 0 Completion** (`.taskmaster/docs/tdd-workflow-phase-0-spike.md`) - ✅ Marked as complete with implementation reference #### **Orchestration Model Clarification** (`.taskmaster/docs/autonomous-tdd-git-workflow.md`) Added **"Execution Model"** section clarifying the orchestration approach: **Orchestrator Role** (tm-core): - Maintains state machine tracking TDD phases per subtask - Returns "work units" describing what to do next - Validates preconditions (tests pass, git clean, etc.) - Records progress and persists for resumability **Executor Role** (Claude Code/AI via MCP): - Queries orchestrator for next work unit - Executes work (writes tests, code, runs commands) - Reports results back to orchestrator - Handles all file operations and tool invocations **Why This Architecture?** - ✅ Leverages existing AI capabilities (no code generation in orchestrator) - ✅ Clean separation: state management vs execution - ✅ Human-in-the-loop: easy to inspect and intervene - ✅ Simpler implementation: orchestrator is pure logic - ✅ Flexible: any executor (Claude Code, human, other AI) can execute #### **Phase 1 Roadmap** (`.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md`) New comprehensive specification for next phase: - Detailed WorkflowOrchestrator state machine design - MCP integration plan with new tool definitions - API specifications (`getNextWorkUnit`, `completeWorkUnit`, `getRunState`) - Implementation checklist with 6 clear steps - Example usage flows showing Claude Code interaction --- ## 🚀 Example Usage ```bash # Dry-run autopilot for task 42 $ tm autopilot 42 --dry-run Autopilot Plan for Task #42 [analytics]: User metrics tracking ───────────────────────────────────────────────────────────── Preflight Checks: ✓ Working tree is clean ✓ Test command detected: npm test ✓ Tools available: git, gh, node, npm ✓ Current branch: main (will create new branch) ✓ Task has 3 subtasks ready to execute Branch & Tag: → Will create branch: analytics/task-42-user-metrics → Will set active tag: analytics Execution Plan (3 subtasks): 1. Subtask 42.1: Add metrics schema RED: Generate tests → src/__tests__/schema.test.js GREEN: Implement code → src/schema.js COMMIT: "feat(metrics): add metrics schema (task 42.1)" 2. Subtask 42.2: Add collection endpoint [depends on 42.1] RED: Generate tests → src/api/__tests__/metrics.test.js GREEN: Implement code → src/api/metrics.js COMMIT: "feat(metrics): add collection endpoint (task 42.2)" 3. Subtask 42.3: Add dashboard widget [depends on 42.2] RED: Generate tests → src/components/__tests__/MetricsWidget.test.jsx GREEN: Implement code → src/components/MetricsWidget.jsx COMMIT: "feat(metrics): add dashboard widget (task 42.3)" Finalization: → Run full test suite with coverage (threshold: 80%) → Push branch to origin (will confirm) → Create PR targeting main Run without --dry-run to execute. ``` --- ## 🔧 Technical Details ### Preflight Validation The `PreflightChecker` runs 4 comprehensive checks: 1. **Test Command** - Validates `package.json` has a test script 2. **Git Working Tree** - Ensures clean state (no uncommitted changes) 3. **Required Tools** - Verifies `git`, `gh`, `node`, `npm` availability 4. **Default Branch** - Detects repository default branch ### Task Validation The `TaskLoaderService` performs multi-step validation: 1. **Task Existence** - Loads from TaskMaster state 2. **Status Check** - Rejects completed/cancelled tasks 3. **Subtask Presence** - Ensures task has been expanded 4. **Structure Validation** - Verifies subtask fields (title, description) 5. **Dependency Analysis** - Detects circular and missing dependencies 6. **Execution Order** - Topological sort for safe execution sequence ### Error Handling Comprehensive error types with actionable suggestions: - `task_not_found` → suggests using `task-master list` - `task_completed` → suggests choosing different task - `no_subtasks` → suggests `task-master expand --id=<id>` - `circular_dependencies` → shows dependency chain - `missing_dependencies` → lists invalid references - `invalid_structure` → suggests re-expansion --- ## 🎨 Architecture Highlights ### State Machine Design Phase transitions follow strict rules: ``` START → RED → GREEN → COMMIT → (next subtask RED) → ... → FINALIZE → END ``` **Preconditions**: - RED: Clean git state (or staged from failed GREEN) - GREEN: Tests exist and are failing - COMMIT: All tests passing, coverage meets threshold ### Work Unit API (Phase 1) ```typescript 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 } ``` ### MCP Integration (Phase 1) New tools to be added: - `mcp__task_master_ai__autopilot_start(taskId, dryRun?)` - `mcp__task_master_ai__autopilot_next_work_unit(runId)` - `mcp__task_master_ai__autopilot_complete_work_unit(runId, workUnitId, result)` - `mcp__task_master_ai__autopilot_get_state(runId)` - `mcp__task_master_ai__autopilot_pause/resume(runId)` --- ## 📦 Files Changed ### New Files - `apps/cli/src/commands/autopilot.command.ts` (425 lines) - `packages/tm-core/src/services/preflight-checker.service.ts` (317 lines) - `packages/tm-core/src/services/task-loader.service.ts` (390 lines) - `.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md` (500+ lines) ### Modified Files - `apps/cli/src/command-registry.ts` - Added autopilot command - `apps/cli/src/index.ts` - Exported AutopilotCommand - `packages/tm-core/src/services/index.ts` - Exported new services - `.taskmaster/docs/autonomous-tdd-git-workflow.md` - Added execution model section - `.taskmaster/docs/tdd-workflow-phase-0-spike.md` - Marked complete - `.taskmaster/tasks/tasks.json` - Updated task statuses --- ## ✅ Success Criteria Met - [x] `tm autopilot <taskId> --dry-run` command functional - [x] Preflight checks detect environment issues - [x] Task loading integrates with TaskMaster state - [x] Dependency resolution handles circular references - [x] Execution order respects dependencies - [x] Dry-run shows complete execution plan - [x] No actual git operations or file modifications in dry-run - [x] Clean error messages with actionable suggestions - [x] Architecture documentation complete for Phase 1 --- ## 🚫 Out of Scope (Phase 0) The following are **intentionally deferred** to Phase 1: - ❌ Actual test generation - ❌ Actual code implementation - ❌ Git operations (branch creation, commits, push) - ❌ PR creation - ❌ Test execution - ❌ WorkflowOrchestrator implementation - ❌ MCP tool integration --- ## 🔜 Next Steps (Phase 1) Phase 1 will implement the **WorkflowOrchestrator** state machine: 1. **WorkflowOrchestrator Service** - State machine with work unit generation 2. **Git/Test Adapters** - Status checks and validation (no execution) 3. **MCP Integration** - Expose work unit API to Claude Code 4. **CLI Integration** - Interactive mode showing work units 5. **State Persistence** - Run state in `.taskmaster/reports/runs/` 6. **Integration Testing** - End-to-end with Claude Code via MCP See `.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md` for detailed roadmap. --- ## 🧪 Testing ### Manual Testing Performed - [x] Dry-run with task having 1 subtask - [x] Dry-run with multiple subtasks - [x] Dry-run with subtask dependencies - [x] Error handling: task without subtasks - [x] Error handling: dirty git working tree - [x] Error handling: missing tools - [x] Build verification: `npm run build` successful ### Automated Tests - Unit tests for state machine logic (Phase 1) - Integration tests for MCP tools (Phase 1) --- ## 📝 Migration Notes **No breaking changes** - This is purely additive: - New command: `tm autopilot` - New services in `@tm/core` - All existing functionality unchanged --- ## 🤝 Review Focus Please review: 1. **Architecture Decision**: Orchestration model (state machine) vs direct execution 2. **PreflightChecker**: Are the checks comprehensive enough? 3. **TaskLoaderService**: Dependency resolution logic (circular detection) 4. **Error Messages**: Are suggestions actionable and helpful? 5. **Phase 1 Roadmap**: Does the WorkflowOrchestrator design make sense? --- 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **New Features** * New "autopilot" CLI to run tasks autonomously with preflight checks, task validation, dry‑run and JSON/text output. * Exposed preflight, task-loading and Git helper utilities for CLI and programmatic use. * Safer worktree creation script with clearer guidance and upstream handling. * **Documentation** * Expanded autonomous TDD workflow docs: overview, Phase 0 status, Phase 1 orchestrator, execution model and roadmap. * **Chores** * Updated state/metadata, minor config reformatting, and removal of an auto-review base-branches setting.