---
name: execution-orchestrator
description: Smart hybrid execution engine that dispatches agents in parallel or sequential order based on task dependencies. Manages the Agent tool calls, result collection, conflict detection, and integration review.
---

# Execution Orchestrator - Smart Hybrid Dispatch

Executes the task plan generated by the task-router by spawning agents with the right models, collecting results, and coordinating integration.

## When to Activate

- Called by task-router after generating an execution plan
- When re-executing after a conflict resolution

## Core Principle

**Each agent is self-contained.** When spawning an agent via the Agent tool:
- Include ALL context the agent needs in its prompt
- Include the Index-First Protocol
- Include relevant skill guidance
- Include the specific files/symbols to work on
- Include expected output format
- Include context carry-forward from previous task (if applicable, see below)
- The agent should be able to complete its subtask with ZERO additional context

## Context Carry-Forward

Before dispatching agents, check if context from the previous task can reduce re-reading:

1. Read the last entry in `.claude/crew-history.json`
2. Check if the previous task's `filesModified` overlaps with the current task's focus files
3. If overlap exists AND the previous task was recent (same session):
   - Include a "Previous Context" section in the agent prompt (max 500 tokens):
     ```
     ## Previous Task Context
     The previous task ("{task description}") modified these overlapping files:
     - {file}: {summary of what changed}
     Key decisions: {summary field from history}
     ```
   - This helps agents understand recent changes without re-reading unchanged sections
4. If no overlap or no recent history: skip this section

**Token budget**: Max 500 tokens for carry-forward context. If the previous summary is longer, condense to the most relevant parts for the current task's scope.

## Execution Modes

### Sequential Execution
For dependent subtasks where output of one feeds into the next:

```
Phase 1: Agent A completes → result
Phase 2: Agent B receives result + its task → completes → result
Phase 3: Agent C receives combined results → completes
```

Implementation:
1. Spawn Agent A, wait for result
2. Include Agent A's result summary in Agent B's prompt
3. Spawn Agent B, wait for result
4. Continue chain

### Parallel Execution
For independent subtasks that don't share files:

```
Phase 1 (parallel):
  Agent A → subtask on files {X, Y}
  Agent B → subtask on files {Z, W}
  Agent C → subtask on files {V}
All complete → collect results
```

Implementation:
1. Verify no file overlap between parallel agents (check via crew-index.json)
2. Spawn ALL agents in a SINGLE message using multiple Agent tool calls
3. Wait for all to complete
4. Collect and verify results

### Hybrid Execution (Most Common)
Mix of sequential and parallel phases:

```
Phase 1 (sequential): Investigation/Planning
  CEO or debugger investigates → produces plan

Phase 2 (parallel): Independent Implementation
  senior-dev implements feature A on src/moduleA.js
  test-engineer writes tests on test/moduleA.test.js
  doc-writer updates docs/api.md

Phase 3 (sequential): Integration Review
  code-reviewer reviews all changes
  → report to user
```

## Agent Prompt Template

When spawning each agent, construct this prompt:

```markdown
# Task: {specific description of what to do}

**Agent**: {agent-name} | **Model**: {opus|sonnet|haiku}

## Context
{Brief from crew-profile.md — project type, stack, key patterns}

Focus files (from index analysis):
- {file1}: {relevant symbols and line ranges}
- {file2}: {relevant symbols and line ranges}

## Index Protocol
INDEX-FIRST: Read .claude/crew-index.json → crew-symbols.json → only specific lines. Never read entire files.

## Skill Guidance
{Condensed skill injections from skill-injector}

## Output
Report: what changed (file:lines), FILES_MODIFIED: {list}, confidence: high|medium|low, any concerns or dependencies.
```

## Conflict Detection

After parallel agents complete:

1. **File overlap check**: Did any two agents modify the same file?
   - If yes: escalate to vp-engineering for merge review
   - If no: safe to proceed

2. **Import/dependency check**: Did any agent add imports that conflict?
   - Check via git diff or by reading modified sections

3. **Test verification**: If test-engineer was involved, run tests
   - If tests pass: proceed
   - If tests fail: route failures back to relevant agent

## Result Collection

After all agents complete, compile:

```
Done: "{task}" — {SUCCESS|PARTIAL|NEEDS_REVIEW}
  {strategy} | Agents: {agent(model), agent(model), ...}
  Skills: {deduplicated list of all skills injected across agents}
  Changes: {per-agent 1-line summary}
  Files: {file1}, {file2}, ...
  Index: {updated N files | skipped | failed — run /crew reindex}
```

