first-plan-protocol

Protocol - first-plan

Skill base obrigatória do plugin. Toda execução de comando /fp:* carrega esta skill.

Filosofia

Antes de escrever uma linha de código, entenda o projeto. O plugin existe pra forçar essa disciplina. Não improvisar, não impor padrões externos, não duplicar trabalho.

Protocolo PLAN-FIRST (obrigatório)

Discovery -> Plan -> Approval -> Execution -> Report

Fases bloqueantes. Cada uma só inicia quando a anterior estiver concluída e validada.

Fase 1 - Discovery

Disparada por /fp:init. Resultado: .first-plan/ populado.

Mapear:

• Topologia (stacks, arquitetura, boundaries, deployment)
• Convenções (naming, errors, testing, logging, di, security)
• Reuse Index invertido (componentes, utils, types, hooks)
• Domínio (glossário, entidades, flows)
• Riscos (fragile, untested, magic, debt)
• Rationale (do, dont, why)
• Spec-Code Reconciliation (matriz feature × status × evidência)
• Git intelligence (activity, ownership, in-flight)

Cada finding tem confidence: 0.0-1.0. Findings com confidence < 0.7 viram entradas em .first-plan/08-meta/questions.md.

Fase 2 - Plan

Disparada por /fp:plan <feature>. Resultado: .first-plan/07-state/plans/<slug>.md.

Antes de escrever o plano:

1. Consultar .first-plan/09-features/ - a feature ja existe?
2. Consultar .first-plan/07-state/in-flight.md - alguém ja esta fazendo?
3. Consultar .first-plan/03-reuse/INDEX.md - o que reusar?

O plano deve seguir o template em ${CLAUDE_PLUGIN_ROOT}/meta-templates/plan.md. Pausa pedindo aprovação humana ao final.

Fase 3 - Approval (gate humano)

Estado: awaiting_approval em .first-plan/07-state/STATE.md.

Aguardar:

• /fp:execute → prossegue
• Mensagem com mudança → reescreve plano e volta a aguardar

Não executa nada antes da aprovação. Não há atalho.

Fase 4 - Execution

Disparada por /fp:execute. Resultado: código modificado conforme plano + atualização do STATE.

Durante:

• Seguir o plano à risca, na ordem definida
• Commits pequenos e atômicos no padrão do projeto
• Se descobrir algo que invalide o plano (premissa errada, contrato diferente, erro de discovery): PARAR e reportar, não improvisar
• Atualizar STATE.md a cada passo

Fase 5 - Report

Após execução completa. Resultado: .first-plan/07-state/reports/<slug>.md.

Incluir:

• O que foi feito
• O que foi reusado vs criado do zero (com justificativa)
• Desvios do plano (se houver)
• Riscos remanescentes
• Sugestões fora do escopo

Recomendar /fp:refresh para atualizar a camada.

7 Regras invioláveis

Estas regras nascem do briefing original do projeto. Não negociar.

1. Reuse first

Antes de criar qualquer função, componente, hook, helper ou tipo, verificar .first-plan/03-reuse/INDEX.md. Se existir equivalente, usar. Criar do zero é exceção que exige justificativa explícita no plano.

2. A verdade do projeto está no projeto

Não impor "best practices" externas. Se o projeto faz feio mas consistente, seguir o feio. Refatoração não está no escopo a menos que solicitada.

3. Sem dependências novas

Usar apenas o que ja está em go.mod / package.json / composer.json / etc. Adicionar lib exige justificativa explícita no plano e aprovação separada.

4. Consistência > elegância

Se o projeto tem padrão estabelecido, seguir mesmo que voce ache que existe forma melhor. Sugestões de melhoria vão pra "fora do escopo" do report, nunca executadas no fluxo da feature.

5. Criação do zero é exceção

Permitida apenas quando não há precedente (primeiro componente de um tipo no projeto, primeiro endpoint de um domínio). Sempre justificar no plano + report.

6. Acentuação completa em português

Comentários, mensagens de erro, docs, commits - tudo com acentuação correta.

7. Tipagem forte

Respeitar o nível de tipagem do projeto. Nada de any / interface{} / dynamic se o projeto é estrito.

Comportamento "não inventa, pergunta"

Quando confidence < 0.7 em qualquer finding crítico para uma decisão:

1. Não assumir
2. Adicionar entrada em 08-meta/questions.md com hipóteses
3. Em /fp:plan, listar as perguntas pendentes na seção "Riscos e ambiguidades" do plano
4. Aguardar resposta humana antes de prosseguir com partes que dependem da pergunta

Estado entre sessões

Tudo persiste em arquivos:

• .first-plan/07-state/STATE.md - máquina de estado, phase atual
• .first-plan/07-state/plans/ - planos ativos
• .first-plan/08-meta/cache.json - hashes de arquivos para invalidação

Ao reabrir o Claude Code, o entry point é STATE.md. Claude lê phase e age conforme.

Convenção de wikilinks (v0.5.0+)

Cross-references entre arquivos do .first-plan/ usam sintaxe Obsidian-compatible:

Veja [[02-conventions/errors]] para padrões de error handling.
Detalhes em [[08-meta/questions]].

Formato: [[secao/arquivo]] (sem extensão .md, sem prefixo de path).

Razão: permite navegação como graph no Obsidian/Logseq. No GitHub web os wikilinks aparecem como texto plano (limitação aceita).

Quando referenciar:

• Cross-section sempre - se um finding em 02-conventions/errors.md exemplifica ou conflita com 06-rationale/dont.md, usar wikilink
• Cross-feature em 09-features - features relacionadas linkam entre si
• Reuse Index - cada item linka pra arquivo onde está catalogado

Quando NÃO usar:

• Links externos (GitHub URLs, docs externos) - usar markdown padrão [label](url)
• Path arquivos do projeto-alvo (não do .first-plan/) - usar path:line
• File system paths (/etc/..., comandos) - texto direto

Detecção de invalidação durante execução

Se durante /fp:execute Claude perceber que:

• Um arquivo que o plano assumia existir não existe
• Um símbolo que o plano referenciava tem assinatura diferente
• Um teste que deveria passar mostra comportamento inesperado
• Discovery indicou algo que se mostra incorreto

Então: parar imediatamente, atualizar STATE.md para paused, reportar ao usuário com:

1. Premissa que falhou
2. Evidência da falha
3. Opções: replanejar / abortar / continuar com adaptação