AGENTIC QA · ORCHESTRATION SKILL
Un conductor coordinando una flota de sesiones persistentes: una por historia, por módulo o por cluster de fallos.
El mapa completo · índice del deck
Paso 1 · es orquestación de verdad?
La doctrina del repo (AGENTS.md §3) no cambia: el subagente one-shot ejecuta casi todo. El worker supervisado es el segundo ejecutor, y solo cuando el trabajo no cabe en un turno.
No compiten. El conductor sigue usando subagentes para sus propias lecturas. Y la lección de coste del dogfood va en la misma dirección: lo caro fueron las lecturas de los subagentes del conductor, no el trabajo paralelo de los workers. Las cifras, con su fecha y su fuente, están en .context/ADR/ADR-0006-forensic-measurements-ledger.md.
Arquitectura · por qué este skill es corto
Regla de composición
Si la guía del binario ya lo dice, aquí va un puntero, no una copia. Una copia se desincroniza en silencio en el próximo release.
Consecuencia para el gate
Se evalúa sobre binario + runtime, nunca sobre "está instalado el skill del vendor?". Una máquina con binario y sin stubs es plenamente capaz.
Consecuencia para el coste
Los stubs de orchestration.orchestrator_skills son pequeños y SE CARGAN junto a esta skill, en el conductor y en el worker: saltárselos es lo que produce flags inventados. Al binario se le pide solo el tema profundo al que un stub apunta. La medición que lo decidió está en ADR-0006, no aquí.
Paso 2 · el gate de tres estados
| Estado | En un workflow skill (sprint-testing, test-automation…) | En este skill |
|---|---|---|
| A · sin binario | Silencio total. No se nombra, no se recomienda, no es prerequisito, no entra en el ATR ni en el barrido de tokens de bloqueo. El flujo escribe su launch file y el humano pega las líneas. La única excepción es /sprint-conductor, que corre solo sobre Orca: una línea y se detiene. | Una línea, y solo porque el usuario PIDIÓ orquestación; después se continúa por el fallback. |
| B · binario, runtime inalcanzable | Silencio (mismo fallback). /sprint-conductor abre la app una vez y re-chequea una vez; si sigue inalcanzable, su línea del estado A. | Un intento de abrir el runtime, un re-chequeo; si sigue inalcanzable se trata como estado A. |
| C · listo | El refuerzo se activa sin anunciarse: el runtime lanza los workers y les entrega el prompt idéntico, y ellos reportan al mailbox ADEMÁS de a los tokens de archivo. | Modo completo: conductor / worker / automation. |
El gotcha que hace fallar el gate
La bandera de alcanzabilidad está anidada en la salida JSON del binario. Un gate que busca un campo plano falla en cerrado y en silencio sobre una máquina perfectamente capaz. Verifica cualquier edición del gate corriendo las dos ramas.
Regla de plataforma (Linux)
Fuera de una terminal gestionada, en Linux el CLI se registra con otro nombre porque el binario de sistema homónimo es el lector de pantalla de GNOME. El hook aplica exactamente esa regla: señal de entorno primero, luego el nombre alternativo en Linux. Usa el mismo ejecutable para todos los comandos de la sesión.
Vocabulario compartido · sin esto los reportes no se leen
| conductor | la sesión que habla con el owner y coordina |
| worker | una sesión lanzada, con un scope propio |
| fleet | todos los workers de un Run |
| round | un grupo de concurrencia: hasta el tope de workers en vuelo a la vez |
| wave | un bucket de estado del tracker, y existe solo en sprint-testing |
| roster | una fila por worker: label · KEY · ids · terminal · worktree · agente · modelo · estado |
| brief | el archivo que define el scope de un worker, citado por ruta absoluta |
| claim | la reserva de un fixture, una credencial o un registro compartido |
La regla que evita reportes ilegibles
Los rounds se numeran dentro de una wave: "Wave 1, round 2". Nunca se reutiliza "wave" para concurrencia.
Defaults, no política
El bloque orchestration de .agents/project.yaml lleva el tope de workers, el agente, el modelo y el nivel de esfuerzo por defecto. Una instrucción explícita del usuario en la sesión conductora SIEMPRE los pisa para ese run. Los defaults aplican solo cuando el usuario no dijo nada.
Quién carga qué · y cómo se invoca en los tres hosts
| Modo | Quién | Carga | No carga |
|---|---|---|---|
| CONDUCTOR | la sesión que habla con el owner | este SKILL.md + references/coordinator-playbook.md + cada stub de orchestration.orchestrator_skills, de entrada; un tema profundo del binario solo cuando un stub apunta a él | nada más: sus lecturas van por subagentes |
| WORKER | cada sesión lanzada | los stubs de orchestration.orchestrator_skills + references/worker-contract.md + references/channel-discipline.md + su skill de dominio (/sprint-testing, /test-automation…) | nada más: el preámbulo inyectado lleva el resto de su contrato |
| AUTOMATION | una rutina programada, sin nadie al volante | references/automations.md + este SKILL.md en modo conductor | todo lo que produce: el dispatcher nunca produce. Además toma el lock de la rutina antes de nada (lock.json, sin esperar ni encolar), abre como mucho orchestration.max_workers workers en una ronda, y una corrida vacía es un resultado válido (references/automations.md) |
| OWNER | el usuario, por chat o desde el móvil | el phrasebook |
Invocación en los tres hosts
Claude Code: /orca-orchestration, o una frase como "orquesta esto" o "lanza workers".
OpenCode y Codex: no hay slash commands; se pide en prosa: "carga la skill orca-orchestration". No hay token de modo que escribir: la sesión que habla con el owner es el CONDUCTOR.
Cómo entra un worker
El modo WORKER se activa cuando un brief nombra esta skill. Su prompt abre con /<workflow-skill> <KEY> fleet worker: ese token le dice a la skill de dominio que corre en flota y, en Claude Code, al hook de identidad cómo titular la sesión.
Pasos 3-12 · el ciclo, en ese orden
El paso 5 es el que más incidentes produjo: crear + lanzar + entregar el brief es una operación indivisible. Un worker quedó ocioso durante horas porque el brief nunca llegó (G32).
Paso 7 · el lanzamiento, y la distinción que costó un run entero
Native path · el default supervisado
El verbo worker-start con task, worktree, agente, modelo y nivel de esfuerzo. El runtime lanza al agente, así que lo reconoce y lo supervisa.
El spec de la task ya llega como primer prompt (G58), así que se basta solo. El prompt que se envía después de verificar la pantalla debe empezar por /<workflow-skill> <KEY> fleet worker …, para que el hook de identidad pueda titular la sesión; después va el puntero al brief y la frase de continuidad, y el prompt cierra con una última frase ROUTE-SCOPE: que nombra los ids de sección de instrucciones que el trabajo necesita (o none).
Credenciales sin argv: cada MCP, en cualquier harness, lee el .env del propio worktree a través del loader de .env de las configs MCP. Ningún secreto se exporta al shell del worker: los scripts de Bun leen el .env con su propio autoload y acli usa su login guardado. El conductor verifica las credenciales en la pantalla del worker antes de despacharle trabajo.
Custom argv · siempre sin supervisión
Una terminal creada con una línea de comando propia nunca queda supervisada: el runtime solo reconoce a los agentes que él lanzó, y rechaza la adopción aunque el agente esté vivo en pantalla (G44).
Le queda un rol, y es legítimo: la línea autocontenida y byte-idéntica del launch.txt que un humano pega en su propia terminal. El prefijo de variables de entorno tampoco sobrevive a esa vía.
Por eso la detección de "modo worker" no vive en variables de entorno, sino en el prompt (el token fleet worker) más los campos del brief.
Prometer las dos cosas a la vez es lo que costó más caro. En el dogfood ningún terminal de argv propio fue adoptado, la flota entera corrió sin supervisión y el conductor lo pagó en empujones manuales, uno por cada worker parado en cada límite de stage.
Paso 7 · el brief
Qué lleva encima de los 7 componentes
Por qué archivo y no mensaje
Todo lo que pase de un par de frases va en un archivo con un puntero de una línea: se relee después, cosa que un mensaje no permite, y por terminal send llegaría truncado. Se cita por ruta absoluta al checkout primario, y nunca en un directorio temporal del sistema: eso dispara un prompt de permisos que nadie está mirando.
Una sola frase, y es la más importante
"No vuelvas al prompt hasta enviar worker_done; los límites de stage no son checkpoints."
Va en el prompt de lanzamiento, no solo en el brief. La frase funciona como instrucción y falla como puntero a archivo: en una flota real, workers con un brief que decía "sin checkpoints" se detuvieron igual en un límite de stage con trabajo pendiente (G58).
El worker · tres mensajes y ni uno más
| Mensaje | Cuándo | Regla |
|---|---|---|
| worker_done | una sola vez, al terminar todo su scope | Lleva el resultado, los archivos modificados y la ruta del reporte. Después: parar. |
| ask | bloqueante, cuando la respuesta condiciona el trabajo | Se sigue con lo que no dependa de la respuesta. Si expira, se reanuda por id. |
| escalation | bloqueo real | Por la vía sin supervisión el runtime la rechaza: ahí el bloqueo va como mensaje de estado con el asunto prefijado BLOCKED: |
| heartbeat | nunca | Solo dice "estoy vivo" y despierta al conductor. Prohibido explícitamente en el brief, porque contradice el preámbulo que inyecta el runtime. |
El trigger de ask que salvó el dogfood
Cuando tu propia medición contradice una instrucción del conductor: PARA y pregunta, con las dos lecturas y la evidencia. Nunca cumplas en silencio, nunca te desvíes en silencio.
Un worker lo hizo por criterio propio y es la razón de que el reporte del run no esté equivocado. Ahora es doctrina, no suerte.
El canal, y lo que no es canal
Todo lo que el worker debe hacia arriba (estado, ask, worker_done, un bloqueo) va por el mailbox, que llega intacto; lo largo va en su archivo de reporte con un puntero. Nunca reporta con terminal send: trunca y no puede verificar el destino. La pantalla renderizada es respaldo para ver qué hace un worker, nunca el canal.
Hard rule 4 · el canal es una asignación, no una preferencia
| Canal | Qué lleva | Integridad |
|---|---|---|
| orchestration send (el mailbox) | Todo mensaje entre sesiones: estado, preguntas, respuestas, decisiones, escalations. | Intacto byte a byte (G66) |
| un archivo + un puntero de una línea | Todo lo que pase de un par de frases: briefs, reportes, acuerdos de scope, evidencia, cualquier tabla. | perfecta, y se relee después |
| terminal send | Manejar una terminal: comandos, llamadas a CLI, slash commands del harness, teclas. | Con pérdida: trunca en silencio, conserva solo la COLA y reporta éxito igual (G60, G64) |
La prueba
Si lo va a LEER un humano, no va por terminal send. Si lo va a EJECUTAR un shell o una TUI, para eso está el verbo.
La única excepción
El primer prompt de un worker supervisado va por terminal send, porque el lanzamiento nativo no tiene argv. Corto, y apuntando a un archivo. La regla es ninguna conversación por terminal send.
El empujón no es el mensaje
El correo no llega a un worker ocupado entre turnos y reporta éxito igual (G46). Por eso existe el empujón de una línea por terminal send: "revisa tu mailbox: <asunto>". El mensaje sigue en el mailbox.
Paso 6 · fixtures, datos y credenciales compartidos
| Entidad | Por qué colisiona |
|---|---|
| user | dos workers logueados con la misma cuenta se invalidan la sesión |
| fixture | uno mutando el dataset sobre el que otro está aseverando |
| record | la lectura sucia clásica entre dos sesiones |
| credential | un refresh rota el token que el otro tiene en la mano |
| env-resource | una feature flag cambiada para uno altera lo esperado del otro |
| tracker-artifact | dos escritores sobre una descripción se sobrescriben entero |
Tres intents
read · write · enumerate. El tercero es el aprendizaje del dogfood: un endpoint de colección sobre una cuenta compartida expone las entidades de los hermanos. Eso nunca es un target de aserción, y se reclama como enumerate para que el conductor lo sepa.
Cuándo se espera y cuándo no
Los claims listados en el brief están pre-declarados y pre-concedidos por el conductor al lanzar: el worker no espera. Solo los claims nuevos, descubiertos en marcha, esperan el grant.
Arbitraje y ledger
Gana el primer mensaje. El conductor lleva claims.md y decide las disputas raras. Todo se libera con el worker_done. Sin runtime: el mismo ledger, append-only, con un grep antes de escribir y rounds más pequeños.
Pasos 8-9 · esperar sin construir un monitor
Cómo se espera
Cómo se distingue atascado de ocioso
stalled = no hay línea de spinner en pantalla y no llegó el worker_done. Eso es atascado, no ocioso, y pide un empujón.
idle = listo para recibir input después del worker_done. Eso es terminado.
La caja del prompt se dibuja siempre: verla no significa nada. La señal es el spinner con su contador de tiempo y tokens encima de la caja.
Y si el runtime avisa de que un prompt quedó atascado mientras el worker está a mitad de turno: ya quedó en cola. No lo reenvíes.
Paso 3 · la topología sale de lo que el trabajo ESCRIBE
| Actividad | Topología | Regla de git |
|---|---|---|
| /sprint-testing sprint-wide | Mismo checkout, una terminal por historia. El trabajo es QA manual: escribe en el tracker, no en el código. | Añadir y commitear por rutas explícitas, releer antes de editar, reintentar si el índice está tomado. |
| /shift-left-testing batch | Mismo checkout, un worker por historia: la salida son criterios refinados y un plan de pruebas temprano. | Solo el tracker. |
| /test-automation batch | Híbrido por componente: un worktree por worker, un worker por módulo, dueño de tests/components/<módulo>/. Las historias que comparten módulo van secuenciales dentro de ese worker. Nunca dos workers en el mismo módulo. | Rama y PR propios. El conductor regenera el manifest de componentes al integrar cada rama. |
| /framework-development | Mismo checkout con file ownership por worker, o un worktree por wave. | Igual que sprint-wide si comparten checkout. |
| /regression-testing | Un worktree por cluster de fallos. | Fetch, verificar el SHA del worktree nuevo contra la base remota, merge aditivo. |
| /project-discovery · /project-context | Subagentes. No es una flota: son lecturas. | Ninguna. |
La regla "cuándo un worktree?"
Un worktree cuando dos workers escribirían el mismo archivo de código. Mismo checkout cuando escriben en sistemas distintos (el tracker, artefactos distintos) y se puede declarar file ownership.
El gotcha que se pagó dos veces
La bandera de referencia base resuelve refs locales. Verifica el SHA del worktree nuevo contra la base remota, y sin un || true que esconda el fallo.
Paso 5 · antes de lanzar, no después
Lo que está commiteado viaja solo (la configuración de MCP de los tres harnesses, el hook, las skills T1). Lo que está gitignoreado no viaja, y cada hueco se disfraza de otro fallo. La tabla es lo que cierra bun run worktree:provision; su --dry-run imprime qué haría sin tocar nada.
| Hueco | Cómo se cierra |
|---|---|
| .env, .claude/settings.local.json, .auth/ | se copian del primario, los secretos en modo 0600 |
| alias .claude/skills | bun run agents:compat dentro del destino |
| skills T3 (community) | se copian desde el checkout primario |
| node_modules | bun install --frozen-lockfile |
| api/openapi.json | se copia del primario (o bun run api:sync): sin él, el MCP de OpenAPI muere al arrancar y parece una herramienta rota |
| .context/PBI/ | bun run context:hydrate, o una sync por issue nombrada en el brief: decisión humana |
| .session/ | no se copia nunca: se cita por ruta absoluta al primario |
Un solo comando, y la misma lista en dos sitios
bun run worktree:provision hace todos los pasos de la tabla, se niega a correr sobre el checkout primario y sale con código distinto de cero ante cualquier fallo duro. El .worktreeinclude commiteado nombra los mismos archivos para los worktrees que crean Claude Code y la app de Codex, y un test mantiene iguales las dos listas.
Credenciales: el archivo no basta
El worktree necesita su propio .env, que los MCP leen a través del loader y los scripts de Bun con su propio autoload, y tras cada cambio se reinicia la sesión del agente. El conductor lo confirma en la pantalla del worker.
Dos límites físicos
Un dev server y un browser por worktree, y toda sesión de automatización de browser se cierra antes de reportar: los browsers headless huérfanos llegaron a correr durante horas sin que la flota lo notara (G37).
Hooks commiteados · y lo que muere con un worktree
Lo que todavía decide cada máquina
El prompt de confianza la primera vez que corre cada hook. La política de origen de los hooks del repositorio: si es solo-local, orca.yaml se ignora y manda el script puesto en la UI. Y el CLI salta el hook de archive salvo con --run-hooks. Donde los hooks no corren, los mismos dos comandos van a mano.
| Clase | Qué es, según AUDIT_RULES |
|---|---|
| STATE | .session/, .scratch/, la evidencia y las notas [LOCAL] del PBI, .context/reports/, el estado del updater. --rescue lo copia a la misma ruta del primario, sin sobrescribir. |
| CACHE | vuelve con el comando que la regla nombra. |
| DISPOSABLE | se puede perder; las salidas de corridas de test, por decisión del owner, nunca se rescatan. |
| UNKNOWN | no matcheó ninguna regla: se decide a mano, igual que un CONFLICT. |
El hook avisa en el propio worktree
Sin .env, el hook inyecta una línea CREDENTIALS:. En un worktree vinculado sin node_modules/ o sin .husky/_, una línea WORKTREE:: los git hooks no corren ahí y Claude Code puede no ver las skills del repo. La salida es la misma: provisionar y reiniciar la sesión.
Quién hizo qué · identidad y trazas
Un emisor, tres adaptadores
El hook de .agents/hooks/personality-reinject.mjs calcula la identidad una vez por prompt y la inyecta en el contexto. La segunda línea aparece solo cuando el binario está presente; sin él, silencio. Como mucho se suma un aviso de setup (CREDENTIALS: o WORKTREE:).
La regla del label
Nombre puesto por el usuario → ese nombre. Nombre derivado o automático → nombre (id corto). Solo id → el id completo. Nada → unknown.
Los trailers forenses
Cada commit termina con Worktree: y Session:. Son forense, no atribución: no hay atribución de IA en los commits, ni trailers con marca del harness. Canon: /git-flow-master.
Por la vía native, en Claude Code el hook titula la sesión desde el prompt, y por eso el prompt empieza por /<workflow-skill> <KEY> fleet worker …. En OpenCode y Codex ningún hook puede ponerle nombre: el conductor teclea /rename <KEY> en la terminal del worker cuando lo ve listo. Un worker no puede renombrarse solo, así que el brief nunca se lo pide.
Las reglas duras · cada una se pagó con un incidente
Y una que no es del skill
Los commits del worker llevan cero atribución de IA (Critical Rule #3) y los dos trailers forenses. En un fleet de mismo checkout, la Critical Rule #15 (nada de descartes globales de git) cuenta doble.
La que se descubrió cerrando
El coste de un worker solo es visible en su propia pantalla y desaparece cuando el conductor cierra la terminal. Si quieres contabilidad de coste, leer el footer es parte del ritual de cierre. En el dogfood se perdieron los números de un worker por cerrarlo correcta y puntualmente.
Hard rules 17-19 · cómo verifica un conductor
Un recibo verde es el verde más peligroso, porque suprime justo el chequeo que habría encontrado el fallo. Se lee la pantalla, el mailbox o la fila: en el destino, nunca en quien llamó (AGENTS.md, Critical Rule #16).
| Lo que reportó éxito | Dónde se verifica |
|---|---|
| una línea de lanzamiento | la pantalla: el comando pudo morir en el shell (G11) |
| un terminal send | la pantalla: pudo llegar solo la cola (G60, G64) |
| un orchestration send | la respuesta del destinatario: el recibo puede traer "delivered_at": null (G67) |
| un dispatch en dispatched | la terminal: pudo haber sido reemplazada (G68) |
| el brief entregado | un status del árbol de trabajo unos minutos después |
| un worker listo | sus credenciales, en su propia pantalla |
| un worker terminado | la integración: git cherry, el PR, el estado en el tracker, antes de cerrar |
ok: false = un humano está tecleando
En un terminal send es el runtime protegiendo la caja de input de una persona. Nunca se reintenta: el reintento mezcla tus teclas con las suyas. Se espera y se lee la pantalla (G65).
A mitad de frase = truncado
Lo que se pierde es la cabeza, así que el daño parece un typo y nadie busca el resto. Se pide el puntero; nunca se responde al fragmento ni se reconstruye lo que creías que decía (G64).
Hard rules 20-23 · quién habla, quién decide, qué se reporta
Firma con handle y Run
Un brief, un reporte o una semilla nombra a su autor por el handle de terminal (ORCA_TERMINAL_HANDLE, que está en el entorno y no es un autorreporte) más el id del Run. Un nombre puede no resolver a nada, resolver solo a sí mismo o hacer prefix-match con otra sesión de otro repositorio y devolver éxito (G69, G70).
El que recibe verifica al que envía
El canal no lleva identidad. Si el payload no identifica al remitente, el receptor pregunta en vez de inferirlo del contexto. Duele más en una respuesta: contestar a un autor supuesto es cómo un acuerdo de scope de un repo terminó en una sesión de otro.
El conductor decide el scope; el worker, la ejecución
Es radio de impacto, no jerarquía. Lo que ensancha el brief (otro dueño de archivo, otro ticket, otra rama, un fixture compartido) para y escala. Y al revés: un brief tan estrecho que el worker tiene que ensancharlo para terminar es un defecto del conductor.
Un reporte es un CONTEO
"Casi listo" no es un estado. Cada reporte abre con números: cuántos pasan, cuántos faltan, cuántos están bloqueados y por quién. El reporte de standby (references/standby-report-contract.md) tiene seis partes: veredicto de una línea, tabla de métricas, detalle con bloqueador de vocabulario cerrado y quién lo desbloquea, causa raíz, opciones y el negativo explícito.
Estado A y B · el fallback, completo
| Paso | Fallback |
|---|---|
| plan | Idéntico: misma decisión de topología, mismo chequeo de colisiones en triage, mismos rounds. |
| brief | Idéntico: COMMON.md + W-<label>.md en el scope, citados por ruta absoluta. |
| launch | El conductor imprime launch.txt y el humano abre N terminales y pega N líneas. Es la ÚNICA vía donde la línea misma es el payload, y por eso el archivo se escribe sin condiciones. |
| identidad | La bandera de nombre de la propia línea titula la sesión; donde el harness no la tiene, el humano teclea /rename <KEY> cuando la sesión arranca (un worker no puede renombrarse solo). |
| estado | Los tokens de bloqueo del propio workflow más el tracker, exactamente como ya hace una sesión sola. |
| preguntas | El worker escribe la pregunta en su reporte, con opciones y una recomendación, y sigue con lo que no dependa de la respuesta. |
| cierre | El humano cierra las terminales. |
| claims | El ledger degradado append-only (references/claims-protocol.md §6), con rounds más pequeños. |
Este camino es el contrato y el runtime es el atajo. Por eso el prompt es idéntico en los dos, desde su token de apertura hasta la frase de continuidad: el camino que nadie ejercita es el que se rompe en silencio. La línea de lanzamiento no pudo seguir compartida (un worker supervisado no tiene argv), así que lo compartido es el prompt, y es el prompt el que lleva el comportamiento.
Dogfood · un sprint real, varios workers en paralelo
Una instrucción del conductor, equivocada
Un worker se negó a cumplirla porque su propia medición decía lo contrario, y paró a preguntar. Una sesión secuencial habría tenido la misma derivación confiada y ningún segundo par de ojos, y habría enviado un bloqueo equivocado contra un release. De ahí sale la hard rule 16.
Un claim de la doctrina que ya era falso
Una afirmación obsoleta sobre los usuarios de prueba del proyecto, que habría debilitado cada ATR del sprint. La encontró un worker midiendo, no leyendo.
Un peligro entre workers
La lista de tokens de una cuenta compartida es visible para todos los que la usan. El vocabulario de claims no podía expresarlo: de ahí nace el intent enumerate.
Trazabilidad decorativa
Al cosechar, el conductor vio historias con links a sus tests en la dirección que el TMS no cuenta: la cobertura existía en el tracker y no se registraba en ningún lado.
Lo que no funcionó
La vía supervisada no funcionó en esa máquina: todo corrió por el fallback documentado y el conductor lo pagó en empujones manuales. De ahí sale el native path como default supervisado y el custom argv como pegado humano.
Dónde están las cifras
El deck enseña las lecciones, no los números. Duración, artefactos, hallazgos y coste del run están con su fecha y su fuente en .context/ADR/ADR-0006-forensic-measurements-ledger.md; los incidentes, por id G, en references/gotchas.md.
Cuándo NO usar este skill · tres cosas que se parecen
| Situación | Qué es en realidad | Usa |
|---|---|---|
| una lectura, una verificación, un mapa que cabe en este turno | la mayor parte del trabajo | subagentes one-shot (AGENTS.md §3) |
| darle una TAREA a otro agente y supervisarla | orquestación: Task, Dispatch, mailbox; el trabajo vuelve | /orca-orchestration |
| darle una TAREA a otro agente y olvidarse | un handoff: transferencia de dueño en una dirección, sin Task ni mailbox | la guía orca-cli del binario |
| pasar la SESIÓN entera a una nueva porque el contexto se llena | la misma sesión con una ventana nueva, en el mismo worktree y el mismo harness | /session-handoff |
La pregunta que decide
Necesitas supervisar, esperar resultados, responder preguntas o coordinar dependencias? Entonces es orquestación. Quieres soltar el trabajo y dejar de ocuparte? Es un handoff, y no lleva Run.
Tampoco es para
QA manual por ticket (/sprint-testing), escribir código de test (/test-automation), mecánica de rama, commit, push o PR, ni un git worktree sin flota (/git-flow-master).
references/html-surfaces.md · una línea con gate, como las demás
El mapa de cobertura de bun run tests:map, un reporte de Allure, estos decks o un deck de decisión: con el runtime listo se abren en una pestaña ligada al worktree, en la misma tarjeta del board y visible desde el móvil. Sin runtime se abren de la forma normal y no se dice nada: el navegador del sistema es el resultado normal, no uno degradado.
Dos rutas
Una URL file:// alcanza para una página que el owner solo LEE. Para una que el owner RESPONDE, una URL de loopback servida por la herramienta que la renderiza devuelve el resultado al agente sin copiar ni pegar.
El callejón sin salida
Leer el resultado del portapapeles no funciona: la página embebida no gana el foco del DOM, ni trayendo la pestaña al frente (G62). Por eso la ruta de loopback es la única que elimina el pegado manual.
Una sola copia
El storage del navegador es por origen: la misma página abierta en dos sitios guarda dos juegos de respuestas que nunca se juntan. Abre una, di cuál es la viva y cierra la otra. Antes de moverla, mira si ya tiene respuestas guardadas.
Para llevarte · cómo invocarlo y qué leer
Frases que lo activan
"orquesta esto", "lanza workers", "una sesión por historia", "paraleliza el sprint", "cómo va la flota", "comunícate con el worker de BK-123", "retoma el run de anoche", "automatización nocturna".
Frases que NO
Un subagente para una lectura de este turno (eso es AGENTS.md §3 y sigue siendo el default). Un handoff puro, sin supervisión. Pasar la sesión entera a otra (/session-handoff). QA por ticket (/sprint-testing). Código de test (/test-automation). Mecánica de git (/git-flow-master).
Sin el binario
Orquestación nivel 1 = subagentes en esta misma sesión. Orquestación profesional = el runtime instalado. El skill lo dice una vez, y solo si preguntaste.
Dónde está la profundidad
El SKILL.md es corto a propósito. El ciclo completo está en references/coordinator-playbook.md; cada tema tiene su propia reference, y la tabla References del SKILL.md es la lista.
Tres reglas de oro
1 El subagente sigue siendo el default: orquesta solo lo que no cabe en un turno. 2 Crear + lanzar + briefar es indivisible, y el cierre va en el mismo turno. 3 Sin runtime, silencio total en los workflow skills: el launch.txt se escribe igual.
Pruébalo: «orquesta el sprint 12 con tres workers» · ← → navegar · S presentador · O overview