modo-autonomo

orca-stack

Instala de una vez el stack de agentes que uso para trabajar con Orca: la política del stack, las skills propias, los wrappers de proveedores, Pi con Gentle Shell y los mods de Claude Code. Todo en un comando, con respaldo de lo que toca y con vuelta atrás.

¿Cómo se usa día a día? Leé el manual de uso: comandos, mods, marchas, cuándo conviene usarlo y cuándo no, casos borde y manejo. Marca lo que está solo en main y todavía no salió en un release.

npx github:Gagaismo/orca-stack#v0.12.0 global     # instalación a nivel usuario
npx github:Gagaismo/orca-stack#v0.12.0 init       # cablea el proyecto actual
npx github:Gagaismo/orca-stack#v0.12.0 doctor     # verifica que todo funcione de verdad
npx github:Gagaismo/orca-stack#v0.12.0 remove     # deshace lo que instaló global
npx github:Gagaismo/orca-stack#v0.12.0 sesiones   # lista las sesiones recientes de Claude, Pi y agy (para `/retro`)
npx github:Gagaismo/orca-stack#v0.12.0 despachar 12 agy   # desde el checkout principal: despacha el ticket #12 al agente
npx github:Gagaismo/orca-stack#v0.12.0 revisar 15 pi      # despacha el review del PR #15
npx github:Gagaismo/orca-stack#v0.12.0 brief-revision 15 --modelo <modelo>   # modo un-agente: worktree y brief de review para un subagente
npx github:Gagaismo/orca-stack#v0.12.0 consultas 42 57    # filtra y avisa consultas nuevas en issues y PRs en curso
npx github:Gagaismo/orca-stack#v0.12.0 avisar 42 <url>    # Proactive: le toca el timbre al worker de #42 con la URL de la respuesta
npx github:Gagaismo/orca-stack#v0.12.0 vigilar 42 57      # el Monitor de la tanda: solo eventos de sus PRs, hasta tanda-cerrada

¿Primera vez, o un proyecto nuevo o ya empezado? Seguí la guía de setup: tiene un cuestionario que dice qué configurar en cada caso.

Cero dependencias, Node 20 o más nuevo. Funciona en Windows, macOS y Linux.

Qué instala

global (idempotente; todo archivo que modifica se respalda antes en ~/.orca-stack/backups/<fecha>/ (nunca al lado del archivo, para que ningún agente cargue el respaldo)):

Gentle Shell se actualiza volviendo a correr global con la versión nueva de orca-stack. Desde gentle-pi 4.2.0, gentle-shell update reinstala solo el paquete global dueño del Pi que corre, y si no puede probar qué paquete global es dueño de Pi, no toca nada.

Los wrappers se llaman distinto del binario real a propósito: así nunca se llaman a sí mismos. Cada uno fija los marcadores ORCA_STACK_*, busca el binario real en el PATH, pasa los argumentos tal cual y devuelve su código de salida.

global instala herramientas, skills, mods y wrappers, pero ningún texto de metodología: una sesión de Claude en un proyecto sin .orca-stack.json no recibe nada del stack por esta vía. La metodología llega por el proyecto, con init (el contrato y las líneas de la política en AGENTS.md, y @AGENTS.md en CLAUDE.md). Del CLAUDE.md global global solo saca el bloque entre orca-stack:begin y orca-stack:end (o orca-stack:auto, el viejo) que dejó una versión anterior, y respeta todo lo demás. Con settings.json hace algo parecido: solo suma sus carpetas a CLAUDE_CODE_PLUGIN_DIRS (con el separador de tu sistema), conserva las que ya había y no toca ninguna otra clave.

El bloque gentle-ai:sdd-orchestrator (v2/v3) o gentle-ai:orchestrator (v4) de ~/.claude/CLAUDE.md (unos 16 KB: coordinación, delegación, tabla de modelos y el flujo de cada versión) se carga en cada sesión. Por eso global lo achica según gentle.orchestrator en ~/.orca-stack/config.json:

