.agent/global/workflows/plano.md

type	name	description	scope	updatedAt
workflow	plano	Workflow oficial de Gestão, Criação e Execução de Planos Técnicos (fila PLANOS/pendente/ e PLANOS/executado/)	global	2026-09-28

Workflow: /plano (Gestão de Planos Técnicos Tester ➔ Dev)

Workflow oficial para captura estruturada de demandas pelo Tester / QA durante homologações e execução determinística pelo Desenvolvedor no ecossistema Azteca.

💡 Comandos Rápidos:

• /plano <instrução> \rightarrow Diagnostica a demanda e gera um plano em PLANOS/pendente/YYYY-MM-DD-<slug>.md.
• /plano listar \rightarrow Exibe o panorama da fila de planos pendentes e executados.
• /plano executar <slug> \rightarrow Carrega o plano pendente, implementa o código, valida e arquiva em PLANOS/executado/.
• /plano arquivar <slug> \rightarrow Move manualmente um plano para PLANOS/executado/.

---

🎯 Por que este Workflow existe?

Durante a navegação, testes manuais ou homologação de telas e rotas, o tester frequentemente encontra inconsistências, comportamentos inesperados, melhorias visuais ou lacunas de negócio.

• Problema anterior: O tester precisava parar os testes para tentar implementar na hora, ou anotava observações soltas no chat que se perdiam ao final da conversa.
• Solução com /plano: O tester invoca /plano <instrução>. A IA analisa tecnicamente o código e materializa a demanda em um arquivo padronizado em PLANOS/pendente/. O tester pode criar múltiplos planos em sequência na mesma sessão de review. Mais tarde, o desenvolvedor implementa cada um deles com foco total.

---

🔄 Fluxo de Operação em 4 Fases

┌───────────────────────────┐      ┌───────────────────────────┐
│     1. FASE DE REVIEW     │      │     2. FILA DE TRABALHO   │
│   (Tester / Homologação)  │ ───▶ │    (./PLANOS/pendente/)   │
│   /plano <instrução>      │      │                           │
└───────────────────────────┘      └─────────────┬─────────────┘
                                                 │
                                                 ▼
┌───────────────────────────┐      ┌───────────────────────────┐
│     4. ARQUIVAMENTO       │      │   3. IMPLEMENTAÇÃO DEV    │
│   (./PLANOS/executado/)   │ ◀─── │   (Desenvolvedor / IA)    │
│   Metadados & Histórico   │      │   /plano executar <slug>  │
└───────────────────────────┘      └───────────────────────────┘

---

📝 Fase 1: Criação pelo Tester (/plano <instrução>)

Quando o comando for executado:

1. Interpretação e Diagnóstico Rápido:

   • A IA extrai o núcleo da demanda (o que está quebrado ou precisa ser feito).
   • Investiga o código-fonte (sem alterá-lo) para identificar arquivos, componentes Vue, rotas Bun/Hono, schemas Zod ou tabelas impactadas.
   • Identifica a causa raiz ou o ponto exato de intervenção.

2. Formatação do Nome do Arquivo:

   • Formato: PLANOS/pendente/YYYY-MM-DD-<slug-em-kebab-case>.md
   • Onde YYYY-MM-DD é a data atual da máquina e <slug> reflete a essência do plano.

3. Escrita do Documento:

   • Utiliza a estrutura do template canônico .agent/DOCUMENTACAO/templates/plano.md.template.
   • Preenche:
     • Frontmatter com status: pendente e tags do domínio.
     • Objetivo & Contexto (visão funcional).
     • Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados).
     • Critérios de Aceite (Definition of Done).
     • Especificação Técnica passo a passo para orientar o desenvolvedor.
     • Plano de Verificação & Testes.

4. Feedback Imediato ao Tester:

   • Informa o caminho do plano gerado e confirma que o review pode prosseguir.

---

📋 Fase 2: Gestão da Fila (/plano listar)

Para visualizar o status atual de todos os planos:

• Lista arquivos em PLANOS/pendente/ (status, título, prioridade, data).
• Lista arquivos em PLANOS/executado/ (data de execução, executor).

---

💻 Fase 3: Execução pelo Desenvolvedor (/plano executar <slug>)

Quando o desenvolvedor (ou operador) ordenar a implementação de um plano:

1. Carregamento do Plano:

   • A IA lê o arquivo correspondente em PLANOS/pendente/<nome-do-arquivo>.md.
   • Se o usuário passou apenas parte do nome (ex.: filtro-denuncia), localiza o arquivo correspondente.

2. Planejamento & Execução Cirúrgica:

   • Respeita as regras fundamentais:
     • rules/diagnostico-antes-correcao.md
     • rules/literatura-tecnica-e-usabilidade.md
     • workflows/codigo-limpo.md (limite de 250 linhas, Dispatch Tables)
     • rules/feedback-visivel.md (visibilidade de erros)
     • rules/fronteiras-monorepo.md (respeitar fronteiras dos pacotes)
   • Executa as alterações passo a passo nos pacotes afetados (*-comuns, *-back, *-front, etc.).

3. Verificação & Testes:

   • Roda checagem de tipos (tsc --noEmit / bun run typecheck).
   • Roda formatação (biome check --write <arquivos>).
   • Roda governança de linhas (sh .agent/verificar-linhas.sh).
   • Valida os critérios de aceite definidos na seção 3 do plano.

---

📦 Fase 4: Conclusão e Arquivamento (PLANOS/executado/)

Ao confirmar que a implementação está verde e validada:

1. Atualização do Plano:

   • Atualiza o frontmatter do arquivo:
     • status: executado
     • data-execucao: "YYYY-MM-DD HH:mm"
     • executor: "<nome-do-dev-ou-agente>"
   • Preenche a Seção 6 (Histórico de Execução) com o resumo das modificações feitas e evidências de validação.

2. Movimentação do Arquivo:

   • Move o arquivo de: PLANOS/pendente/YYYY-MM-DD-<slug>.md para: PLANOS/executado/YYYY-MM-DD-<slug>.md

3. Registro na Memória do Projeto (Pilar 6):

   • Cria o registro de sessão em memorias-ia/sessao-YYYY-MM-DD-<slug>.md.
   • Indexa no memorias-ia/historico-acoes.md.
   • Sugere o comando de commit staged para a aplicação (lembrando que commit automatizado na aplicação é proibido por rules/proibido-commit-ia.md).