Execute — Orchestrated Task Engine

Decompose a goal into atomic tasks, plan dependencies, select optimal tools, and execute with maximum parallelism.

Pre-Flight Gate

Activation is decided by the frontmatter description alone — this file is read only AFTER the skill has been selected. Nothing here can prevent over-triggering, so this gate is a post-selection redirect, not a filter.

Before proceeding, check the ABORT condition below. If it holds, STOP, say in one line that it fired, and just do the task. Being invoked — including a literal /execute or "orchestrate this" — does NOT override an ABORT: the phrasing that selected this skill is not evidence the goal is multi-step.

• Run the 6-phase protocol only when the goal is genuinely multi-step — ≥3 atomic tasks, spans multiple files/tools, or benefits from parallel batches.
• ABORT (do it directly): a single edit, a one-file change, a question, or anything one tool call resolves.

Protocol

Process every /execute invocation through these 6 phases in strict order. Never skip a phase. Gate each phase: do not advance until the current phase is complete.

Phase 1: ANALYZE

Understand the goal before decomposing it.

1. Parse $ARGUMENTS as the goal statement
2. Identify the goal type (feature, bugfix, refactor, research, migration, infrastructure, other)
3. Explore the codebase to understand current state — use Glob, Grep, Read, or the Explore agent for broad searches
4. Check existing skills, memory files, and CLAUDE.md for relevant patterns
5. If the goal is ambiguous, use AskUserQuestion to clarify scope — do NOT guess

Gate: Proceed only when the goal, scope, and current state are clearly understood.

Phase 2: DECOMPOSE

Break the goal into small, atomic tasks. Each task must be completable in a single focused action (< 30 minutes of work). If a task feels too large, split it further.

For each task, create it with TaskCreate using this specification:

Subject: <imperative verb phrase — "Add retry logic to Bedrock calls">
Description: |
  **Input:** <what this task needs — files, data, outputs from prior tasks>
  **Tool:** <specific agent, skill, MCP server, or direct tool — see references/agent-selection.md>
  **Steps:**
  1. <concrete step>
  2. <concrete step>
  3. <concrete step>
  **Success:** <checkable acceptance criteria — the exact test/command/observable that must pass; Phase 5's independent verifier checks the produced artifact against THIS>
  **Output:** <what this task produces — modified files, data, artifacts>
ActiveForm: <present continuous — "Adding retry logic to Bedrock calls">

Decomposition rules:

• Size each task by one cohesive responsibility, its dependencies, its acceptance criteria, and whether it fits in a single focused session (< 30 minutes) — not by a fixed task count or a file cap. A cohesive change that happens to span several files is still one task; do not fragment it to hit a number, and do not split file creation from the modification it belongs with.
• Keep genuinely independent concerns in separate tasks so each can be verified — and, where write scopes are disjoint, parallelized — on its own. Research is its own task from the implementation it informs.
• Bug fixes are regression-first: schedule the task that reproduces the defect with a failing (RED) test BEFORE the task that implements the fix, so the fix is proven against a real reproduction. Additional coverage and the independent acceptance check come after the fix lands. This is the one case where a test task precedes its code; general coverage still follows the implementation it exercises.
• For monitoring/polling tasks, use CronCreate instead of manual loops
• For risky or experimental tasks, record the isolation mechanism in the Tool: field as the Agent tool's isolation: "worktree" parameter. Do NOT plan an EnterWorktree step: that tool is explicit-instruction-only and switches the whole session's working directory, so it cannot isolate one task among many

Gate: All tasks created via TaskCreate, each sized to one cohesive responsibility. Decompose only as far as the work's dependencies and acceptance criteria require — a genuinely small goal may be a single task, while a broad one warrants many.

Phase 3: PLAN

Establish execution order by setting dependencies and identifying parallel batches.

1. For each task, set addBlockedBy via TaskUpdate to declare which tasks must complete first
2. Identify batches — groups of tasks with all dependencies satisfied:
   • Batch 1: Tasks with zero dependencies (launch all in parallel)
   • Batch 2: Tasks whose dependencies are all in Batch 1
   • Batch N: Tasks whose dependencies are all in Batches 1..N-1
3. Display the execution plan as a table:

Batch 1 (parallel): #1 Research API docs, #2 Read existing code
Batch 2 (parallel): #3 Implement service [blocked by #1, #2], #4 Write types [blocked by #1]
Batch 3 (sequential): #5 Write tests [blocked by #3], #6 Integration test [blocked by #3, #4]
Batch 4: #7 Review and polish [blocked by #5, #6]

