Plan-Doc-Do-Follow Skill
Plan → Doc → Do → Follow
Corresponder intenção → primeira rota vence → ler routes/a-b.md (rota a/b) → segui-la → aplicar Invariantes Globais + Modelo de Status. Carregar apenas a rota necessária, seus templates, seus subagentes — nunca tudo
Rotas
Planejamento
| Intenção | Rota | Parâmetros |
|---|---|---|
| Extrair épicos da visão do produto | plan/proj | |
| Validar épicos com stakeholders | plan/proj-review | |
| Criar PRD e rastreamento do épico | plan/epic | E{n} |
| Validar especificação ou arquitetura do épico | plan/epic-review | E{n} {prd|arch} |
| Projetar arquitetura do épico | plan/epic-arch | E{n} |
| Criar PRD da funcionalidade | plan/feat | E{n} F{n} |
| Validar especificação ou arquitetura da funcionalidade | plan/feat-review | E{n} F{n} {prd|arch} |
| Arquitetura da funcionalidade (somente exceção) | plan/feat-arch | E{n} F{n} |
| Dividir funcionalidade em tarefas | plan/tasks | E{n} F{n} |
| Mudança de escopo — adicionar/atualizar funcionalidade ou épico, mesmo se implementado | plan/change | descrição |
| Migrar docs do projeto v2 para v3 (one-shot) | plan/migrate |
Execução
| Intenção | Rota | Parâmetros |
|---|---|---|
| Configurar ferramentas de economia de tokens (LSP, filtros, economia, agentes nativos) | do/init | |
| Executar uma tarefa | do/task | E{n} F{n} T{n} |
| Executar todas as tarefas da funcionalidade, verificar inline | do/all-tasks | E{n} F{n} |
| Verificar trabalho concluído (caminho tarefa por tarefa) | do/verify | E{n} F{n} |
| Recalcular e reparar todos os status | do/sync-status | |
| Memorizar boas práticas | do/memorize |
Invariantes Globais (todas as rotas)
- Verificação do Espírito: alinhar com
docs/product.md; Espírito do Produto (topo dedocs/project-status.md) literalmente em toda rota de planejamento + brief do revisor - Vontade do usuário:
docs/decisions.mdvinculante; desvio = perguntar, nunca aplicar silenciosamente - Negócios primeiro: revisão de especificação antes da próxima fase
- Verificação de arquitetura: alinhar com
docs/global_architecture.md+docs/technical-stack.md - Um fato, um arquivo: status/fato tem um arquivo proprietário (Modelo de Status); outros vinculam, nunca copiam
- Linguagem do público: humano/negócios = frases completas, sem abreviações não explicadas; voltado ao agente = estilo Documento (conciso-caverna)
- Sem andaimes vazios: excluir seções de template não utilizadas; nunca "N/A" ou placeholders
- Sem adivinhação: ambiguidade bloqueadora → perguntar primeiro; rotular bloqueador / importante / menor
- Rastreabilidade: cada documento referencia o pai; histórias ↔ requisitos ↔ tarefas ↔ testes vinculados
- Documentos globais vivos:
docs/data-model.md,docs/ui-map.md,docs/decisions.mdatualizados na mesma alteração que os afeta — nunca "depois" - Hierarquia de modelos:
plan/*+ revisores = modelo forte; toda tarefaplan/tasksexecutável por modelo mais fraco sem abrir PRD - Sincronização de Status: toda rota que altera status termina com procedimento de Sincronização de Status
- Formato de handoff: resumo curto · progresso atual · próximo comando exato · perguntas em aberto
- Subagentes com escopo: apenas as entradas que suas listas de definição listam
- Mentalidade por rota: adotar a linha de Mentalidade da rota
- Deliberação permanece interna: trocas entre críticos nunca em documentos/handoffs — humano vê resultado final + o que validar
- Economia em todo lugar: Economia de Trabalho em toda rota e subagente
Modelo de Status
⚪ TODO · 🟡 SPEC especificado · 🟣 PLAN tarefas geradas · 🔵 DEV em andamento · 🟢 DONE concluído e verificado
Propriedade — fonte única de verdade
| Fato | Arquivo proprietário (ÚNICO lugar onde é escrito) |
|---|---|
| Status da tarefa | feat-tasks.md — Tabela de Resumo de Tarefas |
| Status e progresso da funcionalidade | epic-status.md — Tabela de Funcionalidades |
| Status e progresso do épico | docs/project-status.md — Tabela de Roadmap de Épicos |
| Progresso do projeto | docs/project-status.md — Seção de Progresso |
Sem feat-status.md. Seções por tarefa: sem linha de status. Mermaid = decorativo, regenerado a partir das tabelas proprietárias, nunca fonte de verdade
Regras de derivação
- Funcionalidade: sem
feat-prd.md→ ⚪ · PRD existe → 🟡 ·feat-tasks.mdexiste, nenhuma tarefa além de TODO → 🟣 · qualquer tarefa DEV/DONE → 🔵 · 🟢 somente através de portões de verificação (do/verify, ou fase final dedo/all-tasks). Tarefas adicionadas a funcionalidade 🟢 → reverter para 🔵 - Épico: sem
epic-prd.md→ ⚪ · PRD existe → 🟡 · todas as funcionalidades ≥ 🟣 → 🟣 · qualquer funcionalidade 🔵/🟢 (nem todas 🟢) → 🔵 · todas 🟢 → 🟢 - Projeto: mesma agregação sobre épicos
- Progresso: tarefas concluídas / total de tarefas (0 se nenhuma), somado no nível do épico e do projeto
Procedimento de Sincronização de Status
Final de qualquer rota que altera status (autônoma: do/sync-status, todos os épicos):
- Ler Tabelas de Resumo de Tarefas da(s) funcionalidade(s) afetada(s)
- Recalcular status + progresso de cada funcionalidade; atualizar linha em
epic-status.md - Recalcular cada épico afetado; atualizar sua linha, seção de Progresso, gráfico de pizza em
docs/project-status.md. Sync de Status nunca escreve changelog — apenas eventos nomeados pela regra rígida de changelog (estilo Documento), escritos pela rota que produziu o marco - Reportar desvio (armazenado ≠ derivado) no handoff
Determinístico e idempotente
Subagentes
Definições em subagents/ — um arquivo por agente (formato: subagents/README.md). Invocar: ler arquivo → montar exatamente as entradas listadas (revisores sempre recebem Espírito do Produto) → gerar com o corpo do arquivo como prompt de sistema
Perfil de economia
Ler Economia do subagente: da seção Ferramentas do arquivo de instruções do repositório (do/init escreve). Ausente → balanced
| Perfil | Comportamento |
|---|---|
strict | Inline-first rígido · scout quase sempre inline · limites de pergunta/ferramenta/retorno aplicados · críticos ainda geram |
balanced | Inline-first conforme descrito abaixo · limites aplicados · aviso suave se >5 perguntas do scout |
quality | Portão de custo apenas consultivo · limites ainda se aplicam ao uso de ferramenta do scout e tamanho do retorno |
Antes de qualquer geração (inline-first)
Executar em ordem — primeira correspondência vence → não gerar:
- Fatos já no contexto do principal → trabalhar inline
- Respondível pelo principal em ≤5 chamadas Grep/Glob/Read (ou LSP) → inline (usar checklist scout-lite em
subagents/repo-scout.md) - Brief se aproximaria do tamanho da resposta esperada → inline
- Descobertas provavelmente cosméticas / checklist mecânico em superfície pequena → inline (mesmo portão de custo de hoje)
- Caso contrário, gerar
repo-scout extra (sob strict / balanced): gerar somente se ≥3 perguntas falseáveis e a busca abranger ≥2 áreas que o principal não abriu, ou o contexto do principal já estiver cheio e o isolamento claramente mais barato. Caso contrário, scout-lite inline
Ao gerar:
- Injeção de ferramentas: brief inclui bloco de Ferramentas de uma linha do arquivo de instruções do repositório (prefixo de filtro CLI, preferência LSP, perfil de economia) — subagente deve obedecê-lo
- Brief preciso: perguntas/verificações exatas · padrões contra os quais o trabalho é construído · fora do escopo · para scout, caminhos/globs iniciais quando a área é conhecida · ≤5 perguntas por onda do scout (
balanced/strict; dividir ou inline o restante) - Carregar a barra antecipadamente: antes do rascunho, ler as perguntas de Revisão do crítico; rascunhar para passar na primeira tentativa
- Limite de retorno: scout ≤15 linhas · críticos ≤25 linhas · principal mantém apenas fatos necessários — nunca colar despejos do scout em documentos
Descobertas do crítico: aplicar se alterar comportamento, contrato ou decisão humana; descartar fúteis/cosméticas silenciosamente. Chamada de julgamento rejeitada → pergunta de decisão para o humano. Convergência: uma execução por documento; no máximo uma reexecução após retrabalho substancial de descobertas bloqueadoras, com escopo nelas — reexecução aceita apenas bloqueadoras; nunca terceira execução. Nunca relatar troca (Invariante 16)
| Subagente | Tipo | Chamado por | Quando |
|---|---|---|---|
repo-scout | pesquisa | plan/epic-arch, plan/feat, plan/feat-arch, plan/change | plano deve se basear em código existente |
prd-critic | revisor | plan/epic, plan/feat | sempre |
arch-critic | revisor | plan/epic-arch, plan/feat-arch | sempre |
perf-critic-backend / -frontend | revisor | rotas de arquitetura, portões de verificação | apenas quando os critérios de gatilho (topo de seus arquivos) disparam |
task-checker | revisor | plan/tasks | após auto-revisão; no máximo duas execuções |
feature-coder | executor | do/all-tasks | um por tarefa paralelizável por onda |
ui-consistency-reviewer | revisor | portões de verificação | funcionalidades de UI, superfície não trivial |
doc-coherence-reviewer | revisor | portões de verificação · plan/change · plan/migrate | conclusão do épico · após mudança · após migração |
Portões de verificação (+ seus subagentes) executam em do/verify ou inline como fase final de do/all-tasks
UX de Revisão Humana
Conclusões, não processo. Verificações mecânicas auto-verificadas → uma linha de resumo. "Decisões que exigem sua validação": ≤10 afirmações em frases simples + perguntas em aberto rotuladas bloqueadoras/importantes/menores. Decisões validadas → docs/decisions.md. Respostas de stakeholders literalmente — nunca parafrasear, nunca perguntar novamente (se ambíguo, perguntar apenas esclarecimento)
Economia de Trabalho (Invariante 17)
Economia de entrada
- Preferir navegação LSP/semântica a leituras de arquivos inteiros; intervalos de linha com escopo
- Preferir Grep/Glob/LSP a Shell para busca de código — Shell apenas quando necessário
- Saída longa de CLI (testes, builds, git, gerenciadores de pacotes) através de filtro declarado no repositório (ex.
rtk,snip) —do/initconfigura; se Shell usado sem hook ativo, prefixar manualmente - Nunca reler o que está no contexto; nunca carregar documento "por segurança"
- Obedecer perfil de economia + inline-first antes de gerar (Subagentes)
Estilo de saída (principal e subagentes)
- Conciso-caverna (mesmo padrão de documentos voltados ao agente): sem preâmbulo, sem reafirmar solicitação, sem resumo final, sem enchimento/hesitação
- Código, comandos, caminhos, erros: byte-exato — nunca parafrasear
- Alterações de código como diffs ou edições direcionadas — nunca listagens de arquivo completo a menos que solicitado
- Respostas de pesquisa ≤10 linhas a menos que profundidade seja solicitada; retornos de subagentes obedecem ao limite de retorno
- Handoff (Invariante 13) = apenas bloco de fechamento: ≤5 linhas
Implementação mínima (rotas do e feature-coder)
Entender completamente, parar no primeiro degrau que se sustenta:
- Não precisa existir → pular (YAGNI)
- Já está no código → reutilizar
- Stdlib faz → usar
- Recurso nativo da plataforma → usar
- Dependência instalada → usar
- Uma linha é suficiente → uma linha
- Só então escrever o mínimo que funciona
Nunca cortar: validação de limite de confiança, tratamento de perda de dados, segurança, acessibilidade
Estilo de documento
Dois públicos — escolher pelo propósito do arquivo, não pelo humor da rota
Humano / negócios (prosa completa) — PRDs (epic-prd.md, feat-prd.md), docs/product.md, Espírito do Produto, corpos de revisão humana (seções de decisão *-review.md), documentos centrados no usuário (developer-setup, onboarding, READMEs humanos). Frases completas. Legível para stakeholders. Sem abreviações não explicadas
Voltado ao agente (conciso-caverna) — playbooks da skill (SKILL.md, routes/, subagents/, comentários de template), feat-tasks.md, epic-arch.md / feat-arch.md, tabelas/notas de status, documentos técnicos vivos (data-model.md, ui-map.md, decisions.md), docs/patterns/*. Inspirado pelo caveman completo:
- Apenas fatos e ordens — sem artigos/enchimento/hesitação quando o significado está claro; fragmentos OK
- Sinônimos curtos; padrão
[coisa] [ação] [motivo]·[próximo passo] - Sem abreviações inventadas (
cfg/impl/fn); acrônimos técnicos conhecidos OK (DB/API/HTTP) - Caminhos, símbolos, código, comandos, strings de erro: exatos
- Nunca omitir
não/nunca/sem/somente/exceto - Sem ponto final antes de quebra de linha (pontos no meio da linha em linhas com múltiplas cláusulas permanecem)
- Decisões e fatos apenas — nunca processo ("revisor sugeriu…", "após discussão…")
- Justificar apenas quando agente futuro precisar do porquê (trade-off, corte de escopo): ≤2 linhas curtas
- Clareza automática: prosa mais completa para avisos de segurança, passos irreversíveis ou fragmentos que correm risco de má interpretação de ordem/negação — então retomar conciso
Regra rígida de changelog: uma linha {data}: {fato}, ≤25 palavras. Elegível apenas — projeto: épico concluído, mudança de escopo importante, migração; épico: funcionalidade verificada 🟢, mudança de escopo. Todo o resto (tarefas geradas, PRD rascunhado/aprovado, ondas, sincronizações, reparos de desvio) = sem entrada. Nunca: trocas de críticos (Invariante 16), listas de tarefas, resultados de portões, números de progresso, comandos Próximo:. Entradas existentes verbosas = legado, nunca precedente — escrever apenas linha elegível, ou nada
Organização de Arquivos
docs/
├── product.md (entrada: visão do produto)
├── global_architecture.md (entrada: visão geral da arquitetura)
├── technical-stack.md (entrada: decisões tecnológicas)
├── project-status.md (proprietário: Espírito do Produto, status dos épicos, progresso)
├── project-review.md
├── decisions.md (vivo: decisões vinculantes do usuário, uma linha cada)
├── data-model.md (vivo: esquema global de dados, se houver)
├── ui-map.md (vivo: mapa de navegação global, se UI)
├── design-guidelines.md (vivo: convenções de estilo de UI, se UI)
├── patterns/{pattern-name}.md (de do/memorize)
└── epics/e{n}-{epic-name}/ (slug ex. e2-orm-discovery)
├── epic-brief.md (plan/proj)
├── epic-prd.md (plan/epic)
├── epic-status.md (proprietário: status das funcionalidades)
├── epic-arch.md (plan/epic-arch)
├── epic-review.md (plan/epic-review)
└── f{n}-{feat-name}/ (filho direto — sem nível features/)
├── feat-prd.md (plan/feat; tem Pontos de Entrada + Delta de Arquitetura)
├── feat-arch.md (plan/feat-arch — apenas exceções)
├── feat-tasks.md (proprietário: status das tarefas)
└── feat-review.md (plan/feat-review)
Integração com plataforma
Convenções do repositório, precedência: CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursor/rules/ · .github/instructions/. do/memorize escreve de volta no(s) arquivo(s) realmente presente(s)
Templates
Em templates/ — nomes espelham os arquivos de saída