Ciclos de Vida

O SpecForge opera como dois lifecycles interconectados — planejamento e trabalho. Cada um tem uma entrada clara, um gate de qualidade e um caminho de feedback. Nada avança sem aprovação.

Os Dois Lifecycles

Lifecycle de Planejamento — Da Ideia à Spec Executável

O lifecycle de planejamento transforma uma descrição em linguagem natural em um plano de execução estruturado. Você descreve o que quer. O motor (através do seu agente de código via MCP) decompõe em épicos, tickets e um grafo de dependência. O gate de Planning Review valida tudo antes de uma única linha de código ser escrita.

Entrada: Uma especificação com título e descrição.

O que acontece:

1. Definir — Você cria uma especificação. Descreve a feature, seus objetivos, restrições e contexto técnico. Isso pode acontecer na webapp ou pela CLI.

2. Decompor — Seu agente de código (via ferramentas MCP) divide a descrição em épicos e tickets. Cada ticket recebe passos de implementação, critérios de aceite e expectativas de arquivo. Dependências são mapeadas em um grafo acíclico direcionado.

3. Refinar — Você (ou o agente) itera no plano. Adiciona tickets faltando, ajusta dependências, vincula blueprints, esclarece critérios de aceite. É aqui que a especificação fica afiada. Durante todo o refinamento a especificação fica no único estado planning; a sessão de planejamento avança pela sua própria máquina de 7 fases conforme você cria estrutura, vincula dependências e executa verificações de qualidade.

4. Revisar — O gate de Planning Review (dentro de complete_planning_session) avalia a especificação em cinco dimensões: completude, dependências, cobertura, qualidade de ticket e critérios de aceite. Cada uma produz uma pontuação. A pontuação geral deve atingir o limite (padrão: 80).

Se aprovado: A especificação avança para ready. A implementação pode começar.

Se reprovado: O gate retorna achados específicos — quais tickets não têm critérios de aceite, quais dependências são circulares, quais requirements da descrição não são cobertos por nenhum ticket. Você volta para Refinar com feedback acionável. Não ao ponto zero — correções direcionadas.

💡 O lifecycle de planejamento é onde o trabalho mais importante acontece. Uma especificação bem planejada com tickets claros, dependências corretas e blueprints vinculados produz implementações limpas. Uma especificação planejada apressadamente produz retrabalho. O Planning Review existe para capturar isso antes de você gastar tokens com implementação.

Lifecycle de Trabalho — Agentes Executam em Ordem de Dependência

O lifecycle de trabalho é onde código é escrito. Agentes pegam tickets ready, implementam, e ao completar automaticamente desbloqueiam tickets dependentes. O grafo de dependência dirige tudo — nenhuma coordenação manual necessária. Cada ticket carrega seu próprio gate de qualidade: um assay por ticket roda dentro de complete_work_session, então a qualidade é verificada conforme cada ticket é entregue, e não em um único review em massa no final.

Entrada: Uma especificação em estado ready com tickets em status ready.

O que acontece:

1. Claim — O agente (ou orquestrador no Agent Teams) chama get_next_actionable_tickets para encontrar tickets com todas as dependências satisfeitas. Estas são a wave atual — trabalho que pode acontecer em paralelo com segurança.

2. Executar — O agente abre uma work session em um ticket. Recebe o contexto completo de implementação: passos, critérios de aceite, expectativas de arquivo, outputs de dependência e blueprints vinculados. Escreve código, roda testes, reporta progresso.

3. Completar — O agente fecha a work session com um resumo e resultados de validação. complete_work_session roda o gate de assay do ticket — pontuando conclusão de passos, critérios de aceite, entrega de arquivos, evidência git e testes. Quando o assay passa, o ticket transiciona para done.

4. Cascata — Completar um ticket dispara recálculo. Todo ticket que dependia do completado é reavaliado. Se todas suas dependências agora estão done, transiciona de pending para ready — juntando-se à próxima wave. Quando todos os tickets em um épico estão done, o épico auto-completa. Quando todos os épicos completam, a especificação é marcada como done.

Se bloqueado: Se um agente descobre um bloqueador externo durante a implementação (algo não capturado no plano original), reporta um motivo de bloqueio. O status do ticket passa a ser blocked — um estado de primeira classe, diferente de pending. O bloqueio é visível no painel e em get_blocked_tickets. O agente ou um humano resolve o bloqueador, limpa-o, e o ticket se torna trabalhável novamente.

Se interrompido: Se uma sessão do agente termina, a work session permanece aberta e o progresso é preservado. Um agente diferente (ou o mesmo agente em uma nova sessão) pode continuar chamando start_work_session no mesmo ticket. Isso lida com resets de janela de contexto, implementações de vários dias e checkpoints manuais.

Resolução humana: Uma work session completada pode ser revisada por um humano. O veredito é registrado como um WorkSessionResolution na sessão daquele ticket — uma aprovação ou um pedido de mudanças com escopo no ticket. Isso é por ticket, não um gate de nível de spec: não há um lifecycle de revisão separado pelo qual a especificação inteira passa depois da implementação.