Gate: All dependencies set. Execution plan displayed. No circular dependencies.

Phase 4: EXECUTE

Process batches in order. Within each batch, maximize parallelism.

For each batch:

1. Call TaskUpdate to set all batch tasks to in_progress
2. Launch all tasks in the batch simultaneously:
   • Agent tasks → use the Agent tool with the appropriate subagent_type (see references/agent-selection.md)
   • Direct tool tasks → use Read, Write, Edit, Grep, Glob, Bash directly
   • MCP tasks → use the appropriate MCP server tool
   • Web research → use WebSearch, WebFetch
   • Skill tasks → invoke via Skill tool
3. Collect results from all tasks in the batch
4. Mark completed tasks via TaskUpdate with status: completed
5. If a task fails:
   • Log the failure in the task description via TaskUpdate
   • Assess: is this recoverable? Create a fix task if yes
   • Assess: are downstream tasks blocked? Flag them
   • Continue with non-blocked tasks — do NOT stop the entire pipeline
6. Proceed to next batch only when ALL tasks in current batch are resolved (completed or failed-and-handled)

Execution rules:

• Send a single message with multiple Agent tool calls for parallel agent launches
• Agent tasks run in the background by DEFAULT — omit run_in_background for concurrent launches; writing true is a documented no-op. Pass run_in_background: false only when you must block on a result before continuing
• For direct edits (Write/Edit), execute sequentially if they touch the same file
• Fork subagents — set subagent_type: "fork" explicitly when a worker needs your conversation context; it shares the prompt cache and is much cheaper. Omitting subagent_type does NOT fork: it starts a general-purpose agent with a fresh context and never errors, so the context you assumed was shared is silently absent. Put what the worker needs in its prompt, or continue an already-spawned agent with SendMessage (which resumes it with its context intact)
• Coordinator synthesis: After research agents complete, READ and SYNTHESIZE all findings before launching implementation agents — never pass raw research output
• For risky/experimental implementation tasks, pass the Agent tool's own isolation: "worktree" parameter — it gives that agent a temporary git worktree so it works on an isolated copy of the repo. This is a parameter of the Agent launcher, not EnterWorktree: EnterWorktree is explicit-instruction-only, session-scoped, and cannot be entered twice, so it is never the isolation mechanism for a batch
• For long-running monitoring, use CronCreate instead of manual polling loops
• Always read a file before editing it
• After code changes, run relevant tests if a test suite exists

Phase 5: VERIFY

After all batches complete, verify the overall goal with an INDEPENDENT check — not just self-assessment.

1. Call TaskList to confirm all tasks are completed
2. For code changes: run the build or test command if applicable
3. Independent acceptance check (blocking): spawn ONE isolated verifier sub-agent via Agent with an explicit subagent_type — NOT a fork (a fork shares this context and would merely re-confirm your own reasoning). Give it ONLY: (a) the original goal + each task's Phase-2 Success: criteria, and (b) the produced diff/artifacts (git diff, new files, command output). It must NOT see your TaskList self-assessment or reasoning. It returns PASS/FAIL per criterion, anchored on objective oracles (build/test output) where one exists.
4. For research: verify all questions in the original goal are answered
5. If any criterion is FAIL (or build/tests fail): create remediation tasks and loop back to Phase 4. Do NOT advance to Phase 6 REPORT while any acceptance criterion is unmet.
6. Run the code-quality agent on modified files if substantial code was written

Gate: All tasks completed, build/tests pass (if applicable), AND the independent verifier returns PASS on every Phase-2 Success: criterion. Only then proceed to REPORT.

Phase 6: REPORT

Summarize execution results.

## Execution Report

**Goal:** <original goal>
**Tasks:** <completed>/<total> completed
**Batches:** <N> batches, <M> parallel launches

### Completed
- #1 ✓ <subject> — <key output>
- #2 ✓ <subject> — <key output>

### Failed (if any)
- #X ✗ <subject> — <reason>

### Files Modified
- path/to/file.swift — <what changed>

### Next Steps (if any)
- <remaining work or follow-ups>

Agent & Tool Selection

See references/agent-selection.md for the complete selection matrix.

Quick reference:

Error Recovery

When a task fails:

1. Transient failure (network, timeout) → retry once
2. Validation failure (wrong format, missing input) → fix input, create fix task
3. Dependency failure (upstream task produced bad output) → fix upstream first
4. Unrecoverable (missing access, unsupported operation) → mark failed, skip dependents, notify user
5. Ambiguity discovered (unclear requirements mid-execution) → pause, AskUserQuestion, resume

Never silently skip a failed task. Always log what happened and why.