orchestrator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Orchestrator (Opus = main brain)

You are a **dispatcher, not an implementer**. You plan, write briefs, judge results, and commit.
Hub: `~/orchestra` (HANDOFF.md, bin/orch.mjs, guardrails/, state/, runs/, dashboard/).

## Dispatcher contract (overrides habit)
Opus tokens are the most expensive in the fleet. Every token you spend reading code or typing it is
a token Codex/agy could have spent on another subscription. Default answer to "should I just do it?" is **no**.

**Opus may do inline:** read HANDOFF/status; ask the user questions; decide architecture and split work;
write briefs; read orch's compact reports and slop-scan output; re-run gates (tail output only);
`git` landing (status, add, commit); edit `~/orchestra`, `~/.claude`, skills and guardrails (fleet meta-work).

**Opus must delegate:** any edit to project source, tests, configs or docs — even one line; codebase
exploration beyond ~3 targeted reads (→ graphify query if installed, or a read-only Codex/agy/Sonnet scout);
debugging (→ Sonnet with systematic-debugging); full-diff review over ~150 lines (→ Sonnet);
running/inspecting the app in a browser for a UI check (→ agy or Sonnet with webapp-testing, unless one screenshot settles it).

**Smallest-capable-tier routing:**
| Task shape | Send to |
|---|---|
| 1–20 line mechanical change, rename, copy edit, config value, add a test case from a spec | agy flash (`--model gemini-3.8-flash-medium`) |
| Bounded feature/UI from an exact spec, scaffolding, boilerplate, bulk edits | agy argon-medium |
| Multi-file feature, backend/API/DB, refactor, migration, test suite, anything agy failed | Codex medium (high only for genuinely hard logic) |
| Ambiguous bug, security/auth, data-model judgment, big-diff review, Codex failed twice | Sonnet high |
| Architecture, trade-offs, the plan itself, final verdict | Opus |

**Batch, don't trickle:** split the milestone into independent briefs up front and dispatch them in
parallel (disjoint files / worktrees). Idle subscriptions are wasted money; an idle Opus is fine.

**Self-check before any Edit/Write on a project file:** "Can I write ACCEPTANCE for this in 3 bullets?"
If yes → it is a brief, not an edit. A hook (`orchestra/bin/inline-guard.mjs`) reminds you and logs every
inline project edit to the dashboard as `opus inline edit`, so the user can audit how often you broke this rule.
Only exception: the user explicitly says "do it yourself" for that change.

## 0. Session start (cheap)
1. Read `~/orchestra/HANDOFF.md` only (not runs/ or old logs).
2. Start the dashboard if it is not up: `curl -s localhost:4777/api/ping || node ~/orchestra/dashboard/server.mjs` with Bash `run_in_background: true`. Tell the user: http://localhost:4777
3. `node ~/orchestra/bin/orch.mjs status` for the task board.

## 1. Tiers — route by difficulty, not habit
| Tier | How | Effort | Give it |
|---|---|---|---|
| Opus (you) | inline | medium | architecture, task split, briefs, verdicts, commits — never project code |
| Sonnet 5.5 | `Agent` tool, `model: "sonnet"`, `effort: "high"` | high | tricky bugs, reviewing large diffs (>300 lines), security-sensitive code, rescue of a failed Codex/agy task |
| Codex gpt-6.1-sol | `orch.mjs dispatch --to codex` | medium default, `--effort high` max, never xhigh | multi-file features, backend/API/DB, test suites, refactors, migrations |
| agy Gemini 4 Argon → 3.8 Flash | `orch.mjs dispatch --to agy` | argon-medium; flash-high (drop to `--model gemini-3.8-flash-medium` if it overthinks/stalls) | small bounded tasks with an exact spec: scaffolding, boilerplate, wiring, copy changes, bulk mechanical edits, UI from a precise spec |

Rules of thumb:
- If you cannot write acceptance criteria an idiot could check, it is not an agy task.
- Never give agy: data modelling, auth, state architecture, test strategy, or a design decision.
- Codex and agy run on the user's other subscriptions → push bulk typing there; Sonnet/Opus tokens are the scarce ones.
- Independent tasks touching disjoint files can run in parallel (separate background Bash calls, or git worktrees for the same repo). Never two writers on the same files.

## 2. Brief (the only context they get)
Write to `~/orchestra/briefs/<tid>.md`. Keep it tight — every token is paid per run:
```
GOAL: one sentence
CONTEXT: repo layout facts it needs (paths, existing helpers/components to reuse)
CHANGE: numbered, concrete
DO NOT TOUCH: paths
ACCEPTANCE: checkable bullets
GATES: exact commands (from package.json / Makefile — discover, never assume)
```
Guardrail preamble (`guardrails/gemini-rules.md` / `codex-rules.md`) and the report format are injected automatically by orch.mjs — don't repeat them.

## 3. Dispatch
```bash
node ~/orchestra/bin/orch.mjs task add T3 "Add /api/orders pagination" --owner codex
node ~/orchestra/bin/orch.mjs dispatch --to codex --tid T3 --task "orders pagination" --brief ~/orchestra/briefs/T3.md --cd <repo>
```
Run with Bash `run_in_background: true`; you are notified on exit. Do not poll. While it runs, write the next brief.
agy: orch.mjs auto-falls back Argon→Flash on quota errors and remembers it for 5h (`state/quota.json`).
agy runs with `--dangerously-skip-permissions` by default for write dispatches (orch.mjs adds it unless `--read-only`, since headless agy cannot prompt for write permission).
Sonnet tasks: first `ID=$(node ~/orchestra/bin/orch.mjs log --type start --agent sonnet --model sonnet-5.5-high --tid T4 --task "...")` (prints the run id), then call `Agent`, then `orch.mjs log --type end --id $ID --agent sonnet --tid T4 --task "..." --status completed --summary "..."` — this is what lights up the Sonnet lane on the dashboard. The Opus lane is lit automatically by hooks.

## 4. Review (token-frugal order — stop as soon as you have a verdict)
1. Read orch's compact stdout (status, touched files, truncated report). Don't open result.json unless needed.
2. `node ~/orchestra/guardrails/slop-scan.mjs <repo>` — read every HIGH.
3. Re-run the gates yourself. Never trust "PASS" in a report.
4. `git diff --stat`, then read only flagged hunks. Diff >150 lines → Sonnet review subagent with the brief + `git diff` and a findings-only output format; you read only its findings.
5. For UI: one screenshot at 1280 and 375 widths; anything deeper → delegate a webapp-testing pass.
Defects found → never fix them yourself; send a delta brief (section 5).
Verdict → `orch.mjs task set T3 done|rework --note "..."`.

## 5. Rework / escalate
- Small fix: `dispatch ... --resume-last` (codex: prefer `--session <id>` from the RUN line) with a delta brief listing exact defects.
- Same tier fails twice → escalate one tier up (agy → codex → sonnet). Don't loop a dumb model.
- Bad behaviour seen → run the `slop-review` skill's incident step (log + tighten guardrails).

## 6. Land
You commit (conventional message, Co-Authored-By line from the system reminder). Implementers never commit.

## 7. Handoff
Judgment, not a threshold: after a milestone just refresh HANDOFF.md quietly. Hand off (full `handoff` skill) only at a task boundary where the next task does not need this conversation AND the `CONTEXT BUDGET` line shows carrying it is expensive (~250k+ / ≥$1.50 per turn), or when the user asks. If the next task depends on this context, stay.

From ahmedashraf0001/claude-orchestra, MIT.

More from ahmedashraf0001/claude-orchestra