Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

33.0 KB
Raw Blame

Summary

  • Put the existing git and test workflows on rails: a repeatable, automated process that can run autonomously, with guardrails and a compact TUI for visibility.

  • Flow: for a selected task, create a branch named with the tag + task id → generate tests for the first subtask (red) using the Surgical Test Generator → implement code (green) → verify tests → commit → repeat per subtask → final verify → push → open PR against the default branch.

  • Build on existing rules: .cursor/rules/git_workflow.mdc, .cursor/rules/test_workflow.mdc, .claude/agents/surgical-test-generator.md, and existing CLI/core services.

Goals

  • Deterministic, resumable automation to execute the TDD loop per subtask with minimal human intervention.

  • Strong guardrails: never commit to the default branch; only commit when tests pass; enforce status transitions; persist logs/state for debuggability.

  • Visibility: a compact terminal UI (like lazygit) to pick tag, view tasks, and start work; right-side pane opens an executor terminal (via tmux) for agent coding.

  • Extensible: framework-agnostic test generation via the Surgical Test Generator; detect and use the repo’s test command for execution with coverage thresholds.

Non‑Goals (initial)

  • Full multi-language runner parity beyond detection and executing the project’s test command.

  • Complex GUI; start with CLI/TUI + tmux pane. IDE/extension can hook into the same state later.

  • Rich executor selection UX (codex/gemini/claude) — we’ll prompt per run; defaults can come later.

Success Criteria

  • One command can autonomously complete a task's subtasks via TDD and open a PR when done.

  • All commits made on a branch that includes the tag and task id (see Branch Naming); no commits to the default branch directly.

  • Every subtask iteration: failing tests added first (red), then code added to pass them (green), commit only after green.

  • End-to-end logs + artifacts stored in .taskmaster/reports/runs//.

Success Metrics (Phase 1)

  • Adoption: 80% of tasks in a pilot repo completed via tm autopilot
  • Safety: 0 commits to default branch; 100% of commits have green tests
  • Efficiency: Average time from task start to PR < 30min for simple subtasks
  • Reliability: < 5% of runs require manual intervention (timeout/conflicts)

User Stories

  • As a developer, I can run tm autopilot and watch a structured, safe workflow execute.

  • As a reviewer, I can inspect commits per subtask, and a PR summarizing the work when the task completes.

  • As an operator, I can see current step, active subtask, tests status, and logs in a compact CLI view and read a final run report.

Example Workflow Traces

Happy Path: Complete a 3-subtask feature

# Developer starts
$ tm autopilot 42
→ Checks preflight: ✓ clean tree, ✓ npm test detected
→ Creates branch: analytics/task-42-user-metrics
→ Subtask 42.1: "Add metrics schema"
  RED: generates test_metrics_schema.test.js → 3 failures
  GREEN: implements schema.js → all pass
  COMMIT: "feat(metrics): add metrics schema (task 42.1)"
→ Subtask 42.2: "Add collection endpoint"
  RED: generates test_metrics_endpoint.test.js → 5 failures
  GREEN: implements api/metrics.js → all pass
  COMMIT: "feat(metrics): add collection endpoint (task 42.2)"
→ Subtask 42.3: "Add dashboard widget"
  RED: generates test_metrics_widget.test.js → 4 failures
  GREEN: implements components/MetricsWidget.jsx → all pass
  COMMIT: "feat(metrics): add dashboard widget (task 42.3)"
→ Final: all 3 subtasks complete
  ✓ Run full test suite → all pass
  ✓ Coverage check → 85% (meets 80% threshold)
  PUSH: confirms with user → pushed to origin
  PR: opens #123 "Task #42 [analytics]: User metrics tracking"

✓ Task 42 complete. PR: https://github.com/org/repo/pull/123
  Run report: .taskmaster/reports/runs/2025-01-15-142033/

Error Recovery: Failing tests timeout

$ tm autopilot 42
→ Subtask 42.2 GREEN phase: attempt 1 fails (2 tests still red)
→ Subtask 42.2 GREEN phase: attempt 2 fails (1 test still red)
→ Subtask 42.2 GREEN phase: attempt 3 fails (1 test still red)

⚠️  Paused: Could not achieve green state after 3 attempts
📋 State saved to: .taskmaster/reports/runs/2025-01-15-142033/
    Last error: "POST /api/metrics returns 500 instead of 201"

Next steps:
  - Review diff: git diff HEAD
  - Inspect logs: cat .taskmaster/reports/runs/2025-01-15-142033/log.jsonl
  - Check test output: cat .taskmaster/reports/runs/2025-01-15-142033/test-results/subtask-42.2-green-attempt3.json
  - Resume after manual fix: tm autopilot --resume

