--- 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-30" --- # 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/AAAA-MM-DD-HH-mm-.md`. > - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes (FIFO) 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 ordem de chegada (FIFO - 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 │ │ Ordem de Chegada (FIFO) │ └─────────────────────────────────┘ └──────────────┬──────────────┘ │ ▼ ┌─────────────────────────────────┐ ┌─────────────────────────────┐ │ 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/AAAA-MM-DD-HH-mm-.md` - Onde `AAAA-MM-DD-HH-mm` é a data e hora locais atuais da máquina (com dois dígitos para dia, mês, hora 24h e minuto). - **Propósito:** A inclusão de hora e minuto viabiliza que a ordenação alfabética/lexicográfica coincida nativamente com a ordem de chegada (FIFO), orientando a fila de execução serial do desenvolvedor. 3. **Escrita do Documento:** - Utiliza a estrutura do template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`. - Preenche: - Frontmatter com `id: AAAA-MM-DD-HH-mm-`, `data-criacao: "AAAA-MM-DD HH:mm"`, `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/` ordenados por ordem de chegada FIFO (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 --session --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 (suportando formatos novo e legado). - **Modo 3: Fila serial em ordem de chegada (`/plano.executar todos`)** $\rightarrow$ Ordena os pendentes em estrita ordem cronológica de chegada (FIFO: o mais antigo criado é executado primeiro; arquivos com prefixo temporal `AAAA-MM-DD-HH-mm-` ordenam-se alfabeticamente; legados usam data de criação/mtime) e processa 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: "AAAA-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 preservando o nome original: `PLANOS/pendente/.md` para: `PLANOS/executado/.md` 3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** - Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-.md`. - Indexa no `memorias-ia/historico-acoes.md`. - Executa `git add` nos arquivos alterados e realiza o `git commit` semântico (se a branch atual for `master`, cria e seleciona previamente uma nova branch de trabalho — nunca comita em `master`, conforme `rules/proibido-commit-ia.md`). 4. **Notificação no Sistema Operacional (Linux & macOS):** - Dispara alerta sonoro e notificação visual de desktop via `.agent/notificar.sh`: `sh .agent/notificar.sh "Plano Concluído" "" sucesso` - Na conclusão de toda a fila serial de `/plano.executar todos`, emite a notificação consolidada de encerramento do lote para avisar o operador no CLI.