/orca-orchestration coordina trabajo que no entra en una sola sesión: una sesión conductor habla con el dueño y reparte; cada worker es una sesión persistente que se queda con un alcance de punta a punta (una historia, un módulo, un racimo de bugs), reporta por un buzón y se puede interrumpir, consultar y retomar. La skill pone el CÓMO. El QUÉ sigue siendo de la skill de workflow que la llama.
Tres estados. En las skills de workflow, los que fallan son silencio total.
Se decide por lo que el trabajo ESCRIBE, no por cuántos workers hay.
Una sola operación indivisible, verificada en la pantalla del worker.
Integración verificada, costo leído, worker liberado, auditoría de huérfanos.
AGENTS.md §3 está siempre activo: la conversación principal es el centro de comando y el subagente de un solo uso es el ejecutor por defecto. Esta skill agrega un SEGUNDO ejecutor y declara la excepción por escrito, porque un worker supervisado rompe tres supuestos del contrato de un solo uso: un agente nuevo por despacho, ningún canal hasta que termina, y el orquestador como único que le pregunta al usuario.
| Subagente de un solo uso (default) | Worker supervisado (esta skill) | |
|---|---|---|
| Vive | Adentro del turno | Hasta que lo cierras |
| Contexto | Se pierde cuando reporta | Persiste; le sigues hablando |
| Canal | Ninguno hasta que termina; no se puede pausar | Mensajes, preguntas bloqueantes y respuestas en cualquier momento |
| El dueño lo ve | No | Sí: tablero, terminal, teléfono |
| Git | El del orquestador | Su propio worktree, o el checkout compartido con dueños de archivo explícitos |
| Sirve para | Leer, verificar, mapear | Escribir e integrar por su cuenta: una historia entera, trabajo largo |
Casi todo el trabajo no lo es. El árbol de decisión de la skill corta temprano.
Subagente de un solo uso. Fin. Esto es la mayoría del trabajo.
Eso es un handoff, transferencia de dueño: sin Task, sin Dispatch, sin buzón. Una tarea suelta va por la guía orca-cli del binario; la sesión entera, porque la ventana se llena, va por /session-handoff.
Orquestación. Sigue.
Un worktree de Orca por worker. No escribe código? Flota en el mismo checkout (references/topologies.md).
Lanzamiento nativo, y nada más: el runtime solo reconoce agentes que arrancó él. Si a la máquina le faltan los argumentos por defecto del agente o las credenciales no llegan al worker, la flota corre igual, sin supervisión, y se le avisa al dueño antes de lanzar.
references/automations.md. Para entrega desatendida, /autonomous-delivery decide qué corre y esta skill lo lanza.
| Situación | Se usa en cambio |
|---|---|
| Una historia, una sesión, sus etapas corridas por subagentes | /sprint-development en modo de un ticket. Una flota es su modo batch-sprint con más de un ejecutor |
| Decidir QUÉ puede trabajar una corrida desatendida | /autonomous-delivery: auditoría, selección, topes |
| Rama, commit, push, PR, o un git worktree sin flota | /git-flow-master |
| Una tarea larga, una sesión, sin hermanos | Hacer la tarea |
El gate mira el binario más un runtime alcanzable. Nunca mira si la skill del proveedor está instalada: una máquina con el binario y sin esas guías es igual de capaz, porque esta skill sabe pedirle la gramática al binario.
# el gate de SKILL.md: el flag de alcance está ANIDADO
command -v orca >/dev/null 2>&1 \
&& [ "$(orca status --json </dev/null 2>/dev/null | jq -r '.result.runtime.reachable' 2>/dev/null)" = "true" ]
| Estado | En una skill de workflow | En esta skill |
|---|---|---|
| A · sin binario | Silencio total. No se nombra, no se recomienda, no es prerequisito, no aparece en un PR ni en un plan. El flujo escribe su launch.txt y el humano pega las líneas | Una línea, y solo porque el usuario PIDIÓ orquestación; después, el fallback |
| B · binario, runtime inalcanzable | Silencio (el mismo fallback) | orca open --json una vez, se vuelve a chequear una vez; sigue sin responder, se trata como A |
| C · listo | El refuerzo se activa sin anunciarse: el runtime lanza los workers con el prompt idéntico, y reportan al buzón ADEMÁS de los tokens en archivo | Modo completo: conductor, worker, automatización |
Si la guía del binario ya lo dice, esta skill lleva un puntero. Una copia se desincroniza en silencio con la próxima versión.
CAPA 3 · DOCTRINA DEL REPO .agents/skills/orca-orchestration/ (T1, versionada) cuándo partir el trabajo · topología por actividad · provisión · brief · gotchas medidos · frases del dueño ^ apunta a v CAPA 2 · GRAMÁTICA + MÁQUINA orca skills get orchestration (buzón, Run, Task, ciclo del worker) orca skills get orca-cli (terminales, worktrees, tablero, navegador) la sirve EL BINARIO, versionada con él ^ opera sobre v CAPA 1 · APP la app corriendo · runtime alcanzable · tablero · teléfono
Los modos son roles, no subcomandos: cada sesión carga lo justo para el suyo.
| Modo | Quién | Carga |
|---|---|---|
| CONDUCTOR | La sesión que habla con el dueño | SKILL.md + references/coordinator-playbook.md + las guías del proveedor. Sus lecturas van por subagentes |
| WORKER | Cada sesión lanzada | Las guías del proveedor + worker-contract.md + channel-discipline.md + su skill de dominio (/sprint-development, /product-management) |
| AUTOMATION | Una rutina programada, desatendida | references/automations.md + esta skill en modo conductor. El despachador nunca produce: producen sus workers |
| OWNER | El dueño, por chat o desde el teléfono | Las frases de abajo; el conductor traduce |
Tres cosas, ninguna más: worker_done (una vez, con --outcome explícito), ask (bloqueante) y escalation.
Nada de heartbeats, aunque el preámbulo inyectado los pida: cada uno despierta al conductor para leer "vivo".
Nunca le pregunta al humano: ni herramienta de preguntas, ni deck de mkd, ni barrido. Errores, bloqueos y decisiones que no son suyas van a la sesión que lo lanzó, que se las pasa al humano. Excepción: el humano le escribió en su propia terminal, o el brief lo autoriza por escrito.
El alcance: el conductor decide alcance, el worker decide ejecución.
Lo que cambia el brief: un archivo nuevo, otro ticket, otra rama o un esquema compartido frena al worker y se escala.
Un PR por worker, que se detiene ahí, y un reporte largo escrito ANTES de worker_done, por ruta absoluta al checkout primario.
El reporte es un CONTEO, no una narración.
Sin binario y sin runtime el trabajo no cambia. Cambia quién lanza y cómo se lee el estado.
| Paso | Sin runtime |
|---|---|
| Plan | Idéntico: misma topología, mismo chequeo de colisiones, mismas rondas |
| Brief | Idéntico: COMMON.md + W-<label>.md, citados por ruta absoluta |
| Lanzar | El conductor imprime launch.txt; el humano abre las terminales y pega una línea en cada una |
| Identidad | En Claude Code la línea no lleva flag de nombre: el hook nombra la sesión desde el token del prompt. En Codex y OpenCode v2.2 el humano escribe /rename <label>--<handle> (solo <label> fuera de Orca) |
| Estado | Los tokens de bloqueo del workflow, más el tracker y git |
| Preguntas | En el reporte, con opciones y una recomendación; el worker sigue con lo que no depende de la respuesta |
| Cerrar | El humano cierra las terminales |
| Claims | El ledger degradado, solo de anexado, con rondas más chicas |
# una línea de launch.txt (Claude Code). El prompt entre comillas simples es el PAYLOAD: # idéntico, byte por byte, al que el camino supervisado manda al worker nativo. # Es el binario pelado: sus MCPs leen .env por el loader de .env. claude --model <full-model-id> --effort high --dangerously-skip-permissions \ '/<workflow-skill> <label> fleet worker. Read <ABS>/.../COMMON.md then <ABS>/.../W-<label>.md and execute your brief. Run every stage without returning to the prompt until worker_done is sent; stage boundaries are not checkpoints. Channel: orca orchestration. No heartbeats.'
La topología sale de lo que el trabajo escribe. Y un hueco de provisión nunca se anuncia como tal: se disfraza de otra falla, y el worker depura lo que no es durante una hora.
| Actividad | Topología |
|---|---|
| Batch-sprint de /sprint-development | Un worktree de Orca por worker, un worker por historia. Dos sesiones en un checkout chocan en el índice de git aunque nunca toquen el mismo archivo |
| Bugs independientes | Un worktree por RACIMO: tres bugs con una causa raíz son un worker |
| Refinamiento con /product-management | Flota en el MISMO checkout: escribe en Jira, no en código |
| Mapas, auditorías, investigación | No es flota: subagentes de un solo uso |
| Falta en el worktree | Cómo falla sin eso |
|---|---|
| .env | En silencio en todos los hosts: el servidor MCP arranca y muere en su primera llamada autenticada (Critical Rule #9) |
| node_modules/ y los shims de husky | Cannot find module, que se lee como un import roto; sin hooks, un commit se salta todos los gates |
| .context/PBI/ | En silencio: el worker no ve la historia sincronizada y trabaja con el título del ticket |
| .session/ | No se copia: el prompt cita rutas ABSOLUTAS al checkout primario (<<PRIMARY_ROOT>>). Lo escrito adentro de un worktree muere con él |
bun run worktree:provision [<ruta>] cierra los huecos reparables de una vez: copia lo gitignorado desde el primario (la lista es PROVISION_COPIES en cli/lib/worktree.ts), instala dependencias, corre bun run agents:compat y no copia .session/. Hidratar el cache del tracker queda para una decisión humana.
El repo commitea orca.yaml: scripts.setup provisiona cada worktree que Orca crea y scripts.archive corre bun run worktree:audit --rescue antes de borrarlo. Confianza y política de hooks se deciden por máquina, y el CLI salta el hook de archive por defecto: el conductor pasa --run-hooks al borrar, y sin hooks corre la auditoría a mano.
Ningún lanzamiento carga .env en el proceso del agente, con o sin línea de lanzamiento. Los servidores MCP no lo necesitan: en los tres harnesses cada uno lee el .env del worktree con el loader de .env; las CLIs (acli, supabase, vercel) usan su propio login y nada se exporta a la shell. El conductor confirma en pantalla antes de mandar trabajo.
Cambios sin commitear, commits sin integrar, bun run worktree:audit <wt> (STATE, CACHE, DISPOSABLE, UNKNOWN; exit 0 es el gate) y si alguien va a retomar esa sesión. Recién ahí se borra.
Un claim es un MENSAJE con un prefijo reservado en el asunto, y el conductor lleva el ledger. No hay comando de claim ni demonio de locks. Los archivos no se reclaman: sus choques se evitan al asignar dueños.
# .session/orchestration/<slug>/claims.md: del conductor, solo de anexado
[09:30] W1 record:orders@staging enumerate pre-granted -> no assertion on the collection
[09:41] W2 seed:checkout-cart write granted
[09:44] W3 seed:checkout-cart write denied -> seeds own cart
Vive en .agents/project.yaml y lo documenta .agents/README.md. Los valores se leen ahí; esta página no los repite.
orchestration: max_workers: # workers concurrentes por ronda {{MAX_WORKERS}} default_agent: # claude | codex | opencode {{DEFAULT_AGENT}} default_model: # modelo del worker, id completo {{DEFAULT_MODEL}} default_effort: # esfuerzo del worker {{DEFAULT_EFFORT}} conductor_model: # modelo del conductor, id completo {{CONDUCTOR_MODEL}} conductor_effort: # esfuerzo del conductor {{CONDUCTOR_EFFORT}} subagent_model: # sonnet | opus | haiku | fable {{SUBAGENT_MODEL}} permission_modes: # conductor auto · worker bypass · subagent inherit model_overrides: # modelo y esfuerzo por tema del brief orchestrator_name: # la app, como la nombra el operador orchestrator_cli: # el binario; vacío = no hay orquestador en esta máquina message_verb: # mensajes ENTRE sesiones, intactos terminal_verb: # comandos y teclas, NUNCA conversación orchestrator_skills: # guías del proveedor, cargadas AL LADO de esta skill
Una automatización corre un prompt versionado sobre un disparador tipo cron, sin humano. No produce ningún artefacto, ni un borrador ni un plan: crea al worker que produce y cierra su sesión. Ante algo ambiguo, lo reporta en vez de adivinar.
El roster.md del Run es lo que convierte "el de BK-123" en una task, un dispatch, una terminal y un worktree.
| El dueño dice | El conductor hace |
|---|---|
| "cómo van?" | Una tabla: KEY · etapa · estado · último mensaje |
| "decile al de BK-123 que…" | El MENSAJE va al buzón; a la terminal, como mucho, un aviso de una línea para que revise su correo |
| "pausa a X" | Una interrupción en su terminal, verificada en pantalla: no hay pausa nativa |
| "cierra a X" | Liberar por dispatch; sin dispatch, contar las terminales del worktree antes, porque el verbo de stop tiene radio de worktree entero |
| "retoma el run de anoche" | Atar esta sesión al Run id de run.md y listar tasks |
| "mergea la historia de W2" | Checks y review del PR, merge en orden de dependencias, deploy de staging verificado para ese SHA. Solo el conductor |
La lista completa está en "Hard rules" de la skill; las compactas viajan a los subagentes por .agents/skills/REGISTRY.md.
No tiene modos de invocación: el rol sale del contexto. Alcanza con nombrarla o con frases como "orquesta", "lanza workers", "una sesión por historia", "estado de la flota" o "retoma el run". En modo WORKER se carga sola cuando un brief la nombra.
La barra de la skill, sin argumentos.
Sin barra: nombras la skill en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
Cada skill de workflow es dueña de su QUÉ; esta pone el CÓMO, y el único lugar donde una skill de workflow menciona la orquestación es references/launch-seam.md.
Su modo batch-sprint con más de un ejecutor es la flota; el QUÉ vive en sprint-development/references/fleet-mode.md.
Decide qué corre (auditoría, selección, topes); esta skill lanza y cierra sus workers.
Pasa la sesión entera a su sucesor en el mismo worktree. Es un handoff, no orquestación.
Ramas, commits, PR, trailers y la mecánica de worktrees (git-flow-master/references/worktrees.md).