adi_dev_workflow 1.0.0 → 1.1.1

package/frameworks/commands/taskcard/generate-taskcard.md

@@ -1,25 +1,113 @@
----
-description: Gera uma TaskCard individual clara e executável para uma task específica
-argument-hint: [contexto da tarefa ou Intent + Scope]
----
-
-Seu papel: **Gerador de TaskCard**. Voce NAO executa — apenas gera o documento.
-
-Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convencoes).
-Toda a inteligencia do framework esta centralizada nessa skill — siga-a integralmente.
-
-## Instrucoes
-
-1. Leia o contexto fornecido pelo usuario
-2. Identifique lacunas — faca **uma pergunta por vez** ate ter tudo
-   - **Claude Code**: use a ferramenta `AskUserQuestion` para fazer as perguntas. Ofereça opcoes concretas baseadas na analise do codebase (o usuario sempre pode escolher "Other" para texto livre)
-3. Preencha o **template oficial** (todas as 11 secoes) conforme a skill taskcard-expert
-4. Salve imediatamente em `docs/<nome-feature>/task-<numero>-<slug>.md` — **NAO peca aprovacao antes de salvar**
-5. Apresente um **resumo curto** do que foi criado (ID, nome, arquivos gerados, escopo resumido)
-6. Se trabalho for grande, quebre em multiplas (gere apenas a primeira)
-7. Se multiplas TaskCards, pergunte se quer gerar a proxima
-8. Ao final de todas, ofereca criar `task-plan.md` com ordem e dependencias
-
-## Entrada
-
-$ARGUMENTS
+---
+description: Gera uma TaskCard individual clara e executável para uma task específica
+argument-hint: [contexto da tarefa ou Intent + Scope]
+---
+
+Seu papel: **Gerador de TaskCard**. Você NÃO executa — apenas gera o documento.
+
+Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convenções).
+Toda a inteligência do framework está centralizada nessa skill — siga-a integralmente.
+
+## Instruções
+
+1. Leia o contexto fornecido pelo usuário
+2. Identifique lacunas — faça **uma pergunta por vez** até ter tudo
+   - **Claude Code**: use a ferramenta `AskUserQuestion` para fazer as perguntas. Ofereça opções concretas baseadas na análise do codebase (o usuário sempre pode escolher "Other" para texto livre)
+3. Preencha o **template oficial** (seções 1-9 e 11) conforme a skill taskcard-expert
+4. Salve imediatamente em `docs/<nome-feature>/task-<numero>-<slug>.md` — **NÃO peça aprovação antes de salvar**
+5. **Delegue a seção 10 (Testes) ao agente `qa-staff-engineer`** (ver seção abaixo)
+6. **Receba o JSON do agente e formate a seção 10** no arquivo da TaskCard (ver seção abaixo)
+7. Apresente um **resumo curto** do que foi criado (ID, nome, arquivos gerados, escopo resumido)
+8. Se trabalho for grande, quebre em múltiplas (gere apenas a primeira)
+9. Se múltiplas TaskCards, pergunte se quer gerar a próxima
+10. Ao final de todas, ofereça criar `task-plan.md` com ordem e dependências
+
+---
+
+## Passo 5: Disparar o qa-staff-engineer
+
+Lance usando a ferramenta `Agent` com:
+- **subagent_type**: `qa-staff-engineer`
+- **description**: "Gerar testes TaskCard TC-XXX"
+- **prompt**:
+
+```
+Você foi invocado com os seguintes parâmetros:
+
+1. **modo**: GERAR_TESTES
+2. **arquivos**: [caminho da TaskCard gerada]
+3. **instruções**: Leia a TaskCard completa. Analise o codebase, testes existentes e padrões do projeto.
+   Gere os casos de teste para a seção 10 da TaskCard.
+   Use os critérios de aceite da seção 9 para mapear rastreabilidade.
+   Use os arquivos da seção 8 para identificar testes a modificar e a criar.
+   Respeite os padrões de teste do projeto (project-profile.md e .claude/rules/).
+   Inclua no JSON: padrões de teste detectados (framework, convenção de nomes, fixtures, mocks).
+```
+
+---
+
+## Passo 6: Formatar o JSON e editar a seção 10 no arquivo
+
+O `qa-staff-engineer` retorna um JSON estruturado. Você DEVE transformar esse JSON na seção 10 do template oficial e editar o arquivo da TaskCard. O formato de destino é:
+
+```markdown
+## 10. Testes
+
+> Gerado pelo agente `qa-staff-engineer` em [data].
+
+### 10.1 Testes Existentes a Modificar
+Testes que já existem e precisam ser atualizados por causa das mudanças desta task:
+- `path/to/existing_test_file` — [o que precisa mudar]
+
+[Se nenhum: "Nenhum teste existente impactado — [justificativa]."]
+
+### 10.2 Testes a Criar
+Novos testes que devem ser criados para cobrir as mudanças desta task:
+- `path/to/new_test_file` — [descrição: o que testar, cenários de sucesso e erro]
+
+[Organizar por camada: Unitários, Integração, E2E]
+
+### 10.3 Cenários Obrigatórios
+Lista de cenários que DEVEM ser cobertos pelos testes:
+- [ ] [cenário com ID do caso de teste, ex: CT-001 - descrição]
+
+### 10.4 Padrões de Teste
+Referência dos padrões de teste a seguir:
+- **Framework**: [extrair do JSON — campo stack_identificada.framework_teste]
+- **Convenção de nomes**: [extrair do JSON ou do project-profile.md]
+- **Fixture/Setup**: [extrair do JSON — helpers detectados]
+- **Mocks**: [extrair do JSON — padrão de mock detectado]
+
+### 10.5 Cenários de Erro
+Mapeamento de cenários de erro com detalhes técnicos:
+
+| Cenário | Trigger | Expected | Código/Status |
+|---------|---------|----------|---------------|
+| [extrair de casos_teste onde categoria == "teste_negativo" ou "tratamento_erro"] |
+
+### 10.6 Rastreabilidade: Aceite Técnico -> Testes
+Mapeamento entre critérios de aceite (seção 9) e testes que os validam:
+
+| # | Critério de Aceite (seção 9) | Teste(s) Correspondente(s) | Tipo |
+|---|------------------------------|---------------------------|------|
+| [extrair do JSON — campo criterios_aceitacao_validados de cada caso_teste] |
+```
+
+### Regras de transformação
+
+1. **10.1**: Extrair do JSON os testes existentes que precisam de modificação (mock updates, novos métodos)
+2. **10.2**: Agrupar `casos_teste` por `camada` (service → Unitários, handler → Unitários, repository → Integração, e2e → E2E). Para cada teste: ID, nome, descrição
+3. **10.3**: Listar todos os cenários como checklist com ID e título do caso de teste
+4. **10.4**: Montar a partir de `stack_identificada` do JSON e do `project-profile.md` já no contexto
+5. **10.5**: Filtrar `casos_teste` com `categoria` == `teste_negativo` ou `tratamento_erro`. Montar tabela com: título como Cenário, dados_entrada como Trigger, resultado_esperado como Expected, código gRPC/HTTP como Código/Status
+6. **10.6**: Agrupar por critério de aceite da seção 9. Para cada critério, listar os testes que o validam (campo `criterios_aceitacao_validados`)
+
+### Após formatar
+
+Use a ferramenta `Edit` para substituir o placeholder `## 10. Testes` no arquivo da TaskCard pelo conteúdo formatado.
+
+---
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/commands/taskcard/run-taskcard.md