## Auto Index Update (Post-Execution)

After ALL agents have completed and results are collected:

1. **Aggregate FILES_MODIFIED** from all agent outputs
   - Parse each agent's output for the `FILES_MODIFIED:` line
   - Combine into a deduplicated list
   - If no files were modified (e.g., review-only tasks), skip index update

2. **If files were modified**, invoke the `index-updater` skill:
   - Pass the deduplicated list of modified file paths
   - The index-updater will:
     a. Recompute hashes for only those files
     b. Update Layer 1 entries (crew-index.json)
     c. Update Layer 2 entries (crew-symbols.json)
     d. Update global metadata (contentHash, stats, lastIndexed)

3. **Report index update** in the task completion summary:
   - `"Index updated: {count} files refreshed"` if successful
   - `"Index update skipped: no files modified"` if no changes
   - `"Index update failed: {reason} — run /crew reindex"` if error

4. **If index update fails** (e.g., file was deleted between edit and index):
   - Log the warning but do NOT fail the overall task
   - Recommend `/crew reindex` for a full rebuild in the completion report

This step is **mandatory** — do not skip it. A fresh index saves tokens on every subsequent task.

## Error Recovery

| Scenario | Action |
|----------|--------|
| Agent times out | Retry once with simplified prompt |
| Agent reports "can't find function" | Index is stale → incremental update → retry |
| Parallel agents conflict on same file | Fall back to sequential for those agents |
| Agent reports "task too complex" | Escalate complexity → re-route through CEO (or vp-engineering in lite mode) |
| Agent reports "need more context" | Provide additional index data + broader file reads |
| All agents fail | Report to user with diagnostics |

## Logging

After each task execution, append to `.claude/crew-history.json`:

```json
{
  "timestamp": "2026-04-04T12:00:00Z",
  "task": "original task description",
  "type": "bug-fix",
  "complexity": "moderate",
  "strategy": "hybrid",
  "mode": "full|lite",
  "gitRefBefore": "abc1234",
  "agents": [
    {"name": "debugger", "model": "sonnet", "status": "success", "confidence": "high"},
    {"name": "senior-dev", "model": "sonnet", "status": "success", "confidence": "high"}
  ],
  "filesModified": ["src/parser.js"],
  "skillsInjected": ["iterative-retrieval", "typescript-patterns", "verification-loop"],
  "duration": "45s",
  "status": "success",
  "summary": "Debugger traced bug to parser.js:45, senior-dev fixed off-by-one in parseToken()"
}
```

Fields added for new features:
- `mode`: "full" or "lite" — tracks which routing mode was used
- `gitRefBefore`: git commit hash captured before execution (for rollback support)
- `confidence`: per-agent confidence level from their output
- `skillsInjected`: deduplicated list of all skills injected across all agents in this task
- `summary`: 2-3 sentence summary for context carry-forward to subsequent tasks

## Ongoing Agent Suggestions

After logging the task, check if a new custom agent should be suggested to the user. This runs **every 5th task** (check if the history array length is a multiple of 5).

### Trigger Condition

1. Read `.claude/crew-history.json` — if `length % 5 !== 0`, skip this section entirely
2. Read `.claude/crew-team.json` — get the list of existing custom agents

### Pattern Detection

Analyze the last 10 history entries for these patterns:

| Pattern | Signal | Suggested Agent |
|---------|--------|-----------------|
| **Repeated task type** | Same `type` appears 3+ times in last 10 tasks | Specialist for that type (e.g., repeated `security` → suggest security-focused custom agent if none exists) |
| **File cluster** | Same directory appears in `filesModified` across 3+ tasks | Directory-specific specialist (e.g., `src/api/` repeatedly modified → suggest api-specialist) |
| **Complexity escalation** | Average complexity is `moderate+` and senior-dev is used in 60%+ of tasks | Domain specialist to offload senior-dev |
| **Repeated escalation** | Agent reports "ESCALATE" 2+ times in last 10 | Specialist to handle that area directly |

### Output

If a pattern is found AND no existing custom agent covers it:

```
Tip: Your last {n} tasks frequently involve {pattern}. Consider adding a custom agent:
  /crew agent create "{suggested-name}" --model sonnet --description "{suggested-description}"
```

Rules:
- Show **at most one** suggestion per task completion
- Never repeat the same suggestion in the same session
- If all patterns are already covered by existing custom agents, show nothing