O que plan-it faz?
Pegue uma demanda vaga → entregue um pacote de entrega construível. Este é o maestro
de planejamento: a metade frontal disciplinada do ciclo de vida que termina exatamente onde
/build-it começa. Ele faz descoberta (pesquisar a verdade dos fatos), especificação
(escrever os documentos de design) e divisão ágil (PRDs, épicos, testes, o contrato
compartilhado) — e então faz a entrega.
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(descoberta → especificação → plano) (o pacote construível) (constrói)
Utilizável diretamente por um humano, e por qualquer agente orquestrador que recebe uma nova demanda e deve transformá-la em um pacote de entrega antes de despachar trabalhadores.
As cinco regras não negociáveis (imponha estas — não apenas sugira)
Estas são as regras estruturais engenheiradas reversamente de cada execução bem-sucedida. Se você violar uma, a construção a jusante desvia ou falha silenciosamente.
-
Congele um CONTRATO compartilhado antes de qualquer planejamento paralelo. O CONTRATO é a lei: entidades canônicas, esquema, API/interface, enums, mapa de repositório/ramo e a definição de "entregue." As equipes escrevem para ele; qualquer descoberta transversal se dobra de volta nele como uma emenda datada (v1.0 → v1.1 …). Sem contrato congelado → sem equipes paralelas.
-
Agrupe toda decisão exclusivamente humana em UM portão. Não pré-decida nada irreversível (topologia do repositório, hospedagem, nome do produto, modo arquitetural, construir-vs-comprar). Apresente-os juntos, cada um com uma recomendação anexada, e deixe o humano responder numerando. Este portão é onde o humano injeta visão, não apenas escolhe opções — deixe espaço para eles adicionarem um conceito que você não propôs. Trave cada resposta com proprietário + data.
-
Verifique a saída de cada agente no disco — "ocioso ≠ entregue." Uma equipe ficando ociosa NÃO significa que escreveu arquivos. Após qualquer dispersão, verifique se os caminhos reais existem e não estão vazios antes de prosseguir. Se uma equipe manteve sua saída como uma mensagem, direcione-a para
Writeno caminho absoluto exato. Nunca confie em um "pronto." -
Fundamente o plano contra o sistema ATIVO, não o repositório — antes de congelar. Para qualquer plano que toque um sistema em execução, o repositório é uma hipótese; a realidade implantada é a verdade, e eles divergem. Antes de congelar o CONTRATO, verifique contra o sistema real e escreva as observações nele (não suposições derivadas do repositório). Testado em batalha: em um programa, TODA correção em voo foi rastreada a uma suposição inferida do repositório que a realidade contradisse — identificadores canônicos errados (manifestos tinham divergido do catálogo implantado), um valor de configuração que estava presente-mas-apontando-para-um-host-morto, componentes "a serem construídos" que já estavam implantados, e uma credencial encontrada que era a errada. Veja o portão de fundamentação ativa da Fase 3 para as verificações concretas.
-
Execute a máquina, não o texto. O fluxo de controle do pipeline reside em
machine.json(o statechart explícito), não neste documento — este texto explica a máquina. Na invocação, leia ou inicialize.plan-it/state.json(no projeto alvo) e retome do seustate; escreva-o em cada transição. Em cada transição guardada, execute o subcomando mapeado da guarda (node scripts/gate-check.mjs <check> …) e nunca avance em uma saída diferente de zero — corrija, re-execute, então faça a transição. Se o Node estiver indisponível, execute as mesmas verificações manualmente e registre-as no arquivo de estado (degrade, nunca quebre). Protocolo completo:references/machine.md.
O núcleo determinístico (v2) — por que uma máquina
Fluxo de controle escrito como texto ("faça o passo 1, nunca pule o portão") é o que a literatura de determinismo chama de fluxo de controle textual: ele depende da disciplina do modelo através de um contexto longo e propenso a sumarização, e às vezes o modelo não o segue. O v2 inverte isso na altitude certa — não-determinismo nas bordas, determinismo no núcleo:
machine.json— Statechart compatível com XState v5 do pipeline: 15 estados, os três portões humanos (meta.gate+meta.human), transições guardadas, e um auto-loopAMENDMENTemparallelPlanning. Cole em stately.ai/viz para vê-lo..plan-it/state.json— A execução persistida: estado atual, aprovações de portão (proprietário + data), versão do contrato, registro de artefatos verificados, histórico. Isso é o que faz uma execução sobreviver a uma falha ou a uma nova sessão.scripts/gate-check.mjs— As guardas como códigos de saída:verify(Regra 3, ocioso ≠ entregue),freeze(Regra 1, sem contrato → sem equipes),handoff(a metade mecanizável dos playbooks §F),state(Regra 2, portões registrados),adversary(Regra 6 / D4 — profundidade de modo de falha: uma máquina modelada deve cobrir-ou- renunciar às cinco classes de cascata; N/A para fluxos de trabalho lineares). As transiçõesLINT_CLEANeADVERSARY_CLEAN(verify → adversaryGate → handoff) dependem das duas últimas.
As fases difusas — descoberta, síntese, autoria de especificações, julgamento — permanecem
LLM-no-nó (marcadas llmAtTheNode na máquina). Não as formalize;
modelagem não é cerimônia apenas quando substitui confusão. Detalhes, esquema do arquivo de estado,
e o protocolo de retomada: references/machine.md.
Imposição rígida (v2.1, instalação de plugin apenas no Claude Code): um hook
PreToolUse (scripts/hooks/planit-guard.mjs) nega chamadas Write/Edit em artefatos
PRD/épico enquanto o contrato da execução não estiver congelado — a Regra 1 deixa de ser uma
instrução e se torna algo que o harness recusa. Fail-open: ele nunca
toca trabalho não relacionado ao plan-it. Instalações apenas como skill dependem da disciplina da Regra 5.
O Contrato de Teste — o diferencial de qualidade (torne isso não negociável)
A única coisa que mais aumenta a qualidade do código entregue: cada PRD/épico termina
gerando seu próprio contrato de teste — até ~20 casos de uso/cenários concretos que
estressam a implementação — e a funcionalidade NÃO está "pronta" até que 100% deles passem.
O agente de construção não pode apenas entregar a funcionalidade; ele deve satisfazer o contrato,
e /iterate até estar verde.
Esta é uma disciplina nomeada e comprovada: Especificação por Exemplo (Gojko Adzic) + ATDD/BDD para código (exemplos concretos se tornam testes de aceitação executáveis e documentação viva), e Desenvolvimento Orientado a Avaliação para skills/funcionalidades LLM (registre golden com saídas esperadas, itere até passarem). Escrever os casos no momento do planejamento é o ponto principal — eles se tornam um contrato vinculativo, não um pensamento posterior.
Regras do Contrato de Teste:
- Escrito no momento do planejamento — o ÚLTIMO passo de escrever cada épico/PRD é seu contrato de teste. Saídas esperadas são registradas agora ("projetado primeiro; saídas esperadas registradas"), não descobertas durante a construção.
- Até ~20 casos de alta qualidade por funcionalidade — o suficiente para estressar o comportamento real + bordas; não milhares de casos rasos (qualidade > quantidade — lote automático = "porcaria", de acordo com a literatura de avaliação). Extraia casos de modos de falha reais/prováveis. Regra de contagem por formato: programas grandes de Formato-1 com múltiplas equipes têm um piso ≥10 casos por épico (cada épico é uma funcionalidade grande); formatos pequenos (skill/funcionalidade única, P/M) escrevem ~20 casos no total no pacote (alguns por épico). Nunca ambos ao mesmo tempo — escolha pelo formato para que um revisor não sinalize um pacote pequeno correto como subtestado.
- Vinculativo — DoD = 100% do contrato passa; até lá,
/iterate. Nenhuma entrega parcial; nenhum VERIFICADO-em-um-mock (um caso[REAL]cujo alvo é inalcançável → IMPLEMENTADO-NÃO-VERIFICADO, nunca um verde falso). - Escolha os tipos de teste pela implementação (um ou mais de unitário / e2e / casos de uso / estresse):
| Implementação | Tipos de teste | Como |
|---|---|---|
| CRUD / API REST | casos de uso (feliz+borda) + e2e | execute cada cenário via API e via UI com Chrome CDP (chrome-cdp-control); teste unitário da lógica |
| Skill / prompt / função LLM | casos de uso com saída esperada | execute, compare real vs esperado — correspondência exata para saídas fechadas, rubrica / LLM-como-juiz para abertas (make-eval, promptfoo, DeepEval G-Eval) |
| Agente / stateful / multi-etapas | cenários de estresse + casos de uso | seis eixos: assíncrono, dispersão, escalonamento, portão humano, recursão, guarda de ciclo (Setup/Esperado/Passa) |
| Lógica pura / biblioteca | unitário + baseado em propriedades | casos enumerados + invariantes |
| Pipeline de dados / migração | valor golden + e2e | valores esperados calculados manualmente; idempotência/rollback |
| Qualquer coisa com superfície de carga/abuso | estresse / adversarial | concorrência, taxa, entrada malformada, equipe vermelha |
- Caminho de execução:
/full-qaexecuta o contrato,/iteratefaz um loop até 100%,chrome-cdp-controlconduz cenários de UI. O contrato é a ponte do plan-it → build-it:/build-it's Definition of Done = este contrato.
Gramáticas e o formato do cabeçalho do contrato: references/formats.md (o bloco do Contrato de Teste
- §4–5).
Postura de autonomia (guiada com rajadas autônomas)
Execute pesquisa e autoria autonomamente com alto esforço, mas pare em três portões:
| Portão | Quando | O que perguntar |
|---|---|---|
| G1 — Escopo | após o intake (Fase 2) | confirme o dimensionamento (funcionalidade vs programa) + o DoD numerado antes de gastar esforço |
| G2 — Decisões | após os rascunhos das especificações (Fase 7) | as "decisões que só você pode tomar" agrupadas, cada uma com uma recomendação |
| G3 — Entrega | antes da divisão ágil (Fase 8) | "especificações parecem alinhadas — prosseguir para PRDs/épicos?" |
Tudo entre os portões funciona sem supervisão. Recomende /effort xhigh no início
(você não pode definir isso sozinho — diga ao usuário para executar /effort xhigh se ele não tiver feito).
Fase 0 — Intake
Máquina primeiro (Regra 5): se .plan-it/state.json existir no projeto alvo,
execute node scripts/gate-check.mjs state .plan-it/state.json e retome do
estado impresso — não reinicie as fases já em history. Se não existir,
crie-o agora no estado intake (esquema em references/machine.md) e mantenha-o atualizado
em cada transição pelo resto da execução.
Aceite a demanda na forma que chegar: um despejo de cérebro, uma transcrição colada,
uma lista de desejos, ou uma frase curta. Espere ponteiros, não conteúdo —
nomes de sessão (/read-chat "<nome>"), caminhos de repositório, pastas de documentos. Seu trabalho é ir
buscar a verdade dos fatos, não recebê-la.
Capture de início:
- A visão bruta nas próprias palavras do usuário (você a citará de volta em
02 §1). - Ponteiros para sessões anteriores / repositórios / documentos a serem pesquisados.
- Caso de uso (detecção automática — isso direciona o formato do pacote no Portão G1):
- novo aplicativo único, greenfield · funcionalidade em um repositório grande existente · programa multissubsistema do zero · plataforma multi-app (muitos PRDs) · refatoração / migração / dívida · pico de pesquisa (sem construção ainda) · automação PM/board · documento/auditar um sistema já construído.
- Método de pesquisa: padrão para equipes paralelas Claude em xhigh.
Se a demanda é genuinamente um parágrafo vago sem ponteiros e um repositório existente, tudo bem — a fundamentação prévia (Fase 3) encontrará os alvos.
Fase 1 — Bloqueio de DoD
Reestruture o texto vago em uma Definição de Pronto (DoD) numerada e individualmente verificável
- uma lista curta de suposições declaradas. Este é seu contrato com o usuário para o próprio trabalho de planejamento. Exemplo de formato:
DoD para esta execução de planejamento:
1. Documento de descobertas da verdade dos fatos (cada afirmação → caminho:linha ou tabela)
2. Documento de visão + arquitetura que resolve cada descoberta/contradição
3. Contrato de dados/interface
4. … (tamanho automático — veja Fase 2)
N. Entrega: contrato congelado, PRDs+épicos com ≥10 testes cada, prompt de kickoff
Suposições: <lista>
Fase 2 — Governador de escopo e formato ⏸ PORTÃO G1
Escolha o tamanho (quanto) e o formato (qual forma) antes de gastar esforço. Confirme ambos com o usuário.
Tamanho dimensiona a contagem de artefatos:
| Sinal | Tamanho |
|---|---|
| Funcionalidade única, 1 subsistema | P |
| Multifuncionalidade / novo subsistema, 1–2 repositórios | M |
| Programa do zero / muitos subsistemas | G |
Formato é escolhido pelo caso de uso (definições completas + tabela caso de uso→formato em
references/templates.md PARTE D):
- Multi-doc +
delivery/(linha de base) — programa do zero, equipes paralelas. - PRD de arquivo único como tudo — aplicativo único greenfield; CONTRATO embutido como regras-G.
- Pesquisa → arquitetura travada → PRDs master+fase — funcionalidade em um repositório grande existente.
implementation/<nome>/com PRD-NN numerado — plataforma multi-app, muitos PRDs.- Catálogo de workstream de refatoração/dívida — brownfield in-loco. (+ modos de pico de pesquisa, quadro executável e documento reverso — veja PARTE D.)
Mesmas fases independentemente — apenas a contagem de artefatos e a forma mudam. Não dê a uma
funcionalidade uma organização de 4 equipes; não dê a uma refatoração brownfield um documento de visão greenfield.
Apresente o tamanho + formato escolhidos + o DoD numerado e obtenha um sim antes de prosseguir.
No sim, registre G1 = {approved, owner, date} mais o tamanho/formato escolhidos em
.plan-it/state.json — a transição G1_APPROVED é guardada por gateRecorded.
Fase 3 — Pré-fundamentação
Antes de qualquer dispersão, localize os alvos exatos para que os agentes recebam caminhos precisos, não instruções vagas:
- Resolva sessões de ponteiro com uma skill de leitura de sessão (
/read-chatou similar) se uma estiver instalada; caso contrário, peça a transcrição ou resumo relevante. ls/grepos repositórios nomeados; encontre osdocs/, arquivos de esquema, pontos de entrada.- Leia o cache quente/índice da wiki se o repositório estiver conectado a vault (por seu
CLAUDE.md).
Saída: uma lista de {subsistema → caminhos exatos para ler} que alimenta as equipes de pesquisa.
Portão de fundamentação ativa (regra 4) — quando o plano toca um sistema EM EXECUÇÃO
O repositório diz o que deveria ser verdade; o sistema ativo diz o que é. Faça isso antes do congelamento da Fase 8, e escreva as descobertas no CONTRATO como fatos observados:
- Atingibilidade da configuração, não presença. Para cada alavanca de ambiente/config da qual o plano depende (URLs base, hosts de API, feature flags), ative-a — não apenas confirme que está definida. Um valor pode estar definido para um host morto e passar em uma verificação "existe" enquanto quebra silenciosamente a produção.
- Registro ativo / identificadores canônicos. Du
…
[truncado para tradução]