rig-epic — flujo de trabajo con rama de integración

¿Qué hace rig-epic — flujo de trabajo con rama de integración?

Para arcos de múltiples elementos donde aterrizar cada elemento directamente en la rama principal rompería temporalmente el contrato de ejecución, apila las PRs hijas en una rama de integración compartida y fusiona esa rama en la principal como un solo PR al final. Cada PR hija se revisa como el paso que realmente es; la entrega a la rama principal es un rebase fusionado.

Configuración

Lee .rig/config.json (valores predeterminados entre paréntesis):

• tracker.provider — linear | github | none (none). Cómo se almacenan los elementos padre/hijo. none → los elementos viven solo en el archivo de estado de la épica (abajo); no se realizan llamadas al sistema de seguimiento.
• tracker.team / tracker.project / tracker.ticketPrefix / tracker.githubIntegration.
• vcs.baseRef (origin/main), vcs.defaultBranch (main), vcs.protectedBranchMergeQueue (false).
• sourceScope[0] — dónde explorar durante plan.
• agents.architect / agents.reviewer (por defecto rig-<rol>) — para el panel de review con contexto fresco.

Delega en /rig-task (por cada hija), /rig-worktree (clonados), /rig-review

• /rig-review fix (revisión de diff combinado), /rig-tidy (opcional).

Archivo de estado de la épica (reemplaza cualquier memoria externa)

Cada épica activa se rastrea en un archivo JSON local del repositorio en .rig/epics/<rama-de-integración>.json:

{
  "parent": "ABC-42 o un slug en tracker=none",
  "parentTitle": "…",
  "integrationBranch": "abc-42-<slug>",
  "whyEpic": "qué hijas se entrelazan y por qué",
  "children": [
    { "id": "ABC-43", "title": "…", "blockedBy": [], "branch": null, "status": "todo|merged" }
  ]
}