# Developer manually fixes the issue, then:
$ tm autopilot --resume
→ Resuming subtask 42.2 GREEN phase
  GREEN: all tests pass
  COMMIT: "feat(metrics): add collection endpoint (task 42.2)"
→ Continuing to subtask 42.3...

Dry Run: Preview before execution

$ tm autopilot 42 --dry-run
Autopilot Plan for Task #42 [analytics]: User metrics tracking
─────────────────────────────────────────────────────────────
Preflight:
  ✓ Working tree is clean
  ✓ Test command detected: npm test
  ✓ Tools available: git, gh, node, npm
  ✓ Current branch: main (will create new branch)

Branch & Tag:
  → Create branch: analytics/task-42-user-metrics
  → Set active tag: analytics

Subtasks (3 pending):
  1. 42.1: Add metrics schema
     - RED: generate tests in src/__tests__/schema.test.js
     - GREEN: implement src/schema.js
     - COMMIT: "feat(metrics): add metrics schema (task 42.1)"

  2. 42.2: Add collection endpoint [depends on 42.1]
     - RED: generate tests in src/api/__tests__/metrics.test.js
     - GREEN: implement src/api/metrics.js
     - COMMIT: "feat(metrics): add collection endpoint (task 42.2)"

  3. 42.3: Add dashboard widget [depends on 42.2]
     - RED: generate tests in src/components/__tests__/MetricsWidget.test.jsx
     - GREEN: implement src/components/MetricsWidget.jsx
     - COMMIT: "feat(metrics): add dashboard widget (task 42.3)"

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

Run without --dry-run to execute.

