agentleFS
upex-galaxyupex-galaxy/agentic-qa-boilerplate/.agents/skills/orca-orchestration/SKILL.md

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

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
  1. Distinctive:

    Run the gate. State A or B → say the one line below and continue on the fallback.

    line 69
  2. Very specific:

    Create the scope .session/orchestration/<slug>/, seed run.md, roster.md, COMMON.md, launch.txt from templates/.

    line 72
  3. Very specific:

    Run the cycle in references/coordinator-playbook.md §1, in that order: Run → Tasks → placement → NATIVE launch → verify readiness and …

    line 73
  4. Distinctive:

    Wait inside the turn, one waiter, rolling windows of at most 540 s, ack verified in the same command that re-arms.

    line 74
  5. Very specific:

    A base-ref flag resolves LOCAL refs: verify the new worktree's SHA against the remote base, with no || true to hide the failure.

    line 198

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

SituationUse instead
a read, a verification, a map — anything that fits in this turnone-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 siblingsjust do the task

Quick start (conductor)

  1. Run the gate. State A or B → say the one line below and continue on the fallback.
  2. Load every skill in orchestration.orchestrator_skills now, 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.
  3. 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).
  4. Create the scope .session/orchestration/<slug>/, seed run.md, roster.md, COMMON.md, launch.txt from templates/.
  5. 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.
  6. Wait inside the turn, one waiter, rolling windows of at most 540 s, ack verified in the same command that re-arms.
  7. Close each finished worker AND its worktree in the same turn: orphan audit first, then remove (references/coordinator-playbook.md §6).
  8. Harvest learnings.md and skill-improvements.md, write kickoff.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 · phone

Composition 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.

StateIn a workflow skill (sprint-testing, test-automation, …)In this skill
A · no binarytotal 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 stopsone line, and only because the user ASKED for orchestration (see the exact text below), then continue on the fallback
B · binary, runtime unreachablesilence (same fallback). /sprint-conductor opens the app once and re-checks once, as this skill does; still unreachable → its state-A lineorca open --json once, re-check once; still unreachable → treat as state A
C · readythe 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 tokensfull 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.txt with 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)
Livesinside the turnuntil you close it
Contextlost when it reportspersists; you keep talking to it
Channelnone until it finishes; cannot be pausedmessages, blocking questions and replies at any time
Owner sees itnoyes: board, terminal, phone
Gitthe orchestrator'sits own (worktree) or shared under explicit file ownership
Best forreading, verifying, mapping; the 7-component briefingwriting 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

ModeWhoLoadsDoes NOT load
CONDUCTORthe session talking to the ownerthis 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 onenothing else; its reads go through subagents
WORKEReach launched sessionorchestration.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
AUTOMATIONan unattended scheduled routinereferences/automations.md + this SKILL.md in conductor modeanything that produces output: the dispatcher never produces
OWNERthe user, by chat or phonethe phrasebook below

Decision tree: is this even orchestration?

  1. Does the work fit in this turn, and is it a read / verification / map? → one-shot subagent. Stop here. This is most work.
  2. 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-cli guide; 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.
  3. Do you need to supervise, wait for results, answer questions, or coordinate a dependency graph? → orchestration. Continue.
  4. Does the work write code? → one Orca worktree per worker. Does it not? → fleet in the same checkout. See references/topologies.md.
  5. 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.worker and fixes a mismatch before dispatching work (hard rule 5); credentials reach the worker through a provisioned .env, which every MCP server reads through the .env loader (references/orca-machine-setup.md §3).
  6. 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 saysThe conductor doesNotes