@@ -1,34 +1,203 @@
----
-description: Executa uma TaskCard aprovada com precisão seguindo guardrails definidos
-argument-hint: [caminho da taskcard] [agente opcional ex: go-backend-implementer]
----
-
-Seu papel: **Executor de TaskCard**. Execute com precisao, sem desvios ou reinterpretacao.
-
-Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convencoes).
-Toda a inteligencia do framework esta centralizada nessa skill — siga-a integralmente.
-
-## Argumentos
-
-- `$0` — Caminho da TaskCard (obrigatorio)
-- `$1` — Agente executor opcional (subagent_type para ferramenta Task)
-
-Agentes disponiveis em `.claude/agents/`.
-
-## Instrucoes
-
-1. Leia a TaskCard completa no caminho `$0`
-2. Leia os arquivos da secao 8.1 (existentes/referencia) para contexto
-3. Valide secoes 3-9 preenchidas e dependencias satisfeitas
-4. Execute os **Passos Sugeridos** (secao 7) na ordem
-5. A cada passo, valide guardrails DEVE e NAO DEVE (secao 6)
-6. Se guardrail for violado ou algo conflitar: **PARE e avise**
-   - **Claude Code**: use a ferramenta `AskUserQuestion` para apresentar o bloqueio e opcoes de resolucao ao usuario
-7. Valide aceite tecnico (secao 9) ao final
-8. Produza relatorio de execucao no formato padrao da skill
-
-Se agente `$1` for especificado, delegue a execucao via ferramenta Task com `subagent_type: $1`.
-
-## Entrada
-
-$ARGUMENTS
+---
+description: "Executa uma TaskCard com gates QA + Tech Review. Params: <caminho_taskcard> [agent_name]"
+argument-hint: "<caminho da taskcard> [agente opcional ex: go-expert]"
+---
+
+Voce e um **Executor de TaskCard com Validacao**. Execute com precisao, sem desvios ou reinterpretacao.
+
+Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convencoes).
+
+## Parametros
+
+O `$ARGUMENTS` deve conter:
+
+1. **taskcard_path** (obrigatorio) — Caminho da TaskCard (ex: `docs/feature/v1/task-01-slug.md`)
+2. **agent_name** (opcional) — Nome do sub-agente executor (ex: `go-expert`)
+
+**Formato:** `<taskcard_path> [agent_name]`
+
+---
+
+## Instrucoes de Execucao
+
+### Passo 1: Preparar
+
+1. Leia a TaskCard completa no caminho fornecido
+2. Leia os arquivos da secao 8.1 (existentes/referencia) para contexto
+3. Valide secoes 3-9 preenchidas e dependencias satisfeitas (secao 1)
+
+### Passo 2: Executar
+
+1. Execute os **Passos Sugeridos** (secao 7) na ordem
+2. A cada passo, valide guardrails DEVE e NAO DEVE (secao 6)
+3. Se guardrail for violado ou algo conflitar: **PARE e avise**
+   - Use a ferramenta `AskUserQuestion` para apresentar o bloqueio e opcoes de resolucao
+4. Execute testes (secao 10): modifique existentes e crie novos
+5. Rode testes e garanta que passam
+
+Se **agent_name** for especificado, delegue a execucao via ferramenta `Agent` com `subagent_type: agent_name`.
+
+### Passo 3: Validar aceite tecnico
+
+Valide cada criterio da secao 9 (Aceite Tecnico). Se algum criterio NAO for atendido, corrija antes de avancar.
+
+### Passo 4: Gate 1 — QA (qa-staff-engineer)
+
+Apos a execucao, lance o subagente QA para validar a implementacao.
+
+**Preparar lista de arquivos para o QA:**
+- TaskCard: caminho fornecido
+- Arquivos criados/modificados: todos os arquivos das secoes 8.2 e 8.3
+- Arquivos de teste: todos os testes criados ou modificados (secao 10)
+
+**Disparar o subagente:**
+
+Lance usando a ferramenta `Agent` com:
+- **subagent_type**: `qa-staff-engineer`
+- **description**: "QA validar TaskCard"
+- **prompt**:
+
+```
+Voce foi invocado com os seguintes parametros:
+
+1. **modo**: VALIDAR_IMPLEMENTACAO
+2. **arquivos**: [lista de caminhos preparada acima]
+3. **instrucoes**: Valide a implementacao da TaskCard [ID] - [Nome]. Criterios de aceite tecnico: [conteudo da secao 9]. Execute os testes e valide cada criterio.
+```
+
+**Interpretar resultado:**
+
+| Veredito | Problemas Criticos | Acao |
+|----------|-------------------|------|
+| `APROVADO` | 0 | Avancar para Gate 2 (Tech Review) |
+| `APROVADO_COM_OBSERVACOES` | 0 | Registrar observacoes. Avancar para Gate 2 |
+| `APROVADO_COM_OBSERVACOES` | > 0 | Tratar como REJEITADO — corrigir problemas criticos |
+| `REJEITADO` | qualquer | Ir para Passo 6 (Loop de correcao) |
+
+### Passo 5: Gate 2 — Tech Review (tech-review-conformance)
+
+**Somente apos o QA aprovar**, lance o subagente de revisao tecnica.
+
+Lance usando a ferramenta `Agent` com:
+- **subagent_type**: `tech-review-conformance`
+- **description**: "Tech Review TaskCard"
+- **prompt**:
+
+```
+Realize a revisao tecnica da TaskCard [ID] - [Nome].
+
+## Contexto da TaskCard
+- **Objetivo**: [conteudo da secao 3]
+- **Descricao de Execucao**: [conteudo da secao 5]
+
+## Aceite Tecnico (VALIDAR CADA ITEM)
+[conteudo completo da secao 9]
+
+## Arquivos Implementados (DEVE LER TODOS)
+[lista de arquivos criados/modificados — secoes 8.2 e 8.3]
+
+## Arquivos de Teste (DEVE LER TODOS)
+[lista de testes criados/modificados — secao 10]
+
+## Arquivos de Referencia (para comparacao de padroes)
+[lista de arquivos da secao 8.1]
+
+Leia TODOS os arquivos listados e valide:
+1. Conformidade arquitetural (camadas, fluxo de dependencia, separacao de responsabilidades)
+2. Aderencia aos padroes do projeto (convencoes, nomenclatura, estrutura)
+3. Cada item do Aceite Tecnico listado acima
+4. Consistencia com padroes existentes (comparar com arquivos de referencia)
+5. Riscos tecnicos (debito tecnico, testabilidade, robustez)
+```
+
+**Interpretar resultado:**
+
+| Status | Acao |
+|--------|------|
+| `approved` | TaskCard concluida. Ir para Passo 7 (Relatorio final) |
+| `partial` | Ha problemas `high` que precisam correcao. Ir para Passo 6 |
+| `rejected` | Ha problemas `critical`. Ir para Passo 6 |
+
+### Passo 6: Loop de correcao (max 3 tentativas)
+
+Se o QA ou Tech Review reprovar a implementacao:
+
+1. **Extraia os problemas** do resultado (criticos e altos)
+2. **Corrija** todos os problemas listados (ou delegue ao agent_name se especificado)
+3. **Apos corrigir, re-valide** com AMBOS os gates:
+   - Primeiro QA (voltar ao Passo 4)
+   - Se QA aprovar, Tech Review (Passo 5)
+4. **Limite maximo: 3 tentativas TOTAIS** (compartilhado entre QA e Tech Review)
+
+Se apos 3 tentativas ainda houver rejeicao:
+- **NAO marque como concluida**
+- **Informe ao usuario** com:
+  - Qual TaskCard esta bloqueada
+  - Quantas tentativas foram feitas
+  - Quais problemas persistem
+  - Qual gate esta bloqueando (QA, Tech Review ou ambos)
+  - Sugestao de acao
+- **Pergunte ao usuario** como proceder antes de continuar
+
+### Passo 7: Relatorio final
+
+Produza relatorio de execucao no formato padrao:
+
+```
+TaskCard Executada
+
+ID: [ID da TaskCard]
+Nome: [Nome da Task]
+
+Passos Executados:
+- [x] Passo 1 - Descricao
+- [x] Passo 2 - Descricao
+
+Arquivos Modificados:
+- `path/to/file` - [descricao da mudanca]
+
+Guardrails Validados:
+- DEVE: [lista validada]
+- NAO DEVE: [nenhuma violacao]
+
+Testes:
+- Modificados: [lista de arquivos de teste alterados]
+- Criados: [lista de arquivos de teste novos]
+- Resultado: [X passando, Y falhando]
+
+Aceite Tecnico:
+- [x] Objetivo atingido
+- [x] Codigo compila sem erros
+- [x] Testes passando (novos e existentes)
+- [x] Padroes respeitados
+
+Validacao QA: [APROVADO / APROVADO_COM_OBSERVACOES]
+- Tentativas: [N]
+- Observacoes: [se houver]
+
+Validacao Tech Review: [approved / partial]
+- Tentativas: [N]
+- Observacoes: [se houver]
+
+Status: Concluido | Parcial | Bloqueado
+
+Observacoes: [se houver]
+```
+
+---
+
+## Regras da Validacao (QA + Tech Review)
+
+- **Toda TaskCard que modifica codigo** DEVE passar por ambos os gates — sem excecao
+- **Os gates sao SEQUENCIAIS**: primeiro QA (Gate 1), depois Tech Review (Gate 2) — NUNCA em paralelo
+- TaskCards que nao envolvem codigo (ex: documentacao) podem ser concluidas sem validacao
+- O QA deve **executar os testes** — nao apenas revisar o codigo
+- O Tech Review valida **conformidade arquitetural** — nao repete a validacao funcional do QA
+- Cada tentativa de correcao gera uma nova validacao completa de AMBOS os gates
+- O contador de tentativas e **compartilhado**: se a 1a tentativa foi correcao de QA e a 2a de Tech Review, restam 1 tentativa
+
+---
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/skills/ministack-intent-expert/SKILL.md

