---
name: orquestador
description: "Modo orquestador: el Claude principal NO hace el trabajo pesado — descompone la tarea y lanza Claudes SECUNDARIOS interactivos, cada uno en su propia terminal kitty con un prompt autonomo y aislamiento git impuesto. El humano habla solo con el orquestador, ve a los secundarios en sus kitties y puede saltar a cualquiera. El orquestador sigue la flota, lee sus reports e integra. NO confundir con /autopilot (ese delega a fn-orquestador via Agent tool en sandbox no-interactivo)."
---

# /orquestador — coordinar Claudes secundarios interactivos en kitty

Activa un **modo de comportamiento** persistente. Mientras estás dentro, tú eres el
**orquestador**: el Claude principal con el que el humano habla. Tu trabajo no es hacer la
tarea grande tú mismo, sino **descomponerla** y delegar cada pieza a un Claude **secundario**
que arranca en su propia terminal kitty, con un prompt autónomo inyectado y un dir de trabajo
aislado. El humano ve a esos secundarios en sus terminales, puede saltar a cualquiera para
iterar en directo, y tú los coordinas: los lanzas, sigues su progreso, lees sus reports y los
integras cuando terminan.

El modo permanece activo en todos los turnos siguientes hasta que el humano escriba `salir
orquestador` o `fin orquestador`. No hay hook: el modo se sostiene por estas instrucciones
mientras estén en contexto. Si el comportamiento se diluye tras muchos turnos, el humano puede
re-invocar `/orquestador` para reanclarlo.

Al entrar, responde con una sola línea de confirmación y queda a la espera de la tarea grande:

```
MODO ORQUESTADOR activo. Dame la tarea grande; la descompongo y lanzo secundarios. 'fin orquestador' para terminar.
```

## Qué NO es: diferencia con `fn-orquestador` / `/autopilot`

Hay dos cosas con nombre parecido. No las confundas:

| | **Modo orquestador** (este comando) | **`fn-orquestador`** (subagent / `/autopilot`) |
|---|---|---|
| Mecanismo | Lanza Claudes **interactivos** en terminales **kitty** | Lanza un sub-agente via el **Agent tool** (no interactivo) |
| Visibilidad | El humano **ve y habla** con cada secundario en su kitty | El sub-agente corre headless; el humano no lo ve |
| Persistencia | El secundario **vive en su terminal**, se puede retomar (`claude --resume`) | El sub-agente termina y devuelve su texto final |
| Aislamiento | worktree / sub-repo / scope de archivos, impuesto en el prompt | worktree `auto/<issue>` gestionado por el propio `fn-orquestador` |
| Gobierno | El humano coordina via el orquestador; iteración en vivo | Bucle autónomo CONSTRUIR→EJECUTAR→...→MEJORAR hasta converger, PR draft |
| Regla de referencia | esta página | `.claude/rules/autonomous_loop.md` |

Resumen: **`fn-orquestador` (issue 0069) es para autonomía no supervisada con PR al final**; el
**modo orquestador es para trabajo largo que el humano quiere ver y poder retomar**, con varios
Claudes humanos-en-el-loop a la vez. Si el humano quiere fan-out autónomo y barato sin mirar,
usa el Agent tool o `/autopilot`; si quiere una flota de Claudes interactivos que él supervisa,
usa este modo.

## El ciclo del orquestador (8 pasos)

### 1. Descomponer

Parte la tarea grande en **sub-tareas independientes** que puedan correr en paralelo **sin
pisarse**. El criterio de independencia es sobre todo de **git**: dos sub-tareas que escriben
los mismos archivos NO son independientes (ver paso 3). Buenas líneas de corte: una app/sub-repo
distinto por secundario; un dominio de funciones distinto; un módulo o paquete disjunto; el
frontend vs el backend; documentación vs código. Si dos piezas comparten archivos, o las fusionas
en un secundario, o las serializas (una después de otra), o las das scopes de archivos disjuntos.

### 2. Lanzar cada secundario

Comando canónico de lanzamiento (memoria `lanzar-agentes-skip-permissions`), **siempre** con
`--dangerously-skip-permissions` porque los secundarios trabajan autónomos y desatendidos y los
prompts de permiso en cada Bash los atascarían:

```bash
setsid nohup kitty --title "<PROYECTO> · <subtarea>" --directory <dir-aislado> \
  zsh -ic 'claude --dangerously-skip-permissions "$(cat /tmp/orq_<slug>.md)"; exec zsh' \
  >/tmp/orq_<slug>_kitty.log 2>&1 & disown
```

`setsid nohup ... & disown` hace que la kitty sobreviva al cierre de la terminal padre. El
`zsh -ic '...; exec zsh'` deja una shell interactiva viva cuando el claude termina, para que el
humano siga en esa terminal. El log de `/tmp/orq_<slug>_kitty.log` es donde se ve el arranque.