High‑Level Workflow

  1. Pre‑flight

    • Verify clean working tree or confirm staging/commit policy (configurable).

    • Detect repo type and the project’s test command (e.g., npm test, pnpm test, pytest, go test).

    • Validate tools: git, gh (optional for PR), node/npm, and (if used) claude CLI.

    • Load TaskMaster state and selected task; if no subtasks exist, automatically run “expand” before working.

  2. Branch & Tag Setup

    • Checkout default branch and update (optional), then create a branch using Branch Naming (below).

    • Map branch ↔ tag via existing tag management; explicitly set active tag to the branch’s tag.

  3. Subtask Loop (for each pending/in-progress subtask in dependency order)

    • Select next eligible subtask using tm-core TaskService getNextTask() and subtask eligibility logic.

    • Red: generate or update failing tests for the subtask

      • Use the Surgical Test Generator system prompt .claude/agents/surgical-test-generator.md) to produce high-signal tests following project conventions.

      • Run tests to confirm red; record results. If not red (already passing), skip to next subtask or escalate.

    • Green: implement code to pass tests

      • Use executor to implement changes (initial: claude CLI prompt with focused context).

      • Re-run tests until green or timeout/backoff policy triggers.

    • Commit: when green

      • Commit tests + code with conventional commit message. Optionally update subtask status to done.

      • Persist run step metadata/logs.

  4. Finalization

    • Run full test suite and coverage (if configured); optionally lint/format.

    • Commit any final adjustments.

    • Push branch (ask user to confirm); create PR (via gh pr create) targeting the default branch. Title format: Task # []: .</p> </li> </ul> </li> <li><p>Post‑Run</p> <ul> <li><p>Update task status if desired (e.g., review).</p> </li> <li><p>Persist run report (JSON + markdown summary) to .taskmaster/reports/runs/<run-id>/.</p> </li> </ul> </li> </ol> <h2>Guardrails</h2> <ul> <li><p>Never commit to the default branch.</p> </li> <li><p>Commit only if all tests (targeted and suite) pass; allow override flags.</p> </li> <li><p>Enforce 80% coverage thresholds (lines/branches/functions/statements) by default; configurable.</p> </li> <li><p>Timebox/model ops and retries; if not green within N attempts, pause with actionable state for resume.</p> </li> <li><p>Always log actions, commands, and outcomes; include dry-run mode.</p> </li> <li><p>Ask before branch creation, pushing, and opening a PR unless --no-confirm is set.</p> </li> </ul> <h2>Integration Points (Current Repo)</h2> <ul> <li><p>CLI: apps/cli provides command structure and UI components.</p> <ul> <li><p>New command: tm autopilot (alias: task-master autopilot).</p> </li> <li><p>Reuse UI components under apps/cli/src/ui/components/ for headers/task details/next-task.</p> </li> </ul> </li> <li><p>Core services: packages/tm-core</p> <ul> <li><p>TaskService for selection, status, tags.</p> </li> <li><p>TaskExecutionService for prompt formatting and executor prep.</p> </li> <li><p>Executors: claude executor and ExecutorFactory to run external tools.</p> </li> <li><p>Proposed new: WorkflowOrchestrator to drive the autonomous loop and emit progress events.</p> </li> </ul> </li> <li><p>Tag/Git utilities: scripts/modules/utils/git-utils.js and scripts/modules/task-manager/tag-management.js for branch→tag mapping and explicit tag switching.</p> </li> <li><p>Rules: .cursor/rules/git_workflow.mdc and .cursor/rules/test_workflow.mdc to steer behavior and ensure consistency.</p> </li> <li><p>Test generation prompt: .claude/agents/surgical-test-generator.md.</p> </li> </ul> <h2>Proposed Components</h2> <ul> <li><p>Orchestrator (tm-core): WorkflowOrchestrator (new)</p> <ul> <li><p>State machine driving phases: Preflight → Branch/Tag → SubtaskIter (Red/Green/Commit) → Finalize → PR.</p> </li> <li><p>Exposes an evented API (progress events) that the CLI can render.</p> </li> <li><p>Stores run state artifacts.</p> </li> </ul> </li> <li><p>Test Runner Adapter</p> <ul> <li><p>Detects and runs tests via the project’s test command (e.g., npm test), with targeted runs where feasible.</p> </li> <li><p>API: runTargeted(files/pattern), runAll(), report summary (failures, duration, coverage), enforce 80% threshold by default.</p> </li> </ul> </li> <li><p>Git/PR Adapter</p> <ul> <li><p>Encapsulates git ops: branch create/checkout, add/commit, push.</p> </li> <li><p>Optional gh integration to open PR; fallback to instructions if gh unavailable.</p> </li> <li><p>Confirmation gates for branch creation and pushes.</p> </li> </ul> </li> <li><p>Prompt/Exec Adapter</p> <ul> <li>Uses existing executor service to call the selected coding assistant (initially claude) with tight prompts: task/subtask context, surgical tests first, then minimal code to green.</li> </ul> </li> <li><p>Run State + Reporting</p> <ul> <li><p>JSONL log of steps, timestamps, commands, test results.</p> </li> <li><p>Markdown summary for PR description and post-run artifact.</p> </li> </ul> </li> </ul> <h2>CLI UX (MVP)</h2> <ul> <li><p>Command: tm autopilot [taskId]</p> <ul> <li><p>Flags: --dry-run, --no-push, --no-pr, --no-confirm, --force, --max-attempts <n>, --runner <auto|custom>, --commit-scope <scope></p> </li> <li><p>Output: compact header (project, tag, branch), current phase, subtask line, last test summary, next actions.</p> </li> </ul> </li> <li><p>Resume: If interrupted, tm autopilot --resume picks up from last checkpoint in run state.</p> </li> </ul> <h3>TUI with tmux (Linear Execution)</h3> <ul> <li><p>Left pane: Tag selector, task list (status/priority), start/expand shortcuts; "Start" triggers the next task or a selected task.</p> </li> <li><p>Right pane: Executor terminal (tmux split) that runs the coding agent (claude-code/codex). Autopilot can hand over to the right pane during green.</p> </li> <li><p>MCP integration: use MCP tools for task queries/updates and for shell/test invocations where available.</p> </li> </ul> <h2>TUI Layout (tmux-based)</h2> <h3>Pane Structure</h3> <pre><code>┌─────────────────────────────────────┬──────────────────────────────────┐ │ Task Navigator (left) │ Executor Terminal (right) │ │ │ │ │ Project: my-app │ $ tm autopilot --executor-mode │ │ Branch: analytics/task-42 │ > Running subtask 42.2 GREEN... │ │ Tag: analytics │ > Implementing endpoint... │ │ │ > Tests: 3 passed, 0 failed │ │ Tasks: │ > Ready to commit │ │ → 42 [in-progress] User metrics │ │ │ → 42.1 [done] Schema │ [Live output from Claude Code] │ │ → 42.2 [active] Endpoint ◀ │ │ │ → 42.3 [pending] Dashboard │ │ │ │ │ │ [s] start [p] pause [q] quit │ │ └─────────────────────────────────────┴──────────────────────────────────┘ </code></pre> <h3>Implementation Notes</h3> <ul> <li><strong>Left pane</strong>: <code>apps/cli/src/ui/tui/navigator.ts</code> (new, uses <code>blessed</code> or <code>ink</code>)</li> <li><strong>Right pane</strong>: spawned via <code>tmux split-window -h</code> running <code>tm autopilot --executor-mode</code></li> <li><strong>Communication</strong>: shared state file <code>.taskmaster/state/current-run.json</code> + file watching or event stream</li> <li><strong>Keybindings</strong>:<ul> <li><code>s</code> - Start selected task</li> <li><code>p</code> - Pause/resume current run</li> <li><code>q</code> - Quit (with confirmation if run active)</li> <li><code>↑/↓</code> - Navigate task list</li> <li><code>Enter</code> - Expand/collapse subtasks</li> </ul> </li> </ul> <h2>Prompt Composition (Detailed)</h2> <h3>System Prompt Assembly</h3> <p>Prompts are composed in three layers:</p> <ol> <li><p><strong>Base rules</strong> (loaded in order from <code>.cursor/rules/</code> and <code>.claude/agents/</code>):</p> <ul> <li><code>git_workflow.mdc</code> → git commit conventions, branch policy, PR guidelines</li> <li><code>test_workflow.mdc</code> → TDD loop requirements, coverage thresholds, test structure</li> <li><code>surgical-test-generator.md</code> → test generation methodology, project-specific test patterns</li> </ul> </li> <li><p><strong>Task context injection</strong>:</p> <pre><code>You are implementing: Task #42 [analytics]: User metrics tracking Subtask 42.2: Add collection endpoint Description: Implement POST /api/metrics endpoint to collect user metrics events Acceptance criteria: - POST /api/metrics accepts { userId, eventType, timestamp } - Validates input schema (reject missing/invalid fields) - Persists to database - Returns 201 on success with created record - Returns 400 on validation errors Dependencies: - Subtask 42.1 (metrics schema) is complete Current phase: RED (generate failing tests) Test command: npm test Test file convention: src/**/*.test.js (vitest framework detected) Branch: analytics/task-42-user-metrics Project language: JavaScript (Node.js) </code></pre> </li> <li><p><strong>Phase-specific instructions</strong>:</p> <ul> <li><strong>RED phase</strong>: "Generate minimal failing tests for this subtask. Do NOT implement any production code. Only create test files. Confirm tests fail with clear error messages indicating missing implementation."</li> <li><strong>GREEN phase</strong>: "Implement minimal code to pass the failing tests. Follow existing project patterns in <code>src/</code>. Only modify files necessary for this subtask. Keep changes focused and reviewable."</li> </ul> </li> </ol> <h3>Example Full Prompt (RED Phase)</h3> <pre><code class="language-markdown"><SYSTEM PROMPT> [Contents of .cursor/rules/git_workflow.mdc] [Contents of .cursor/rules/test_workflow.mdc] [Contents of .claude/agents/surgical-test-generator.md] <TASK CONTEXT> You are implementing: Task #42.2: Add collection endpoint Description: Implement POST /api/metrics endpoint to collect user metrics events Acceptance criteria: - POST /api/metrics accepts { userId, eventType, timestamp } - Validates input schema (reject missing/invalid fields) - Persists to database using MetricsSchema from subtask 42.1 - Returns 201 on success with created record - Returns 400 on validation errors with details Dependencies: Subtask 42.1 (metrics schema) is complete <INSTRUCTION> Generate failing tests for this subtask. Follow project conventions: - Test file: src/api/__tests__/metrics.test.js - Framework: vitest (detected from package.json) - Test cases to cover: * POST /api/metrics with valid payload → should return 201 (will fail: endpoint not implemented) * POST /api/metrics with missing userId → should return 400 (will fail: validation not implemented) * POST /api/metrics with invalid timestamp → should return 400 (will fail: validation not implemented) * POST /api/metrics should persist to database → should save record (will fail: persistence not implemented) Do NOT implement the endpoint code yet. Only create test file(s). Confirm tests fail with messages like "Cannot POST /api/metrics" or "endpoint not defined". Output format: 1. File path to create: src/api/__tests__/metrics.test.js 2. Complete test code 3. Command to run: npm test src/api/__tests__/metrics.test.js </code></pre> <h3>Example Full Prompt (GREEN Phase)</h3> <pre><code class="language-markdown"><SYSTEM PROMPT> [Contents of .cursor/rules/git_workflow.mdc] [Contents of .cursor/rules/test_workflow.mdc] <TASK CONTEXT> Task #42.2: Add collection endpoint [same context as RED phase] <CURRENT STATE> Tests created in RED phase: - src/api/__tests__/metrics.test.js - 5 tests written, all failing as expected Test output: </code></pre> <p>FAIL src/api/<strong>tests</strong>/metrics.test.js POST /api/metrics ✗ should return 201 with valid payload (endpoint not found) ✗ should return 400 with missing userId (endpoint not found) ✗ should return 400 with invalid timestamp (endpoint not found) ✗ should persist to database (endpoint not found)</p> <pre><code> <INSTRUCTION> Implement minimal code to make all tests pass. Guidelines: - Create/modify file: src/api/metrics.js - Use existing patterns from src/api/ (e.g., src/api/users.js for reference) - Import MetricsSchema from subtask 42.1 (src/models/schema.js) - Implement validation, persistence, and response handling - Follow project error handling conventions - Keep implementation focused on this subtask only After implementation: 1. Run tests: npm test src/api/__tests__/metrics.test.js 2. Confirm all 5 tests pass 3. Report results Output format: 1. File(s) created/modified 2. Implementation code 3. Test command and results </code></pre> <h3>Prompt Loading Configuration</h3> <p>See <code>.taskmaster/config.json</code> → <code>prompts</code> section for paths and load order.</p> <h2>Configuration Schema</h2> <h3>.taskmaster/config.json</h3> <pre><code class="language-json">{ "autopilot": { "enabled": true, "requireCleanWorkingTree": true, "commitTemplate": "{type}({scope}): {msg}", "defaultCommitType": "feat", "maxGreenAttempts": 3, "testTimeout": 300000 }, "test": { "runner": "auto", "coverageThresholds": { "lines": 80, "branches": 80, "functions": 80, "statements": 80 }, "targetedRunPattern": "**/*.test.js" }, "git": { "branchPattern": "{tag}/task-{id}-{slug}", "pr": { "enabled": true, "base": "default", "bodyTemplate": ".taskmaster/templates/pr-body.md" } }, "prompts": { "rulesPath": ".cursor/rules", "testGeneratorPath": ".claude/agents/surgical-test-generator.md", "loadOrder": ["git_workflow.mdc", "test_workflow.mdc"] } } </code></pre> <h3>Configuration Fields</h3> <h4>autopilot</h4> <ul> <li><code>enabled</code> (boolean): Enable/disable autopilot functionality</li> <li><code>requireCleanWorkingTree</code> (boolean): Require clean git state before starting</li> <li><code>commitTemplate</code> (string): Template for commit messages (tokens: <code>{type}</code>, <code>{scope}</code>, <code>{msg}</code>)</li> <li><code>defaultCommitType</code> (string): Default commit type (feat, fix, chore, etc.)</li> <li><code>maxGreenAttempts</code> (number): Maximum retry attempts to achieve green tests (default: 3)</li> <li><code>testTimeout</code> (number): Timeout in milliseconds per test run (default: 300000 = 5min)</li> </ul> <h4>test</h4> <ul> <li><code>runner</code> (string): Test runner detection mode (<code>"auto"</code> or explicit command like <code>"npm test"</code>)</li> <li><code>coverageThresholds</code> (object): Minimum coverage percentages required<ul> <li><code>lines</code>, <code>branches</code>, <code>functions</code>, <code>statements</code> (number): Threshold percentages (0-100)</li> </ul> </li> <li><code>targetedRunPattern</code> (string): Glob pattern for targeted subtask test runs</li> </ul> <h4>git</h4> <ul> <li><code>branchPattern</code> (string): Branch naming pattern (tokens: <code>{tag}</code>, <code>{id}</code>, <code>{slug}</code>)</li> <li><code>pr.enabled</code> (boolean): Enable automatic PR creation</li> <li><code>pr.base</code> (string): Target branch for PRs (<code>"default"</code> uses repo default, or specify like <code>"main"</code>)</li> <li><code>pr.bodyTemplate</code> (string): Path to PR body template file (optional)</li> </ul> <h4>prompts</h4> <ul> <li><code>rulesPath</code> (string): Directory containing rule files (e.g., <code>.cursor/rules</code>)</li> <li><code>testGeneratorPath</code> (string): Path to test generator prompt file</li> <li><code>loadOrder</code> (array): Order to load rule files from <code>rulesPath</code></li> </ul> <h3>Environment Variables</h3> <pre><code class="language-bash"># Required for executor ANTHROPIC_API_KEY=sk-ant-... # Claude API key # Optional: for PR creation GITHUB_TOKEN=ghp_... # GitHub personal access token # Optional: for other executors (future) OPENAI_API_KEY=sk-... GOOGLE_API_KEY=... </code></pre> <h2>Run Artifacts & Observability</h2> <h3>Per-Run Artifact Structure</h3> <p>Each autopilot run creates a timestamped directory with complete traceability:</p> <pre><code>.taskmaster/reports/runs/2025-01-15-142033/ ├── manifest.json # run metadata (task id, start/end time, status) ├── log.jsonl # timestamped event stream ├── commits.txt # list of commit SHAs made during run ├── test-results/ │ ├── subtask-42.1-red.json │ ├── subtask-42.1-green.json │ ├── subtask-42.2-red.json │ ├── subtask-42.2-green-attempt1.json │ ├── subtask-42.2-green-attempt2.json │ ├── subtask-42.2-green-attempt3.json │ └── final-suite.json └── pr.md # generated PR body </code></pre> <h3>manifest.json Format</h3> <pre><code class="language-json">{ "runId": "2025-01-15-142033", "taskId": "42", "tag": "analytics", "branch": "analytics/task-42-user-metrics", "startTime": "2025-01-15T14:20:33Z", "endTime": "2025-01-15T14:45:12Z", "status": "completed", "subtasksCompleted": ["42.1", "42.2", "42.3"], "subtasksFailed": [], "totalCommits": 3, "prUrl": "https://github.com/org/repo/pull/123", "finalCoverage": { "lines": 85.3, "branches": 82.1, "functions": 88.9, "statements": 85.0 } } </code></pre> <h3>log.jsonl Format</h3> <p>Event stream in JSON Lines format for easy parsing and debugging:</p> <pre><code class="language-jsonl">{"ts":"2025-01-15T14:20:33Z","phase":"preflight","status":"ok","details":{"testCmd":"npm test","gitClean":true}} {"ts":"2025-01-15T14:20:45Z","phase":"branch","status":"ok","branch":"analytics/task-42-user-metrics"} {"ts":"2025-01-15T14:21:00Z","phase":"red","subtask":"42.1","status":"ok","tests":{"failed":3,"passed":0}} {"ts":"2025-01-15T14:22:15Z","phase":"green","subtask":"42.1","status":"ok","tests":{"passed":3,"failed":0},"attempts":2} {"ts":"2025-01-15T14:22:20Z","phase":"commit","subtask":"42.1","status":"ok","sha":"a1b2c3d","message":"feat(metrics): add metrics schema (task 42.1)"} {"ts":"2025-01-15T14:23:00Z","phase":"red","subtask":"42.2","status":"ok","tests":{"failed":5,"passed":0}} {"ts":"2025-01-15T14:25:30Z","phase":"green","subtask":"42.2","status":"error","tests":{"passed":3,"failed":2},"attempts":3,"error":"Max attempts reached"} {"ts":"2025-01-15T14:25:35Z","phase":"pause","reason":"max_attempts","nextAction":"manual_review"} </code></pre> <h3>Test Results Format</h3> <p>Each test run stores detailed results:</p> <pre><code class="language-json">{ "subtask": "42.2", "phase": "green", "attempt": 3, "timestamp": "2025-01-15T14:25:30Z", "command": "npm test src/api/__tests__/metrics.test.js", "exitCode": 1, "duration": 2340, "summary": { "total": 5, "passed": 3, "failed": 2, "skipped": 0 }, "failures": [ { "test": "POST /api/metrics should return 201 with valid payload", "error": "Expected status 201, got 500", "stack": "..." } ], "coverage": { "lines": 78.5, "branches": 75.0, "functions": 80.0, "statements": 78.5 } } </code></pre> <h2>Execution Model</h2> <h3>Orchestration vs Direct Execution</h3> <p>The autopilot system uses an <strong>orchestration model</strong> rather than direct code execution:</p> <p><strong>Orchestrator Role</strong> (tm-core WorkflowOrchestrator):</p> <ul> <li>Maintains state machine tracking current phase (RED/GREEN/COMMIT) per subtask</li> <li>Validates preconditions (tests pass, git state clean, etc.)</li> <li>Returns "work units" describing what needs to be done next</li> <li>Records completion and advances to next phase</li> <li>Persists state for resumability</li> </ul> <p><strong>Executor Role</strong> (Claude Code/AI session via MCP):</p> <ul> <li>Queries orchestrator for next work unit</li> <li>Executes the work (generates tests, writes code, runs tests, makes commits)</li> <li>Reports results back to orchestrator</li> <li>Handles file operations and tool invocations</li> </ul> <p><strong>Why This Approach?</strong></p> <ul> <li>Leverages existing AI capabilities (Claude Code) rather than duplicating them</li> <li>MCP protocol provides clean separation between state management and execution</li> <li>Allows human oversight and intervention at each phase</li> <li>Simpler to implement: orchestrator is pure state logic, no code generation needed</li> <li>Enables multiple executor types (Claude Code, other AI tools, human developers)</li> </ul> <p><strong>Example Flow</strong>:</p> <pre><code class="language-typescript">// Claude Code (via MCP) queries orchestrator const workUnit = await orchestrator.getNextWorkUnit('42'); // => { // phase: 'RED', // subtask: '42.1', // action: 'Generate failing tests for metrics schema', // context: { title, description, dependencies, testFile: 'src/__tests__/schema.test.js' } // } // Claude Code executes the work (writes test file, runs tests) // Then reports back await orchestrator.completeWorkUnit('42', '42.1', 'RED', { success: true, testsCreated: ['src/__tests__/schema.test.js'], testsFailed: 3 }); // Query again for next phase const nextWorkUnit = await orchestrator.getNextWorkUnit('42'); // => { phase: 'GREEN', subtask: '42.1', action: 'Implement code to pass tests', ... } </code></pre> <h2>Design Decisions</h2> <h3>Why commit per subtask instead of per task?</h3> <p><strong>Decision</strong>: Commit after each subtask's green state, not after the entire task.</p> <p><strong>Rationale</strong>:</p> <ul> <li>Atomic commits make code review easier (reviewers can see logical progression)</li> <li>Easier to revert a single subtask if it causes issues downstream</li> <li>Matches the TDD loop's natural checkpoint and cognitive boundary</li> <li>Provides resumability points if the run is interrupted</li> </ul> <p><strong>Trade-off</strong>: More commits per task (can use squash-merge in PRs if desired)</p> <h3>Why not support parallel subtask execution?</h3> <p><strong>Decision</strong>: Sequential subtask execution in Phase 1; parallel execution deferred to Phase 3.</p> <p><strong>Rationale</strong>:</p> <ul> <li>Subtasks often have implicit dependencies (e.g., schema before endpoint, endpoint before UI)</li> <li>Simpler orchestrator state machine (less complexity = faster to ship)</li> <li>Parallel execution requires explicit dependency DAG and conflict resolution</li> <li>Can be added in Phase 3 once core workflow is proven stable</li> </ul> <p><strong>Trade-off</strong>: Slower for truly independent subtasks (mitigated by keeping subtasks small and focused)</p> <h3>Why require 80% coverage by default?</h3> <p><strong>Decision</strong>: Enforce 80% coverage threshold (lines/branches/functions/statements) before allowing commits.</p> <p><strong>Rationale</strong>:</p> <ul> <li>Industry standard baseline for production code quality</li> <li>Forces test generation to be comprehensive, not superficial</li> <li>Configurable per project via <code>.taskmaster/config.json</code> if too strict</li> <li>Prevents "green tests" that only test happy paths</li> </ul> <p><strong>Trade-off</strong>: May require more test generation iterations; can be lowered per project</p> <h3>Why use tmux instead of a rich GUI?</h3> <p><strong>Decision</strong>: MVP uses tmux split panes for TUI, not Electron/web-based GUI.</p> <p><strong>Rationale</strong>:</p> <ul> <li>Tmux is universally available on dev machines; no installation burden</li> <li>Terminal-first workflows match developer mental model (no context switching)</li> <li>Simpler to implement and maintain; can add GUI later via extensions</li> <li>State stored in files allows IDE/extension integration without coupling</li> </ul> <p><strong>Trade-off</strong>: Less visual polish than GUI; requires tmux familiarity</p> <h3>Why not support multiple executors (codex/gemini/claude) in Phase 1?</h3> <p><strong>Decision</strong>: Start with Claude executor only; add others in Phase 2+.</p> <p><strong>Rationale</strong>:</p> <ul> <li>Reduces scope and complexity for initial delivery</li> <li>Claude Code already integrated with existing executor service</li> <li>Executor abstraction already exists; adding more is straightforward later</li> <li>Different executors may need different prompt strategies (requires experimentation)</li> </ul> <p><strong>Trade-off</strong>: Users locked to Claude initially; can work around with manual executor selection</p> <h2>Risks and Mitigations</h2> <ul> <li><p>Model hallucination/large diffs: restrict prompt scope; enforce minimal changes; show diff previews (optional) before commit.</p> </li> <li><p>Flaky tests: allow retries, isolate targeted runs for speed, then full suite before commit.</p> </li> <li><p>Environment variability: detect runners/tools; provide fallbacks and actionable errors.</p> </li> <li><p>PR creation fails: still push and print manual commands; persist PR body to reuse.</p> </li> </ul> <h2>Open Questions</h2> <ol> <li><p>Slugging rules for branch names; any length limits or normalization beyond {slug} token sanitize?</p> </li> <li><p>PR body standard sections beyond run report (e.g., checklist, coverage table)?</p> </li> <li><p>Default executor prompt fine-tuning once codex/gemini integration is available.</p> </li> <li><p>Where to store persistent TUI state (pane layout, last selection) in .taskmaster/state.json?</p> </li> </ol> <h2>Branch Naming</h2> <ul> <li><p>Include both the tag and the task id in the branch name to make lineage explicit.</p> </li> <li><p>Default pattern: <tag>/task-<id>[-slug] (e.g., master/task-12, tag-analytics/task-4-user-auth).</p> </li> <li><p>Configurable via .taskmaster/config.json: git.branchPattern supports tokens {tag}, {id}, {slug}.</p> </li> </ul> <h2>PR Base Branch</h2> <ul> <li><p>Use the repository’s default branch (detected via git) unless overridden.</p> </li> <li><p>Title format: Task #<id> [<tag>]: <title>.</p> </li> </ul> <h2>RPG Mapping (Repository Planning Graph)</h2> <p>Functional nodes (capabilities):</p> <ul> <li><p>Autopilot Orchestration → drives TDD loop and lifecycle</p> </li> <li><p>Test Generation (Surgical) → produces failing tests from subtask context</p> </li> <li><p>Test Execution + Coverage → runs suite, enforces thresholds</p> </li> <li><p>Git/Branch/PR Management → safe operations and PR creation</p> </li> <li><p>TUI/Terminal Integration → interactive control and visibility via tmux</p> </li> <li><p>MCP Integration → structured task/status/context operations</p> </li> </ul> <p>Structural nodes (code organization):</p> <ul> <li><p>packages/tm-core:</p> <ul> <li><p>services/workflow-orchestrator.ts (new)</p> </li> <li><p>services/test-runner-adapter.ts (new)</p> </li> <li><p>services/git-adapter.ts (new)</p> </li> <li><p>existing: task-service.ts, task-execution-service.ts, executors/*</p> </li> </ul> </li> <li><p>apps/cli:</p> <ul> <li><p>src/commands/autopilot.command.ts (new)</p> </li> <li><p>src/ui/tui/ (new tmux/TUI helpers)</p> </li> </ul> </li> <li><p>scripts/modules:</p> <ul> <li>reuse utils/git-utils.js, task-manager/tag-management.js</li> </ul> </li> <li><p>.claude/agents/:</p> <ul> <li>surgical-test-generator.md</li> </ul> </li> </ul> <p>Edges (data/control flow):</p> <ul> <li><p>Autopilot → Test Generation → Test Execution → Git Commit → loop</p> </li> <li><p>Autopilot → Git Adapter (branch, tag, PR)</p> </li> <li><p>Autopilot → TUI (event stream) → tmux pane control</p> </li> <li><p>Autopilot → MCP tools for task/status updates</p> </li> <li><p>Test Execution → Coverage gate → Autopilot decision</p> </li> </ul> <p>Topological traversal (implementation order):</p> <ol> <li><p>Git/Test adapters (foundations)</p> </li> <li><p>Orchestrator skeleton + events</p> </li> <li><p>CLI autopilot command and dry-run</p> </li> <li><p>Surgical test-gen integration and execution gate</p> </li> <li><p>PR creation, run reports, resumability</p> </li> </ol> <h2>Phased Roadmap</h2> <ul> <li><p>Phase 0: Spike</p> <ul> <li><p>Implement CLI skeleton tm autopilot with dry-run showing planned steps from a real task + subtasks.</p> </li> <li><p>Detect test runner (package.json) and git state; render a preflight report.</p> </li> </ul> </li> <li><p>Phase 1: Core Rails (State Machine & Orchestration)</p> <ul> <li><p>Implement WorkflowOrchestrator in tm-core as a <strong>state machine</strong> that tracks TDD phases per subtask.</p> </li> <li><p>Orchestrator <strong>guides</strong> the current AI session (Claude Code/MCP client) rather than executing code itself.</p> </li> <li><p>Add Git/Test adapters for status checks and validation (not direct execution).</p> </li> <li><p>WorkflowOrchestrator API:</p> <ul> <li><code>getNextWorkUnit(taskId)</code> → returns next phase to execute (RED/GREEN/COMMIT) with context</li> <li><code>completeWorkUnit(taskId, subtaskId, phase, result)</code> → records completion and advances state</li> <li><code>getRunState(taskId)</code> → returns current progress and resumability data</li> </ul> </li> <li><p>MCP integration: expose work unit endpoints so Claude Code can query "what to do next" and report back.</p> </li> <li><p>Branch/tag mapping via existing tag-management APIs.</p> </li> <li><p>Run report persisted under .taskmaster/reports/runs/ with state checkpoints for resumability.</p> </li> </ul> </li> <li><p>Phase 2: PR + Resumability</p> <ul> <li><p>Add gh PR creation with well-formed body using the run report.</p> </li> <li><p>Introduce resumable checkpoints and --resume flag.</p> </li> <li><p>Add coverage enforcement and optional lint/format step.</p> </li> </ul> </li> <li><p>Phase 3: Extensibility + Guardrails</p> <ul> <li><p>Add support for basic pytest/go test adapters.</p> </li> <li><p>Add safeguards: diff preview mode, manual confirm gates, aggressive minimal-change prompts.</p> </li> <li><p>Optional: small TUI panel and extension panel leveraging the same run state file.</p> </li> </ul> </li> </ul> <h2>References (Repo)</h2> <ul> <li><p>Test Workflow: .cursor/rules/test_workflow.mdc</p> </li> <li><p>Git Workflow: .cursor/rules/git_workflow.mdc</p> </li> <li><p>CLI: apps/cli/src/commands/start.command.ts, apps/cli/src/ui/components/*.ts</p> </li> <li><p>Core Services: packages/tm-core/src/services/task-service.ts, task-execution-service.ts</p> </li> <li><p>Executors: packages/tm-core/src/executors/*</p> </li> <li><p>Git Utilities: scripts/modules/utils/git-utils.js</p> </li> <li><p>Tag Management: scripts/modules/task-manager/tag-management.js</p> </li> <li><p>Surgical Test Generator: .claude/agents/surgical-test-generator.md</p> </li> </ul>