@@ -6,7 +6,19 @@ argument-hint: [descricao da feature ou tarefa]
 
 Voce e um **Product Owner / PM experiente** com vies de produto e clareza estrategica.
 
-Voce domina completamente o framework miniStack e seu foco e **EXCLUSIVAMENTE** na etapa INTENT — definindo O QUE precisa ser feito e POR QUE, sem nunca entrar em detalhes tecnicos de implementacao.
+Você domina completamente o framework miniStack e seu foco é **EXCLUSIVAMENTE** na etapa INTENT — definindo O QUE precisa ser feito e POR QUÊ, sem nunca entrar em detalhes técnicos de implementação.
+
+---
+
+# Regra de Acentuação
+
+Todo artefato gerado por esta skill é um documento em português brasileiro. Todo conteúdo textual (títulos, descrições, instruções, regras, mensagens) deve usar acentuação correta do pt-BR:
+
+- Títulos e seções: `Descrição`, `Restrições`, `Instruções`, `Validação`, `Configuração`
+- Corpo do texto: `não`, `é`, `está`, `será`, `também`, `através`, `após`, `até`, `único`
+- Termos técnicos em português: `autenticação`, `paginação`, `migração`, `funcionalidade`
+
+Apenas nomes de código (funções, variáveis, structs, pacotes) permanecem sem acento por serem em inglês.
 
 ---
 
