rig-epic (rig-epe)

rig-epic — workflow de branch de integração

Para arcos de vários itens onde pousar cada item diretamente no tronco quebraria temporariamente o contrato de runtime, empilhe os PRs filhos em uma branch de integração compartilhada e faça squash dessa branch no tronco como um PR no final. Cada PR filho é revisado como o passo que ele realmente é; a entrega vinculada ao tronco é um rebase com squash.

Configuração

Lê .rig/config.json (padrões entre parênteses):

• tracker.provider — linear | github | none (none). Como os itens pai/filho são armazenados. none → os itens vivem apenas no arquivo de estado do epic (abaixo); sem chamadas de rastreador.
• tracker.team / tracker.project / tracker.ticketPrefix / tracker.githubIntegration.
• vcs.baseRef (origin/main), vcs.defaultBranch (main), vcs.protectedBranchMergeQueue (false).
• sourceScope[0] — onde explorar durante plan.
• agents.architect / agents.reviewer (padrão rig-<role>) — para o painel review com contexto novo.

Delega para /rig-task (por filho), /rig-worktree (checkouts), /rig-review

• /rig-review fix (a revisão de diff combinada), /rig-tidy (opcional).

Arquivo de estado do epic (substitui qualquer memória externa)

Cada epic ativo é rastreado em um arquivo JSON local do repositório em .rig/epics/<branch-de-integracao>.json:

{
  "parent": "ABC-42 ou um slug em rastreador=none",
  "parentTitle": "…",
  "integrationBranch": "abc-42-<slug>",
  "whyEpic": "quais filhos se intercalam e porquê",
  "children": [
    { "id": "ABC-43", "title": "…", "blockedBy": [], "branch": null, "status": "todo|merged" }
  ]
}

