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.

Step 3: Write control directive

Read current generation from $HARNESS_DIR/orchestrator/control.json (or 0 if file doesn't exist). Increment by 1.

Write to $HARNESS_DIR/orchestrator/control.json:

{
  "action": "pause|cancel|redirect|resume",
  "target": "agent_id or 'all'",
  "message": "optional user message",
  "generation": <current_generation + 1>
}

For redirect, the message field contains the new instruction. For pause/cancel, the message field is optional — use an empty string if none provided. For resume, set action to "resume" and target to the agent_id.

Additional actions by type:

• cancel all: Also update $HARNESS_DIR/orchestrator/run.json status to "aborted"
• redirect: Also append the new instruction to the target agent's $HARNESS_DIR/orchestrator/inbox/{agent_id}.jsonl as a new line: {"type": "redirect", "instruction": "{new_instruction}", "at": "{ISO-8601}"}
• cancel {agent_id}: Also update the agent's status in run.json to "cancelled"

Step 4: Confirm

Output confirmation:

Intervention recorded: {action} {target}
The {target} agent will respond on its next tool call.
Use /status to monitor.

Notes:

• Multiple interventions can be queued (generation number increases each time)
• The orchestrate hook checks control.json before every agent tool call, so interventions take effect within one tool call cycle
• "cancel all" is destructive — confirm with the user before executing
• "redirect" requires a new instruction — if none is provided, ask the user

Message Format Convention

When agents need to communicate (via SendMessage or future inbox/outbox):

{
  "from": "agent_id",
  "to": "agent_id",
  "type": "handoff|question|blocked|result",
  "body": "message content",
  "timestamp": "ISO-8601"
}

Anti-Rationalization

Evidence Required

• Inbox checked before starting work
• Control directives checked (auto mode)
• Dependencies verified (all upstream agents DONE)
• Structured output format used for completion report
• Dashboard shows all agent states accurately (status mode)
• Intervention written to control.json with incremented generation (intervene mode)

Red Flags

• Starting work before dependencies are met
• Ignoring inbox messages from other agents
• Not reporting BLOCKED state when stuck
• Modifying orchestration state in status mode (read-only)
• Cancelling all agents without user confirmation
• Redirecting an agent without a concrete new instruction
• Writing to control.json when run.json status is "aborted" or "complete"
• Intervening without an active orchestration (check run.json first)
• Showing raw JSON instead of a formatted dashboard (status mode)

Source: hashgraph-online/awesome-codex-plugins → plugins/epicsagas/epic-harness/skills/orchestrate/SKILL.md