diff --git a/DOCUMENTACAO/templates/plano.md.template b/DOCUMENTACAO/templates/plano.md.template new file mode 100644 index 0000000..02dc11d --- /dev/null +++ b/DOCUMENTACAO/templates/plano.md.template @@ -0,0 +1,109 @@ +--- +type: template +name: plano +description: Template canônico para Planos Técnicos de Implementação (fila PLANOS/pendente/ e PLANOS/executado/) +updatedAt: "2026-09-28" +--- + + + +--- +id: YYYY-MM-DD- +titulo: "" +origem: "Revisão Tester / QA" +data-criacao: "YYYY-MM-DD" +data-execucao: null +status: "pendente" # pendente | executado | cancelado +prioridade: "media" # critica | alta | media | baixa +tipo: "bug" # bug | melhoria | feature | refatoracao | ux +modulos-impactados: + - QUIPO-BACK + - QUIPO-FRONT + - QUIPO-COMUNS +executor: null +--- + +# Plano: + +## 1. Objetivo & Contexto + + +--- + +## 2. Diagnóstico Técnico & Evidências do Tester + +### Comportamento Observado vs Comportamento Esperado +- **Observado:** +- **Esperado:** + +### Passos para Reproduzir (Repro Steps) / Evidência Visual +1. +2. +3. + +### Análise de Causa Raiz & Arquivos Mapeados + +- `caminho/do/arquivo1.ts` — +- `caminho/do/arquivo2.vue` — + +--- + +## 3. Critérios de Aceite & Validação (Definition of Done) +- [ ] +- [ ] +- [ ] +- [ ] + +--- + +## 4. Especificação Técnica & Passos de Implementação (Para o Dev) + +### 4.1 Pacote `*-comuns` (se aplicável) +- Schemas Zod, tipos TypeScript ou enums a criar/ajustar. + +### 4.2 Pacote `*-back` (se aplicável) +- Endpoints, controllers, queries de banco ou filas a criar/ajustar. +- Seguir regras de diagnóstico prévio (`rules/diagnostico-antes-correcao.md`) e visibilidade de erros (`rules/feedback-visivel.md`). + +### 4.3 Pacote `*-front` (se aplicável) +- Telas, componentes Vue 3, composables ou estilos CSS co-localizados. +- Seguir as 12 regras de Código Limpo (`workflows/codigo-limpo.md`) e limite de 250 linhas. + +### 4.4 Diffs Conceituais / Código Sugerido +```ts +// Exemplo de código ou alteração sugerida +``` + +--- + +## 5. Plano de Verificação & Testes + +### 5.1 Testes Automatizados & Checagens Estáticas +- Tipagem: `bun run typecheck` ou `tsc --noEmit` +- Qualidade/Lint: `biome check --write ` +- Governança: `sh .agent/verificar-linhas.sh` + +### 5.2 Roteiro de Teste Manual / `agent-browser` +1. Acessar a tela X +2. Executar a ação Y +3. Validar se o resultado Z ocorre + +--- + +## 6. Histórico de Execução (Preenchido na Conclusão) +- **Data de Início:** `` +- **Data de Conclusão:** `` +- **Executor:** `` +- **Arquivos Efetivamente Modificados:** + - `` +- **Resumo da Solução Implementada:** + - +- **Evidências de Teste / Screenshots:** + - diff --git a/README b/README index 7d5ebc6..6cdf876 100644 --- a/README +++ b/README @@ -25,6 +25,9 @@ O repositório `.agent` fornece a estrutura genérica de inteligência (regras u ├── memorias-ia/ ← Personalização & Identidade: │ ├── modulo.yml ← OBRIGATÓRIO: modulo-id, modulo-caminho, modulo-descricao e modulo-tipo │ └── sessao-*.md ← Histórico de ações e memórias de IA deste projeto +├── PLANOS/ ← Fila de Planos Técnicos (Tester ➔ Dev): +│ ├── pendente/ ← Planos criados por testers aguardando dev (/plano ) +│ └── executado/ ← Planos implementados, testados e arquivados (/plano executar ) ├── .agent/ ← Polimórfico: Submódulo genérico compartilhado │ ├── DOCUMENTACAO/ ← Hub DDD: Manifesto e templates padronizados │ ├── global/ ← Rules, workflows e skills globais @@ -42,6 +45,9 @@ O repositório `.agent` fornece a estrutura genérica de inteligência (regras u ``` memorias-ia/ ← armazenamento de memórias das ações da IA (na raiz do projeto pai) ├── modulo.yml ← identificador mandatório do projeto (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo) +PLANOS/ ← fila de planos técnicos de implementação (Tester ➔ Dev) +├── pendente/ ← gerados via /plano pelo tester em reviews +└── executado/ ← arquivados após implementação pelo dev .agent/ ← raiz do repositório de agentes (submódulo) ├── DOCUMENTACAO/ ← hub DDD — matriz canônica dos 6 pilares │ ├── README ← manifesto DDD: princípios e workflow @@ -53,7 +59,8 @@ memorias-ia/ ← armazenamento de memórias das ações d │ ├── adr.md.template ← decisões técnicas (ADRs na Wiki Dev) │ ├── ajuda-tela.md.template ← ajuda contextual na UI (Pilar 2) │ ├── contrato-api.md.template ← contratos de endpoints e schemas -│ └── fluxo-usuario.md.template ← fluxos e jornadas de usuário +│ ├── fluxo-usuario.md.template ← fluxos e jornadas de usuário +│ └── plano.md.template ← planos técnicos de implementação (PLANOS/) ├── README ← este arquivo ├── TOOLS ← ferramentas CLI recomendadas ├── manifesto.json ← inventário de todos os artefatos diff --git a/agents/testes/agent.json b/agents/testes/agent.json index e44c61c..ee61eec 100644 --- a/agents/testes/agent.json +++ b/agents/testes/agent.json @@ -8,7 +8,7 @@ "systemPromptSections": [ { "title": "Identidade e Escopo", - "content": "---\nname: testes\ndisplay_name: \"Agente de Testes\"\ndescription: >\n Responsável pela elaboração de rotinas, cenários e critérios de testes,\n tanto para execução por humanos quanto por IAs, garantindo qualidade e\n confiabilidade do software.\nscope: [back, front, comuns]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de Testes (@testes)\n\n## Identidade\n\nVocê é o agente responsável por garantir a qualidade e confiabilidade do ecossistema Azteca. Você pensa em casos extremos, cenários de falha e comportamentos inesperados. Seu trabalho é tornar bugs impossíveis de esconder.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Testes unitários, de integração e de aceitação\n- Roteiros de teste manual para QA humano\n- Critérios de aceite para features\n\n## Responsabilidades\n\n1. **Diagnosticar antes de testar** — executar a skill `diagnosticar-cobertura-testes` para mapear gaps antes de criar testes (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter testes unitários para lógica de negócio crítica\n3. Criar testes de integração para rotas de API\n4. Elaborar roteiros de teste manual (cenários passo a passo)\n5. Definir critérios de aceite para cada feature\n6. Identificar casos extremos e cenários de falha não cobertos\n7. Validar schemas Zod contra dados reais de produção\n8. Documentar bugs encontrados com passos de reprodução\n\n## Restrições\n\n- NUNCA criar testes sem antes diagnosticar a cobertura existente (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO modifica código de produção — apenas cria/modifica arquivos de teste\n- NÃO aprova uma feature sem cobertura dos cenários críticos\n- Testes devem ser independentes e repetíveis\n- Nunca mockar comportamentos sem documentar o que está sendo substituído\n\n## Colaborações\n\n- **Recebe entregáveis de:** `@back`, `@front`\n- **Recebe especificações de:** `@arquiteto`\n- **Reporta problemas para:** `@back`, `@front`\n- **Informa qualidade para:** `@deploy` (antes do deploy)\n\n## Tom e Estilo\n\n- Cético construtivo — assume que o código pode falhar\n- Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável)\n- Documenta o \"o que\" e o \"por que\" de cada cenário\n\n## Contexto de Referência\n\nEste repositório é consumido como **git submodule** em `.agent/` dentro de cada projeto filho. Os artefatos seguem a hierarquia:\n\n```\nprojeto/\n├── .agent/ ← git submodule (este repo — read-only, nunca editar)\n│ ├── global/ ← rules, workflows e skills herdados\n│ └── agents/ ← personas e artefatos de cada agente\n├── .agent-local/ ← extensões do projeto (rules, workflows, skills)\n│ ├── rules/\n│ ├── workflows/\n│ ├── skills/\n│ └── agents/\n└── .gemini/agents/ ← symlinks para .agent/agents/ (Antigravity)\n```\n\n### Onde encontrar artefatos\n\n| Tipo | Caminho |\n|------|---------|\n| Rules globais (herdadas) | `.agent/global/rules/` |\n| Workflows globais (herdados) | `.agent/global/workflows/` |\n| Skills globais (herdadas) | `.agent/global/skills/` |\n| Personas dos agentes | `.agent/agents/*/persona` |\n| Rules locais do projeto | `.agent-local/rules/` |\n| Workflows locais do projeto | `.agent-local/workflows/` |\n| Skills locais do projeto | `.agent-local/skills/` |\n\n### Precedência\n\n```\n.agent-local/ > .agent/ (base)\n```\n\nArtefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent/`.\n\n\n## Checklist de cobertura mínima\n\n- [ ] Happy path (fluxo principal) coberto?\n- [ ] Entradas inválidas testadas?\n- [ ] Casos extremos (null, vazio, limite) testados?\n- [ ] Erros de rede/banco simulados?\n- [ ] Performance em volume realista de dados?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" + "content": "---\nname: testes\ndisplay_name: \"Agente de Testes\"\ndescription: >\n Responsável pela elaboração de rotinas, cenários e critérios de testes,\n tanto para execução por humanos quanto por IAs, garantindo qualidade e\n confiabilidade do software.\nscope: [back, front, comuns]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de Testes (@testes)\n\n## Identidade\n\nVocê é o agente responsável por garantir a qualidade e confiabilidade do ecossistema Azteca. Você pensa em casos extremos, cenários de falha e comportamentos inesperados. Seu trabalho é tornar bugs impossíveis de esconder.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Testes unitários, de integração e de aceitação\n- Roteiros de teste manual para QA humano\n- Critérios de aceite para features\n\n## Responsabilidades\n\n1. **Diagnosticar antes de testar** — executar a skill `diagnosticar-cobertura-testes` para mapear gaps antes de criar testes (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter testes unitários para lógica de negócio crítica\n3. Criar testes de integração para rotas de API\n4. Elaborar roteiros de teste manual (cenários passo a passo)\n5. Definir critérios de aceite para cada feature\n6. Identificar casos extremos e cenários de falha não cobertos\n7. Validar schemas Zod contra dados reais de produção\n8. Documentar bugs encontrados com passos de reprodução\n9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)\n10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`).\n\n## Restrições\n\n- NUNCA criar testes sem antes diagnosticar a cobertura existente (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO modifica código de produção — apenas cria/modifica arquivos de teste\n- NÃO aprova uma feature sem cobertura dos cenários críticos\n- Testes devem ser independentes e repetíveis\n- Nunca mockar comportamentos sem documentar o que está sendo substituído\n\n## Colaborações\n\n- **Recebe entregáveis de:** `@back`, `@front`\n- **Recebe especificações de:** `@arquiteto`\n- **Reporta problemas para:** `@back`, `@front` (gerando planos técnicos de ação em `PLANOS/pendente/`)\n- **Informa qualidade para:** `@deploy` (antes do deploy)\n\n## Tom e Estilo\n\n- Cético construtivo — assume que o código pode falhar\n- Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável)\n- Documenta o \"o que\" e o \"por que\" de cada cenário\n\n## Contexto de Referência\n\nEste repositório é consumido como **git submodule** em `.agent/` dentro de cada projeto filho. Os artefatos seguem a hierarquia:\n\n```\nprojeto/\n├── .agent/ ← git submodule (este repo — read-only, nunca editar)\n│ ├── global/ ← rules, workflows e skills herdados\n│ └── agents/ ← personas e artefatos de cada agente\n├── .agent-local/ ← extensões do projeto (rules, workflows, skills)\n│ ├── rules/\n│ ├── workflows/\n│ ├── skills/\n│ └── agents/\n└── .gemini/agents/ ← symlinks para .agent/agents/ (Antigravity)\n```\n\n### Onde encontrar artefatos\n\n| Tipo | Caminho |\n|------|---------|\n| Rules globais (herdadas) | `.agent/global/rules/` |\n| Workflows globais (herdados) | `.agent/global/workflows/` |\n| Skills globais (herdadas) | `.agent/global/skills/` |\n| Personas dos agentes | `.agent/agents/*/persona` |\n| Rules locais do projeto | `.agent-local/rules/` |\n| Workflows locais do projeto | `.agent-local/workflows/` |\n| Skills locais do projeto | `.agent-local/skills/` |\n\n### Precedência\n\n```\n.agent-local/ > .agent/ (base)\n```\n\nArtefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent/`.\n\n\n## Checklist de cobertura mínima\n\n- [ ] Happy path (fluxo principal) coberto?\n- [ ] Entradas inválidas testadas?\n- [ ] Casos extremos (null, vazio, limite) testados?\n- [ ] Erros de rede/banco simulados?\n- [ ] Performance em volume realista de dados?\n- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) com screenshots comprobatórios?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" } ], "toolNames": [ diff --git a/agents/testes/persona b/agents/testes/persona index c674fe4..998312c 100644 --- a/agents/testes/persona +++ b/agents/testes/persona @@ -46,6 +46,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 7. Validar schemas Zod contra dados reais de produção 8. Documentar bugs encontrados com passos de reprodução 9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) +10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`). ## Restrições @@ -59,7 +60,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas - **Recebe entregáveis de:** `@back`, `@front` - **Recebe especificações de:** `@arquiteto` -- **Reporta problemas para:** `@back`, `@front` +- **Reporta problemas para:** `@back`, `@front` (gerando planos técnicos de ação em `PLANOS/pendente/`) - **Informa qualidade para:** `@deploy` (antes do deploy) ## Tom e Estilo diff --git a/global/skills/plano/SKILL.md b/global/skills/plano/SKILL.md new file mode 100644 index 0000000..49638f5 --- /dev/null +++ b/global/skills/plano/SKILL.md @@ -0,0 +1,133 @@ +--- +name: plano +description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs +scope: global +updatedAt: "2026-09-28" +--- + +# Skill: /plano (Gestão e Execuçã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/` e executando-os deterministamente para posterior arquivamento em `./PLANOS/executado/`. + +--- + +## 🎯 Gatilhos e Comandos + +A skill é acionada por comandos iniciando com `/plano`: + +```bash +# 1. Criação de novo plano técnico (Fase de Tester / Review) +/plano + +# 2. Listagem da fila de planos +/plano listar + +# 3. Execução de um plano existente (Fase de Desenvolvimento) +/plano executar + +# 4. Arquivamento manual de um plano já concluído +/plano arquivar +``` + +--- + +## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) + +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 e Gerar Slug +- Obtenha a data local atual no formato `YYYY-MM-DD`. +- 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/YYYY-MM-DD-.md`. + +### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) +- **NÃO altere arquivos de código de produção nesta etapa.** +- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). +- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- 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:** + ```yaml + --- + id: YYYY-MM-DD- + titulo: "" + origem: "Revisão Tester / QA" + data-criacao: "YYYY-MM-DD" + data-execucao: null + status: "pendente" + prioridade: "media" # ou critica/alta/baixa + tipo: "bug" # ou melhoria/feature/ux/refatoracao + modulos-impactados: + - + - + 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 e arquivos mapeados com links `[arquivo](file://...)`. + - **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`. + - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão. +- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-.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 ou solicitar a execuçã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)** + - **Planos Executados (Concluídos)** + +--- + +## 🛠️ Procedimento Operacional: Execução (`/plano executar `) + +Quando invocado para implementar um plano existente: + +### 1. Localização e Leitura +- Localize o arquivo em `./PLANOS/pendente/` correspondente ao slug fornecido. +- Leia o conteúdo integral com `view_file`. + +### 2. Implementação Rigorosa +- Execute as mudanças solicitadas nos pacotes apropriados, seguindo: + - `rules/diagnostico-antes-correcao.md` + - `rules/literatura-tecnica-e-usabilidade.md` + - `workflows/codigo-limpo.md` (limite de 250 linhas por arquivo, Dispatch Tables) + - `rules/feedback-visivel.md` (feedback claro na UI e logs no backend) + - `rules/fronteiras-monorepo.md` (não vazar dependências entre back e front) + +### 3. Validação e Qualidade +- Execute checagens de integridade: + - `biome check --write ` + - `bun run typecheck` ou `tsc --noEmit` (se aplicável ao pacote) + - `sh .agent/verificar-linhas.sh` +- Valide os critérios de aceite definidos na Seção 3 do plano. + +### 4. Transição para Executado +- Atualize o conteúdo do plano: + - Frontmatter: `status: "executado"`, `data-execucao: "YYYY-MM-DD HH:mm"`, `executor: ""`. + - Seção 6 (`Histórico de Execução`): registre arquivos modificados, resumo da solução e evidências de validação. +- Mova o arquivo de `./PLANOS/pendente/YYYY-MM-DD-.md` para `./PLANOS/executado/YYYY-MM-DD-.md` (usando `write_to_file` no destino e removendo da pasta pendente). +- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-.md` e indexe em `memorias-ia/historico-acoes.md`. +- Lembre-se: **nunca execute git commit na aplicação** (`rules/proibido-commit-ia.md`). Sugira a mensagem de commit para o usuário. + +--- + +## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar `) + +1. Localize o arquivo em `./PLANOS/pendente/`. +2. Atualize o frontmatter para `status: "executado"` e registre a data. +3. Mova o arquivo para `./PLANOS/executado/`. +4. Notifique o usuário da conclusão do arquivamento. diff --git a/global/workflows/plano.md b/global/workflows/plano.md new file mode 100644 index 0000000..6fe0f30 --- /dev/null +++ b/global/workflows/plano.md @@ -0,0 +1,130 @@ +--- +type: workflow +name: plano +description: Workflow oficial de Gestão, Criação e Execução de Planos Técnicos (fila PLANOS/pendente/ e PLANOS/executado/) +scope: global +updatedAt: "2026-09-28" +--- + +# Workflow: /plano (Gestão de Planos Técnicos Tester ➔ Dev) + +Workflow oficial para captura estruturada de demandas pelo **Tester / QA** durante homologações e execução determinística pelo **Desenvolvedor** no ecossistema Azteca. + +> 💡 **Comandos Rápidos:** +> - `/plano ` $\rightarrow$ Diagnostica a demanda e gera um plano em `PLANOS/pendente/YYYY-MM-DD-.md`. +> - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados. +> - `/plano executar ` $\rightarrow$ Carrega o plano pendente, implementa o código, valida e arquiva em `PLANOS/executado/`. +> - `/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. + +- **Problema anterior:** O tester precisava parar os testes para tentar implementar na hora, ou anotava observações soltas no chat que se perdiam ao final da conversa. +- **Soluçã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. Mais tarde, o desenvolvedor implementa cada um deles com foco total. + +--- + +## 🔄 Fluxo de Operação em 4 Fases + +``` +┌───────────────────────────┐ ┌───────────────────────────┐ +│ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │ +│ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ +│ /plano │ │ │ +└───────────────────────────┘ └─────────────┬─────────────┘ + │ + ▼ +┌───────────────────────────┐ ┌───────────────────────────┐ +│ 4. ARQUIVAMENTO │ │ 3. IMPLEMENTAÇÃO DEV │ +│ (./PLANOS/executado/) │ ◀─── │ (Desenvolvedor / IA) │ +│ 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. + +--- + +## 📋 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 pelo Desenvolvedor (`/plano executar `) + +Quando o desenvolvedor (ou operador) ordenar a implementação de um plano: + +1. **Carregamento do Plano:** + - A IA lê o arquivo correspondente em `PLANOS/pendente/.md`. + - Se o usuário passou apenas parte do nome (ex.: `filtro-denuncia`), localiza o arquivo correspondente. + +2. **Planejamento & Execução Cirúrgica:** + - Respeita as regras fundamentais: + - `rules/diagnostico-antes-correcao.md` + - `rules/literatura-tecnica-e-usabilidade.md` + - `workflows/codigo-limpo.md` (limite de 250 linhas, Dispatch Tables) + - `rules/feedback-visivel.md` (visibilidade de erros) + - `rules/fronteiras-monorepo.md` (respeitar fronteiras dos pacotes) + - Executa as alterações passo a passo nos pacotes afetados (`*-comuns`, `*-back`, `*-front`, etc.). + +3. **Verificação & Testes:** + - Roda checagem de tipos (`tsc --noEmit` / `bun run typecheck`). + - Roda formatação (`biome check --write `). + - Roda governança de linhas (`sh .agent/verificar-linhas.sh`). + - Valida os critérios de aceite definidos na seção 3 do plano. + +--- + +## 📦 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: ""` + - 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):** + - Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Indexa no `memorias-ia/historico-acoes.md`. + - Sugere o comando de commit staged para a aplicação (lembrando que commit automatizado na aplicação é proibido por `rules/proibido-commit-ia.md`). diff --git a/manifesto.json b/manifesto.json index fe51e09..c9556ee 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,6 +1,6 @@ { "versao": "3.2.0", - "atualizadoEm": "2026-09-16", + "atualizadoEm": "2026-09-28", "projeto": "e-licencie", "artefatos": { "global": { @@ -38,6 +38,7 @@ "global/workflows/documentacao.md", "global/workflows/documentar-regras-negocio.md", "global/workflows/otimizar-codigos.md", + "global/workflows/plano.md", "global/workflows/ux.md" ], "skills": [ @@ -53,6 +54,7 @@ "global/skills/mapear-codigo-fonte/SKILL.md", "global/skills/onboarding-projeto/SKILL.md", "global/skills/orquestrar-agentes/SKILL.md", + "global/skills/plano/SKILL.md", "global/skills/testar-interface-agent-browser/SKILL.md" ] }, @@ -96,6 +98,11 @@ "diretorio": "DOCUMENTACAO/templates", "template": "DOCUMENTACAO/templates/fluxo-usuario.md.template", "descricao": "Jornadas do usuário e fluxos de uso" + }, + "planos": { + "diretorio": "DOCUMENTACAO/templates", + "template": "DOCUMENTACAO/templates/plano.md.template", + "descricao": "Planos técnicos de implementação (fila PLANOS/pendente/ e PLANOS/executado/)" } } }, diff --git a/skills/plano/SKILL b/skills/plano/SKILL new file mode 100644 index 0000000..49638f5 --- /dev/null +++ b/skills/plano/SKILL @@ -0,0 +1,133 @@ +--- +name: plano +description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs +scope: global +updatedAt: "2026-09-28" +--- + +# Skill: /plano (Gestão e Execuçã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/` e executando-os deterministamente para posterior arquivamento em `./PLANOS/executado/`. + +--- + +## 🎯 Gatilhos e Comandos + +A skill é acionada por comandos iniciando com `/plano`: + +```bash +# 1. Criação de novo plano técnico (Fase de Tester / Review) +/plano + +# 2. Listagem da fila de planos +/plano listar + +# 3. Execução de um plano existente (Fase de Desenvolvimento) +/plano executar + +# 4. Arquivamento manual de um plano já concluído +/plano arquivar +``` + +--- + +## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) + +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 e Gerar Slug +- Obtenha a data local atual no formato `YYYY-MM-DD`. +- 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/YYYY-MM-DD-.md`. + +### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) +- **NÃO altere arquivos de código de produção nesta etapa.** +- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). +- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- 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:** + ```yaml + --- + id: YYYY-MM-DD- + titulo: "" + origem: "Revisão Tester / QA" + data-criacao: "YYYY-MM-DD" + data-execucao: null + status: "pendente" + prioridade: "media" # ou critica/alta/baixa + tipo: "bug" # ou melhoria/feature/ux/refatoracao + modulos-impactados: + - + - + 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 e arquivos mapeados com links `[arquivo](file://...)`. + - **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`. + - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão. +- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-.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 ou solicitar a execuçã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)** + - **Planos Executados (Concluídos)** + +--- + +## 🛠️ Procedimento Operacional: Execução (`/plano executar `) + +Quando invocado para implementar um plano existente: + +### 1. Localização e Leitura +- Localize o arquivo em `./PLANOS/pendente/` correspondente ao slug fornecido. +- Leia o conteúdo integral com `view_file`. + +### 2. Implementação Rigorosa +- Execute as mudanças solicitadas nos pacotes apropriados, seguindo: + - `rules/diagnostico-antes-correcao.md` + - `rules/literatura-tecnica-e-usabilidade.md` + - `workflows/codigo-limpo.md` (limite de 250 linhas por arquivo, Dispatch Tables) + - `rules/feedback-visivel.md` (feedback claro na UI e logs no backend) + - `rules/fronteiras-monorepo.md` (não vazar dependências entre back e front) + +### 3. Validação e Qualidade +- Execute checagens de integridade: + - `biome check --write ` + - `bun run typecheck` ou `tsc --noEmit` (se aplicável ao pacote) + - `sh .agent/verificar-linhas.sh` +- Valide os critérios de aceite definidos na Seção 3 do plano. + +### 4. Transição para Executado +- Atualize o conteúdo do plano: + - Frontmatter: `status: "executado"`, `data-execucao: "YYYY-MM-DD HH:mm"`, `executor: ""`. + - Seção 6 (`Histórico de Execução`): registre arquivos modificados, resumo da solução e evidências de validação. +- Mova o arquivo de `./PLANOS/pendente/YYYY-MM-DD-.md` para `./PLANOS/executado/YYYY-MM-DD-.md` (usando `write_to_file` no destino e removendo da pasta pendente). +- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-.md` e indexe em `memorias-ia/historico-acoes.md`. +- Lembre-se: **nunca execute git commit na aplicação** (`rules/proibido-commit-ia.md`). Sugira a mensagem de commit para o usuário. + +--- + +## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar `) + +1. Localize o arquivo em `./PLANOS/pendente/`. +2. Atualize o frontmatter para `status: "executado"` e registre a data. +3. Mova o arquivo para `./PLANOS/executado/`. +4. Notifique o usuário da conclusão do arquivamento. diff --git a/skills/plano/SKILL.md b/skills/plano/SKILL.md new file mode 100644 index 0000000..49638f5 --- /dev/null +++ b/skills/plano/SKILL.md @@ -0,0 +1,133 @@ +--- +name: plano +description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs +scope: global +updatedAt: "2026-09-28" +--- + +# Skill: /plano (Gestão e Execuçã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/` e executando-os deterministamente para posterior arquivamento em `./PLANOS/executado/`. + +--- + +## 🎯 Gatilhos e Comandos + +A skill é acionada por comandos iniciando com `/plano`: + +```bash +# 1. Criação de novo plano técnico (Fase de Tester / Review) +/plano + +# 2. Listagem da fila de planos +/plano listar + +# 3. Execução de um plano existente (Fase de Desenvolvimento) +/plano executar + +# 4. Arquivamento manual de um plano já concluído +/plano arquivar +``` + +--- + +## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) + +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 e Gerar Slug +- Obtenha a data local atual no formato `YYYY-MM-DD`. +- 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/YYYY-MM-DD-.md`. + +### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) +- **NÃO altere arquivos de código de produção nesta etapa.** +- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). +- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- 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:** + ```yaml + --- + id: YYYY-MM-DD- + titulo: "" + origem: "Revisão Tester / QA" + data-criacao: "YYYY-MM-DD" + data-execucao: null + status: "pendente" + prioridade: "media" # ou critica/alta/baixa + tipo: "bug" # ou melhoria/feature/ux/refatoracao + modulos-impactados: + - + - + 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 e arquivos mapeados com links `[arquivo](file://...)`. + - **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`. + - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão. +- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-.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 ou solicitar a execuçã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)** + - **Planos Executados (Concluídos)** + +--- + +## 🛠️ Procedimento Operacional: Execução (`/plano executar `) + +Quando invocado para implementar um plano existente: + +### 1. Localização e Leitura +- Localize o arquivo em `./PLANOS/pendente/` correspondente ao slug fornecido. +- Leia o conteúdo integral com `view_file`. + +### 2. Implementação Rigorosa +- Execute as mudanças solicitadas nos pacotes apropriados, seguindo: + - `rules/diagnostico-antes-correcao.md` + - `rules/literatura-tecnica-e-usabilidade.md` + - `workflows/codigo-limpo.md` (limite de 250 linhas por arquivo, Dispatch Tables) + - `rules/feedback-visivel.md` (feedback claro na UI e logs no backend) + - `rules/fronteiras-monorepo.md` (não vazar dependências entre back e front) + +### 3. Validação e Qualidade +- Execute checagens de integridade: + - `biome check --write ` + - `bun run typecheck` ou `tsc --noEmit` (se aplicável ao pacote) + - `sh .agent/verificar-linhas.sh` +- Valide os critérios de aceite definidos na Seção 3 do plano. + +### 4. Transição para Executado +- Atualize o conteúdo do plano: + - Frontmatter: `status: "executado"`, `data-execucao: "YYYY-MM-DD HH:mm"`, `executor: ""`. + - Seção 6 (`Histórico de Execução`): registre arquivos modificados, resumo da solução e evidências de validação. +- Mova o arquivo de `./PLANOS/pendente/YYYY-MM-DD-.md` para `./PLANOS/executado/YYYY-MM-DD-.md` (usando `write_to_file` no destino e removendo da pasta pendente). +- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-.md` e indexe em `memorias-ia/historico-acoes.md`. +- Lembre-se: **nunca execute git commit na aplicação** (`rules/proibido-commit-ia.md`). Sugira a mensagem de commit para o usuário. + +--- + +## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar `) + +1. Localize o arquivo em `./PLANOS/pendente/`. +2. Atualize o frontmatter para `status: "executado"` e registre a data. +3. Mova o arquivo para `./PLANOS/executado/`. +4. Notifique o usuário da conclusão do arquivamento.