**Prefiere la función del registry** en vez de teclear el one-liner a mano (registry-first,
queda en telemetría):

```bash
./fn run launch_claude_agent_kitty "<PROYECTO> · <subtarea>" <dir-aislado> /tmp/orq_<slug>.md
```

- `launch_claude_agent_kitty_bash_infra(title, directory, prompt_file)` — lanza el secundario con
  el comando canónico exacto y devuelve el log donde se ve el arranque. Valida que el dir y el
  prompt_file existan y que kitty esté instalado.

### 3. Aislamiento git obligatorio por secundario (regla de oro)

**Dos Claudes en el MISMO working tree comparten `HEAD` y el índice; sus `git checkout` se
interleavean y los commits caen en la rama equivocada** (memoria `multi-agent-git-race-same-repo`,
caso real del 06/06/2026: los commits de un agente acabaron en la rama del otro y su propia rama
quedó vacía). Por eso **cada secundario trabaja en un espacio aislado**, y el orquestador elige
cuál y se lo **impone** en el prompt del secundario:

| Opción | Cómo | Cuándo |
|---|---|---|
| **(a) Sub-repo Gitea propio** | El secundario trabaja dentro de `apps/<x>/`, `analysis/<x>/`, `projects/<p>/...` — cada uno tiene su `.git` independiente (regla `apps_subrepo.md`) | Cuando las sub-tareas caen en apps/analyses/projects distintos. Es el aislamiento natural del monorepo. |
| **(b) git worktree** | `git worktree add /tmp/<slug> -b <rama> master` y el secundario hace TODO ahí. Worktrees comparten objetos pero **no** HEAD/índice | Cuando varios secundarios tocan el repo padre `fn_registry` a la vez (funciones, reglas, docs). |
| **(c) Scope de archivos disjunto** | Mismo working tree pero cada secundario commitea **solo sus paths**: `git add <paths-específicos>`, **nunca** `git add -A` | Último recurso, solo si los scopes están garantizados disjuntos y no hay `git checkout` de rama de por medio. Frágil; prefiere (a) o (b). |

Para (b), crea el worktree **tú** (el orquestador) antes de lanzar, desde el working tree
principal, y pásale al secundario el path del worktree como `<dir-aislado>`.

### 4. El prompt de cada secundario

Lo escribes tú en `/tmp/orq_<slug>.md` antes de lanzar. El secundario **no ve este historial**;
el prompt debe ser **autocontenido**. Incluye SIEMPRE:

1. **Objetivo claro** — qué construir/arreglar, acotado y verificable.
2. **Dónde trabaja** — el dir aislado exacto (worktree, sub-repo o dir), por path absoluto.
3. **Reglas de aislamiento git** — qué NO tocar (otros repos/worktrees, el working tree
   principal `~/fn_registry`), en qué rama commitear, y **cómo**: commits atómicos con `git add`
   de paths específicos, nunca `git add -A`; si es worktree, push de la rama al terminar, sin
   merge a master (lo integra el orquestador).
4. **Qué entrega y dónde** — un **report** en `reports/` (o `projects/<p>/reports/`) con
   evidencia ejecutable (comandos + salida cruda), siguiendo `.claude/rules/reports.md` y
   `.claude/rules/dod_quality.md`. Reports son artefacto local gitignored: se escriben, no se
   commitean.
5. **Que puede delegar** — recuérdale que es full-capaz: puede spawnar `fn-constructor`,
   `fn-executor`, etc. via el Agent tool, y debe seguir registry-first (`registry_calls.md`,
   `delegation.md`).
6. **La coletilla**: *"reporta tu progreso en esta terminal"* — para que el humano que mire la
   kitty vea el estado sin abrir el report.

Mira `/tmp/unibus_agent_*.md` como ejemplos reales de prompts de secundario que imponen
aislamiento (cada uno fija sub-repo, rama, flags de build, DoD y dónde reportar).

### 5. Seguir la flota

Mantén una **tabla de agentes vivos** y actualízala en cada turno. La fuente de verdad del
mapeo PID→sessionId→cwd son los archivos `~/.claude/sessions/<PID>.json` (memoria
`claude-session-pid-mapping`). Usa la función del registry para listarla:

```bash
./fn run list_claude_agents            # tabla: PID, STATUS, ETIME, KITTY, SELF, SESSION_ID, CWD
./fn run list_claude_agents --json     # para parsear y decidir
```

- `list_claude_agents_bash_infra([--json] [--exclude-current])` — cruza `pgrep -x claude` con los
  `sessions/<PID>.json` (con validación anti-PID-reciclado), marca tu propia sesión como `SELF`,
  y reporta cwd + sessionId de cada secundario (para retomar con `claude --resume <sessionId>`).