• "lazy" (por defecto): guarda el texto completo, tal cual lo escribió gentle-ai, en ~/.orca-stack/gentle/orchestrator.md y deja entre los marcadores un puntero corto (empieza con <!-- orca-stack:gentle-lazy v1 -->). El puntero dice que ODD es el flujo predeterminado y que la sesión que orquesta (main) debe leer la copia completa; también exige presentar completos los menús y pedidos de consentimiento, sin responder por el humano. Hace respaldo, es idempotente, respeta --dry-run e imprime cuántos KB ahorró. Con marcadores incompletos, repetidos o desordenados no escribe nada y dice por qué. Se omite mientras el RDD de gentle-ai esté prendido (o no se pueda leer): el bloque trae su contrato de review y el puntero lo apagaría en silencio; si ya estaba en lazy, global lo restaura desde la copia.
• "full": deja el bloque como lo escribe gentle-ai (y, si estaba en lazy, lo restaura desde la copia, con respaldo; si la copia falta, avisa que corras gentle-ai sync). Con el RDD de gentle-ai apagado (gentle-ai review mode status dice off), además recorta las secciones de review, que no hacen nada y se cargan igual (unos 26 KB); si RDD está prendido o gentle-ai no está instalado, ese recorte se omite y dice por qué.

gentle-ai sync reescribe el bloque entre los marcadores (reemplaza el contenido, no duplica ni valida un hash), así que después de cada sync hay que correr orca-stack global de nuevo, que además refresca la copia y el puntero. doctor avisa si la sync lo reescribió, si falta la copia o si todavía está en la ruta antigua. Para volver al bloque completo: poné "gentle": { "orchestrator": "full" } y corré orca-stack global, o corré gentle-ai sync. orca-stack remove también lo restaura desde la copia. La clave antigua gentle.sddOrchestrator sigue funcionando durante la migración; doctor sugiere renombrarla y, si están las dos, gentle.orchestrator tiene prioridad. global mueve la copia antigua sdd-orchestrator.md a orchestrator.md; si existen ambas, conserva la más nueva por fecha de modificación y respalda la otra.

gentle-ai v4. v4 retiró SDD y OpenSpec: ODD es su único flujo y gentle-ai sync renombra el bloque en el lugar a gentle-ai:orchestrator, con el orquestador ODD adentro y las mismas secciones de review. global, doctor y remove reconocen los dos nombres: el modo lazy, el recorte y la restauración funcionan igual; el puntero indica que ODD es el flujo predeterminado y que la sesión main lee la copia completa. La copia queda en ~/.orca-stack/gentle/orchestrator.md. Para pasar a v4 en Windows (necesita Go 1.25.10 o más nuevo en el PATH):

go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.1
gentle-ai sync
npx github:Gagaismo/orca-stack global

La sync deja el bloque completo y la copia vieja (de v2) queda desactualizada: doctor avisa que corras orca-stack global, que guarda el texto de v4 en la copia y vuelve a dejar el puntero.

Los mods

Son plugins de Claude Code que se recargan en caliente (.claude-plugin/plugin.json + hooks/). Se activan con la variable CLAUDE_CODE_PLUGIN_DIRS, que global completa por vos; se cargan en las sesiones que abras después.

El mod marchas actúa solo en el checkout principal de un repo con .orca-stack.json o .orca-stack.local.json cuyo contrato incluye la sección Marchas. Para mostrar la marcha actual, usá /marcha; para cambiarla, /marcha lazy, /marcha medium o /marcha proactive. Para apagarlo, corré claude plugin disable marchas@inline --scope user; usá --scope local para este repo en esta máquina o --scope project para el equipo.

Prerrequisitos

• Node.js 20 o más nuevo (Pi pide Node 22.19 o más nuevo).
• Git y GitHub CLI (gh), para el tablero y para el puente.
• Claude Code, para los mods.
• En Windows, el postinstall de gentle-pi compila el binario de gentle-ai con Go (1.25.10 o más nuevo): si pi install de gentle-pi falla, revisá que go esté en el PATH.

global detecta estas herramientas, no las instala; si faltan, imprime el comando oficial de cada una: Orca, engram, gentle-ai y Pi.

Uso

