Estados da Especificação

Referência de máquina de estados para especificações — todos os 5 estados, transições e regras.

Toda especificação se move por um ciclo de vida de 5 estados. Transições são disparadas por ações de usuário, chamadas de ferramentas e avaliações automáticas.

Máquina de estados da especificação: 5 estados com setas de transição

Referência Rápida

Estado	Você deve…
`draft`	Começar a planejar — criar seu primeiro épico ou ticket
`planning`	Continuar construindo estrutura (épicos, tickets, dependências, blueprints)
`ready`	Começar a implementação — lançar seu agente
`in_progress`	Monitorar painel, resolver bloqueios
`done`	Feito 🎉

Estados

Estado	Fase	Descrição
`draft`	Planejamento	Estado inicial. Especificação criada mas planejamento não iniciado.
`planning`	Planejamento	Épicos, tickets, dependências e blueprints estão sendo definidos. A sessão de planejamento avança por suas próprias fases enquanto a especificação permanece em `planning`.
`ready`	Planejamento	Planejamento completo. Especificação passou no gate de Planning Review.
`in_progress`	Implementação	Work sessions ativas. Tickets sendo implementados.
`done`	Implementação	Todos os tickets completos. Especificação está fechada. Este é o estado terminal.

Tabela de Transições

Gatilho	De	Para	Condição
Épico criado	`draft`	`planning`	Primeiro épico adicionado
Ticket criado	`draft`	`planning`	Primeiro ticket adicionado
Planning review passou	`planning`	`ready`	Planning gate passa o limite dentro de `complete_planning_session`
Work session iniciada	`ready`	`in_progress`	Primeira chamada `start_work_session`
Todos tickets completados	`in_progress`	`done`	Todo ticket alcança `done`
Especificação reaberta	`done`	`in_progress`	`reopen_specification` chamado

O Estado `planning`

Uma especificação tem um único estado planning — não existe um corredor de sub-estados de planejamento com auto-transição no nível da especificação. Todo o trabalho estrutural (criar épicos, criar tickets, adicionar dependências, vincular blueprints) acontece enquanto a especificação está em planning.

A máquina de planejamento de 7 fases — planning_spec, epic_decomposition, epic_expansion, ticket_decomposition, ticket_expansion, cross_validation, planned — avança na PlanningSession, não na especificação. A especificação permanece em planning durante toda a sessão e move para ready apenas quando o gate de Planning Review da sessão passa dentro de complete_planning_session.

ℹ️ Você não avança a especificação manualmente pelo planejamento. Dirija a sessão de planejamento com operações action_planning_session; a sessão rastreia a fase e a especificação avança para ready quando o gate passa.

Auto-Transições

Várias transições acontecem automaticamente sem ação explícita do usuário:

Evento	Transição	Descrição
Primeiro épico ou ticket criado	`draft` → `planning`	Especificação entra no planejamento
Planning review passou	`planning` → `ready`	Especificação liberada para implementação
Todos tickets alcançam `done`	`in_progress` → `done`	Disparado quando o último ticket completa

Estados Protegidos

Uma vez que uma especificação alcança ready, ela não regride automaticamente para planning. Esta proteção garante que planos validados permaneçam estáveis durante a implementação.

Para fazer mudanças estruturais em uma especificação ready, você deve explicitamente reabrir a sessão de planejamento — uma ação deliberada que reconhece que a especificação precisa de revalidação.

⚠️ Reabrir uma especificação após ready requer reopen_specification. Quaisquer work sessions em progresso devem ser completadas ou resetadas primeiro.

Veja Também

Estados do Ticket — Máquina de estados do ticket e regras de auto-cálculo
Ciclos de Vida — Os dois lifecycles que impulsionam essas transições
Gates de Qualidade — Os gates que disparam avanços de estado