orca-orchestration
Skill26 starsChanged 10 days agoMITView on GitHub
Multi-session agent orchestration for this repo: one conductor session coordinating a fleet of persistent worker sessions (one per story, per module, per failure cluster) through the Orca runtime, plus the non-Orca fallback where the same launch lines are pasted by hand. Owns the HOW of fleet work — terminals, Runs, Tasks, dispatch, briefs, claims, board cards, liveness, cleanup — while each workflow skill keeps owning the WHAT. Use when the user wants to: orchestrate or parallelize work across sessions (`orchestrate`, `fleet`, `launch workers`, `one session per story`, `parallelize the sprint`, `run these in parallel`, `orquestar`, `lanza workers`, `una sesión por historia`, `paraleliza el sprint`), talk to or steer a running worker (`talk to the worker on BK-123`, `ask W2 if`, `pause X`, `close X`, `comunícate con el worker`, `pregúntale a W2`, `cierra las sesiones`), check or resume a fleet (`how is the fleet doing`, `fleet status`, `resume the run`, `pick up last night's wave`, `estado de la flota`, `retoma el run`), set up an Orca worktree for a worker, or schedule an unattended routine (`automation routine`, `nightly triage`, `automatización nocturna`). ALSO trigger in WORKER mode when a brief names this skill. Do NOT use for: one-shot subagent dispatch inside the current turn (that is AGENTS.md §3 and stays the default), a pure ownership handoff of work to another agent with no supervision (that is the vendor `orca-cli` guide, not orchestration), per-ticket manual QA (use /sprint-testing), writing test code (use /test-automation), branch / commit / PR mechanics (use /git-flow-master), or plain `git worktree` work with no fleet (use /git-flow-master `git-flow-master/references/worktrees.md`).
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- askprateek/skillstheir own version, first seen Sep 1, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- askprateek/skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- acliSkill
- agentic-qa-coreSkill
- agentic-qa-onboardSkill
- bug-screenshot-annotationSkill
- business-api-contextSkill
- business-data-contextSkill
- business-domain-contextSkill
- business-e2e-contextSkill
- evidence-artifactSkill
- exploratory-testingSkill
- framework-developmentSkill
- git-flow-masterSkill
- infra-contextSkill
- iql-contextSkill
- jira-administrationSkill
- judgment-daySkill
- project-contextSkill
- project-discoverySkill
- pr-review-leadSkill
- regression-testingSkill
- session-handoffSkill
- shift-left-testingSkill
- sprint-conductorSkill
- sprint-testingSkill
- test-automationSkill
- test-documentationSkill
- test-framework-adaptationSkill
- xray-cliSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 69
Run the gate. State A or B → say the one line below and continue on the fallback.
- Very specific: line 72
Create the scope .session/orchestration/<slug>/, seed run.md, roster.md, COMMON.md, launch.txt from templates/.
- Very specific: line 73
Run the cycle in references/coordinator-playbook.md §1, in that order: Run → Tasks → placement → NATIVE launch → verify readiness and …
- Distinctive: line 74
Wait inside the turn, one waiter, rolling windows of at most 540 s, ack verified in the same command that re-arms.
- Very specific: line 198
A base-ref flag resolves LOCAL refs: verify the new worktree's SHA against the remote base, with no || true to hide the failure.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Orca Orchestration — One Conductor, a Fleet of Sessions
This skill is the transport layer for work that does not fit in one session. A conductor talks to the owner and coordinates workers; each worker is a persistent agent session that owns a scope from start to finish, reports through a mailbox, and can be interrupted, questioned and resumed. The fleet is all workers of one Run.
It is optional by construction. Everything here has a path that works with no runtime at all: the same launch lines, pasted into terminals by a human, and the same tokens and artifacts the workflow skills already write. What the runtime buys is the step a human would otherwise do with their hands, plus a mailbox instead of screen-scraping.
Read full SKILL.md when: starting a fleet cold, arbitrating a claim, choosing a topology, recovering a Run from a previous session, or writing an unattended automation.
When to use
- The user asks to parallelize, orchestrate, or run "one session per story / module / failure cluster".
- The user wants to talk to, steer, interrupt, question or close a session that is already running.
- The user wants the state of a fleet, or to pick up a wave from a previous session.
- A brief names this skill (WORKER mode).
- An unattended routine has to dispatch work with nobody at the wheel.
When NOT to use
| Situation | Use instead | |
| a read, a verification, a map — anything that fits in this turn | one-shot subagents (AGENTS.md §3). This is most work | |
| "hand this TASK to another agent and forget it" | that is a HANDOFF, not orchestration: no Task, no Dispatch, no mailbox. Ask the binary for its orca-cli guide | |
| "hand this whole SESSION to a fresh one, my context is full" | ownership transfer of the session itself, same worktree, same harness | /session-handoff |
| per-ticket manual QA | /sprint-testing | |
| writing test code | /test-automation | |
branch / commit / push / PR mechanics, or a plain git worktree with no fleet | /git-flow-master | |
| one long task, one session, no siblings | just do the task |
Quick start (conductor)
- Run the gate. State A or B → say the one line below and continue on the fallback.
- Load every skill in
orchestration.orchestrator_skillsnow, alongside this one. They are the vendor's command grammar and they are small; this skill is the WHEN and the WHAT. Skipping them is what produces invented flags. Then ask the binary for a DEEP topic only when a stub points at one ({{ORCHESTRATOR_CLI}} skills get <topic>). Nothing installed → skip straight to asking the binary; the gate never depended on the stubs. - Pick the topology from what the work WRITES (
references/topologies.md), and run the triage-time collision check in claim vocabulary (references/claims-protocol.md§5). - Create the scope
.session/orchestration/<slug>/, seedrun.md,roster.md,COMMON.md,launch.txtfromtemplates/. - Run the cycle in
references/coordinator-playbook.md§1, in that order: Run → Tasks → placement → NATIVE launch → verify readiness and credentials on screen → send the prompt. Those last three are not separable. - Wait inside the turn, one waiter, rolling windows of at most 540 s, ack verified in the same command that re-arms.
- Close each finished worker AND its worktree in the same turn: orphan audit first, then remove (
references/coordinator-playbook.md§6). - Harvest
learnings.mdandskill-improvements.md, writekickoff.md, then report to the owner.
Three layers, and ours points instead of copying
LAYER 3 · REPO DOCTRINE .agents/skills/orca-orchestration/ (T1, versioned, this skill)
when to split work · topology per activity · provisioning · brief · measured gotchas · phrasebook
^ points at v
LAYER 2 · GRAMMAR + MACHINE orca skills get orchestration (mailbox, Run, Task, worker lifecycle)
orca skills get orca-cli (terminals, worktrees, board, browser)
served BY THE BINARY, versioned with it. The user-level stubs carry the command grammar and load alongside this skill; the binary serves the DEEP topics a stub points at.
^ operates on v
LAYER 1 · APP the app running · runtime reachable · board · phoneComposition rule: if the binary's own guide says it, this skill carries a pointer, not a copy. A copy desynchronizes in silence on the next release. What lives HERE is what no vendor guide has: this repo's provisioning gaps, the topology per activity, the brief, the measured gotchas, the git integration, the owner phrasebook.
Consequence for the gate: it is evaluated on binary + runtime, NEVER on "is the vendor skill installed". A machine with the binary and no stubs is fully capable, because this reference knows how to ask the binary for the grammar.
Consequence for cost. The user-level stubs are small (measure with wc -c on the installed stubs; the figure that settled this is recorded in .context/ADR/ADR-0006-forensic-measurements-ledger.md). The trap is conflating the user-level SKILL.md STUB with the full topic payload the binary serves on demand ({{ORCHESTRATOR_CLI}} skills get <topic>) — those are different artifacts and only the second is large.
So the rule is: orchestration.orchestrator_skills load ALONGSIDE this skill, never instead of it. This skill owns WHEN and WHAT; the vendor stubs own the command grammar. A small load up front is cheaper than one iteration spent correcting an invented flag (measured: ADR-0006). The on-demand fetch stays for the DEEP topics a stub only points at.
The list is orchestration.orchestrator_skills in .agents/project.yaml, not a hardcoded name here. Empty list = nothing installed, and this skill falls back to asking the binary for its grammar — which is still fully capable, per the gate rule above.
The gate: three states
command -v orca >/dev/null 2>&1 \
&& [ "$(orca status --json </dev/null 2>/dev/null | jq -r '.result.runtime.reachable' 2>/dev/null)" = "true" ]The reachability flag is NESTED (.result.runtime.reachable). A gate that looks for a flat field fails closed and silently on a perfectly capable machine. Verify any edit to a gate by running BOTH branches.
Platform rule (Linux): inside an Orca-managed terminal orca always resolves to the Orca CLI (Orca exports ORCA_APP_VERSION / ORCA_TERMINAL_HANDLE there). Outside one, on Linux, the CLI registers as orca-ide because bare /usr/bin/orca is the GNOME Orca screen reader: probe orca-ide there, never orca. The hook's orcaAvailable() applies exactly this rule (env signal first, then orca-ide on Linux, orca elsewhere); use the same executable for every later command in the session.
| State | In a workflow skill (sprint-testing, test-automation, …) | In this skill |
| A · no binary | total silence. Not named, not recommended, not a prerequisite, not in the ATR, not in the blocked-token sweep. The flow writes its launch file and the human pastes the lines. The one exception is /sprint-conductor, which runs only on Orca: one line, then it stops | one line, and only because the user ASKED for orchestration (see the exact text below), then continue on the fallback |
| B · binary, runtime unreachable | silence (same fallback). /sprint-conductor opens the app once and re-checks once, as this skill does; still unreachable → its state-A line | orca open --json once, re-check once; still unreachable → treat as state A |
| C · ready | the reinforcement activates without announcing itself: the runtime launches the workers and delivers the identical prompt, and they report to the mailbox IN ADDITION to the file tokens | full mode: conductor / worker / automation |
The exact recommendation (state A or B, this skill only), adapted to the user's language:
Level-1 orchestration is already available in this session: one-shot subagents (AGENTS.md §3). That is mini-orchestration and it covers reads, verification and mapping. Professional orchestration — persistent sessions you can talk to, a mailbox, a board, your phone — needs Orca installed on this machine. Without it I will still write
launch.txtwith one ready-to-paste line per worker, and you open the terminals.
The test that settles any future edit: would this line still make sense, unchanged, to a tester who has never heard of Orca? If not, the edit belongs in this skill, not in the workflow skill. The real prohibition was never "workflow skills must not know about the orchestrator"; it was "the absence of the orchestrator must cost nothing and must never be reported". A silent gate satisfies that, which is why a workflow skill may carry a few gated lines.
Orchestration executors (complements AGENTS.md §3)
AGENTS.md §3 is permanently active and unchanged: the main conversation is the command center, and one-shot subagents remain the default executor. This skill adds a SECOND executor and declares the exception in writing, because a supervised worker breaks three assumptions the one-shot contract makes (a fresh agent per dispatch, no channel until it finishes, the orchestrator as the only one who can ask the user).
| One-shot subagent (default) | Supervised worker (this skill) | |
| Lives | inside the turn | until you close it |
| Context | lost when it reports | persists; you keep talking to it |
| Channel | none until it finishes; cannot be paused | messages, blocking questions and replies at any time |
| Owner sees it | no | yes: board, terminal, phone |
| Git | the orchestrator's | its own (worktree) or shared under explicit file ownership |
| Best for | reading, verifying, mapping; the 7-component briefing | writing and integrating on its own; a whole story; long work; when the owner wants to step in |
Practical rule: the subagent explores and returns a map; the worker executes a complete scope. The conductor keeps using subagents for ITS OWN reads, which is what keeps the main context lean. The fan-out cap of the dispatch doctrine still applies to fleets, for a different reason: tracker and TMS rate limits, not context.
Modes
| Mode | Who | Loads | Does NOT load |
| CONDUCTOR | the session talking to the owner | this SKILL.md + references/coordinator-playbook.md + every stub in orchestration.orchestrator_skills, loaded up front; a DEEP topic from the binary only when a stub points at one | nothing else; its reads go through subagents |
| WORKER | each launched session | orchestration.orchestrator_skills + references/worker-contract.md (short) + references/channel-discipline.md (shorter) + its domain skill (/sprint-testing, /test-automation, …) | nothing else: the injected preamble carries the rest of its contract |
| AUTOMATION | an unattended scheduled routine | references/automations.md + this SKILL.md in conductor mode | anything that produces output: the dispatcher never produces |
| OWNER | the user, by chat or phone | the phrasebook below |
Decision tree: is this even orchestration?
- Does the work fit in this turn, and is it a read / verification / map? → one-shot subagent. Stop here. This is most work.
- Do you want to hand the work away and stop caring? → that is a handoff, ownership transfer, not orchestration: no Task, no Dispatch, no mailbox. A single TASK handed to another agent is the binary's
orca-cliguide; ask for that guide and follow it. A whole SESSION handed to its own successor because the context window is filling up is/session-handoff. - Do you need to supervise, wait for results, answer questions, or coordinate a dependency graph? → orchestration. Continue.
- Does the work write code? → one Orca worktree per worker. Does it not? → fleet in the same checkout. See
references/topologies.md. - Do you want the workers SUPERVISED (addressable by dispatch, closable one by one, preamble injected)? → the NATIVE launch, and nothing else: the runtime recognizes only agents it started itself. Supervision comes from that launch alone. The agent's per-machine default arguments decide only the worker's PERMISSION MODE: the conductor verifies it at readiness against
orchestration.permission_modes.workerand fixes a mismatch before dispatching work (hard rule 5); credentials reach the worker through a provisioned.env, which every MCP server reads through the.envloader (references/orca-machine-setup.md§3). - Is there no human at the wheel? →
references/automations.md.
The owner phrasebook
The owner speaks natural language to the conductor; the conductor translates. The roster is what resolves "the one on BK-123" into a task, a dispatch, a terminal handle and a worktree.
| The owner says | The conductor does | Notes |
| "how are they doing?" / "fleet status" | task list (brief) + worker list + the cross-worktree summary | answer as one table: KEY · stage · state · last message |
| "talk to the worker on BK-123, tell it …" | the MESSAGE goes to the mailbox (orchestration send, or a file plus a pointer if it runs long); terminal send may carry only a one-line nudge — "check your mailbox: <subject>" — and only when G46 says the worker is busy and would not read mail between turns | hard rule 4. Mail does NOT reach a busy worker and reports success anyway (G46), which is why the nudge exists; the nudge is not the message. The roster resolves the label |
| "ask W2 whether …" | a question message to that dispatch, then one mailbox wait | |
| "what is X doing?" | read the worker's output by dispatch, then the rendered screen as backup | the screen is backup, never the channel |
| "tell it yes" | reply to that message id | the id comes from the pending batch |
| "launch another worker for …" | task-create → placement → native launch → verify on screen → send the prompt | one indivisible operation (see the playbook) |
| "pause / interrupt X" | send an interrupt into its terminal, then verify on the rendered screen | there is no native pause/resume |
| "close X" / "it is done" | release the supervised worker by dispatch · without a dispatch: count terminals, then close that one terminal and its tab | never the worktree-wide stop without counting |
| "pick up last night's wave" | bind this session to the existing Run id from run.md, then list tasks | a Run outlives the session that made it |
| "send me the summary on my phone" | board card comment + an HTML log as a shareable artifact |
Hard rules
- A finished worker is closed in the same turn. Live worktrees left open have taken the runtime down (G31).
- Provision the worktree BEFORE launching (
references/provisioning.md). Provisioning gaps disguise themselves as other failures. - Create + launch + deliver the brief = one indivisible operation. Verify with a working-tree status check a few minutes later: a worker has sat idle for hours because the brief never arrived (G32).
- One message, one task — and the channel is an ASSIGNMENT, not a preference.
orchestration send(the mailbox) carries every message between sessions: it is byte-intact (G66). Anything longer than a couple of sentences goes in a FILE cited by absolute path into the primary checkout (never in a system temp directory: it triggers a permission prompt), and the message is the one-line pointer.terminal sendis for driving a terminal — commands, CLI calls, harness slash-commands, keystrokes — and it is lossy: it truncates silently, keeps only the TAIL, and reports success anyway (G60, G64). The test: if a human would READ it, it does not go throughterminal send; if a shell or a TUI would EXECUTE it, that is what the verb is for. Exactly one structural exception: the launch handoff prompt of a supervised worker, because the native launch takes an agent, a model and an effort level and has no argv at all (step 6 of the launch flow, G58) — kept short and pointing at a file. So the rule is never "no prompt throughterminal send"; it is no conversation throughterminal send. Full discipline, plus what the verb is genuinely excellent at:references/channel-discipline.md. - Launch each tier in the permission mode
orchestration.permission_modesdeclares, never an edits-only mode. The defaults decided in.context/ADR/ADR-0024-agentic-work-profile-and-permission-posture.mdare conductorauto, workerbypass, subagentinherit, translated per harness in ONE table (references/orca-machine-setup.md§3.1).autois NOT non-interactive: Claude Code's classifier pauses and PROMPTS after 3 consecutive or 20 total blocks, which is why a worker, whom nobody watches, defaults tobypass. An edits-only mode covers file edits but not commands, so every Bash call waits on a human who is not watching; one worker left every tracker mutation computed and unexecuted (G27). A supervised worker's mode comes from the app's per-agent default arguments, not from the launch, so the conductor VERIFIES it at readiness (status bar or process argv) and fixes a mismatch before dispatching work. Orca's own default Claude launch already carries the bypass flag (G79). - Never acknowledge a batch you did not process. Verified ack (the acknowledged id equals the one requested, the pending count drops), never inside a compound command. An unacknowledged batch hides everything behind it AND the runtime will not notify again.
- Do not build a monitor, and roll the wait instead. The runtime notifies the conductor when mail arrives; a homemade monitor competes with that notice, arrives late by construction, and triggers on echoes of the conductor's own messages. The harness kills a foreground command at 600 s, so a realistic round is covered by successive waits of at most 540 s, each re-armed with the verified ack in the same command — not by one long block, and never by a shell background job.
- The stop verb has worktree radius: count first. To close one terminal, close that terminal (and its tab).
- A base-ref flag resolves LOCAL refs: verify the new worktree's SHA against the remote base, with no
|| trueto hide the failure. - Never name the orchestrator to the user from a workflow skill when the gate fails, and never put it in prerequisites, in a non-bypassable probe, in the ATR environment block, or in a blocked-token sweep. The single exception is
/sprint-conductor, which the owner invokes to run ON Orca: its gate failure is one line and a stop, never a prerequisite list or a recommendation. - Text typed into a terminal and not sent is not an instruction.
- One dev server and one browser per worktree; close every browser-automation session before reporting (orphaned headless browsers, measured: G37).
- Critical Rule #15 counts double in a same-checkout fleet: no global discards, another session shares the tree.
- Worker commits carry zero AI attribution (Critical Rule #3) and the two forensic trailers (
Worktree:/Session:), which are forensics, not attribution. Canon:/git-flow-master. - A stage boundary is not a checkpoint. The launch prompt and the brief both say: run every stage without returning to the prompt until
worker_doneis sent. The pressure has to be in the PROMPT, because as a file pointer it reads as reference material — measured on a real fleet (G58): workers stopped mid-work on briefs that already forbade checkpoints. - "My measurement contradicts the conductor" is a mandatory
ask. The worker stops, sends both readings with its evidence, and waits. Never silent compliance, never silent deviation. This is the behaviour that makes a fleet worth more than a faster single session: a worker refused a wrong instruction from its conductor and was right, and nothing else in the run came close in value. - A success code describes the CALL, never the OUTCOME — verify at the destination. Four surfaces returned success while nothing arrived: a launch line that died in the shell (
terminal create --command, G11), aterminal sendthat delivered a tail fragment (G60, G64), anorchestration sendwhose receipt carried"delivered_at": null, "read": 0in the same payload that proved acceptance (G67), and a dispatch still readingdispatchedwhile pointing at a terminal that no longer existed (G68). A green receipt is the most dangerous kind of green, because it suppresses the check that would have caught the failure. Read the screen, read the mailbox, read the row — at the destination, never at the caller. ok: falseon aterminal sendmeans a HUMAN is typing in that terminal. Never retry. It is the runtime protecting that person's input box, not a transport failure: a retry interleaves your keystrokes with theirs, and a fallback to a longer message makes it worse. Wait, then read the screen (G65). Do not conclude the session is unreachable.- A message that begins mid-sentence is a TRUNCATION until proven otherwise. The head is what gets lost, so the damage reads like a typo or a stray keystroke rather than like a missing message, and nobody goes looking for the rest (G64). Ask for the pointer; never answer the fragment, and never reconstruct what you think it said.
- A name is not an address: sign with the terminal handle plus the Run id. Addressing has failed in three measured ways (G69, G70), and the two quiet ones cost more than the loud one: a name that resolves to NOTHING (loud — three sessions were routed at a dead conductor name and each improvised differently); a name that resolves ONLY TO ITSELF, read by a session out of its own roster and unresolvable by every peer, which looks verified from the inside (G70); and a name that PREFIX-MATCHES the wrong session in a different repository and returns success (G69). A brief, a report or a seed names its author by the terminal handle (
ORCA_TERMINAL_HANDLE, which is in the environment and is not a self-report) plus the Run id — never by a name the session read about itself. - The channel carries no identity, so a RECIPIENT verifies the sender. Rule 20 is the sending half; this is the other one, and it is the half that actually got burned. A message arrives with no trustworthy author — the transport can prefix-match the wrong session in another repository and still return success (G69) — so a recipient that cannot identify the sender from the payload ASKS instead of inferring from context. The corollary bites hardest on a REPLY: answering a message whose author you assumed is how a scope agreement about one repository landed in a session working in another.
- A conductor decides scope; a worker decides execution. The split is not seniority, it is blast radius: a worker changes what its brief already named, and anything that widens the brief — a new file owner, another ticket, a different branch, a schema or fixture other workers share — stops and escalates. A worker that quietly widens its own scope is the failure the claims protocol cannot see, because no claim was ever filed. Conductors own the inverse error: a brief so narrow the worker must widen it to finish is a conductor defect, not a worker one.
- A report is a COUNT, not a narrative. "Mostly done", "almost there" and "a few failures" are not states a conductor can act on: they force a follow-up question that the report existed to prevent. Every stage report and every standby report leads with numbers — how many passed, how many remain, how many are blocked and on whom — and the prose comes after, if at all. Full shape:
references/standby-report-contract.md. - A session launched by another session never asks the human. Its errors, blockers and the four escalation kinds of
agentic-qa-core/references/decision-protocol.md§5 go to its launcher (blockingask,escalation, orBLOCKED:status on the unsupervised path): no user-question prompt, no structured-question tool, nomkddeck, no sweep, and never a guess. A technical call inside its brief is its own, reported as DECIDED. The conductor decides a technical call inside the plan, relays everything else to the human (sweep small, deck heavy), replies by message id and records the answer; a middle conductor (G77) relays upward the same way. Exception: the human typed into that session, or the brief grants it in writing, and the session tells its launcher what was asked and answered. Canon:references/worker-contract.mdrule 16,references/coordinator-playbook.md§4,agentic-qa-core/references/decision-elicitation-doctrine.md§0.
Defaults: the orchestration block
.agents/project.yaml carries an orchestration block owned by this skill: the worker cap per round ({{MAX_WORKERS}}), the default agent ({{DEFAULT_AGENT}}), and the agentic-work profile per tier. Variable syntax: .agents/README.md. How the conductor applies each profile key:
| Key | Applied |
{{DEFAULT_MODEL}} / {{DEFAULT_EFFORT}} | the WORKER tier: passed to worker-start --model / --effort (supervised) or written into the launch.txt line (pasted path). A full model id, never an alias (G29); empty is allowed only when the conductor reads the model off the worker's screen and records it in the roster |
{{CONDUCTOR_MODEL}} / {{CONDUCTOR_EFFORT}} | the CONDUCTOR tier: the model and effort a conductor session runs at, including a middle conductor another conductor launches (agent launch, G77) |
{{SUBAGENT_MODEL}} | one-shot subagents dispatched inside a turn, written in the harness's own subagent vocabulary (Claude Code's Agent tool: sonnet, opus, haiku, fable), never a full id |
orchestration.permission_modes | a map read by path: the mode per tier (conductor, worker, subagent) in the repo vocabulary bypass / auto / ask / inherit, translated per harness in references/orca-machine-setup.md §3.1; the conductor verifies the worker's mode at readiness (hard rule 5) |
orchestration.model_overrides | a list read by path: each entry (topics, tier, model, effort) is matched against the brief's topics when the conductor picks a tier's model and effort; a match replaces the tier default for that brief only |
They are defaults, not policy. An explicit user instruction in the conductor session ALWAYS overrides them for that run, overrides included ("run six", "use the small model for these", "codex for this one"). The defaults apply only when the user said nothing. Never ask the user to confirm a default they never mentioned, and never override an instruction they did give because the yaml disagrees.
Two vocabulary rules that keep reports readable:
- round = one concurrency group, up to the worker cap in flight at once.
- wave = a tracker-status bucket, and it exists only in
sprint-testing. Rounds are numbered INSIDE a wave: "Wave 1, round 2". Never reuse "wave" for concurrency.
The fallback, in full
With no binary and no runtime, nothing about the work changes — only who does the launching and how state is read:
| Step | Fallback |
| plan | identical: same topology decision, same triage-time collision check, same rounds |
| brief | identical: COMMON.md + W-<label>.md in the scope, cited by absolute path |
| launch | the conductor prints launch.txt and the human opens N terminals and pastes N lines. This is the ONLY path where the launch line itself is the payload, which is why the file is still written unconditionally |
| identity | Claude Code and Pi: the identity hook or the adapter names the session from the prompt token (the line carries no name flag); Codex and OpenCode v2.2: the human types /rename <label>--<handle> once it is up (<label> alone outside Orca); a worker never renames its own session |
| state | the workflow's own blocked-state tokens plus the tracker, exactly as a single session already does |
| questions | the worker writes the question in its report with options and a recommendation, and keeps going on what does not depend on the answer |
| close | the human closes the terminals |
| claims | the degraded append-only ledger (references/claims-protocol.md §6), with smaller rounds |
This path is the CONTRACT and the runtime path is the shortcut. Which is why the PROMPT is identical on both, down to its opening token and its no-stopping sentence: the path nobody exercises is the one that silently breaks in three weeks. The launch LINE could not stay shared — a supervised worker has no argv at all — so the shared thing is the prompt, and it is the prompt that carries the behaviour.
Distinctions this skill nails down
| Frequent confusion | What is actually true |
| "installing the vendor skill" enables orchestration | No. The binary already carries the commands, so a machine without the stubs is still capable. The stubs are the loaded grammar, not a precondition. The gate is on the binary |
| a harness worktree equals an Orca worktree | No. The harness one lives inside the repo, invisible to the board and the phone, with no managed terminal. The Orca one has a card, terminals, a browser, and is reachable from the phone. To orchestrate: always the Orca one |
| a context-only injection leaves a supervised worker | No: deliberately unsupervised, and the release verb does not close it. Supervised = the native launch |
| a custom-argv terminal can be supervised | No. The runtime decides "is this an agent" from the argv IT launched, never from the running process, so adoption is refused on a terminal whose agent is alive on screen. Measured (references/gotchas.md G44). Supervision is the native launch or nothing |
| the terminal went idle, so the worker finished | No: idle means ready for input. Finished means worker_done. And the prompt line is ALWAYS drawn, so it cannot tell you either: the spinner line is the signal, and no spinner without worker_done means STALLED, not idle (G55) |
| a heartbeat is useful progress | No: it means "alive", and it wakes the conductor. Prohibited in the brief |
| the stop verb closes one terminal | No: its radius is the whole worktree |
| subagents and workers compete | No: the subagent reads and maps inside the turn; the worker executes a scope and persists |
terminal send is how you talk to a worker | No: it is how you DRIVE a worker's terminal. The message goes to the mailbox and anything long goes in a file; the terminal gets a one-line nudge at most, plus the launch handoff prompt, which is the one exception (hard rule 4) |
| the harness's agent-messaging tool reaches the conductor | Not from an isolated worktree; and a user-question prompt is seen by nobody. It can also PREFIX-MATCH a session in another repository and return success (G69) |
| a handoff is orchestration | No: it is ownership transfer. Orchestration is supervising, waiting and coordinating |
References
| File | What it holds |
references/coordinator-playbook.md | the full conductor cycle, roster and run files, board card, waiting and acking, liveness sweep, closing, conductor-only operations, conductor→conductor handoff, cross-session memory |
references/channel-discipline.md | which verb carries what (mailbox · file plus pointer · terminal send), the one structural exception, what terminal send is genuinely excellent at, and how to read a send result |
references/worker-contract.md | what a worker must and must not do, what the brief has to say, the report protocol |
references/claims-protocol.md | claims over shared fixtures, data and credentials: entities, intents, message shapes, ledger, disputes, non-runtime fallback |
references/topologies.md | topology per repo activity, "when a worktree", git rules per topology |
references/provisioning.md | what a fresh worktree of THIS repo lacks, how to repair it, the provisioning script, the setup hook |
references/brief-template.md | the fleet extension of the 7-component briefing, plus the two templates |
references/standby-report-contract.md | what a session emits when it STOPS: the six parts, the closed blocker vocabulary, the three envelopes, and why it is not a progress table or a heartbeat. Read when a session goes to standby or reaches a final status |
references/gotchas.md | every measured gotcha with symptom, fix, date and the version it was verified against, plus the vendor guide's known lies |
references/automations.md | unattended routines: "the dispatcher never produces", run discipline (lock, worker cap, empty run, report as you go, deployed environment over tracker status), recipes, the frozen-prompt trap, cost per wake-up |
references/launch-seam.md | how a workflow skill writes its launch file and its gated lines, and what it must never do |
references/html-surfaces.md | opening a generated page (coverage map, report, deck) in a worktree-bound browser tab instead of the system browser: the gate, the two routes, the clipboard dead end, the split-state rule |
references/orca-machine-setup.md | the one-time per-machine checklist (not versionable) |
references/session-identity.md | session identity per harness, the label rule, where it is injected, the commit trailers |
templates/run.md · templates/roster.md · templates/launch.txt · templates/COMMON.md · templates/W-brief.md | the files a Run is made of |
Related repo doctrine: agentic-qa-core/references/orchestration-doctrine.md (AGENTS.md §3 mirror), agentic-qa-core/references/briefing-template.md (the 7 components), agentic-qa-core/references/dispatch-patterns.md (when a subagent is the right executor), git-flow-master/references/worktrees.md (worktree mechanics and cleanup).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