orca-stack global [--dry-run] [--force] [--skip-pi] [--limpiar-sdd] [--humano <nombre>]
orca-stack init   [--dry-run]
orca-stack doctor [--offline] [--skip-pi]
orca-stack remove [--dry-run] [--with-pi]
orca-stack sesiones [--desde <AAAA-MM-DD>] [--limite <n>]
orca-stack despachar <issue> <agente> [--nota "<texto>"] [--confirmado] [--perfil-pi <nombre>] [--dry-run]
orca-stack revisar <pr> <agente> [--nota "<texto>"] [--confirmado] [--perfil-pi <nombre>] [--dry-run]
orca-stack consultas <n...>
orca-stack avisar <issue|pr> <url-del-comentario> [--dry-run]
orca-stack reanudar <issue> <url-del-comentario> [--confirmado] [--dry-run]
orca-stack vigilar <n...> [--cada <segundos>] [--una-vez] [--dry-run] [--consultas]
orca-stack vigilar --merge-de-main <pr>

• --dry-run cuenta cada acción sin escribir nada.
• reanudar retoma una TUI detenida o relanza al worker en el mismo worktree con su brief original y la URL de respuesta.
• --force reemplaza archivos que ya existían y no son de orca-stack (por ejemplo, una skill tuya llamada igual). Sin --force se saltean con un aviso ⚠ y quedan como estaban; con --force se respaldan antes.
• global --limpiar-sdd respalda en ~/.orca-stack/backups/sdd-<fecha>/ y mueve solo restos conocidos; doctor lista los que encuentra y muestra el comando exacto. Los nombres desconocidos nunca se mueven y global sin esta opción no limpia nada. Si algún movimiento falla, informa qué quedó pendiente; podés volver a ejecutar el mismo comando.
• init escribe en el AGENTS.md del proyecto el bloque <!-- orca-stack:begin --> … <!-- orca-stack:end --> con el contrato de trabajo completo (assets/stack/CONTRATO.md, igual en todos los proyectos) y las líneas de la política; a CLAUDE.md le pone un bloque corto con @AGENTS.md. Además crea .orca-stack.json y .orca-stack.local.json si faltan y agrega este último a .gitignore. Es idempotente y respalda lo que modifica. Los valores propios de cada proyecto no van en el bloque: viven en .orca-stack.json.
• orca-setup es la skill con la que la sesión de main entrevista al humano, en una sola ronda, para completar .orca-stack.json ("setup": "completo"). La ofrece sola cuando falta y doctor avisa si quedó pendiente.
• sesiones es de solo lectura: lista las sesiones recientes de Claude Code (~/.claude/projects y, si está, la carpeta de agentes.pi.claudeConfigDir), de Pi (~/.pi/agent/sessions) y de agy (~/.gemini/antigravity-cli, solo con Node 22.13 o más nuevo). Por sesión muestra la herramienta, la carpeta, inicio y fin, las llamadas, tus mensajes, las llamadas con error y los resultados de más de 15k caracteres. Es la entrada para quien corre /retro de Matt: --desde fija el día de inicio (por defecto, los últimos 2 días) y --limite cuántas sesiones (por defecto, 10).
• consultas <n...> filtra y avisa consultas nuevas en issues o PRs de una tanda. Consulta gh api user en ejecución, busca comentarios de la cuenta del stack que empiecen con Consulta: e imprime consulta nueva en #<n> una sola vez por comentario, guardando los IDs en .git/orca-stack/consultas-reportadas.json.
• vigilar <n...> es el Monitor de una tanda (<n...>, los issues de la tanda): stdout lleva solo eventos, uno por línea, y todo diagnóstico va a stderr. Cada --cada segundos (por defecto 60) lee gh pr list --state all (sin --state no aparecen los PRs mergeados ni cerrados) y emite pr-abierto, ci-verde, ci-roja (con los checks que fallaron), pr-mergeado, pr-cerrado, vigilar-ciego (tres vueltas seguidas sin poder leer GitHub, una vez por corte; nunca dice que no hay PRs) y, cuando terminaron todos los items, tanda-cerrada, y sale con 0. Un PR es del issue por su referencia de cierre, por la rama del worktree de este repo enlazado al issue (buscado como en avisar) o por una línea Closes #<n> en su cuerpo, nunca por el nombre de la rama; un issue cerrado sin PR cuenta como terminado. De dos corridas de un mismo check en un commit cuenta la última, y cada corrida que termina en rojo es un ci-roja, también un gh run rerun --failed que vuelve a fallar en el mismo commit; la misma corrida leída de nuevo no se repite. Lo emitido queda en .git/orca-stack/vigilar.json: rearmado con los mismos argumentos, retoma sin repetir nada. --una-vez consulta una vez y sale, --dry-run además no escribe nada, y --consultas corre en cada vuelta el chequeo de consultas para los mismos items, así Proactive sigue con un solo Monitor. Como todas las sesiones comparten la cuenta de gh, un merge de main se ve igual que uno del humano: main corre vigilar --merge-de-main <pr> justo antes de cada intento de gh pr merge <pr> (y de nuevo después de gh pr update-branch), que registra el head del PR en .git/orca-stack/vigilar-merges.json; un merge de ese head hecho dentro de los 30 minutos siguientes al registro (según el mergedAt del PR) no emite pr-mergeado, aunque el watcher lo vea más tarde. Con un PR ya mergeado o cerrado, --merge-de-main sale con 1 y no registra nada. El watcher solo lee ese archivo.
• avisar <issue|pr> <url-del-comentario> es el timbre de Proactive: cuando main responde la pregunta de un worker, le escribe en su terminal una sola línea fija, Message from main: <url>, con la URL del comentario y nada de su texto. Encuentra la terminal por el worktree de este repo enlazado a <n> en orca worktree ps (con un PR, el de la rama del PR), buscado solo entre los de git worktree list, porque los selectores issue:<n> y branch: de Orca abarcan todos los repos; lista sus terminales con orca terminal list --worktree path:<ruta> y se niega si alguna no trae ese worktreePath. Si un rebote dejó dos, elige la del agente vivo según orca worktree ps. Manda solo mientras el turno del worker está en curso (estado working en Orca y el indicador de turno de Claude en pantalla): se niega si el turno ya terminó, si la terminal muestra un shell o un diálogo, o si hay más de un agente vivo. Por ahora solo avisa a claude: se niega con pi, que corre sin TUI y relee los comentarios antes de su PR, y con codex y agy hasta que pasen su prueba de Enter a mitad de turno. Se niega si el comentario no es de la cuenta del stack (gh api user), si no está en <issue|pr> o si no empieza con Respuesta de main: o Respuesta del humano: (la misma cuenta publica las Consulta: de los workers). Envía una sola vez con --wait-submit: sin recibo de entrega informa la falla y no reenvía. --dry-run muestra la línea y la terminal elegida sin enviar nada. main nunca arma el timbre con llamadas sueltas a orca.
• despachar y revisar (agentes: claude, agy, codex, codex-cc, pi) corren desde el checkout principal de un repo con el setup completo. Se niegan si el agente no está en agentes.usa, si está en agentes.preguntarAntes (repetí con --confirmado cuando el humano dijo que sí), si el issue está cerrado o asignado, si el revisor es el implementador del PR (línea Implementador:) o corre un modelo de su misma familia (sale de agentes.modelos; pi y claude sí se revisan entre sí), si el agente tiene una regla guardia.bloquear vigente, o si ya hay un worktree o un agente vivo para ese ticket. Antes de tocar nada hacen git fetch origin y comprueban que cada ruta que cita el brief (armado desde assets/stack/brief-ticket.md o brief-revision.md) exista en origin/<ramaBase> (en revisar, en la rama del PR): una ruta que falta o que git ignora aborta sin asignar ni crear nada. Si pasa todo, despachar asigna el issue (el assignee es el cerrojo y lo maneja el comando: no se asigna antes), y ambos crean el worktree con orca worktree create (así lo ve Orca), escriben el brief en ~/orca/briefs/, lanzan el agente en una terminal de Orca y le mandan el brief. despachar imprime Rama: <rama> con el nombre devuelto por Orca; en --dry-run aclara que Orca define la rama al crear el worktree. Después de confirmar el inicio, despachar, revisar y rebote leen tres veces la pantalla de cada terminal salvo pi, con pausas de 5 segundos: fallan si ven un mensaje de cuota o si el último renglón no vacío volvió al prompt de PowerShell (PS <unidad>:\...>). No detectan prompts de bash ni cmd.exe. Si algo falla después de crear el worktree, el mensaje lista lo que quedó (assignee, worktree, brief) y cómo recuperarlo, porque el cerrojo rechaza un reintento. Pi corre sin TUI (pi -p), así que sí puede ejecutar git, gh y la suite. --nota agrega texto al brief y --dry-run muestra el plan y el brief sin escribir nada. Los modelos salen de agentes.modelos de tu config personal: un texto, { "modelo", "esfuerzo" } o { "implementar": {…}, "revisar": {…} } por agente.

