.
This commit is contained in:
parent
a947483a76
commit
e899107f22
9 changed files with 657 additions and 4 deletions
109
DOCUMENTACAO/templates/plano.md.template
Normal file
109
DOCUMENTACAO/templates/plano.md.template
Normal file
|
|
@ -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"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Criação pelo Tester: <base_projeto>/PLANOS/pendente/YYYY-MM-DD-<slug>.md
|
||||
- Arquivamento pelo Dev: <base_projeto>/PLANOS/executado/YYYY-MM-DD-<slug>.md
|
||||
|
||||
EXEMPLO:
|
||||
PLANOS/pendente/2026-09-28-ajuste-filtro-denuncia-anonima.md
|
||||
-->
|
||||
|
||||
---
|
||||
id: YYYY-MM-DD-<slug-do-plano>
|
||||
titulo: "<Título claro e descritivo da demanda>"
|
||||
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: <Título do Plano>
|
||||
|
||||
## 1. Objetivo & Contexto
|
||||
<Descreva o problema encontrado durante o teste ou a funcionalidade requerida. Qual é o contexto de negócio ou operacional? Por que essa mudança é necessária?>
|
||||
|
||||
---
|
||||
|
||||
## 2. Diagnóstico Técnico & Evidências do Tester
|
||||
|
||||
### Comportamento Observado vs Comportamento Esperado
|
||||
- **Observado:** <O que acontece hoje de forma incorreta ou incompleta>
|
||||
- **Esperado:** <O que deve acontecer após a implementação>
|
||||
|
||||
### Passos para Reproduzir (Repro Steps) / Evidência Visual
|
||||
1. <Passo 1>
|
||||
2. <Passo 2>
|
||||
3. <Evidência: link para screenshot em evidencias/ ou anotação do tester>
|
||||
|
||||
### Análise de Causa Raiz & Arquivos Mapeados
|
||||
<Diagnóstico técnico preliminar apontando causas prováveis no código>
|
||||
- `caminho/do/arquivo1.ts` — <motivo do impacto>
|
||||
- `caminho/do/arquivo2.vue` — <motivo do impacto>
|
||||
|
||||
---
|
||||
|
||||
## 3. Critérios de Aceite & Validação (Definition of Done)
|
||||
- [ ] <Critério 1: Condição necessária para aceitar a entrega>
|
||||
- [ ] <Critério 2: Tratamento de exceção / caso de borda>
|
||||
- [ ] <Critério 3: Feedback visual na UI / resposta da API>
|
||||
- [ ] <Critério 4: Ausência de efeitos colaterais em fluxos existentes>
|
||||
|
||||
---
|
||||
|
||||
## 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 <arquivos>`
|
||||
- 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:** `<YYYY-MM-DD HH:mm>`
|
||||
- **Data de Conclusão:** `<YYYY-MM-DD HH:mm>`
|
||||
- **Executor:** `<Nome do Dev ou IA>`
|
||||
- **Arquivos Efetivamente Modificados:**
|
||||
- `<caminho/arquivo>`
|
||||
- **Resumo da Solução Implementada:**
|
||||
- <Descrição das mudanças realizadas e desafios superados>
|
||||
- **Evidências de Teste / Screenshots:**
|
||||
- <Links ou descrições dos testes executados com sucesso>
|
||||
9
README
9
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 <instrução>)
|
||||
│ └── executado/ ← Planos implementados, testados e arquivados (/plano executar <slug>)
|
||||
├── .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
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -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
|
||||
|
|
|
|||
133
global/skills/plano/SKILL.md
Normal file
133
global/skills/plano/SKILL.md
Normal file
|
|
@ -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 <instrução ou descrição da melhoria / bug>
|
||||
|
||||
# 2. Listagem da fila de planos
|
||||
/plano listar
|
||||
|
||||
# 3. Execução de um plano existente (Fase de Desenvolvimento)
|
||||
/plano executar <slug-ou-nome-do-arquivo>
|
||||
|
||||
# 4. Arquivamento manual de um plano já concluído
|
||||
/plano arquivar <slug-ou-nome-do-arquivo>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 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-<slug>.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-<slug>
|
||||
titulo: "<Título claro e direto>"
|
||||
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:
|
||||
- <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 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-<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 ou solicitar a execução via `/plano executar <slug>`.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 <slug>`)
|
||||
|
||||
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 <arquivos-alterados>`
|
||||
- `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: "<nome-ou-agente>"`.
|
||||
- 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-<slug>.md` para `./PLANOS/executado/YYYY-MM-DD-<slug>.md` (usando `write_to_file` no destino e removendo da pasta pendente).
|
||||
- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-<slug>.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 <slug>`)
|
||||
|
||||
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.
|
||||
130
global/workflows/plano.md
Normal file
130
global/workflows/plano.md
Normal file
|
|
@ -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 <instrução>` $\rightarrow$ Diagnostica a demanda e gera um plano em `PLANOS/pendente/YYYY-MM-DD-<slug>.md`.
|
||||
> - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados.
|
||||
> - `/plano executar <slug>` $\rightarrow$ Carrega o plano pendente, implementa o código, valida e arquiva em `PLANOS/executado/`.
|
||||
> - `/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.
|
||||
|
||||
- **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 <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. 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 <instrução> │ │ │
|
||||
└───────────────────────────┘ └─────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐ ┌───────────────────────────┐
|
||||
│ 4. ARQUIVAMENTO │ │ 3. IMPLEMENTAÇÃO DEV │
|
||||
│ (./PLANOS/executado/) │ ◀─── │ (Desenvolvedor / IA) │
|
||||
│ Metadados & Histórico │ │ /plano executar <slug> │
|
||||
└───────────────────────────┘ └───────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 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/YYYY-MM-DD-<slug-em-kebab-case>.md`
|
||||
- Onde `YYYY-MM-DD` é a data atual da máquina e `<slug>` 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 <slug>`)
|
||||
|
||||
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/<nome-do-arquivo>.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 <arquivos>`).
|
||||
- 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: "<nome-do-dev-ou-agente>"`
|
||||
- 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-<slug>.md`
|
||||
para:
|
||||
`PLANOS/executado/YYYY-MM-DD-<slug>.md`
|
||||
|
||||
3. **Registro na Memória do Projeto (Pilar 6):**
|
||||
- Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-<slug>.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`).
|
||||
|
|
@ -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/)"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
|
|||
133
skills/plano/SKILL
Normal file
133
skills/plano/SKILL
Normal file
|
|
@ -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 <instrução ou descrição da melhoria / bug>
|
||||
|
||||
# 2. Listagem da fila de planos
|
||||
/plano listar
|
||||
|
||||
# 3. Execução de um plano existente (Fase de Desenvolvimento)
|
||||
/plano executar <slug-ou-nome-do-arquivo>
|
||||
|
||||
# 4. Arquivamento manual de um plano já concluído
|
||||
/plano arquivar <slug-ou-nome-do-arquivo>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 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-<slug>.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-<slug>
|
||||
titulo: "<Título claro e direto>"
|
||||
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:
|
||||
- <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 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-<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 ou solicitar a execução via `/plano executar <slug>`.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 <slug>`)
|
||||
|
||||
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 <arquivos-alterados>`
|
||||
- `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: "<nome-ou-agente>"`.
|
||||
- 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-<slug>.md` para `./PLANOS/executado/YYYY-MM-DD-<slug>.md` (usando `write_to_file` no destino e removendo da pasta pendente).
|
||||
- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-<slug>.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 <slug>`)
|
||||
|
||||
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.
|
||||
133
skills/plano/SKILL.md
Normal file
133
skills/plano/SKILL.md
Normal file
|
|
@ -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 <instrução ou descrição da melhoria / bug>
|
||||
|
||||
# 2. Listagem da fila de planos
|
||||
/plano listar
|
||||
|
||||
# 3. Execução de um plano existente (Fase de Desenvolvimento)
|
||||
/plano executar <slug-ou-nome-do-arquivo>
|
||||
|
||||
# 4. Arquivamento manual de um plano já concluído
|
||||
/plano arquivar <slug-ou-nome-do-arquivo>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 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-<slug>.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-<slug>
|
||||
titulo: "<Título claro e direto>"
|
||||
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:
|
||||
- <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 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-<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 ou solicitar a execução via `/plano executar <slug>`.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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 <slug>`)
|
||||
|
||||
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 <arquivos-alterados>`
|
||||
- `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: "<nome-ou-agente>"`.
|
||||
- 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-<slug>.md` para `./PLANOS/executado/YYYY-MM-DD-<slug>.md` (usando `write_to_file` no destino e removendo da pasta pendente).
|
||||
- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-<slug>.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 <slug>`)
|
||||
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue