| name | first-plan-protocol |
| description | Esta skill DEVE ser carregada em qualquer comando do plugin first-plan. Define o protocolo PLAN-FIRST (Discovery -> Plan -> Approval -> Execution -> Report), as 7 regras invioláveis e o comportamento esperado em cada fase. Ative quando o usuário invocar /fp:* ou mencionar "first-plan", "context compilation", "discovery layer", "spec-code reconciliation". |
| version | 0.1.0 |
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:
- Consultar
.first-plan/09-features/ - a feature ja existe?
- Consultar
.first-plan/07-state/in-flight.md - alguém ja esta fazendo?
- 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:
- Não assumir
- Adicionar entrada em
08-meta/questions.md com hipóteses
- Em
/fp:plan, listar as perguntas pendentes na seção "Riscos e ambiguidades" do plano
- 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:
- Premissa que falhou
- Evidência da falha
- Opções: replanejar / abortar / continuar com adaptação