"how are they doing?" / "fleet status"task list (brief) + worker list + the cross-worktree summaryanswer 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 turnshard 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 backupthe screen is backup, never the channel
"tell it yes"reply to that message idthe id comes from the pending batch
"launch another worker for …"task-create → placement → native launch → verify on screen → send the promptone indivisible operation (see the playbook)
"pause / interrupt X"send an interrupt into its terminal, then verify on the rendered screenthere 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 tabnever 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 tasksa 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

  1. A finished worker is closed in the same turn. Live worktrees left open have taken the runtime down (G31).
  2. Provision the worktree BEFORE launching (references/provisioning.md). Provisioning gaps disguise themselves as other failures.
  3. 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).
  4. 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 send is 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 through terminal 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 through terminal send"; it is no conversation through terminal send. Full discipline, plus what the verb is genuinely excellent at: references/channel-discipline.md.
  5. Launch each tier in the permission mode orchestration.permission_modes declares, never an edits-only mode. The defaults decided in .context/ADR/ADR-0024-agentic-work-profile-and-permission-posture.md are conductor auto, worker bypass, subagent inherit, translated per harness in ONE table (references/orca-machine-setup.md §3.1). auto is 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 to bypass. 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).
  6. 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.
  7. 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.
  8. The stop verb has worktree radius: count first. To close one terminal, close that terminal (and its tab).
  9. A base-ref flag resolves LOCAL refs: verify the new worktree's SHA against the remote base, with no || true to hide the failure.
  10. 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.
  11. Text typed into a terminal and not sent is not an instruction.
  12. One dev server and one browser per worktree; close every browser-automation session before reporting (orphaned headless browsers, measured: G37).
  13. Critical Rule #15 counts double in a same-checkout fleet: no global discards, another session shares the tree.
  14. 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.
  15. 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_done is 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.
  16. "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.
  17. 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), a terminal send that delivered a tail fragment (G60, G64), an orchestration send whose receipt carried "delivered_at": null, "read": 0 in the same payload that proved acceptance (G67), and a dispatch still reading dispatched while 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.
  18. ok: false on a terminal send means 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.
  19. 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.
  20. 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.
  21. 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.
  22. 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.
  23. 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.
  24. 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 (blocking ask, escalation, or BLOCKED: status on the unsupervised path): no user-question prompt, no structured-question tool, no mkd deck, 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.md rule 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:

KeyApplied
{{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_modesa 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_overridesa 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:

StepFallback
planidentical: same topology decision, same triage-time collision check, same rounds
briefidentical: COMMON.md + W-<label>.md in the scope, cited by absolute path
launchthe 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
identityClaude 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
statethe workflow's own blocked-state tokens plus the tracker, exactly as a single session already does
questionsthe worker writes the question in its report with options and a recommendation, and keeps going on what does not depend on the answer
closethe human closes the terminals
claimsthe 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 confusionWhat is actually true
"installing the vendor skill" enables orchestrationNo. 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 worktreeNo. 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 workerNo: deliberately unsupervised, and the release verb does not close it. Supervised = the native launch
a custom-argv terminal can be supervisedNo. 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 finishedNo: 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 progressNo: it means "alive", and it wakes the conductor. Prohibited in the brief
the stop verb closes one terminalNo: its radius is the whole worktree
subagents and workers competeNo: the subagent reads and maps inside the turn; the worker executes a scope and persists
terminal send is how you talk to a workerNo: 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 conductorNot 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 orchestrationNo: it is ownership transfer. Orchestration is supervising, waiting and coordinating

References

FileWhat it holds
references/coordinator-playbook.mdthe 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.mdwhich 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.mdwhat a worker must and must not do, what the brief has to say, the report protocol
references/claims-protocol.mdclaims over shared fixtures, data and credentials: entities, intents, message shapes, ledger, disputes, non-runtime fallback
references/topologies.mdtopology per repo activity, "when a worktree", git rules per topology
references/provisioning.mdwhat a fresh worktree of THIS repo lacks, how to repair it, the provisioning script, the setup hook
references/brief-template.mdthe fleet extension of the 7-component briefing, plus the two templates
references/standby-report-contract.mdwhat 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.mdevery measured gotcha with symptom, fix, date and the version it was verified against, plus the vendor guide's known lies
references/automations.mdunattended 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.mdhow a workflow skill writes its launch file and its gated lines, and what it must never do
references/html-surfaces.mdopening 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.mdthe one-time per-machine checklist (not versionable)
references/session-identity.mdsession 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.mdthe 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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.