feat: Phase 1 - Complete TDD Workflow Automation System

[Crunchyman-ralph]

Summary

Implements Phase 1 of the autonomous TDD workflow system - a complete infrastructure for AI agents to execute test-driven development workflows automatically. This includes core orchestration, CLI commands, MCP tools, comprehensive documentation, and configuration management.

Architecture Overview

This PR delivers a production-ready TDD workflow system consisting of:

1. Core Orchestration Engine (Tasks 1-6): State machine, persistence, git operations, test validation
2. AI Agent Interface Layer (Tasks 7-8): CLI commands and MCP tools for programmatic control
3. Integration Documentation (Task 9): Comprehensive guides, templates, and examples
4. Configuration System (Task 10): Schema validation, defaults, and gitignore rules

Key Features

TDD State Machine (Tasks 4-6)

• WorkflowOrchestrator: Complete RED → GREEN → COMMIT cycle enforcement
• Phase Validators: Ensures tests fail in RED, pass in GREEN
• Attempt Tracking: Monitors retry attempts with configurable limits
• Activity Logger: Comprehensive event logging with structured JSONL format
• State Persistence: Checkpoint-based recovery from interruptions
• Commit Message Generation: Intelligent scope detection with metadata embedding

CLI Commands (Task 7)

tm autopilot start <taskId>     # Initialize workflow
tm autopilot next               # Get next action
tm autopilot status             # Check progress
tm autopilot complete           # Advance phase with test results
tm autopilot commit             # Save progress with metadata
tm autopilot resume             # Continue from checkpoint
tm autopilot abort              # Cancel and cleanup

All commands support --json for machine-readable output.

MCP Tools (Task 8)

autopilot_start                 // Initialize workflow
autopilot_next                  // Get next action  
autopilot_status                // Check progress
autopilot_complete_phase        // Advance phase
autopilot_commit                // Save progress
autopilot_resume                // Resume from checkpoint
autopilot_abort                 // Cancel workflow

Full Zod schema validation for all tool parameters.

Documentation (Task 9)

• ai-agent-integration.md: 2,800+ line comprehensive integration guide
• tdd-quickstart.md: 5-minute quick start guide with examples
• CLAUDE.md.template: Ready-to-use AI agent template
• example-prompts.md: 550+ lines of effective prompt patterns

Configuration System (Task 10)

• Zod Schema Validation: Runtime validation for all configuration types
• Workflow Settings: 17 configurable autopilot options including:
  • Branch patterns and git requirements
  • Commit templates with co-author attribution
  • Test thresholds for phase validation
  • Timeout and retry limits
  • Activity logging and state backups
• ConfigManager Integration: validate() and validateUpdate() methods
• Gitignore Rules: Excludes workflow state and logs from version control

Implementation Details

Tasks Completed

• ✅ Task 1: Global Storage System (6 subtasks)
• ✅ Task 2: GitAdapter with Safety Checks (8 subtasks)
• ✅ Task 3: TestResultValidator (4 subtasks)
• ✅ Task 4: WorkflowOrchestrator State Machine (8 subtasks)
• ✅ Task 5: Commit Message Generator (3 subtasks)
• ✅ Task 6: Phase-Specific Orchestrators (6 subtasks)
• ✅ Task 7: CLI Commands for AI Agents (5 subtasks)
• ✅ Task 8: MCP Tools Integration (5 subtasks)
• ✅ Task 9: AI Agent Documentation (2 subtasks)
• ✅ Task 10: Configuration System (4 subtasks)

Total: 10 tasks, 51 subtasks, 30 commits

Test Coverage

• Unit Tests: 128 tests covering core functionality
• Integration Tests: Workflow orchestration end-to-end
• Schema Validation: 26 tests for configuration validation
• All tests passing with comprehensive edge case coverage

Files Changed

• Core (packages/tm-core):
  • New: 40+ implementation and test files
  • Modified: Configuration system integration
• CLI (apps/cli):
  • New: 7 autopilot commands with shared utilities
  • New: Unit and integration test suites
• MCP Server (mcp-server):
  • New: 7 autopilot tools with Zod validation
  • Modified: Tool registration and exports
• Documentation (docs/):
  • New: 4,200+ lines of AI agent integration guides
  • New: Templates and example prompts
• Project Root:
  • Modified: .gitignore with workflow state exclusions

Breaking Changes

