publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/global/workflows/plano.md

9.7 KiB
Raw Blame History

type name description scope updatedAt
workflow plano Workflow oficial de Gestão, Criação (/plano) e Execução (/plano.executar) de Planos Técnicos com postura /goal e multiagentes global 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 com Graphify:

    • A IA extrai o núcleo da demanda (o que está quebrado ou precisa ser feito).
    • Consulta o Grafo de Conhecimento via bash .agent/scripts/graphify.sh query "<termo>" e explain "<no>" (o script instala automaticamente o @sentropic/graphify via Bun caso não exista na máquina, atualiza o .gitignore e gera o grafo sob demanda).
    • Investiga o código-fonte (sem alterá-lo) para identificar arquivos, componentes Vue, rotas Bun/Hono, schemas Zod ou tabelas impactadas.
    • Executa bash .agent/scripts/graphify.sh impact <arquivos...> para calcular o raio de impacto em cascata (Blast Radius), cadeias críticas e lacunas de testes entre pacotes.
    • 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, arquivos mapeados e Raio de Impacto & Dependências via Graphify).
      • 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 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>_<contexto?> --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. Atualização do Grafo de Conhecimento (Graphify):

    • Executa bash .agent/scripts/graphify.sh update para sincronizar o grafo do projeto com as alterações recém-implementadas.

  4. Registro na Memória do Projeto (Pilar 6 - @documentacao) e Sugestão de Commit:

    • Cria o registro de sessão em memorias-ia/sessao-AAAA-MM-DD-<slug>.md.
    • Indexa no memorias-ia/historico-acoes.md.
    • Não executa git commit ou git push (exclusivo do operador humano, conforme rules/proibido-commit-ia.md); apresenta ao operador a sugestão de mensagem de commit no padrão Conventional Commits (<tipo>(<escopo>): <descrição>).

  5. 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.