Esta é a fonte única da verdade que next/run/review/finish/prune leem. Adicione .rig/epics/ ao .gitignore (é estado de coordenação transitório). Inferência do pai (quando <PARENT> é omitido): se exatamente um .rig/epics/*.json existir, use-o; se zero ou muitos, pergunte.

Banner de intenção: toda invocação DEVE imprimir uma linha primeiro — modo, qual branch os PRs miram, o que não fará:

rig-epic: <subcomando> — <ação>. PRs miram <branch>. Não fará <coisa>.

status (padrão, apenas relatório)

Leia o(s) arquivo(s) de estado do epic. Relate: branch de integração + commits à frente de vcs.baseRef; PRs filhos abertos (gh pr list --base <branch-de-integracao>) e seu estado; o status do rastreador de cada filho (se houver um rastreador); worktrees restantes mescladas/excluídas (sugira /rig-epic prune); e uma recomendação de uma linha (abrir PR filho X, pronto para /rig-epic next, ou pronto para /rig-epic finish). Não modifique nada; não crie nada.

plan <FEATURE>

Decomponha um recurso em um pai + 3–8 filhos, escreva o arquivo de estado, então encadeie em start.

Use isso apenas quando o trabalho for genuinamente em forma de epic (filhos se intercalam — pelo menos o contrato de runtime de um filho depende de outro estar parcialmente completo). Se os itens forem independentes e cada um puder pousar no tronco sozinho, pare e diga ao usuário para executar /rig-sprint plan — mesma decomposição, sem branch de integração.

Procedimento

1. Leia o contexto. Documentos de produto/especificação se o projeto os tiver (pergunte se não tiver certeza); explore o código-fonte (sourceScope[0]) para ver o que existe. Se um rastreador estiver configurado, pesquise primeiro por itens quase duplicados.
2. Verifique se é um epic (de acordo com o teste de intercalação acima). Se não → envie para /rig-sprint plan.
3. Crie o pai.
   • tracker: linear/github → crie o item pai (time/projeto da configuração); a descrição cobre Visão Geral, por que é um epic e os filhos planejados.
   • tracker: none → o pai é um slug + título registrado apenas no arquivo de estado.
4. Crie cada filho com suas arestas de dependência.
   • Pequeno o suficiente para uma sessão de agente (1–3 arquivos); critérios de aceitação concretos e testáveis; trabalho fundamental primeiro.
   • Registre blockedBy para cada dependência real — isso é o que next lê para escolher o próximo filho desbloqueado. Sem ele, a escolha volta à ordem de declaração e erra os epics intercalados.
   • Modo rastreador: defina as relações nativas de pai/bloqueado-por do rastreador e espelhe-as no arquivo de estado. none: apenas arquivo de estado.
5. Mostre uma tabela de resumo (ID · Título · Depende De).
6. Encadeie em start <PARENT> — plan é planejar e iniciar; não pare para perguntar.
7. Pare após start. Relate a branch de integração, os filhos e o próximo passo (/rig-epic next para um, /rig-epic run para o loop). Nunca inicie run automaticamente — a execução é uma aceitação explícita.

start <PARENT>

Pré-voo: git fetch origin; confirme que o pai e pelo menos um filho existem (no rastreador, ou como argumentos para none).

1. Nome da branch de integração: <slug-do-pai>-<slug-do-titulo> (kebab, ex.: abc-42-agent-as-definition).
2. Corte a branch de integração de vcs.baseRef sem um checkout local:

   git fetch origin
   git push origin <vcs.baseRef>:refs/heads/<branch-de-integracao>
   

   Não destrutivo. Se a branch já existir, deixe-a (nunca sobrescreva — poderia destruir trabalho em andamento).
3. Escreva .rig/epics/<branch-de-integracao>.json (esquema acima) com o pai, por que epic e cada filho + blockedBy. Isso é o que faz cada /rig-task <child> mirar a branch de integração em vez do tronco.
4. Se um rastreador estiver configurado, adicione uma nota "Branch de integração: alvo <branch-de-integracao>, não o tronco" a cada filho para que o próximo agente não releia esta skill e garanta que o pai está Em Andamento (adaptativo: mova-o apenas se já não tiver sido iniciado; adie se uma integração ativa o fez). Os filhos recebem seu próprio Em Andamento de seu /rig-task Passo 1.
5. Nomeie a sessão "EPIC: <título do pai> (<pai>)" via scripts/set-session-name.sh (apenas Claude-Code; sem operação em outros lugares) para que a lista de trabalhos em segundo plano leia como o epic. Os filhos definem seus próprios nomes FEAT:/CHORE: com --skip-if-prefix "EPIC:", para que este rótulo de epic permaneça no topo.
6. Relate a branch, os filhos e o próximo passo.

next (filho único)

1. Resolva a branch de integração ativa (uma esperada; pergunte se muitas). Se a sessão já não estiver nomeada como EPIC:- (ou seja, next invocado diretamente, não via start), nomeie-a "EPIC: <título do pai> (<pai>)" (apenas Claude-Code).
2. Escolha o próximo filho desbloqueado: o primeiro filho não concluído cujo blockedBy estejam todos mesclados na branch de integração. Declare a escolha + raciocínio no banner.
3. Garanta que o filho anterior pousou. Com --auto-merge (Passo 4), cada PR do filho mescla na branch de integração por conta própria assim que o CI passa, então a ponta da integração avança automaticamente — apenas git fetch origin e confirme. (Alternativa para um filho executado sem --auto-merge: fast-forward a branch sobre sua ponta — git push origin origin/<branch-filho-anterior>:refs/heads/<branch-de-integracao>, que fecha automaticamente aquele PR como MERGED. Seguro para reexecutar.)
4. Execute /rig-task <CHILD> --base <branch-de-integracao> --auto-merge (adicione --spec-cleared quando a revisão de especificação frontal de run já tiver liberado as especificações) — --base faz a worktree do filho ramificar de, e seu PR mirar, a branch de integração; --auto-merge faz o filho habilitar gh pr merge --squash --auto em seu próprio PR assim que a revisão estiver limpa, para que CI o pouse na branch de integração (sempre squash — não faça rebase-merge; muitos repositórios o proíbem. Se a branch de integração não tiver verificações obrigatórias, o filho mescla diretamente). Execute um único disparo (iniciar→finalizar); ele retorna uma única string de resultado para a porta de mesclagem.
5. Porta de mesclagem — apenas clean é verde para mesclagem:
   • clean → o filho habilitou o auto-merge, então seu PR pousa quando o CI passa. Aguarde por ele: pesquise gh pr view <N> --json state (~60s, até ~30min) até MERGED, então git fetch origin e confirme que a ponta avançou. Registre o filho merged + sua branch no arquivo de estado e garanta que o ticket do filho está Concluído (adaptativo — mova apenas se já não estiver Concluído; adie se uma integração ativa o fechou). Se o CI falhar / nunca mesclar → trate como não limpo.
   • qualquer outra coisa (actionable/timeout, ou um estado estacionado no rastreador) → o filho não habilitou o auto-merge; pare. Exiba o resultado, a URL do PR e qualquer resumo do revisor. Aguarde o usuário; não tente novamente uma revisão estacionada.

next faz exatamente um filho. Use run para o loop.

run [--advisor]

Revisão de especificação frontal — uma vez, antes do loop. Revise todos as especificações dos filhos juntos, com antecedência, em vez de descobrir bloqueadores um filho de cada vez no meio da execução. Um filho que pausa em uma questão de especificação trava todo o epic (e sob execução paralela ou durável, um filho pausado pode falhar o lote completamente), então resolva as especificações antes que qualquer filho comece a codificar:

1. Distribua agents.architect + agents.qa sobre a especificação de cada filho, lida contra a branch de integração; cada um retorna seus bloqueadores.
2. Consolide em uma lista de bloqueadores e resolva-a uma vez — esclareça no rastreador, ou decida com o usuário. Este é o único ponto de decisão de especificação do epic.
3. Então execute cada filho com sua porta de especificação pré-limpa: /rig-task <CHILD> --base <branch-de-integracao> --auto-merge --spec-cleared, para que nenhum filho pause novamente em uma pergunta já respondida.

Esta é a passagem de especificação pré-codificação; a review de diff combinada (abaixo) é a passagem de código pós-mesclagem — portas diferentes.

--advisor (não supervisionado). Decida aquela porta frontal com uma passagem de advisor em vez de um humano: uma revisão delegada de agents.architect lê as especificações do arquiteto + QA e prossegue com direção por filho sintetizada (entregue literalmente ao codificador de cada filho), ou para com um relatório bloqueado nomeando o que um humano deve decidir. Nenhum humano espera, então o epic executa sem intervenção para PRs filhos, um bloqueador genuíno ainda o para em vez de se espalhar em uma especificação ruim. (O workflow durável Smithers emparelhado implementa isso com um modelo barato — o "advisor Fable" — para que epics iniciados nunca estacionem na porta.)

Em seguida, faça loop next até que nenhum filho desbloqueado permaneça:

while um filho desbloqueado existir:
  execute /rig-epic next            # filhos executam --spec-cleared (especificação foi frontal)
  se parou sem mesclar (resultado ≠ clean) → pare, devolva
  senão → reavalie filhos desbloqueados

Quando a fila esvaziar, relate "epic pronto para /rig-epic finish."

review [<PARENT>]

Execute após o último filho mesclado na branch de integração, antes de finish. A revisão por PR (/rig-review dentro de cada /rig-task) vê cada filho em isolamento; esta vê a forma combinada e a simplificação apenas visível quando tudo está dentro. Subagentes de contexto novo (entrada = o diff com squash + títulos dos PRs filhos) não podem herdar as racionalizações lembradas do implementador.

Execute antes de prune — os subagentes de revisão precisam de um checkout funcional; reutilize uma worktree de filho se ainda existir (evita uma instalação nova + re-link simbólico de env).

1. Resolva a branch de integração; git fetch origin.
2. Garanta uma worktree da branch de integração ($WT). Reutilize uma worktree de filho mesclado com fast-forward para a ponta da integração, caso contrário, crie uma com /rig-worktree (--base <branch-de-integracao> --reuse).
3. Distribua três subagentes em paralelo (uma mensagem, três chamadas Agent), cada um fazendo cd em $WT com a ponta da integração verificada:
   • Lente 1 — Simplificação (agents.architect): diff git diff <vcs.baseRef>...HEAD; lista de PRs filhos via gh pr list --base <BR> --state merged. Mandato: encontre abstrações para colapsar, helpers que um PR adicionou que a forma final de outro PR tornou redundantes, botões de configuração que ninguém define, caminhos de código que o diff combinado tornou mortos, tipos de um chamador. Exclusões/mesclagens concretas, arquivo:linha, maior impacto primeiro. Pule correção.
   • Lente 2 — Correção cruzada entre PRs (agents.reviewer): percorra o catálogo de padrões de revisão do projeto (review.patternsFile) contra o diff combinado. A revisão por PR já foi executada; pegue interações apenas visíveis na forma mesclada (helper do PR-A vs chamador obsoleto do PR-D; PR-B removeu um botão que o PR-F ainda lê). P0/P1/P2 com arquivo:linha + categoria.
   • Lente 3 — Código morto e referências obsoletas (agents.reviewer): para cada símbolo que o diff adicionou, ele é chamado em outro lugar? Para cada símbolo removido, grep na árvore (workflows, manifestos, IaC, scripts, docs) por referências residuais. Relate com arquivo:linha.
4. Consolide — deduplique, produza uma lista P0/P1/P2 agrupada por lente, imprima contagens.
5. Triagem:
   • 0 itens → clean — pronto para /rig-epic finish, pare.
   • descobertas → pergunte via AskUserQuestion: aplicar agora / pular e finalizar mesmo assim (rebaixar para acompanhamentos) / pausar. Em aplicar agora, execute /rig-review fix --source local em $WT (cria agents.coder, reavalia até limpar), commite + git push origin <branch-de-integracao>, reexecute review uma vez para confirmar convergência.
6. String de resultado (para finish): clean — … / applied — … / paused — ….

finish [<PARENT>] [--merge]

Faça squash de toda a branch de integração em um único PR para o tronco. Padrão: abra o PR e pare — este é o único PR para ser examinado.

review é uma porta rígida. finish sempre executa review primeiro; o PR com squash abre apenas em clean ou applied. Em paused, pare e aguarde.

1. Execute review (porta) inline; ramifique em seu resultado (clean/applied → prossiga; paused → pare e imprima descobertas pendentes).
2. Atualize e faça rebase se necessário. git fetch origin; liste git log <vcs.baseRef>..origin/<branch-de-integracao> --oneline. Se o tronco moveu, faça rebase da branch de integração sobre ele primeiro (git rebase <vcs.baseRef> em uma cópia local, então git push --force-with-lease origin <local>:<branch-de-integracao>).
3. Abra o PR final para vcs.defaultBranch com um título referenciando o pai e um corpo resumindo todos os filhos. Em um rastreador com um verbo de fechamento (Fixes <PARENT> / Closes #<n>), inclua-o para que o pai auto-fecha...