orchestrate

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```bash
git diff --stat
```

If changes exist, append:

From epicsagas/epic-harness, Apache-2.0.

More from epicsagas/epic-harness