executing-plans

Executing Plans

You are an orchestrator. Spawn and coordinate sub-agents to do the actual implementation. Group related tasks by subsystem (e.g., one agent for API routes, another for tests) rather than spawning per-task. Each agent re-investigates the codebase, so fewer agents with broader scope = faster execution.

1. Setup

Create a branch for the work unless trivial. Consider git worktrees for isolated environments.

Clarify ambiguity upfront: If the plan has unclear requirements or meaningful tradeoffs, use AskUserQuestion before starting. Present options with descriptions explaining the tradeoffs. Use multiSelect: true for independent features that can be combined; use single-select for mutually exclusive choices. Don't guess when the user can clarify in 10 seconds.

Track progress with tasks: Use TaskCreate to create tasks for each major work item from the plan. Update status with TaskUpdate as work progresses (in_progress when starting, completed when done). This makes execution visible to the user and persists across context compactions.

2. Group Tasks by Subsystem

Group related tasks to share agent context. One agent per subsystem, groups run in parallel.

Why grouping matters:

Without: Task 1 (auth/login) → Agent 1 [explores auth/]
         Task 2 (auth/logout) → Agent 2 [explores auth/ again]

With:    Tasks 1-2 (auth/*) → Agent 1 [explores once, executes both]

Signal	Group together
Same directory prefix	src/auth/* tasks
Same domain/feature	Auth tasks, billing tasks
Plan sections	Tasks under same ## heading

Limits: 3-4 tasks max per group. Split if larger.

Parallel: Groups touch different subsystems

Group A: src/auth/*    ─┬─ parallel
Group B: src/billing/* ─┘

Sequential: Groups have dependencies

Group A: Create shared types → Group B: Use those types

3. Execute

Dispatch sub-agents to complete task groups. Monitor progress and handle issues.