Orchestrate

Skill: Orchestrate

CRITICAL: Run HARNESS_DIR=$(epic-harness path) first. NEVER use .harness/ in the project directory.

Mode: auto (default)

Triggered automatically when an active multi-agent orchestration is detected.

Step 1: Check orchestration state

1. Run HARNESS_DIR=$(epic-harness path)
2. Read $HARNESS_DIR/orchestrator/run.json
3. If no active run, this skill does not apply — return

Step 2: Read agent inbox

1. Read $HARNESS_DIR/orchestrator/agents/{my_id}/inbox.jsonl
2. Process any pending messages from other agents or user interventions
3. Messages from other agents: integrate into current task context
4. Messages from user (via intervene redirect): adjust task accordingly

Step 3: Check control directives

1. Read $HARNESS_DIR/orchestrator/control.json
2. If a directive targets this agent (or "all"), act on it:
   • pause: halt work after current tool call, wait for resume
   • cancel: stop immediately, set status to "cancelled"
   • redirect: adopt the new instruction, discard current task
   • resume: resume from paused state
3. After acting on a directive, increment generation in control.json to acknowledge

Step 4: Check dependencies

1. Read $HARNESS_DIR/orchestrator/run.json dependency graph
2. Identify which agents this agent depends on
3. Read their status.json — if any dependency is not DONE, wait
4. If all dependencies are DONE, proceed with task

Step 5: Execute with progress reporting

While working on the assigned task:

1. The Rust orchestrate hook automatically appends events to stream.jsonl on each tool call
2. Status updates happen automatically via the hook
3. No manual progress reporting needed — the hook handles it

Step 6: Complete and hand off

When task is complete:

1. Report status via structured output format (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT)
2. The orchestrate hook will evaluate dependencies and notify downstream agents
3. If results should be shared with specific agents, include in the output summary

Mode: status — Orchestration Dashboard

Read-only view of the current orchestration run. Displayed when user runs /status or asks about orchestration state.

Step 1: Check orchestration state

1. Check if $HARNESS_DIR/orchestrator/run.json exists
2. If the file does not exist, output:

   No active orchestration. Run /go or /orbit to start.

3. If status is not "running", output:

   Last orchestration ended with status: {status}. No active run.

4. If status is "running", proceed to Step 2.

Step 2: Read all agent states

Extract the agent list from run.json.agents. For each agent {id}:

1. Read agent status from $HARNESS_DIR/orchestrator/agents/{id}/status.json (mark unknown if missing)
2. Read the last 5 events from $HARNESS_DIR/orchestrator/agents/{id}/stream.jsonl (show "no events yet" if missing)
3. Calculate elapsed time:
   • started_at set, completed_at not set: elapsed = now - started_at
   • Both set: elapsed = completed_at - started_at
   • Format as Xm Ys or Xh Ym
4. Read the dependency graph from run.json.dependencies

Step 3: Render dashboard

Output a formatted dashboard (keep total under 30 lines):

## Orchestration Dashboard

- **Run ID**: {run.id}
- **Status**: {run.status}
- **Elapsed**: {total_elapsed since run.started_at}
- **Agents**: {count where status=running} / {total} active

| Agent | Role | Status | Elapsed | Last Event |
|-------|------|--------|---------|------------|
| {id} | {role} | {status} | {elapsed} | {summary of last event} |

### Dependency Graph
{render with ASCII arrows, e.g.:}
  builder ──→ reviewer ──→ integrator
  builder ──→ tester

### Recent Events (last 5 across all agents)
- [{timestamp}] {agent_id}: {event_summary}

### User Interventions
{read control.json; show directives if any, else "none"}

Dependency graph rendering rules:

• Read edges from run.json.dependencies (format: {"agent_a": ["agent_b", "agent_c"]})
• Render using ──→ arrows
• If no dependencies exist, output: "No inter-agent dependencies."

Event summary formatting:

• Each event is one line from stream.jsonl with fields: timestamp, type, message
• Summarize message to at most 60 characters
• Sort by timestamp descending, take top 5

Step 4: Optional — file change summary

git diff --stat

If changes exist, append:

### File Changes
- {count} files modified ({insertions} insertions, {deletions} deletions)
- Key changes: {list up to 5 file paths}

Note: This mode is read-only — never modify orchestration state.

Mode: intervene — Agent Intervention

Write control directives that the orchestrate hook reads on the next agent tool call. Triggered when user runs /intervene.

Step 1: Check active orchestration

1. Read $HARNESS_DIR/orchestrator/run.json
2. If no active run (status != "running"), output: "No active orchestration to intervene in."
3. Show current agent list with statuses

Step 2: Parse user command

Invocation format:

• intervene pause {agent_id} — pause a specific agent (blocks next tool call)
• intervene pause all — pause all agents
• intervene cancel {agent_id} — cancel a specific agent
• intervene cancel all — cancel entire orchestration
• intervene redirect {agent_id} {new_instruction} — change what an agent is doing
• intervene resume {agent_id} — resume a paused agent

If the user provides no arguments, ask which action and target they want.

Validate the agent_id against the agent list in run.json. If not found, output: "Agent '{agent_id}' not found in active orchestration. Available agents: {list}" and stop.