Esta es la única fuente de verdad que next/run/review/finish/prune leen. Agrega .rig/epics/ a .gitignore (es estado de coordinación transitorio). Inferencia del padre (cuando se omite <PADRE>): si existe exactamente un .rig/epics/*.json, úsalo; si hay cero o muchos, pregunta.

Banner de intención: cada invocación DEBE imprimir una línea primero — modo, qué rama objetivo tienen las PRs, qué no hará:

rig-epic: <subcomando> — <acción>. Las PRs apuntan a <rama>. No <cosa>.

status (predeterminado, solo informe)

Lee el/los archivo(s) de estado de la épica. Informa: rama de integración + commits adelantados de vcs.baseRef; PRs hijas abiertas (gh pr list --base <rama-de-integración>) y su estado; estado de cada hija en el sistema de seguimiento (si hay uno); clonados fusionados/eliminados sobrantes (sugiere /rig-epic prune); y una recomendación de una línea (abrir PR hija X, listo para /rig-epic next o listo para /rig-epic finish). No modifica nada; no genera nada.

plan <CARACTERÍSTICA>

Descompone una característica en un padre + 3–8 hijas, escribe el archivo de estado, luego encadena con start.

Usa esto solo cuando el trabajo tenga forma genuina de épica (las hijas se entrelazan — al menos la dependencia de ejecución de una hija depende de que otra esté parcialmente completa). Si los elementos son independientes y cada uno puede aterrizar en la rama principal solo, detente y dile al usuario que ejecute /rig-sprint plan — misma descomposición, sin rama de integración.

Procedimiento

1. Lee el contexto. Documentos de producto/especificaciones si el proyecto los tiene (pregunta si no estás seguro); explora el código base (sourceScope[0]) para ver qué existe. Si hay un sistema de seguimiento configurado, búscalo primero para ver si hay elementos casi duplicados.
2. Verifica que sea una épica (según la prueba de entrelazado anterior). Si no → envía a /rig-sprint plan.
3. Crea el padre.
   • tracker: linear/github → crea el elemento padre (equipo/proyecto de la configuración); la descripción cubre Resumen, por qué es una épica y las hijas planificadas.
   • tracker: none → el padre es un slug + título registrado solo en el archivo de estado.
4. Crea cada hija con sus aristas de dependencia.
   • Suficientemente pequeña para una sesión de agente (1–3 archivos); criterios de aceptación concretos y comprobables; trabajo fundamental primero.
   • Registra blockedBy para cada dependencia real — esto es lo que next lee para elegir la siguiente hija desbloqueada. Sin ello, la selección retrocede al orden de declaración y se equivoca con épicas entrelazadas.
   • Modo con sistema de seguimiento: establece las relaciones nativas padre/bloqueado por del sistema y reflejalas en el archivo de estado. none: solo archivo de estado.
5. Muestra una tabla resumen (ID · Título · Depende de).
6. Encadena con start <PADRE> — plan es planificar y empezar; no te detengas a preguntar.
7. Detente después de start. Informa la rama de integración, las hijas y el siguiente paso (/rig-epic next para una, /rig-epic run para el bucle). Nunca inicies run automáticamente — la ejecución es una aceptación explícita.

start <PADRE>

Pre-vuelo: git fetch origin; confirma que el padre y al menos una hija existen (en el sistema de seguimiento, o como argumentos para none).

1. Nombre de la rama de integración: <slug-del-padre>-<slug-del-título> (kebab, p. ej. abc-42-agent-as-definition).
2. Crea la rama de integración desde vcs.baseRef sin un clonado local:

   git fetch origin
   git push origin <vcs.baseRef>:refs/heads/<rama-de-integración>
   

   No destructivo. Si la rama ya existe, déjala (nunca sobrescribas — podría destruir trabajo en curso).
3. Escribe .rig/epics/<rama-de-integración>.json (esquema anterior) con el padre, por qué es una épica y cada hija + blockedBy. Esto es lo que hace que cada /rig-task <hija> apunte a la rama de integración en lugar de a la principal.
4. Si hay un sistema de seguimiento configurado, agrega una nota "Rama de integración: objetivo <rama-de-integración>, no la principal" a cada hija para que el próximo agente no vuelva a leer esta habilidad, y asegúrate de que el padre esté En Progreso (adaptativo: muévelo solo si aún no ha comenzado; difiere si una integración en vivo lo hizo). Las hijas obtienen su propio En Progreso desde el Paso 1 de su /rig-task.
5. Nombra la sesión "ÉPICA: <título del padre> (<padre>)" mediante scripts/set-session-name.sh (solo para Claude Code; no operativo en otros lugares) para que la lista de trabajos en segundo plano se lea como la épica. Las hijas establecen sus propios nombres CARAC:/CHORE: con --skip-if-prefix "ÉPICA:", por lo que esta etiqueta de épica permanece arriba.
6. Informa la rama, las hijas y el siguiente paso.

next (una sola hija)

1. Resuelve la rama de integración activa (se espera una; pregunta si hay muchas). Si la sesión aún no tiene nombre ÉPICA: (es decir, next se invocó directamente, no mediante start), nómbrala "ÉPICA: <título del padre> (<padre>)" (solo para Claude Code).
2. Elige la siguiente hija desbloqueada: la primera hija no terminada cuyos blockedBy estén todos fusionados en la rama de integración. Indica la elección + razonamiento en el banner.
3. Asegúrate de que la hija anterior haya aterrizado. Con --auto-merge (Paso 4), cada PR de hija se fusiona en la rama de integración por sí sola una vez que CI pase, por lo que la punta de integración avanza automáticamente — solo git fetch origin y confirma. (Plan B para una hija ejecutada sin --auto-merge: avanza rápido la rama sobre su punta — git push origin origin/<rama-hija-anterior>:refs/heads/<rama-de-integración>, lo que cierra automáticamente esa PR como FUSIONADA. Seguro de reejecutar.)
4. Ejecuta /rig-task <HIJA> --base <rama-de-integración> --auto-merge (agrega --spec-cleared cuando la revisión previa de especificaciones de run ya las haya aprobado) — --base hace que la rama de trabajo de la hija se bifurque de, y su PR objetivo sea, la rama de integración; --auto-merge hace que la hija habilite gh pr merge --squash --auto en su propia PR una vez que su revisión esté limpia, por lo que CI la integra en la rama de integración (siempre squash — no uses rebase-merge; muchos repositorios lo prohíben. Si la rama de integración no tiene verificaciones obligatorias, la hija se fusiona directamente). Ejecuta de una sola vez (inicio→fin); devuelve una sola cadena de resultado para la puerta de fusión.
5. Puerta de fusión — solo clean es verde para fusionar:
   • clean → la hija habilitó auto-merge, por lo que su PR aterriza cuando CI pase. Espera: consulta gh pr view <N> --json state (~60s, hasta ~30min) hasta que sea MERGED, luego git fetch origin y confirma que la punta avanzó. Registra la hija como merged + su rama en el archivo de estado, y asegúrate de que el ticket de la hija esté Hecho (adaptativo: muévelo solo si aún no está Hecho; difiere si una integración en vivo lo cerró). Si CI falla / nunca se fusiona → trata como no limpio.
   • cualquier otra cosa (actionable/timeout, o un estado estacionado del sistema de seguimiento) → la hija no habilitó auto-merge; detente. Muestra el resultado, la URL de la PR y cualquier resumen del revisor. Espera al usuario; no reintentes una revisión estacionada.

next hace exactamente una hija. Usa run para el bucle.

run [--advisor]

Revisión previa de especificaciones — una vez, antes del bucle. Revisa todas las especificaciones de las hijas juntas, por adelantado, en lugar de descubrir bloqueadores una hija a la vez en mitad de la ejecución. Una hija que se detiene por una pregunta de especificación estanca toda la épica (y bajo una ejecución paralela o duradera, una hija detenida puede fallar todo el lote), así que resuelve las especificaciones antes de que cualquier hija comience a codificar:

1. Despliega agents.architect + agents.qa sobre cada especificación de hija, leída contra la rama de integración; cada uno devuelve sus bloqueadores.
2. Consolida en una sola lista de bloqueadores y resuélvela una vez — aclara en el sistema de seguimiento, o decide con el usuario. Este es el punto de decisión único de especificación de la épica.
3. Luego ejecuta cada hija con su puerta de especificación preliminarmente aprobada: /rig-task <HIJA> --base <rama-de-integración> --auto-merge --spec-cleared, por lo que ninguna hija se detiene de nuevo en una pregunta ya respondida.

Esta es la pasada de especificaciones previa a la codificación; la review de diff combinado (abajo) es la pasada de código posterior a la fusión — puertas diferentes.

--advisor (sin supervisión). Decide esa puerta previa con una pasada de asesor en lugar de un humano: una revisión delegada de agents.architect lee las especificaciones del arquitecto y QA y procede con una dirección sintetizada por hija (entregada textualmente al codificador de cada hija), o se detiene con un informe bloqueado que nombre lo que un humano debe decidir. Ningún humano espera, por lo que la épica avanza sin intervención a las PRs hijas; un bloqueador genuino aún la detiene en lugar de expandirse con una especificación incorrecta. (El flujo de trabajo duradero de Smithers emparejado implementa esto con un modelo barato — el "asesor Fable" — por lo que las épicas iniciadas nunca se estacionan en la puerta).

Luego repite next hasta que no quede ninguna hija desbloqueada:

mientras exista una hija desbloqueada:
  ejecuta /rig-epic next            # las hijas se ejecutan con --spec-cleared (especificación previa)
  si se detuvo sin fusionar (resultado ≠ clean) → detente, devuelve el control
  si no → reevalúa las hijas desbloqueadas

Cuando la cola se vacíe, informa "épica lista para /rig-epic finish."

review [<PADRE>]

Se ejecuta después de que la última hija se fusionó en la rama de integración, antes de finish. La revisión por PR (/rig-review dentro de cada /rig-task) ve cada hija en aislamiento; esta ve la forma combinada y la simplificación solo visible una vez que todo está dentro. Los subagentes con contexto fresco (entrada = el diff fusionado + títulos de las PRs hijas) no pueden heredar las racionalizaciones recordadas del implementador.

Ejecuta antes de prune — los subagentes de revisión necesitan un clonado funcional; reutiliza un clonado de trabajo de una hija si aún existe (evita una instalación nueva + reenlace de env).

1. Resuelve la rama de integración; git fetch origin.
2. Asegura un clonado de trabajo de la rama de integración ($WT). Reutiliza un clonado de trabajo de una hija fusionada avanzado rápidamente a la punta de integración, o crea uno con /rig-worktree (--base <rama-de-integración> --reuse).
3. Despliega tres subagentes en paralelo (un mensaje, tres llamadas Agent), cada uno haciendo cd a $WT con la punta de integración activada:
   • Lente 1 — Simplificación (agents.architect): diff git diff <vcs.baseRef>...HEAD; lista de PRs hijas mediante gh pr list --base <BR> --state merged. Mandato: encuentra abstracciones para colapsar, ayudantes que una PR agregó que la forma final de otra PR hizo redundantes, perillas de configuración que nadie establece, rutas de código que el diff combinado hizo muertas, tipos con un solo llamante. Eliminaciones/fusiones concretas, archivo:línea, primero el de mayor impacto. Omite corrección.
   • Lente 2 — Corrección entre PRs (agents.reviewer): recorre el catálogo de patrones de revisión del proyecto (review.patternsFile) contra el diff combinado. La revisión por PR ya se ejecutó; captura interacciones solo visibles en la forma fusionada (el ayudante de PR-A vs el llamante obsoleto de PR-D; PR-B eliminó una perilla que PR-F todavía lee). P0/P1/P2 con archivo:línea + categoría.
   • Lente 3 — Código muerto y referencias obsoletas (agents.reviewer): para cada símbolo que el diff agregó, ¿se llama en otro lugar? Para cada símbolo eliminado, haz grep en el árbol (flujos de trabajo, manifiestos, IaC, scripts, docs) en busca de referencias residuales. Informa con archivo:línea.
4. Consolida — deduplica, produce una lista P0/P1/P2 agrupada por lente, imprime conteos.
5. Clasifica:
   • 0 elementos → limpio — listo para /rig-epic finish, detente.
   • hallazgos → pregunta mediante AskUserQuestion: aplicar ahora / saltar y terminar de todos modos (rebajar a seguimientos) / pausar. En aplicar ahora, ejecuta /rig-review fix --source local en $WT (genera agents.coder, reevalúa hasta que esté limpio), confirma + git push origin <rama-de-integración>, vuelve a ejecutar review una vez para confirmar convergencia.
6. Cadena de resultado (para finish): limpio — … / aplicado — … / pausado — ….

finish [<PADRE>] [--merge]

Fusiona toda la rama de integración en un solo PR dirigido a la principal. Predeterminado: abre el PR y detente — este es el PR único para revisar visualmente.

review es una puerta estricta. finish siempre ejecuta review primero; el PR fusionado se abre solo en clean o applied. En paused, detente y espera.

1. Ejecuta review (puerta) en línea; bifurca según su resultado (clean/applied → procede; paused → detente e imprime los hallazgos pendientes).
2. Actualiza y rebasea si es necesario. git fetch origin; lista git log <vcs.baseRef>..origin/<rama-de-integración> --oneline. Si la principal se movió, rebase la rama de integración sobre ella primero (git rebase <vcs.baseRef> en una copia local, luego git push --force-with-lease origin <local>:<rama-de-integración>).
3. Abre el PR final a vcs.defaultBranch con un título que haga referencia al padre y un cuerpo que resuma todas las hijas. En un sistema de seguimiento con un verbo de cierre (Fixes <PADRE> / Closes #<n>), inclúyelo para que el padre se cierre automáticamente...