Execution Orchestrator

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:

# 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

Logging

After each task execution, append to .claude/crew-history.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:

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