💡 O lifecycle de trabalho é auto-dirigido uma vez iniciado. O orquestrador não precisa sequenciar trabalho manualmente — o grafo de dependência produz waves automaticamente. Cada ticket completado potencialmente desbloqueia o próximo lote de trabalho paralelo. O papel do humano é monitorar, não coordenar.

Como os Lifecycles Se Conectam

Os dois lifecycles não são independentes — formam um pipeline com gates entre os estágios:

Definir → Decompor → Refinar → [Gate 1: Planning Review ≥ 80] → Executar → [Gate 2: assay por ticket em cada complete_work_session] → Cascata → Done

Gate 1 (Planning Review) fica entre o lifecycle de planejamento e o lifecycle de trabalho. Responde: “Este plano é bom o suficiente para gastar tokens implementando?” Roda uma vez, no nível da especificação, dentro de complete_planning_session.

Gate 2 (o assay por ticket) fica dentro de cada work session, no momento em que um ticket é completado. Responde: “O agente realmente construiu o que este ticket pediu?” Roda por ticket, dentro de complete_work_session — não como um review de nível de spec depois que todos os tickets estão done.

Falha no Gate 1, e você volta ao planejamento — barato, sem código desperdiçado. Falha o assay em um ticket, e apenas aquele ticket volta — correções direcionadas, não uma reimplementação completa.

Por isso dois gates existem ao invés de um. Um único review de fim de execução capturaria tudo eventualmente — mas só depois que agentes já gastaram tempo e tokens implementando um plano falho ou empilhando tickets completados sobre um quebrado. Gate 1 captura problemas estruturais antes de qualquer código ser escrito. O assay por ticket captura problemas de execução no momento em que cada ticket é entregue.

A Fase de Planejamento

A fase de planejamento tem sua própria máquina de estados interna que vale entender — mas ela roda na sessão de planejamento, não na especificação. Durante todo o planejamento a especificação fica em um único estado planning. A sessão avança por sete fases:

planning_spec → epic_decomposition → epic_expansion → ticket_decomposition → ticket_expansion → cross_validation → planned

Você não gerencia essas transições de fase. O SpecForge rastreia a natureza das suas operações — criar estrutura, vincular dependências, executar verificações de qualidade — e avança a fase da sessão de acordo. É projetado para refinamento iterativo. Crie tickets, vincule dependências, verifique cobertura, crie mais tickets, re-verifique — a sessão segue você enquanto a especificação permanece em planning.

Uma vez que o Planning Review passa, a especificação sai de planning e entra em ready. De lá, só pode avançar para implementação. Para reabrir o planejamento, você deve explicitamente reabrir a especificação — uma ação deliberada que reconhece que o plano precisa de retrabalho.

Caminhos de Falha

O caminho feliz é linear: planejar → gate 1 → implementar (cada ticket passa no seu assay) → done. Mas projetos reais nem sempre são lineares. Veja o que acontece quando as coisas dão errado:

Planning Review Falha

A especificação permanece em planning. O gate retorna achados específicos. Você corrige (adiciona critérios de aceite faltando, resolve dependências circulares, adiciona cobertura para lacunas) e re-executa o review. Nenhum estado é perdido — todo trabalho feito até agora é preservado.

Ticket É Bloqueado Durante a Implementação

O ticket move para blocked (um status de primeira classe) com um motivo de bloqueio. Outros tickets continuam — o bloqueio afeta apenas este ticket e seus dependentes downstream. O bloqueio é visível no painel. Resolva o bloqueador, limpe o motivo, e o ticket recalcula seu estado.

Um Ticket Falha no Seu Gate de Assay

Quando complete_work_session roda o assay do ticket e o ticket fica aquém — passos deixados incompletos, critérios de aceite não atendidos, arquivos esperados faltando, ou evidência de teste ausente — o assay retorna achados para aquele ticket e ele não avança para done. Você endereça os achados apenas naquele ticket e completa a sessão novamente. Tickets que já passaram não são afetados.

Especificação Precisa Ser Reaberta

Uma especificação done pode ser reaberta com reopen_specification. Isso move de volta para in_progress, permitindo resetar tickets específicos e reimplementá-los. Use quando testes pós-deploy revelam problemas que precisam ser endereçados dentro do escopo da especificação.

⚠️ Reabrir é uma ação deliberada. Work sessions ativas devem ser completadas ou resetadas primeiro. A especificação não regride silenciosamente — você está tomando uma decisão consciente de revisitar trabalho concluído.

Onde Estou?

Um guia prático para “estou olhando minha especificação e não sei o que fazer a seguir”:

Veja Também

• Especificações — A unidade de planejamento com anatomia completa
• Épicos & Tickets — As unidades de execução dentro de uma especificação
• Gates de Qualidade — O Planning Review e o gate de assay por ticket em detalhe
• Sessões de Trabalho — Como agentes executam tickets
• Estados da Especificação — Referência completa da máquina de estados