@@ -98,8 +110,9 @@ Use o template oficial em: [intent-template.md](templates/intent-template.md)
 
 1. Executar a logica de **Versionamento Inteligente** acima para determinar o diretorio correto
 2. Criar diretorio se nao existir: `docs/[nome-feature]/vN/`
-3. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/intent.md`
-4. Confirmar que o arquivo foi criado com sucesso
+3. **Remover todos os comentarios `<!-- LLM-ONLY: ... -->`** do conteudo antes de salvar — eles sao instrucoes internas do template e NAO devem aparecer no arquivo gerado
+4. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/intent.md`
+5. Confirmar que o arquivo foi criado com sucesso
 
 ## Saida Esperada
 

package/frameworks/skills/ministack-intent-expert/templates/intent-template.md

@@ -20,7 +20,7 @@
 - O que deve existir ao final desta tarefa?
 - Qual resultado tecnico ou estrutural se espera?
 
-> IMPORTANTE: Descreva apenas O QUE deve ser alcancado, NAO como implementar.
+<!-- LLM-ONLY: Descreva apenas O QUE deve ser alcancado, NAO como implementar. Remova este comentario no arquivo gerado. -->
 
 ---
 

package/frameworks/skills/ministack-scope-expert/SKILL.md

@@ -6,7 +6,19 @@ argument-hint: [INTENT aprovada + detalhes tecnicos]
 
 Voce e um **Arquiteto de Software Senior** que transforma INTENTs em especificacoes tecnicas concretas.
 
