Code Review Overview: Agent Enhancement Phase 1

Code Review Overview: Agent Enhancement Phase 1

Context

This review covers three major enhancements to the Claude Copilot framework, implemented based on competitive analysis of external projects (Karpathy Skills, antirez's Codex patterns, Claude Code RLM, and Superpowers).

Source Analysis: Work products WP-19f11893 and WP-41472944 contain the competitive analysis findings.

Feature 1: Goal-Driven Agent Framework

Purpose: Transform agents from procedural instruction-following to goal-driven verification loops. Agents now iterate until measurable success criteria are met, rather than assuming success after execution.

Files to Review

Key Concepts to Verify

1. Iteration Schema in Frontmatter:

   iteration:
     maxIterations: 5
     completionPromises:
       - "<promise>COMPLETE</promise>"
       - "<promise>BLOCKED</promise>"
   

2. Success Criteria Format: Instructions should use verifiable criteria ("Tests pass", "PRD created") instead of procedural steps ("Run tests", "Create PRD").

3. Iteration Loop Pattern:

   • iteration_start() - Initialize loop with max iterations and completion promises
   • iteration_validate() - Check if criteria met
   • iteration_next() - Advance to next iteration if not complete
   • iteration_complete() - Mark done when criteria satisfied

4. Completion Signals:

   • <promise>COMPLETE</promise> - All criteria met
   • <promise>BLOCKED</promise> - Cannot proceed, escalate

Review Focus Areas

• Are success criteria observable and verifiable?
• Is the iteration loop pattern correctly documented?
• Are the three examples in me.md (TDD, BLOCKED, max iterations) accurate?
• Does the frontmatter schema match Task Copilot's IterationConfig interface?

Feature 2: Git Worktree Support for Task Isolation

Purpose: Enable parallel task execution by isolating each task in its own git worktree. Prevents file conflicts when multiple streams work simultaneously.

Files to Review

Key Implementation Details

1. Task Metadata Extension:

   interface TaskMetadata {
     requiresWorktree?: boolean;
     worktreePath?: string;        // Auto-set by system
     worktreeBranch?: string;      // Auto-set by system
     worktreeBaseBranch?: string;  // User-configurable
   }
   

2. Automatic Lifecycle:

   • On task_create with requiresWorktree: true → Create worktree
   • On task_update(status: 'completed') → Merge and cleanup
   • On merge conflict → Mark task as blocked with conflict details

3. New MCP Tools:

   • worktree_create({ taskId, baseBranch? }) - Manual creation
   • worktree_list({ includeArchived? }) - List all worktrees
   • worktree_cleanup({ taskId, force? }) - Force cleanup
   • worktree_merge({ taskId, targetBranch?, strategy? }) - Manual merge
   • worktree_conflict_status({ taskId }) - Check conflicts (existing)
   • worktree_conflict_resolve({ taskId, targetBranch? }) - Resolve (existing)

4. Worktree Paths:

   • Location: .worktrees/{TASK-ID}
   • Branch naming: task/{task-id-lowercase}

Review Focus Areas

• Is the worktree lifecycle correctly integrated with task state transitions?
• Are merge conflicts properly detected and reported?
• Is the cleanup logic safe (won't delete uncommitted work)?
• Are the new MCP tools properly typed and registered?
• Does the documentation accurately describe the automatic vs manual workflows?

Feature 3: Tiered Model Routing

Purpose: Optimize cost and performance by routing tasks to appropriate model tiers (Opus for orchestration, Sonnet for implementation, Haiku for simple tasks).

Files to Review

Key Implementation Details

1. Model Resolution Priority:

   1. Task metadata.modelOverride (highest)
   2. Agent frontmatter.model
   3. Default: 'sonnet' (fallback)
   

2. Model Recommendation Heuristics:

   function recommendModel(task, agent): 'opus' | 'sonnet' | 'haiku' {
     // Override takes precedence
     if (task.metadata.modelOverride) return task.metadata.modelOverride;
   
     // Agent default
     if (agent.model) return agent.model;
   
     // Complexity-based heuristics
     if (hasOrchestrationKeywords(task)) return 'opus';
     if (isSimpleTask(task)) return 'haiku';
   
     return 'sonnet';
   }
   

3. Orchestration Keywords: ultrawork, parallel, coordinate, orchestrat

4. Simple Task Keywords: quick, typo, simple, trivial

5. Model Usage Tracking:

   interface ProgressSummaryOutput {
     modelUsage?: {
       opus: number;
       sonnet: number;
       haiku: number;
       unknown: number;
     };
   }
   

Review Focus Areas

• Is the model resolution order correctly implemented?
• Are the heuristics reasonable for detecting orchestration vs simple tasks?
• Is model usage correctly tracked in work products?
• Does progress_summary accurately aggregate model usage?
• Is the agent guide documentation clear about when to use each model tier?

Testing

All changes are covered by the existing test suite:

Task Copilot Integration Tests: 28/28 PASS
TypeScript Build: No errors

Key test files:

• mcp-servers/task-copilot/src/tools/full-integration.test.js

File Tree Summary

claude-copilot/
├── .claude/
│   └── agents/
│       ├── me.md          # Goal-driven + model docs
│       ├── ta.md          # Goal-driven + model: opus
│       └── qa.md          # Goal-driven + model docs
├── docs/
│   ├── 30-operations/
│   │   └── 03-agent-guide.md     # NEW: Model routing guide
│   └── 50-features/
│       ├── 04-goal-driven-agents.md  # NEW: Goal-driven guide
│       └── 05-worktree-isolation.md  # NEW: Worktree guide
├── mcp-servers/
│   └── task-copilot/
│       └── src/
│           ├── types.ts           # TaskMetadata extensions
│           ├── index.ts           # Tool registration
│           ├── ecomode/
│           │   └── model-router.ts  # recommendModel()
│           └── tools/
│               ├── task.ts        # Worktree lifecycle
│               ├── worktree.ts    # New worktree tools
│               ├── work-product.ts # modelUsed tracking
│               └── initiative.ts  # modelUsage in progress_summary
└── CLAUDE.md                      # Updated file locations

Suggested Review Order

1. Start with types.ts - Understand the schema changes
2. Review model-router.ts - Core routing logic
3. Review task.ts - Worktree lifecycle integration
4. Review worktree.ts - New MCP tools
5. Review agents (me.md, ta.md, qa.md) - Goal-driven patterns
6. Review documentation - Verify accuracy against implementation

Questions for Review

1. Are there any edge cases in worktree merge conflict handling?
2. Is the model routing heuristic too simplistic? Should it consider task complexity metadata?
3. Are the iteration loop examples in me.md representative of real-world usage?
4. Should worktree cleanup be more aggressive (auto-cleanup stale worktrees)?
5. Is the progress_summary model usage aggregation performant for large datasets?

Related Work Products

• WP-19f11893: Competitive analysis (Karpathy, antirez, RLM, Superpowers)
• WP-41472944: Workflow patterns clarification
• PRD-e0112170-b2f0-4d0e-9a98-792ba967af5d: Agent Enhancement Phase 1 PRD