None. This is a new feature addition with no changes to existing APIs.

Migration Guide

No migration required. New features are opt-in through:

1. CLI: tm autopilot start <taskId>
2. MCP: autopilot_start tool
3. Configuration: workflow settings in .taskmaster/config.json

Testing Instructions

Manual Testing

# 1. Initialize workflow
tm autopilot start 1

# 2. Write failing test
# ... create test file ...

# 3. Complete RED phase
npm test
tm autopilot complete --results '{"total":1,"passed":0,"failed":1,"skipped":0}'

# 4. Implement feature
# ... write code ...

# 5. Complete GREEN phase
npm test
tm autopilot complete --results '{"total":1,"passed":1,"failed":0,"skipped":0}'

# 6. Commit changes
tm autopilot commit

# 7. Repeat for next subtask

Automated Testing

# Run all tests
npm test

# Run specific test suites
npm test packages/tm-core/src/workflow
npm test packages/tm-core/src/config
npm test apps/cli/tests

Configuration Example

.taskmaster/config.json:

{
  "workflow": {
    "enableAutopilot": true,
    "maxPhaseAttempts": 3,
    "branchPattern": "task-{taskId}",
    "requireCleanWorkingTree": true,
    "autoStageChanges": true,
    "includeCoAuthor": true,
    "coAuthorName": "TaskMaster AI",
    "coAuthorEmail": "taskmaster@example.com",
    "testThresholds": {
      "minTests": 1,
      "maxFailuresInGreen": 0
    },
    "commitMessageTemplate": "{type}({scope}): {description} (Task {taskId}.{subtaskIndex})",
    "defaultCommitType": "feat",
    "operationTimeout": 60000,
    "enableActivityLogging": true,
    "enableStateBackup": true,
    "maxStateBackups": 5
  }
}

Documentation Links

• AI Agent Integration Guide
• TDD Quick Start
• Example Prompts
• CLAUDE.md Template

Related Issues

Closes #[issue-number] (if applicable)

Checklist

• All subtasks implemented and tested
• Unit tests written and passing (128 tests)
• Integration tests added
• Documentation complete (4,200+ lines)
• Configuration schema validated (26 tests)
• CLI commands functional with JSON output
• MCP tools registered and tested
• Gitignore rules updated
• No breaking changes
• TypeScript strict mode compliance
• Error handling comprehensive
• State persistence robust

Performance Considerations

• State persistence uses atomic file operations
• Activity logging uses append-only JSONL (efficient for large logs)
• Configuration caching reduces repeated file reads
• Git operations include safety checks to prevent destructive actions

Security Considerations

• Git operations validate repository state before destructive commands
• Configuration validation prevents invalid settings
• Workflow state files excluded from version control
• Activity logs contain no sensitive information

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• New Features

  • Introduces end-to-end TDD Autopilot via CLI and MCP: start, resume, next, complete, commit, status, abort.
  • JSON/text outputs, persistent workflow state (stored globally), branch naming, commit message generation, and activity logging.
  • Clear next-action guidance across RED, GREEN, and COMMIT phases.

• Documentation

  • New Quickstart, AI agent integration guide, and templates/prompts; navigation updated.

• Tests

  • Extensive unit and integration coverage for CLI/MCP tools, Git, workflow orchestration, validators, and utilities.

• Chores

  • Expanded configuration with workflow settings; improved logging and test configurations.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 88b0d7f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[maxtuzz]

Autopilot 👏

[Crunchyman-ralph]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 117

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

packages/tm-core/src/auth/auth-manager.ts (1)

63-64: Consider using the class-level logger.

Line 63 still creates a local logger instance in the static getInstance method. For consistency, consider using the class-level logger or document why a separate instance is needed here.

Apply this diff to use the class-level logger (if appropriate):

-		const logger = getLogger('AuthManager');
-		logger.warn(
+		this.logger.warn(
			'getInstance called with config after initialization; config is ignored.'
		);

Note: If this static method needs to log before instance creation, the local logger is necessary and should be kept as-is.

CLAUDE.md (1)

21-34: Fix import extension in TypeScript example

Caption says “.ts extension” but the snippet imports .js.

Apply:

-  // ✅ CORRECT - Synchronous imports with .ts extension
-  import { MyClass } from '../src/my-class.js';
+  // ✅ CORRECT - Synchronous imports with .ts extension
+  import { MyClass } from '../src/my-class.ts';