• --perfil-pi <nombre> (solo con pi) fija qué perfil de modelos de gentle-pi usa ese despacho, sin tocar el perfil global activo. Los perfiles viven en ~/.pi/gentle-ai/profiles.json; el comando se niega si el nombre no existe o si el clon ya fija otro perfil (<git-common-dir>/gentle-ai/profile-pin.json, que gana en silencio sobre el del worktree). Después de crear el worktree escribe el pin .pi/gentle-ai/profile.json ahí (gentle-pi lo lee en cada lanzamiento de subagente) y, si git no lo ignora, agrega /.pi/gentle-ai/profile.json a <git-common-dir>/info/exclude, así que nunca se commitea. Si el pin ya está versionado en el repo, lo deja como está cuando declara el mismo perfil y se niega (sin escribir) si declara otro; si git sigue sin ignorarlo después de la entrada (por ejemplo un .gitignore con !.pi/gentle-ai/profile.json), también se niega. Un thinking inválido en el perfil se avisa y se ignora. Como un pin no mueve al orquestador, lanza pi con --model <orchestrator.model del perfil> --thinking <orchestrator.thinking>. Con --dry-run cuenta todo esto sin escribir. Sin el flag y sin agentes.pi.perfil (o con "preguntar") rige el perfil activo global, como siempre. agentes.pi.perfil: "<nombre>" lo fija para todos los despachos a pi y el flag gana.
• guardia-despacho pregunta ese perfil por vos: cuando Claude corre orca-stack despachar|revisar <n> pi sin --perfil-pi y agentes.pi.perfil no es un nombre, abre el diálogo "Perfil Pi" con los perfiles de profiles.json (opus-haiku y samu-balanceado primero; máximo cuatro opciones) y agrega --perfil-pi <elegido> justo detrás del agente. Si cierran el diálogo, o no hay nadie que conteste (-p), el comando corre sin cambios. Las consultas (/pi, consultar_gentle_shell) no preguntan, y un --dry-run tampoco.
• Perfil opus-haiku: el orquestador es Opus 5.5 (claude-bridge/claude-opus-5-5, thinking high) y los diez subagentes de gentle-pi (gentle-ai-explore, gentle-ai-verify, gentle-ai-worker, jd-fix-agent, jd-judge-a, jd-judge-b, review-readability, review-reliability, review-resilience, review-risk) corren en Haiku 5.5 (claude-bridge/claude-haiku-5-5). Un perfil tiene que nombrar a todos los agentes: el que omite uno lo deja con el modelo de su frontmatter. Para cambiarlo después: /gentle:profiles en Pi, o editar ~/.pi/gentle-ai/profiles.json (hacé una copia antes).
• --skip-pi no toca Pi (útil si todavía no lo instalaste).
• --humano fija cómo te nombran los mods; si no lo pasás, sale de git config user.name.
• doctor hace sondeos reales y sale con código 1 si hay una falla (✖). Los avisos (⚠) no cambian el código.
• remove borra lo que global creó, restaura lo que había reemplazado, saca sus entradas de CLAUDE_CODE_PLUGIN_DIRS y, si quedó, el bloque de CLAUDE.md de una instalación vieja. Los respaldos (~/.orca-stack/backups/<fecha>/) se quedan. Los paquetes de Pi solo se sacan con --with-pi, y solo los que no tenías antes de instalar. Si editaste ~/.orca-stack/config.json, se conserva.
• Para probar sin tocar tu carpeta personal: ORCA_STACK_HOME=/ruta/temporal orca-stack global.

doctor

No se queda en "el archivo existe":

• corre el --orca-stack-self-test de cada wrapper y comprueba que la ruta de la política exista;
• compara la versión de Pi y de sus paquetes con las fijadas (Pi 1.2.0, gentle-pi 4.2.0, pi-claude-bridge 0.9.2) y avisa si no coinciden; un Pi anterior a 1.2.0 es una falla, porque gentle-pi 4.2.0 no arranca con él;
• sondea con un pi -p corto (con tiempo máximo) si falta el /login (se omite con