-Voce domina completamente o framework miniStack e seu foco e **EXCLUSIVAMENTE** na etapa SCOPE — definindo COMO a feature sera implementada, com limites claros do que esta dentro e fora do escopo.
+Você domina completamente o framework miniStack e seu foco é **EXCLUSIVAMENTE** na etapa SCOPE — definindo COMO a feature será implementada, com limites claros do que está dentro e fora do escopo.
+
+---
+
+# Regra de Acentuação
+
+Todo artefato gerado por esta skill é um documento em português brasileiro. Todo conteúdo textual (títulos, descrições, instruções, regras, mensagens) deve usar acentuação correta do pt-BR:
+
+- Títulos e seções: `Descrição`, `Restrições`, `Instruções`, `Validação`, `Configuração`
+- Corpo do texto: `não`, `é`, `está`, `será`, `também`, `através`, `após`, `até`, `único`
+- Termos técnicos em português: `autenticação`, `paginação`, `migração`, `funcionalidade`
+
+Apenas nomes de código (funções, variáveis, structs, pacotes) permanecem sem acento por serem em inglês.
 
 ---
 
@@ -62,17 +74,12 @@ O SCOPE transforma a INTENT em **definicoes tecnicas concretas**. Responde **COM
    - O tech_direction contem decisoes ja tomadas, tecnologias sugeridas e padroes preferidos
    - Voce pode **complementar, ajustar ou questionar** qualquer item — nao e uma ordem, e um direcionamento
    - Se NAO existir, siga o fluxo normal (propor solucao do zero)
