GravionLabs/deliver

¿Qué hace deliver?

Entrega los PBIs y Bugs abiertos de un issue (un elemento de trabajo = issue abierto etiquetado como pbi o bug; un Bug ejecuta el mismo bucle, tipo de rama fix, Closes #<nr>) uno tras otro: un subagente implementa, un subagente revisa, esta sesión abre el PR, espera a CI y fusiona. Los mismos pasos en cada plataforma (Claude Code, OpenCode, Copilot CLI). El estado reside solo en GitHub (issues, sub-issues, ramas, PRs), por lo que una ejecución puede detenerse en cualquier momento y /deliver <nr> continúa donde se detuvo. El control estricto es el conjunto de reglas en release/next: un check requerido rojo o faltante bloquea la fusión haga lo que haga esta sesión.

Entrada

help (o --help, -h): imprime references/help.md sin cambios, nada más.

/deliver status --milestone <nombre>: imprime el bloque de estado (## Bloque de estado) y se detiene, no se entrega nada.

/deliver <nr> [<nr> …] [--milestone <nombre>] [--unattended] [--inline] [--max <n>]: cada número es un PBI, Bug, Feature o Epic; --milestone <nombre> (un lanzamiento, M<n> o un título legacy) añade los elementos de trabajo abiertos de ese hito (una lectura por lotes del hito (pwsh <skill-dir>/../github-milestone/scripts/Get-Milestones.ps1 -Mode issues -Name <nombre> -State open: REST, todas las páginas, sin PRs; la búsqueda de github-milestone resuelve M4 al título M4 o, después de close, M4 (0.2.0); filtra la lista devuelta por etiqueta: pbi, bug), más los elementos de trabajo debajo de las Features y Epics en él). El milestone.title de esa lectura es el título para gh issue create --milestone; <key> es su M<n> o sub-número M<n>.<m> (legacy: el título) y nombra el archivo de estado y las pistas. Si falta: preguntar una vez. --max <n> se detiene después de n PBIs entregados, bloqueados o en pausa e imprime el informe (scripts/Invoke-DeliverLoop.ps1 usa --max 1 por sesión nueva, references/loop.md).

• Interactivo (por defecto): una regla de pausa pregunta al usuario en el chat; un PBI bloqueado pregunta: reintentar, saltar o una instrucción.
• Sesión de control: interactivo con más PBIs que deliver.loopThreshold (por defecto 3), por ejemplo cada --milestone: no entregarlos aquí, iniciar Invoke-DeliverLoop.ps1 y permanecer como una sesión ligera para decisiones, PBIs interactive y paso 9 (references/control.md). --inline los entrega todos en esta sesión (pasos 1 a 9). --no-preflight omite Inicio 3.
• --unattended (claude -p, opencode run, copilot -p): nunca preguntar. Una pausa comenta en el issue, añade la etiqueta needs-decision y continúa con el siguiente PBI que no dependa de él.

Inicio

1. gh auth status funciona y el repositorio tiene release/next.
2. gh api repos/{owner}/{repo}/rules/branches/release/next --jq '.[].type': ningún required_status_checks en la salida → advertir que CI rojo es fusionable aquí (conjunto de reglas de github-release), luego continuar.
3. Preflight (omitido por --no-preflight): pwsh <skill-dir>/scripts/Test-DeliverPreflight.ps1 -Harness <claude|opencode|copilot> [-Unattended] -Text imprime una línea por verificación, ok / arreglado / acción necesaria: habilidades apiladas, lista blanca (git, gh, pwsh <skill-dir>/scripts/*, los comandos de verificación de AGENTS.md; entradas por plataforma: references/permissions.md, de lo contrario una ejecución desatendida se cuelga en un prompt), worktrees obsoletos; reacciones en references/preflight.md. Escribir comandos sin $(…) entrecomillado; la verificación de permisos no puede ver a través de ellos.
4. Eventos de progreso: sin AGENT_EVENTS_RUN ejecutar pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type run.started -Source session y mantener el ID de ejecución impreso. Añadir -Run <id> a cada llamada posterior (step.finished, attention, issue.finished, run.finished): las llamadas de Bash no comparten estado de shell, y AGENT_EVENTS_RUN como prefijo no coincidiría con la lista blanca. Cada línea de progreso, razón de atención y el final pasan por Report-Progress.ps1; los muestra en cualquier terminal en la que se ejecute la sesión (references/terminal-backends.md).

Pasos

Imprimir una línea por paso en el chat: #<nr> <paso>: <resultado> (#12 review: 1 bloqueante → arreglar 1/2). Reportar cada línea: pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type step.finished -Issue <nr> -Step <paso> -Result "<resultado>" [-Pr <url>]. También -Type attention (-Kind pr_opened con -Pr <url> después del paso 6, review_fix cuando una revisión o ronda de CI inicia una ronda de arreglos, ci_red cuando el paso 7 está rojo; -Reason): las notificaciones del bucle provienen solo de estos eventos. Una pausa, un PBI bloqueado o un punto que necesita al usuario: -Type attention (-Kind paused, blocked o needs_you, -Reason) en su lugar. Después de cada PBI -Type issue.finished -Issue <nr> -Outcome <resultado>.

Cada PR e issue que el chat nombra se escribe como su URL completa (https://github.com/<owner>/<repo>/pull/<n>, .../issues/<n>), no como un #<n> simple: un número simple no es un enlace en la terminal. Esto es válido para las líneas de progreso, las preguntas al usuario y el informe, en particular para el PR de lanzamiento (paso 9), que el usuario debe fusionar. Obtener la URL de gh (html_url), nunca construirla de memoria.

1. Seleccionar. gh api repos/{owner}/{repo}/issues/<nr> --jq '{number,title,state,labels:[.labels[].name],body}' para cada número y sus sub-issues (github-issue references/sub-issues.md, recursivamente hasta PBIs y Bugs). Recopilar los elementos de trabajo abiertos (pbi o bug) de todos los números y del hito, eliminar duplicados, mantener aquellos sin needs-decision (uno cuyo cuerpo tenga el criterio ADR se reporta #<nr> select: decision, write the ADR with adr); ordenarlos por sus enlaces bloqueados-por entre todos ellos, los empates mantienen el orden de los argumentos. Con --milestone, un PBI o Bug alcanzado a través de una Feature o Epic del hito que no tiene o tiene otro hito no se entrega (#<nr> select: outside M<n>, skipped, pista: establecer el hito, github-issue references/milestones.md); /deliver <feature> sin --milestone entrega todos sus PBIs. Un PBI cuyo bloqueador aún está abierto y no está en el conjunto espera y se reporta (un bloqueador fuera del hito nunca se entrega). Un PBI o Bug con needs-refinement, o un Bug sin reproducción o criterios de aceptación, se salta (#<nr> select: needs refinement, skipped, pista planner refine <nr>); /deliver <nr> en tal elemento lo rechaza. Desatendido, un PBI con interactive se salta (#<nr> select: interactive, skipped, pista /deliver <nr> en una sesión); el modo interactivo lo entrega, también a través de una Feature, Epic o hito. Un PBI abierto con release-test (el test RC del hito) nunca se selecciona como trabajo, no en los pasos 1 a 8 y no en la sesión de control, tampoco con interactive o como un <nr> explícito: #<nr> select: release test, left for step 9 (con elementos abiertos antes: release test, waits for <n> open items; esperando, no necesita al usuario; references/loop.md). Permanece abierto para el paso 9 y el humano (el test RC se ejecuta en el RC). Saltar un PBI que otra sesión ha reclamado (#<nr> select: claimed, skipped), tomar un reclamo obsoleto (references/claim.md); /deliver <nr> en el PBI mismo lo continúa independientemente del reclamo. Anunciar el PBI que sigue y reclamarlo: gh issue edit <nr> --add-assignee @me; la línea de selección nombra su nivel y modelo (#<nr> select: next (tier standard → sonnet/medium); sin una línea Tier: tier from size M o default; references/roles.md).
   • Una Feature o Epic hijo sin PBIs: cargar planner (interactivo) y grill-me en esta sesión, crear los issues, luego seleccionar de nuevo. Desatendido: comentar y etiquetar needs-decision en su lugar.
2. Reanudar. Rama <type>/<nr>-<slug> (github-issue). git ls-remote --heads origin <branch> y gh api "repos/{owner}/{repo}/pulls?head=<owner>:<branch>&state=open" --jq '.[].number' (el head necesita el prefijo del propietario): una rama existente se continúa, un PR existente salta al paso 7.
3. Implementar. Un subagente con un contexto nuevo: "Cargar implementation, rol implement. Implementar PBI # (un Bug: cargar diagnose primero, luego implementation) en tu propio worktree en <branch> desde origin/release/next (una rama existente: cambiar a ella y hacer rebase). Criterios de aceptación: . Hacer commit, push, reportar en máximo 10 líneas: hecho o bloqueado, commits, tests ejecutados, y notes[] (una por línea); una entrada specMap coincidente sin un cambio de spec da la nota no spec change needed: <spec> — <reason> (implementation references/specs.md)."
4. Revisar. Un subagente con un contexto nuevo: "Cargar code-review, rol review. Revisar git diff origin/release/next...origin/<branch> contra estos criterios de aceptación: . Con governance: ejecutar Get-GovernanceMatches.ps1 -Head origin/<branch>; etiquetas de issue y notes[] del implementador . Solo lectura: no stash, checkout, switch o commit en ningún checkout existente; si necesitas archivos, usa tu propio worktree temporal. Devolver solo JSON: el resultado por review.schema.json de code-review (blocking[] con file, line, title, why; notes[], hasta 5) más unmet[] (criterios no cumplidos)." Solo los hallazgos bloqueantes y los criterios no cumplidos cuentan. Después de cada ronda, esta sesión (no el subagente) escribe el archivo <git-common-dir>/.agents/state/review-<nr>.json (git rev-parse --git-common-dir, el mismo archivo desde cada worktree, nunca comprometido), sobrescribiendo la ronda anterior: { pbi, branch, sha, round, unmet, review }, sha = git rev-parse origin/<branch>, round = ronda de revisión basada en 1, review = el resultado del subagente; esquema schema/deliver-review.schema.json. También pwsh <skill-dir>/../code-review/scripts/ConvertTo-Findings.ps1 -Review <resultado con unmet> -Sha <sha> -Worktree <pbi-worktree> escribe <pbi-worktree>/.agents/state/findings.json para poimen (nunca comprometido, excluido localmente; references/findings.md).
5. Arreglar. Algo cuenta: un subagente con un contexto nuevo carga implementation con rol fix, cambia su propio worktree a <branch> (git fetch origin <branch>, git switch -C <branch> origin/<branch>), obtiene exactamente esos hallazgos (blocking[] y unmet[]), hace commit y push. Luego paso 4 de nuevo. Máximo 2 rondas de arreglos por PBI, compartidas por revisión y CI; una tercera es una pausa.
6. PR. github-pull-request (su título es el título del issue sin el prefijo de nivel, (#<nr>) añadido) con issue_number, branch: <branch> (el trabajo se ha subido desde otro worktree, este checkout permanece como está), review_notes (notes[] del paso 4), con governance spec_notes (las líneas notes[] del implementador que comienzan con no spec change needed:) y el resultado del test del subagente.
7. CI. Ejecutar gh pr checks <pr> --watch --required --interval 60 directamente (cada sondeo es una consulta GraphQL; el valor predeterminado de 10 s agota el presupuesto), sin tubería o filtro de salida (como tail, head o grep), para que el progreso de vigilancia llegue a la sesión.
   • Rojo por este cambio (error de test, lint o compilación en archivos del diff): ronda de arreglos (paso 5), luego paso 4 y 7 de nuevo.
   • Rojo por otra razón (fallo intermitente, rojo también en release/next): comentar en el PR, el PBI está bloqueado.
8. Fusionar. Sin preguntar, en ambos modos: la última revisión no tuvo hallazgos bloqueantes o criterios no cumplidos y los checks requeridos están verdes. gh pr merge <pr> --squash --delete-branch, luego gh issue close <nr> --comment "Delivered in #<pr>" (Closes no se activa en release/next); los sub-issues legacy [Task] abiertos del PBI se cierran con él (github-issue references/sub-issues.md, "Legacy Task issues"); luego gh issue edit <nr> --remove-assignee @me. Limpiar los worktrees y ramas de los subagentes con el script de esta habilidad, scripts/Remove-PbiWorktrees.ps1 en el directorio de la habilidad (~/.claude/skills/deliver/ global, .claude/skills/deliver/ instalación del proyecto), ejecutar desde el repositorio: pwsh <skill-dir>/scripts/Remove-PbiWorktrees.ps1 -Pr <pr> -Issue <nr>; imprimir #<nr> cleanup: <n> removed y mantener sus entradas left (ruta o rama, razón, comando) para el informe. Siguiente PBI: paso 1.
9. Lanzamiento. Solo con --milestone, antes del informe (también después de --max), cuando no quede ningún PBI para seleccionar. Leer el hito una vez, Get-Milestones.ps1 -Mode issues -Name <nombre> -State all (abiertos y cerrados); la verificación de trabajo abierto, el marcador, el recuento de rondas y los criterios de los issues cerrados provienen de esa lista. Ningún issue abierto etiquetado como pbi o bug en él excepto el issue release-test (nada bloqueado, en pausa, esperando o saltado); el test RC nunca bloquea.
   • Un PBI o Bug cerrado del hito etiquetado como needs-decision es el marcador de pausa de una revisión de lanzamiento de ronda 3: saltar la revisión, imprimir release: paused in round 3, waits for a decision.
   • Revisión de lanzamiento (references/release-review.md): un subagente con un contexto nuevo carga code-review, rol review, en git diff origin/main...origin/release/next con los criterios de aceptación de los PBIs y Bugs cerrados del hito, enfoque en consistencia entre PBIs, y devuelve JSON por review.schema.json, solo lectura (no stash, checkout, switch o commit en ningún checkout existente; propio worktree temporal si necesita archivos); esta sesión escribe <git-common-dir>/.agents/state/release-review-<key>.json.
   • Hallazgos bloqueantes: un issue [Bug] fix: … por hallazgo en el hito (interactivo: mostrarlos y preguntar primero), sin PR de lanzamiento; imprimir release: <n> blocking → #a, #b. Máximo 2 rondas de revisión de lanzamiento por hito; una tercera con hallazgos bloqueantes es una pausa, registrada con ese marcador y un comentario nombrando las dos formas de continuar (references/release-review.md, "Pause marker").
   • Limpio (ninguno bloqueante): cortar el RC, publicarlo en el issue release-test y cerrar los más antiguos (references/release-review.md, "RC test"); release.test.gate: true se detiene ahí con needs you: RC test <URL del issue> hasta que el issue se cierre. De lo contrario, cargar github-release y ejecutar finish con release_review_notes (los notes[], hasta 5): abre el PR de lanzamiento desde release/next hacia main (auto_merge: false) o reporta el existente; se detiene cuando main no es un ancestro de release/next (hacer back-merge primero, github-release), reportar esa detención. Imprimir release: PR #<nr> listo para fusionar y nada más.