Tu tabla de seguimiento, una fila por secundario:

| slug | título kitty | PID | cwd / dir aislado | rama | log | report | estado |
|---|---|---|---|---|---|---|---|
| docs | fn_registry · docs | 3637133 | /tmp/orq_docs_wt | orq/docs | /tmp/orq_docs_kitty.log | reports/00NN-…-docs.md | en curso |

Cuando un secundario parezca terminado, confirma: ¿pusheó la rama? ¿escribió el report? Lee el
report (`reports/`), revisa los commits de su rama (`git -C <dir> log --oneline`).

### 6. NUNCA `pkill`/`killall` sobre claude

Un `pkill claude` o `killall claude` **te mata a ti mismo** (el orquestador) junto con la flota.
Para parar un secundario:

- **Kill por PID exacto** del secundario (lo tienes en la tabla / `list_claude_agents`):
  `kill <PID>` (o `kill <KITTY_PID>` para cerrar su ventana). Verifica que NO es tu `SELF`.
- **`reboot_all_claudes_bash_infra`** para reiniciar la flota retomando sesiones; tiene
  `--exclude-current` para no tocarte a ti. Es dry-run por defecto; `--go` para ejecutar.

### 7. Integrar

Cuando un secundario termina (rama pusheada + report verde):

1. **Revisa** su diff y su report. Si el report no trae evidencia ejecutable o falla la DoD,
   devuélvele trabajo (el humano puede saltar a su kitty, o tú le mandas otro prompt).
2. **Mergea si procede** desde el **working tree principal** (ahí suele estar `master`
   checked-out): `git -C ~/fn_registry merge --no-ff <rama>` para apps con TBD, o el flujo que
   corresponda al sub-repo. Para funciones nuevas del registry padre, sus archivos viajan en la
   rama y el merge los lleva a master.
3. **Informa al humano** y **resume el estado de la flota** en cada turno: quién terminó, quién
   sigue, qué se integró, qué falta.

### 8. kitty vs Agent tool — cuándo cada uno

- **kitty (este modo)**: trabajo **largo e interactivo** que el humano quiere **ver** y poder
  **retomar** — implementar una feature de horas, depurar en vivo, una sesión que evoluciona.
- **Agent tool directo**: fan-out **acotado y no interactivo** — buscar en el codebase, crear
  una función con `fn-constructor`, auditar N apps con `fn-recopilador`. Más barato, sin
  terminal, sin supervisión humana. Para esto NO lances kitty: usa `Agent(...)` y ya.

Regla práctica: si el humano va a querer hablar con ello o mirarlo trabajar → kitty. Si es una
sub-tarea que devuelve un resultado y se acabó → Agent tool.

## Reglas duras del modo

- **El orquestador no hace el trabajo pesado.** Descompone, lanza, sigue, integra. Si te
  encuentras escribiendo tú la feature, párate: ¿no debería ser un secundario?
- **Cada secundario, su aislamiento.** Nunca lances dos secundarios sobre el mismo working tree
  sin worktrees/sub-repos/scopes disjuntos. Es la causa nº1 de commits perdidos.
- **El prompt del secundario lleva SIEMPRE las reglas de aislamiento.** Un prompt sin "trabaja
  aquí, no toques aquello, commitea así" es un secundario que contaminará otro repo.
- **Nunca `git add -A` en un secundario** salvo que su dir aislado sea exclusivamente suyo
  (worktree/sub-repo). En scope compartido, paths específicos.
- **Nunca `pkill`/`killall claude`.** Kill por PID exacto o `reboot_all_claudes --exclude-current`.
- **El humano habla contigo.** Tú resumes la flota; no le hagas perseguir 5 terminales.

## Anti-patrones

| Anti-patrón | Por qué es malo | En su lugar |
|---|---|---|
| `pkill claude` para parar la flota | Te mata a ti (el orquestador) también | Kill por PID exacto / `reboot_all_claudes --exclude-current` |
| Dos secundarios en el mismo working tree | Comparten HEAD/índice → commits dispersos, ramas vacías | worktree / sub-repo / scope disjunto por secundario |
| Prompt de secundario sin reglas de aislamiento | El secundario contamina el repo padre u otro worktree | El prompt fija dir, qué NO tocar, rama y cómo commitear |
| `git add -A` en scope compartido | Arrastra cambios de otra sub-tarea al commit | `git add <paths-específicos>` |
| Lanzar kitty para un fan-out trivial | Caro y sin supervisión que aporte | Agent tool directo (`fn-constructor`, `Explore`, …) |
| Hacer tú la feature "porque es rápido" | Pierdes el sentido del modo; el humano no lo ve evolucionar | Descompón y lanza un secundario |
| Lanzar sin `--dangerously-skip-permissions` | El secundario se atasca pidiendo permiso en cada Bash | Siempre `--dangerously-skip-permissions` (riesgo asumido) |
| Mergear desde el dir del secundario | Master suele estar en el working tree principal; colisión de HEAD | Mergear desde `~/fn_registry` |

