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

7.4 KiB
Raw Blame History

name description scope updatedAt
plano Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs global 2026-09-30

Skill: /plano (Criação e Gestão de Planos Técnicos)

Esta skill capacita o agente a atuar como ponte técnica entre o Tester / QA e o Desenvolvedor, formalizando demandas de homologação em planos de implementação completos na pasta ./PLANOS/pendente/ sem interromper a rotina de testes. Para a fase de implementação e codificação, aciona-se a skill dedicada /plano.executar.

🎯 Gatilhos e Comandos

# 1. Criação de novo plano técnico (Fase de Tester / Review)
/plano <instrução ou descrição da melhoria / bug>

# 2. Listagem e panorama da fila de planos
/plano listar

# 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado)
/plano.executar             # Executa o último plano da conversa ou mais recente
/plano.executar <slug>      # Executa plano específico por slug/ID
/plano.executar todos       # Executa todos os pendentes em lote serial (ordem de chegada - FIFO)

# 4. Arquivamento manual de um plano já concluído
/plano arquivar <slug-ou-nome-do-arquivo>

💡 Nota de Compatibilidade: Caso o operador invoque a sintaxe /plano executar <slug>, o agente automaticamente acionará o procedimento canônico de /plano.executar.

🛠️ Procedimento Operacional: Criação de Plano (/plano <instrução>)

Quando invocado com uma instrução (ex.: /plano corrigir validação do número do processo no formulário de denúncia):

1. Obter Data, Hora e Gerar Slug

  • Obtenha a data e hora locais atuais da máquina no formato AAAA-MM-DD-HH-mm (ano com 4 dígitos, mês, dia, hora 24h e minuto com 2 dígitos, ex.: 2026-09-30-10-35).
  • Converta o tema principal da instrução em um slug sucinto em kebab-case (letras minúsculas e hífens, sem acentos ou caracteres especiais).
  • Caminho alvo: ./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md.
  • Propósito da Nomenclatura: A inclusão de hora (HH) e minuto (mm) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que /plano.executar todos processe os planos estritamente na ordem em que foram criados.

2. Diagnóstico Técnico Pré-Implementação com Graphify (Sem alterar código)

  • NÃO altere arquivos de código de produção nesta etapa.
  • Consultar o Grafo de Conhecimento (graphify.sh):
    • O utilitário .agent/scripts/graphify.sh verifica e instala automaticamente o @sentropic/graphify via Bun caso não esteja instalado na máquina, atualiza de forma idempotente o .gitignore do projeto (.graphify/, .engram/, graphify-out/) e inicializa o grafo sob demanda (ensure) caso ainda não exista: 
      # 1. Localizar nós, rotas, tabelas ou componentes relacionados à demanda
bash .agent/scripts/graphify.sh query "<termo-chave-da-demanda>"
bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"
  • Inspecione rapidamente os arquivos candidatos com view_file ou grep_search para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos.
  • Mapear Raio de Impacto em Cascata (Blast Radius):
    • Com os arquivos candidatos identificados, execute a análise de impacto no grafo: 
      bash .agent/scripts/graphify.sh impact <caminho/arquivo1> <caminho/arquivo2>
    • Utilize a saída (Impacted files, High-risk dependency chains, Likely test gaps) para determinar com precisão todos os pacotes em modulos-impactados (*-comuns, *-back, *-front, *-migracao) e mapear efeitos colaterais entre módulos.
  • Identifique o comportamento atual vs comportamento esperado.

3. Redigir e Persistir o Arquivo de Plano

  • Garanta que o diretório ./PLANOS/pendente/ existe.
  • Baseie-se no template canônico .agent/DOCUMENTACAO/templates/plano.md.template.
  • Preencha o arquivo com:
    • Frontmatter YAML: 
      ---
id: AAAA-MM-DD-HH-mm-<slug>
titulo: "<Título claro e direto>"
origem: "Revisão Tester / QA"
data-criacao: "AAAA-MM-DD HH:mm"
data-execucao: null
status: "pendente"
prioridade: "media" # ou critica/alta/baixa
tipo: "bug" # ou melhoria/feature/ux/refatoracao
modulos-impactados:
  - <PACOTE-1>
  - <PACOTE-2>
executor: null
---
    • 1. Objetivo & Contexto: Descrição concisa da demanda e impacto de negócio.
    • 2. Diagnóstico Técnico & Evidências: Comportamento observado vs esperado, repro steps, evidências salvas em .evidencias/, arquivos mapeados com links [arquivo](file://...) e subseção Raio de Impacto & Dependências (Graphify) extraída via bash .agent/scripts/graphify.sh impact.
    • 3. Critérios de Aceite & Validação (DoD): Checklist com caixas - [ ] contendo condições verificáveis de sucesso.
    • 4. Especificação Técnica & Passos de Implementação: Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
    • 5. Plano de Verificação & Testes: Testes automatizados (typecheck, biome) e roteiro manual/E2E com agent-browser --session <modulo>_<contexto?> --headed (salvando evidências obrigatoriamente em .evidencias/).
    • 6. Histórico de Execução: Cabeçalho reservado para preenchimento na conclusão pelo executor.
  • Salve o arquivo em ./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md usando write_to_file.

4. Resposta ao Usuário

  • Informe o link do arquivo criado em ./PLANOS/pendente/.
  • Apresente um resumo sucinto dos módulos impactados e critérios de aceite.
  • Sinalize que o plano está na fila e que o tester pode continuar a homologação criando novos planos com /plano ou solicitar a implementação via /plano.executar.

🛠️ Procedimento Operacional: Listagem (/plano listar)

  1. Liste os arquivos existentes em ./PLANOS/pendente/ e ./PLANOS/executado/.
  2. Para cada arquivo, extraia título, data e prioridade do frontmatter.
  3. Exiba uma tabela Markdown organizada:
    • Planos Pendentes (Aguardando Dev — Fila FIFO): ID, Título, Prioridade, Data de Criação. Listados em ordem cronológica de chegada (mais antigo primeiro).
    • Planos Executados (Concluídos): ID, Título, Data de Execução, Executor.
  4. Lembre o operador dos atalhos de execução: /plano.executar ou /plano.executar todos.

🛠️ Procedimento Operacional: Execução

Para implementar qualquer plano da fila, a operação canônica é delegada para:

👉 skills/plano.executar/SKILL.md:

  • /plano.executar (sem argumentos: último plano criado na conversa ou pendente mais recente)
  • /plano.executar <slug> (plano específico)
  • /plano.executar todos (processamento serial em ordem de chegada FIFO com circuit breaker)

🛠️ Procedimento Operacional: Arquivamento Manual (/plano arquivar <slug-ou-id>)

Quando um plano foi implementado externamente ou não requer alteração de código:

  1. Localize o arquivo em ./PLANOS/pendente/ (aceita slug puro, ID completo ou nome de arquivo).
  2. Atualize o frontmatter para status: "executado", registrando data-execucao: "AAAA-MM-DD HH:mm" e executor.
  3. Mova o arquivo para ./PLANOS/executado/ preservando o nome original do arquivo.
  4. Notifique o usuário da conclusão do arquivamento.