--- type: workflow name: plano description: Workflow oficial de Gestão, Criação (/plano) e Execução (/plano.executar) de Planos Técnicos com postura /goal e multiagentes scope: global updatedAt: "2026-09-28" --- # Workflow: /plano e /plano.executar (Gestão e Execução de Planos Técnicos) Workflow oficial para captura estruturada de demandas pelo **Tester / QA** durante homologações e execução determinística pelo time de desenvolvimento com postura obstinada **/goal** e orquestração de **multiagentes especialistas** no ecossistema Azteca. > 💡 **Comandos Rápidos:** > - `/plano ` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/YYYY-MM-DD-.md`. > - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados. > - `/plano.executar` $\rightarrow$ Executa o último plano da conversa (ou pendente mais recente) sob a postura autônoma `/goal`. > - `/plano.executar ` $\rightarrow$ Executa plano específico coordenando a equipe de especialistas (`@back`, `@front`, `@ux`, `@refatorar`, `@testes`, `@documentacao`). > - `/plano.executar todos` $\rightarrow$ Executa sequencialmente todos os planos pendentes em lote serial (com circuit breaker). > - `/plano arquivar ` $\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. - **Fase de Homologação com `/plano`:** O tester invoca `/plano `. 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 sem parar os testes. - **Fase de Execução com `/plano.executar`:** O desenvolvedor aciona `/plano.executar`. O agente assume o papel de **Orquestrador Líder sob postura `/goal`**, acionando subagentes especialistas (`@back`, `@front`, `@ux`, `@refatorar`, `@testes`, `@documentacao`) para implementar as demandas de forma autônoma e completa. --- ## 🔄 Fluxo de Operação em 4 Fases ``` ┌─────────────────────────────────┐ ┌─────────────────────────────┐ │ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │ │ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ │ /plano │ │ │ └─────────────────────────────────┘ └──────────────┬──────────────┘ │ ▼ ┌─────────────────────────────────┐ ┌─────────────────────────────┐ │ 4. ARQUIVAMENTO │ │ 3. ORQUESTRADOR DEV /goal │ │ (./PLANOS/executado/) │ ◀─── │ Multiagentes Especialistas│ │ Metadados & Histórico │ │ /plano.executar [...] │ └─────────────────────────────────┘ └─────────────────────────────┘ ``` --- ## 📝 Fase 1: Criação pelo Tester (`/plano `) 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-.md` - Onde `YYYY-MM-DD` é a data atual da máquina e `` 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 com novos testes ou acionar a execução via `/plano.executar`. --- ## 📋 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 com /goal e Multiagentes (`/plano.executar`) A execução é conduzida pela skill canônica [`/plano.executar`](../skills/plano.executar/SKILL.md) atuando como **Orquestrador Líder**: ### 1. Postura Operacional /goal - **Autonomia Contínua:** Não interrompe o fluxo para perguntas triviais; executa de ponta a ponta. - **Loop de Auto-Correção:** Caso linter ou typecheck apresente falhas, diagnostica a causa raiz, refatora e retesta iterativamente até atingir validação 100% verde. ### 2. Ativação da Equipe de Especialistas O Orquestrador divide as tarefas entre os especialistas: - **`@back`**: Implementa endpoints, queries Knex e schemas Zod em `*-comuns`. - **`@front`**: Implementa telas Vue 3, composables e formulários consumindo `*-comuns`. - **`@ux`**: Aplica as Heurísticas de Nielsen (visibilidade de loading/erro, feedback imediato). - **`@refatorar`**: Governança de Código Limpo (limite estrito de 250 linhas, Dispatch Tables). - **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --headed`. - **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio. ### 3. Modos de Invocação - **Modo 1: Sem parâmetros (`/plano.executar` ou `ultimo`)** $\rightarrow$ Localiza o último plano gerado no contexto da sessão ou mais recente na pasta. - **Modo 2: Por identificador (`/plano.executar `)** $\rightarrow$ Localiza por slug, ID ou nome de arquivo. - **Modo 3: Fila serial (`/plano.executar todos`)** $\rightarrow$ Processa todos os pendentes sequencialmente, um a um, com circuit breaker caso ocorra erro irrecuperável. --- ## 📦 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: "Orquestrador /goal + Multiagentes (@back, @front, @ux, @refatorar, @testes, @documentacao)"` - 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-.md` para: `PLANOS/executado/YYYY-MM-DD-.md` 3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** - Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-.md`. - Indexa no `memorias-ia/historico-acoes.md`. - Executa `git add` nos arquivos alterados e sugere o comando de commit semântico ao operador (seguindo `rules/proibido-commit-ia.md`).