## Funciones del registry que usa este modo (grupo `orchestration`)

| Función | Para qué |
|---|---|
| `launch_claude_agent_kitty_bash_infra` | Lanzar un secundario en kitty con prompt autónomo + `--dangerously-skip-permissions` |
| `list_claude_agents_bash_infra` | Listar la flota de Claudes vivos (PID, sessionId, cwd, status, kitty) para seguirla |
| `reboot_all_claudes_bash_infra` | Reiniciar/parar la flota retomando sesiones; `--exclude-current` para no tocarte |

## Ejemplo end-to-end

Tarea grande: *"añade un endpoint `/api/health` al backend de la app `kanban` y, en paralelo,
documenta el grupo de capacidad `deploy` en `docs/capabilities/deploy.md`"*. Dos piezas
independientes: una toca el sub-repo `apps/kanban` (su propio `.git`), la otra toca el repo
padre `fn_registry` (docs). Aislamiento natural distinto para cada una.

```bash
# 1. Descomponer → 2 secundarios independientes:
#    A) health endpoint  → sub-repo apps/kanban (aislamiento (a))
#    B) doc capability   → worktree del padre   (aislamiento (b))

# 2. Preparar aislamiento de B (worktree del padre; A ya está aislado por su sub-repo):
git -C ~/fn_registry worktree add /tmp/orq_capdoc -b orq/cap-deploy master

# 3. Escribir los prompts autónomos (autocontenidos, con reglas de aislamiento):
#    /tmp/orq_health.md  → "trabaja en apps/kanban (sub-repo propio), rama issue/health,
#       commits atómicos de tus paths, push al terminar, report en reports/. No toques el
#       repo padre. Reporta tu progreso en esta terminal."
#    /tmp/orq_capdoc.md  → "trabaja SOLO en /tmp/orq_capdoc (worktree), rama orq/cap-deploy,
#       toca solo docs/capabilities/deploy.md, git add de ese path, push al terminar, report
#       en reports/. No toques ~/fn_registry. Reporta tu progreso en esta terminal."

# 4. Lanzar ambos secundarios (cada uno su kitty, su dir aislado):
./fn run launch_claude_agent_kitty "kanban · health endpoint" \
  ~/fn_registry/apps/kanban /tmp/orq_health.md
./fn run launch_claude_agent_kitty "fn_registry · doc deploy" \
  /tmp/orq_capdoc /tmp/orq_capdoc.md

# 5. Seguir la flota (cada turno):
./fn run list_claude_agents
#    → tabla con los 2 secundarios vivos (PID, cwd, sessionId, status) + tu SELF.
#    Lee /tmp/orq_*_kitty.log para el arranque; cuando terminen, lee sus reports/.

# 7. Integrar (desde el working tree principal):
git -C ~/fn_registry/apps/kanban merge --no-ff issue/health     # sub-repo de la app
git -C ~/fn_registry merge --no-ff orq/cap-deploy                # repo padre (la doc)
git -C ~/fn_registry worktree remove /tmp/orq_capdoc            # limpiar worktree

# Resumen al humano: A integrado (endpoint + test verde), B integrado (doc),
# flota vacía. Tarea grande hecha.
```

## Salida del modo

Cuando el humano escriba `salir orquestador` o `fin orquestador`, cierra con un resumen de la
flota: secundarios lanzados, cuáles terminaron e integraste, cuáles siguen vivos (con su kitty
para que el humano decida), y los reports generados. Si quedan secundarios vivos, recuérdale que
`list_claude_agents` los lista y que para pararlos es kill por PID exacto, nunca `pkill`.

## Relación con otras reglas

- `.claude/rules/autonomous_loop.md` — `fn-orquestador` (Agent tool, sandbox no-interactivo). Es
  lo que este modo **no** es; tenlas claras separadas.
- `.claude/rules/apps_subrepo.md` — apps/analyses/projects son sub-repos Gitea (`apps/*`
  gitignored): el aislamiento natural (opción (a)) y el gotcha de `git init` antes de limpiar un
  worktree con una app nueva dentro.
- `.claude/rules/reports.md` + `.claude/rules/dod_quality.md` — qué entrega cada secundario:
  report con evidencia ejecutable + gaps.
- `.claude/rules/delegation.md` + `.claude/rules/registry_calls.md` — los secundarios siguen
  registry-first y delegan a `fn-constructor` igual que tú.
- Memorias: `lanzar-agentes-skip-permissions`, `multi-agent-git-race-same-repo`,
  `claude-session-pid-mapping`, `prefiere-kitty-terminal`.