Ciclos de Vida

O SpecForge opera como três ciclos interconectados. Cada ciclo tem uma entrada clara, um gate de qualidade e um caminho de feedback. Nada avança sem aprovação.

Os Três Ciclos

Ciclo de Planejamento — Da Ideia à Spec Executável

O ciclo 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. O corredor de planejamento (planning ↔ specifying ↔ validating) lida com transições de estado automaticamente baseado nas operações que você realiza — criar estrutura, vincular dependências ou executar verificações de qualidade.

4. Revisar — O gate de Planning Review 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 ciclo 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.

Ciclo de Implementação — Agentes Executam em Ordem de Dependência

O ciclo de implementação é 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.

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. 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 avança para ready_for_review.

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 ticket reverte para 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 pausado: Work sessions podem ser pausadas e retomadas. Progresso é preservado. Um agente diferente (ou o mesmo agente em uma nova sessão) pode continuar de onde parou. Isso lida com resets de janela de contexto, implementações de vários dias e checkpoints de review manual.

💡 O ciclo de implementação é 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.

Ciclo de Revisão — Garantia de Qualidade Antes da Entrega

O ciclo de revisão valida o trabalho implementado contra a especificação original. Dois gates guardam a qualidade — Planning Review antes do código (coberto acima) e Implementation Review depois do código. Ambos produzem pontuações, ambos devem passar. Nada é entregue sem aprovação.

Entrada: Uma especificação em estado ready_for_review (todos os tickets done).

O que acontece:

1. Disparar — O review pode ser disparado manualmente via CLI ou MCP, ou automaticamente quando todos os tickets completam.

2. Avaliar — O gate de Implementation Review verifica cinco dimensões: conclusão de passos, satisfação de critérios de aceite, entrega de arquivos, evidência git e resultados de teste. Cada dimensão pode ser habilitada/desabilitada independentemente nos padrões de qualidade do seu projeto.

3. Pontuar — Cada dimensão produz uma pontuação de 0 a 100. A pontuação geral deve atingir o limite.

4. Veredito — Aprovado ou reprovado.

Se aprovado: A especificação avança para reviewed, depois para completed após confirmação final. O trabalho está feito.

Se reprovado: O gate retorna um relatório detalhado de achados. Quais tickets têm passos incompletos. Quais critérios de aceite não foram atendidos. Quais arquivos eram esperados mas não entregues. Quais tickets estão sem evidência de teste. A especificação permanece em in_review — você endereça os achados (reabre tickets específicos, corrige os problemas, re-executa o review) sem começar do zero.

ℹ️ maxReviewAttempts (padrão: 3) limita retentativas antes de exigir intervenção manual. Isso previne loops infinitos em especificações com problemas fundamentais que o review automatizado não consegue resolver.

Como os Ciclos Se Conectam

Os três ciclos não são independentes — formam um pipeline com gates entre cada estágio:

Definir → Decompor → Refinar → [Gate 1: Planning Review ≥ 80] → Executar → Cascata → [Gate 2: Implementation Review ≥ 80] → Entregar

Gate 1 (Planning Review) fica entre o Ciclo de Planejamento e o Ciclo de Implementação. Responde: “Este plano é bom o suficiente para gastar tokens implementando?”

Gate 2 (Implementation Review) fica entre o Ciclo de Implementação e a entrega. Responde: “Os agentes realmente construíram o que a spec pediu?”

Falha no Gate 1, e você volta ao planejamento — barato, sem código desperdiçado. Falha no Gate 2, e você volta a tickets específicos — correções direcionadas, não uma reimplementação completa.

Por isso dois gates existem ao invés de um. Um único review pós-implementação capturaria tudo eventualmente — mas só depois que agentes já gastaram tempo e tokens implementando um plano falho. Gate 1 captura problemas estruturais antes de qualquer código ser escrito. Gate 2 captura problemas de execução depois.

O Corredor de Planejamento

A fase de planejamento tem sua própria máquina de estados interna que vale entender. Três estados — planning, specifying, validating — formam um corredor que transiciona automaticamente baseado no que você está fazendo:

• Operações estruturais (criar épicos, criar tickets, deletar) → move para planning
• Operações de vinculação (adicionar dependências, vincular blueprints) → move para specifying
• Operações de avaliação (solicitar relatórios, executar verificações de qualidade) → move para validating

Você não gerencia essas transições. O SpecForge rastreia a natureza das suas operações e transiciona de acordo. O corredor é projetado para refinamento iterativo. Crie tickets, vincule dependências, verifique cobertura, crie mais tickets, re-verifique — o estado segue você.

Uma vez que o Planning Review passa, a especificação sai do corredor e entra em ready. De lá, só pode avançar para implementação. Para re-entrar no corredor de 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 → gate 2 → feito. 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 no corredor de planejamento. 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 reverte para pending 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.

Implementation Review Falha

A especificação permanece em in_review. O gate identifica quais tickets têm problemas. Você reabre esses tickets específicos, corrige-os e re-executa o review. Tickets que passaram não são afetados.

Especificação Precisa Ser Reaberta

Uma especificação completada ou revisada 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 — Os dois gates em detalhe
• Sessões de Trabalho — Como agentes executam tickets
• Estados da Especificação — Referência completa da máquina de estados