137 lines
8.9 KiB
Markdown
137 lines
8.9 KiB
Markdown
---
|
|
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 <instrução>` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.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 <slug>` $\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 <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.
|
|
|
|
- **Fase de Homologaçã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 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 <instrução> │ │ 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 <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/AAAA-MM-DD-HH-mm-<slug-em-kebab-case>.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-<slug>`, `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 <modulo> --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 <slug-ou-id>`)** $\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/<nome-original>.md`
|
|
para:
|
|
`PLANOS/executado/<nome-original>.md`
|
|
|
|
3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
|
|
- Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-<slug>.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" "<Nome ou Título do Plano>" 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.
|