-2. **Ler as rules do projeto** — buscar em:
-   - `.claude/rules/` (Claude Code)
-   - `CLAUDE.md` na raiz
-   - Qualquer arquivo de regras/convencoes do projeto
-3. **Explorar as camadas do projeto** — entender a arquitetura existente:
-   - Identificar as camadas reais do projeto a partir do CLAUDE.md e estrutura de pastas (ex: handlers, services, repositories, controllers, use cases, widgets, blocs, etc.)
-   - Estrutura de diretorios
-   - Padroes de codigo ja estabelecidos
+2. **Regras e perfil do projeto (pre-carregados)** — O `CLAUDE.md`, `.claude/rules/` e `project-profile.md` (se existir) ja estao no contexto — NAO releia. Use essas informacoes como base e foque a exploracao apenas em codigo especifico da feature.
+3. **Explorar a estrutura de pastas do projeto** para mapear as camadas reais existentes, padroes de codigo ja estabelecidos e estrutura de diretorios
 4. **Identificar codigo reutilizavel** — funcoes, tipos, classes, interfaces e componentes existentes
 5. **Mapear dependencias reais** — o que ja existe vs o que precisa ser criado
 6. **Propor a melhor solucao como um arquiteto senior** — considerando padroes, performance e manutenibilidade
+7. **Salvar perfil de testes (se nao existe)** — Se `.claude/rules/project-profile.md` NAO existir no contexto, pesquise padroes de teste do projeto (framework, mocks, helpers, nomenclatura, setup por camada) e salve como `.claude/rules/project-profile.md`. Isso evita que agentes posteriores repitam a exploracao de padroes de teste.
 
 > Nunca assuma que algo precisa ser criado se ja pode existir no projeto.
 > Se houver tech_direction, use-o para acelerar decisoes ja resolvidas — mas sempre valide contra o projeto real.
@@ -108,8 +115,9 @@ Defina com clareza:
 
 1. Identificar nome da feature a partir da INTENT
 2. Criar diretorio se nao existir: `docs/[nome-feature]/vN/`
-3. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/scope.md`
-4. Confirmar que o arquivo foi criado
+3. **Remover todos os comentarios `<!-- LLM-ONLY: ... -->`** do conteudo antes de salvar — sao instrucoes internas do template e NAO devem aparecer no arquivo gerado
+4. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/scope.md`
+5. Confirmar que o arquivo foi criado
 
 ## Template
 

package/frameworks/skills/ministack-scope-expert/templates/scope-template.md

@@ -69,7 +69,7 @@
 
 > **Legenda de Acoes:** `criar` | `modificar` | `remover`
 
-> **IMPORTANTE**: Listar TODOS os arquivos envolvidos economiza tokens e scans durante a execucao.
+<!-- LLM-ONLY: Listar TODOS os arquivos envolvidos economiza tokens e scans durante a execucao. -->
 
 ---