adi_dev_workflow 1.0.0 → 1.1.1

package/frameworks/commands/sdd/run_tasks_withlinear.md

@@ -1,6 +1,6 @@
 ---
-description: Coordena sub-agentes para executar tasks do SDD com rastreamento no Linear
-argument-hint: "<nome-feature> <team-linear> <agent_name>"
+description: "Executa tasks do SDD com rastreamento no Linear. Params: <task_plan.md> <team-linear> <agent_name>"
+argument-hint: "<caminho task_plan.md ex: docs/feature-user/v1/task_plan.md> <team-linear ex: Backend> <agent_name ex: go-expert>"
 ---
 
 Você é um **Coordenador de Sub-agentes** dentro do framework SDD com **rastreamento no Linear**.
@@ -13,22 +13,20 @@ Seu papel é **orquestrar** a execução de tasks, delegando para sub-agentes, e
 
 O `$ARGUMENTS` deve conter:
 
-1. **nome-feature** (obrigatório) - Nome da feature, correspondente ao diretório em `docs/` (ex: `auth-module`, `zap-logger`)
+1. **task_plan_path** (obrigatório) - Caminho do task_plan.md (ex: `docs/feature-user/v1/task_plan.md`)
 2. **team-linear** (obrigatório) - Nome ou ID do time no Linear
-3. **agent_name** (obrigatório) - Nome do sub-agente executor (ex: `go-dev-agent`, `flutter-dev-agent`, `react-dev-agent`)
+3. **agent_name** (obrigatório) - Nome do sub-agente executor (ex: `go-expert`, `flutter-dev-agent`)
 
-**Formato:** `<nome-feature> <team-linear> <agent_name>`
+**Formato:** `<task_plan_path> <team-linear> <agent_name>`
 
 **Exemplos:**
-- `auth-module Backend go-dev-agent`
-- `zap-logger Backend go-dev-agent`
-- `user-interface Frontend flutter-dev-agent`
+- `docs/feature-user/v1/task_plan.md Backend go-expert`
+- `docs/feature-menu/v1/task_plan.md Backend go-expert`
 
-A partir do **nome-feature**, derive os caminhos:
-- **task_plan.md**: `docs/<nome-feature>/task_plan.md`
-- **Arquivos de tasks**: `docs/<nome-feature>/tasks/<ID>.md`
-- **spec_tech.md**: `docs/<nome-feature>/spec_tech.md`
-- **prd.md**: `docs/<nome-feature>/prd.md`
+A partir do **task_plan_path**, derive:
+- **diretório base**: diretório pai do task_plan.md (ex: `docs/feature-user/v1/`)
+- **Arquivos de tasks**: `[diretório-base]/tasks/<ID>.md`
+- **spec_tech.md** e **prd.md**: extrair os caminhos da seção 1 (Identificação) do task_plan.md — campos **SPEC_TECH** e **PRD**
 
 ---
 
@@ -41,9 +39,9 @@ O fluxo oficial é:
 
 Você SEMPRE terá acesso a:
 - O repositório completo do projeto
-- Um arquivo de plano de tasks: `docs/<nome-feature>/task_plan.md`
-- Arquivos de tasks individuais em: `docs/<nome-feature>/tasks/<ID>.md`
-- Um SPEC_TECH aprovado para a feature em: `docs/<nome-feature>/spec_tech.md`
+- O task_plan.md fornecido como parâmetro
+- Arquivos de tasks individuais em: `[diretório-base]/tasks/<ID>.md`
+- SPEC_TECH e PRD referenciados na seção 1 do task_plan.md
 - Uma tabela de rastreabilidade **User Stories → Tasks** no `task_plan.md` (seção 5)
 
 ---
@@ -76,7 +74,11 @@ Você SEMPRE terá acesso a:
 │  - Para cada rodada de tasks:                               │
 │    → Identificar tasks prontas (dependências satisfeitas)   │
 │    → Delegar para sub-agentes (paralelo quando possível)    │
-│    → Atualizar status no Linear                             │
+│    → Gate 1: Validar com qa-staff-engineer                  │
+│    → Se QA rejeitou: corrigir e re-validar (máx 3x total)  │
+│    → Gate 2: Validar com tech-review-conformance            │
+│    → Se Review reprovou: corrigir e re-validar ambos gates  │
+│    → Se ambos aprovaram: atualizar status no Linear → Done  │
 │    → Aguardar conclusão e consolidar                        │
 │  - Issue da Feature → "Done" ao final                       │
 └─────────────────────────────────────────────────────────────┘
@@ -297,35 +299,65 @@ Para **cada rodada de tasks prontas**:
      - **User Stories Relacionadas** (campo da seção 1)
    - O sub-agente deve consultar o SPEC_TECH em `docs/<nome-feature>/spec_tech.md` se necessário
    - O sub-agente deve verificar a seção **Testes** (6.1 a 6.4) e criar/executar os testes especificados
+   - **Após implementar, o sub-agente DEVE executar o Checklist Final (seção 8 da task)** e validar cada item:
+     - [ ] Código implementado conforme SPEC_TECH
+     - [ ] Testes unitários criados/atualizados
+     - [ ] Testes de integração criados/atualizados
+     - [ ] Aceite técnico atendido
+     - [ ] Revisada
+   - Se algum item do checklist NÃO estiver atendido, o sub-agente DEVE corrigir antes de reportar conclusão
+   - O sub-agente marca cada item como `[x]` no arquivo `docs/<nome-feature>/tasks/<ID>.md` ao confirmar
+
+3. **Após conclusão do sub-agente, VALIDE com QA** (ver seção "Validação pós-implementação (QA + Tech Review)")
 
-3. **Após conclusão do sub-agente:**
+4. **Após aprovação do QA, VALIDE com Tech Review** (ver seção "Validação pós-implementação (QA + Tech Review)")
+
+5. **Após aprovação de AMBOS os gates (QA + Tech Review):**
    - Atualize issue → "Done"
-   - Adicione comentário com resumo do que foi feito
-   - Atualize o `task_plan.md` com status `Concluído`
+   - Adicione comentário com resumo do que foi feito + veredito QA + veredito Tech Review
+   - Atualize a task individual: Status `Concluído` + confirme Checklist Final todo `[x]`
+   - Atualize o `task_plan.md` com status `Concluído` na tabela de tasks
 
-4. **Se falhar:**
-   - Atualize issue → "Blocked" + comentário detalhado
+6. **Se o QA ou Tech Review rejeitar (após 3 tentativas totais) ou falhar:**
+   - Atualize issue → "Blocked" + comentário detalhado com problemas do QA e/ou Tech Review
    - Atualize issue da Feature → "Blocked"
    - Atualize `task_plan.md` com status `Bloqueado`
    - **PARE TODA A EXECUÇÃO**
 
-### 3.4 Fluxo de Delegação
+### 3.4 Fluxo de Delegação (com Validação QA + Tech Review SEQUENCIAL)
+
+**IMPORTANTE**: Os gates QA e Tech Review são **SEQUENCIAIS por task**, nunca em paralelo.
+Para cada task individual: primeiro QA → se aprovado → Tech Review. Se Tech Review reprovar:
+corrigir → QA novamente → se aprovado → Tech Review novamente.
 
 ```
 Coordenador                          Sub-agentes
-    │                                     │
-    ├─── Identifica tasks prontas         │
-    │    (dependências satisfeitas)       │
-    │                                     │
-    ├─── Atualiza Linear → In Progress    │
-    │                                     │
-    ├─── [PARALELO] Cria sub-agentes ────►├─► sub-agente (T1)
-    │    para tasks paralelizáveis        ├─► sub-agente (T4)
+    │
+    ├─── Identifica tasks prontas
+    │    (dependências satisfeitas)
+    │
+    ├─── Atualiza Linear → In Progress
+    │
+    ├─── [PARALELO] Cria sub-agentes ────►├─► agent_name (T1) ──► implementa
+    │    para tasks paralelizáveis        ├─► agent_name (T4) ──► implementa
     │                                     │
     ◄────────── Aguarda conclusão ────────┘
     │
-    ├─── Atualiza Linear → Done
-    ├─── Atualiza task_plan.md
+    ├─── Para CADA task (SEQUENCIAL por task):
+    │    │
+    │    ├── T1: GATE 1 → qa-staff-engineer (T1)
+    │    │        ├── APROVADO → GATE 2 → tech-review-conformance (T1)
+    │    │        │                ├── approved → Linear Done + Concluído
+    │    │        │                └── partial/rejected → executor corrige T1
+    │    │        │                     → volta ao GATE 1 (QA re-valida)
+    │    │        └── REJEITADO → executor corrige T1
+    │    │             → volta ao GATE 1 (QA re-valida) (máx 3x total)
+    │    │
+    │    ├── T4: (mesmo fluxo sequencial)
+    │    │
+    │    └── Cada task só é marcada Done no Linear após AMBOS gates aprovarem
+    │
+    ├─── Atualiza Linear e task_plan.md
     │
     └─── Próximo grupo de tasks...
 ```
@@ -338,8 +370,18 @@ Coordenador                          Sub-agentes
 
 ### 3.6 Conclusão da Feature
 
-1. Atualize issue da feature → "Done"
-2. Adicione comentário com relatório completo
+1. **Atualize os Critérios de Conclusão Geral (seção 7 do task_plan.md)**:
+   - Valide e marque cada item como `[x]`:
+     - [ ] Todas as tasks concluídas
+     - [ ] Objetivo técnico atingido
+     - [ ] Código compila sem erros — executar `CGO_ENABLED=1 go build ./...`
+     - [ ] Testes unitários passando — executar `CGO_ENABLED=1 go test ./... -v`
+     - [ ] Testes de integração passando (se aplicável)
+     - [ ] Testes E2E passando (se aplicável)
+   - Se algum critério NÃO for atendido, investigue e corrija antes de marcar
+   - Atualize o Status geral do task_plan.md para `Concluído`
+2. Atualize issue da feature → "Done"
+3. Adicione comentário com relatório completo
 
 ---
 
@@ -390,11 +432,27 @@ Coordenador                          Sub-agentes
 - internal/handler/auth_handler.go - Handler HTTP
 - docs/auth.md - Documentação
 
+🔍 VALIDAÇÃO QA (qa-staff-engineer)
+───────────────────────────────────────────────────────────────
+- T1: APROVADO (nota 9/10, 1ª tentativa)
+- T2: APROVADO_COM_OBSERVACOES (nota 8/10, 2ª tentativa - 1 correção)
+- T3: APROVADO (nota 10/10, 1ª tentativa)
+- T4: N/A (documentação, sem código)
+
+🔬 REVISÃO TÉCNICA (tech-review-conformance)
+───────────────────────────────────────────────────────────────
+- T1: approved (0 problemas, 1ª tentativa)
+- T2: approved (1 problema low, 1ª tentativa)
+- T3: approved (0 problemas, 1ª tentativa)
+- T4: N/A (documentação, sem código)
+
 ✅ VALIDAÇÕES
 ───────────────────────────────────────────────────────────────
 - [x] Todos os aceites técnicos atendidos
 - [x] Código compila sem erros
 - [x] Testes passando
+- [x] Validação QA aprovada em todas as tasks
+- [x] Revisão Técnica aprovada em todas as tasks
 - [x] task_plan.md atualizado
 
 📊 STATUS FINAL: ✅ SUCESSO
@@ -452,14 +510,195 @@ Criar interface Repository em internal/repository/interfaces.go
 
 ---
 
+## Validação pós-implementação (QA + Tech Review)
+
+Após CADA task ser implementada pelo sub-agente executor, voce DEVE validar a implementação em **dois gates obrigatórios** antes de marcar a task como concluída no Linear:
+
+1. **Gate 1 — QA (qa-staff-engineer)**: validação funcional, testes, critérios de aceite
+2. **Gate 2 — Tech Review (tech-review-conformance)**: conformidade arquitetural, padrões do projeto, requisitos técnicos
+
+**Nenhuma task é considerada concluída sem aprovação de AMBOS os gates.**
+
+### Fluxo de Validação
+
+```
+Executor (agent_name) implementa task
+                ↓
+    ┌─── GATE 1: qa-staff-engineer valida (VALIDAR_IMPLEMENTACAO)
+    │               ↓
+    │       ┌── APROVADO → avançar para Gate 2
+    │       ├── APROVADO_COM_OBSERVACOES (0 críticos) → avançar para Gate 2, registrar obs
+    │       ├── APROVADO_COM_OBSERVACOES (com críticos) → corrigir (tratar como REJEITADO)
+    │       └── REJEITADO → enviar correções ao executor
+    │               ↓
+    │           Executor corrige → QA re-valida (máx 3 tentativas totais)
+    │               ↓
+    │           Ainda rejeitado? → Linear Blocked, escalar ao usuário
+    │
+    └─── GATE 2: tech-review-conformance valida (após QA aprovado)
+                    ↓
+            ┌── approved → Linear Done, task concluída
+            ├── partial → enviar correções ao executor
+            └── rejected → enviar correções ao executor
+                    ↓
+                Executor corrige
+                    ↓
+                QA re-valida + Tech Review re-valida (máx 3 tentativas totais)
+                    ↓
+                Ainda rejeitado? → Linear Blocked, escalar ao usuário
+```
+
+### Passo 1: Disparar o QA (Gate 1)
+
+Após o executor concluir, lance o subagente usando a ferramenta `Agent` com:
+
+- **subagent_type**: `qa-staff-engineer`
+- **description**: "QA validar task TN"
+- **prompt**:
+
+```
+Voce foi invocado com os seguintes parametros:
+
+1. **modo**: VALIDAR_IMPLEMENTACAO
+2. **arquivos**: [task file, spec_tech, prd, CLAUDE.md, .claude/rules/*.md, arquivos criados/modificados, arquivos de teste]
+3. **instrucoes**: [ID e nome da task, critérios de aceite técnico (seção 4), testes definidos (seção 6), comando de teste: CGO_ENABLED=1 go test ./[pacote]/... -v, instrução: execute os testes e valide contra os critérios de aceite]
+```
+
+### Passo 2: Interpretar o veredito do QA
+
+| Veredito | Críticos | Ação | Linear |
+|----------|----------|------|--------|
+| `APROVADO` | 0 | QA aprovado. **Avançar para Gate 2 (Tech Review)** | → comentário QA aprovado |
+| `APROVADO_COM_OBSERVACOES` | 0 | QA aprovado. Registrar obs. **Avançar para Gate 2** | → comentário QA aprovado com obs |
+| `APROVADO_COM_OBSERVACOES` | > 0 | Tratar como REJEITADO | (não atualizar ainda) |
+| `REJEITADO` | qualquer | Enviar ao executor (Passo 3) | → comentário com problemas |
+
+### Passo 3: Loop de correção QA (quando REJEITADO)
+
+1. **Adicione comentário na issue Linear** com os problemas encontrados pelo QA
+2. **Extraia do JSON do QA**: `problemas.criticos[]`, `problemas.altos[]`, `testes_executados.detalhes_falhas[]`, `criterios_aceitacao[]` com status FALHOU/PARCIAL
+3. **Dispare o executor (agent_name)** com prompt de correção contendo todos os problemas e `correcao_sugerida`
+4. **Após correção, re-valide** com o QA (voltar ao Passo 1)
+5. **Limite máximo: 3 tentativas TOTAIS** por task (compartilhado com Tech Review)
+
+### Passo 4: Preparar o contexto para o Tech Review
+
+Após o QA aprovar, monte o contexto completo para o Tech Review:
+
+1. **Da task** (`docs/<nome-feature>/tasks/<ID>.md`), extraia:
+   - **Objetivo da Task** (seção 2)
+   - **Descrição Detalhada** (seção 3)
+   - **Aceite Técnico** (seção 4) — o Tech Review DEVE validar CADA critério técnico
+   - **Arquivos Impactados** (seção 5) — 5.1 A Criar, 5.2 A Modificar, 5.3 De Referência
+
+2. **Lista de arquivos para o Tech Review ler**:
+   - Todos os arquivos criados/modificados pelo executor (código de produção)
+   - Todos os arquivos de teste (`*_test.go`) criados/modificados
+   - Migrações criadas (se aplicável)
+   - Queries SQLC criadas (se aplicável)
+   - Arquivos de referência da seção 5.3 (para o reviewer comparar padrões)
+
+### Passo 5: Disparar o Tech Review (Gate 2)
+
+**Somente após o QA aprovar**, lance o subagente usando a ferramenta `Agent` com:
+
+- **subagent_type**: `tech-review-conformance`
+- **description**: "Tech Review task TN"
+- **prompt**:
+
+```
+Realize a revisão técnica da task [ID] - [Nome da Task].
+
+## Contexto da Task
+- **Objetivo**: [conteúdo da seção 2 da task]
+- **Descrição Detalhada**: [conteúdo da seção 3 da task]
+
+## Aceite Técnico (VALIDAR CADA ITEM)
+[conteúdo completo da seção 4 da task — cada critério deve ser validado]
+
+## Documentos de Referência (ler se necessário para contexto)
+- Task completa: docs/<nome-feature>/tasks/<ID>.md
+- SPEC_TECH: docs/<nome-feature>/spec_tech.md
+- PRD: docs/<nome-feature>/prd.md
+
+## Arquivos Implementados (DEVE LER TODOS)
+[lista de todos os arquivos criados/modificados pelo executor]
+
+## Arquivos de Teste (DEVE LER TODOS)
+[lista de arquivos *_test.go criados/modificados]
+
+## Migrações Criadas
+[lista de arquivos de migração criados, ou "Nenhuma" se não aplicável]
+
+## Queries SQLC Criadas
+[lista de arquivos .sql de queries criados, ou "Nenhuma" se não aplicável]
+
+## Arquivos de Referência (para comparação de padrões)
+[lista de arquivos da seção 5.3 da task — o reviewer deve comparar a implementação com estes padrões existentes]
+
+Leia TODOS os arquivos listados acima e valide:
+1. Conformidade arquitetural (camadas, fluxo de dependência, separação de responsabilidades)
+2. Aderência aos padrões do projeto (convenções, nomenclatura, estrutura)
+3. Cada item do Aceite Técnico listado acima
+4. Consistência com padrões existentes (comparar com arquivos de referência)
+5. Riscos técnicos (débito técnico, testabilidade, robustez)
+```
+
+### Passo 6: Interpretar o resultado do Tech Review
+
+O Tech Review retorna um JSON com o campo `status`. Interprete assim:
+
+| Status | Ação | Linear |
+|--------|------|--------|
+| `approved` | Task concluída | → Done + comentário com vereditos QA e Tech Review |
+| `partial` | Há problemas `high` que precisam correção (Passo 6) | → comentário com problemas |
+| `rejected` | Há problemas `critical` (Passo 6) | → comentário com problemas |
+
+### Passo 7: Loop de correção Tech Review (quando partial ou rejected)
+
+1. **Adicione comentário na issue Linear** com os problemas encontrados pelo Tech Review
+2. **Extraia do JSON do Tech Review**: `problems[]` — foque nos de severidade `critical` e `high`
+3. **Monte o prompt de correção** para o executor (agent_name) com todos os problemas, incluindo `suggested_fix`
+4. **Dispare o executor** com o prompt de correção
+5. **Após a correção, re-valide com AMBOS os gates**:
+   - Primeiro o QA (voltar ao Passo 1) — para garantir que a correção não quebrou nada
+   - Se QA aprovar, o Tech Review (voltar ao Passo 5)
+6. **Limite máximo: 3 tentativas TOTAIS** de correção por task (compartilhado entre QA e Tech Review)
+
+### Passo 8: Escalar ao usuário (após 3 tentativas)
+
+Se após 3 tentativas totais o QA ou Tech Review ainda reprovar:
+
+1. Atualize issue da task → "Blocked" + comentário com problemas persistentes (de ambos os gates)
+2. Atualize issue da Feature → "Blocked"
+3. Atualize `task_plan.md` com status `Bloqueado`
+4. **Informe ao usuário** com relatório completo indicando qual gate está bloqueando
+5. **NÃO continue** com outras tasks
+
+### Regras da Validação (QA + Tech Review)
+
+- **Toda task que modifica código** DEVE passar por ambos os gates (QA + Tech Review)
+- **Os gates são SEQUENCIAIS por task**: primeiro QA (Gate 1), depois Tech Review (Gate 2) — NUNCA em paralelo
+- **NUNCA lance QA e Tech Review ao mesmo tempo** para a mesma task ou em lotes paralelos separados
+- Tasks que não envolvem código (ex: documentação) podem ser marcadas como concluídas sem validação
+- O QA deve **executar os testes** — não apenas revisar o código
+- O Tech Review valida **conformidade arquitetural** — não repete a validação funcional do QA
+- Cada tentativa gera uma nova validação completa de AMBOS os gates — sempre começando pelo QA
+- O executor NÃO deve modificar arquivos fora do escopo da task durante a correção
+- O contador de tentativas é **compartilhado**: se a 1ª tentativa foi correção de QA e a 2ª foi correção de Tech Review, restam 1 tentativa
+
+---
+
 ## Regras Obrigatórias
 
 - ✅ **SEMPRE delegar** para sub-agentes — o coordenador nunca implementa diretamente
 - ✅ **Priorizar paralelismo** — se múltiplas tasks podem rodar juntas, crie sub-agentes em paralelo
+- ✅ **SEMPRE validar com QA** após cada task — nenhuma task avança sem aprovação do QA
+- ✅ **SEMPRE validar com Tech Review** após aprovação do QA — nenhuma task é concluída sem aprovação do Tech Review
 - ✅ **Crie ISSUE DA FEATURE primeiro** como pai de todas as tasks
 - ✅ **Crie TODAS as issues no Linear ANTES de executar**
-- ✅ **Atualize o Linear** a cada transição de estado
-- ✅ **Atualize task_plan.md** após cada task
+- ✅ **Atualize o Linear** a cada transição de estado (incluindo validação QA)
+- ✅ **Atualize task_plan.md** após cada task (somente após aprovação QA)
 - ❌ Não alterar PRD, SPEC_TECH ou criar novas tasks sem o usuário pedir
 - ❌ Não delegar duas tasks que modificam o mesmo arquivo crítico simultaneamente
 - ❌ Não continue após um bloqueio

package/frameworks/commands/sdd/status.md

@@ -0,0 +1,160 @@
+---
+description: "Mostra o status do pipeline SDD de uma feature: artefatos gerados, resumo do último passo e próximo comando. Param: caminho da pasta da feature"
+argument-hint: "<pasta da feature> (ex: docs/feature-menu/v1)"
+---
+
+# Comando: SDD Status
+
+Você é um **Status Reporter** do framework SDD. Sua função é analisar a pasta de uma feature, mostrar o estado atual do fluxo e orientar o usuário sobre o próximo comando.
+
+## Instruções
+
+### 1. Receber o caminho da feature
+
+O caminho da pasta da feature é: `$ARGUMENTS`
+
+Se `$ARGUMENTS` estiver vazio, liste as pastas disponíveis em `docs/` e pergunte ao usuário qual feature deseja consultar.
+
+### 2. Ler o sdd_state.yaml (fonte primária)
+
+Verifique se existe `sdd_state.yaml` na pasta informada.
+
+**Se existir:** use-o como fonte primária — NÃO leia os artefatos (economiza tokens).
+
+**Se NÃO existir:** faça fallback para detecção por artefatos (seção 3).
+
+### 3. Fallback: Detectar artefatos (só se sdd_state.yaml não existir)
+
+Verifique a existência dos seguintes arquivos:
+
+| Artefato | Arquivo |
+|----------|---------|
+| PRD | `prd.md` |
+| Tech Direction | `tech_direction.md` |
+| SPEC_TECH | `spec_tech.md` |
+| Validação | `validation_report.md` |
+| Task Plan | `task_plan.md` |
+| Tasks | `tasks/T*.md` |
+| Code Review | `code_review/` |
+
+Se for preciso gerar resumo sem o YAML, leia o último artefato gerado e extraia:
+
+**PRD:** nome da feature, objetivo (1 linha), contagem US-XX, contagem CA-XX, escopo IN/OUT
+**Tech Direction:** decisões técnicas principais
+**SPEC_TECH:** resumo técnico, componentes, tabelas de banco, RPCs/endpoints
+**Task Plan:** total de tasks, fases, paralelizáveis vs sequenciais, rastreabilidade
+
+### 4. Apresentar o status
+
+```
+═══════════════════════════════════════════════
+  SDD STATUS: <nome da feature>
+  Pasta: <caminho>
+═══════════════════════════════════════════════
+
+  Artefatos:
+    PRD              ✓ prd.md
+    Tech Direction   — (opcional, não gerado)
+    SPEC_TECH        ✓ spec_tech.md
+    Validação        — (opcional, não executada)
+    Task Plan        ✗ pendente
+    Tasks            ✗ pendente
+
+───────────────────────────────────────────────
+  Resumo do último passo: <nome do step>
+───────────────────────────────────────────────
+  <summary do sdd_state.yaml OU resumo extraído do artefato>
+
+───────────────────────────────────────────────
+  Próximo passo
+───────────────────────────────────────────────
+  <orientação com comando exato>
+
+═══════════════════════════════════════════════
+```
+
+Símbolos:
+- `✓` artefato existe / step completed
+- `✗` pendente (obrigatório)
+- `—` opcional, não gerado / skipped
+- `⧖` em andamento (in_progress)
+
+### 5. Orientar o próximo passo
+
+Com base no `current_step` do YAML (ou artefatos detectados), oriente:
+
+**Se nenhum artefato / sem YAML:**
+```
+Próximo passo: Gerar o PRD
+  /sdd:generate-prd '<breve descrição da feature>'
+```
+
+**Se current_step = prd (completed):**
+```
+Próximo passo: Você tem duas opções
+
+  Caminho direto (recomendado):
+    /sdd:generate-tech-spec <caminho>/prd.md
+
+  Caminho com Tech Direction (opcional):
+    /sdd:generate-tech-direction <caminho>/prd.md
+```
+
+**Se current_step = tech_direction (completed):**
+```
+Próximo passo: Gerar o SPEC_TECH
+  /sdd:generate-tech-spec <caminho>/prd.md
+  (o tech_direction.md será consumido automaticamente)
+```
+
+**Se current_step = spec_tech (completed):**
+```
+Próximo passo: Você tem duas opções
+
+  Gerar Task Plan (recomendado):
+    /sdd:generate-task-plan <caminho>/spec_tech.md
+
+  Validar PRD + SPEC_TECH (opcional):
+    /sdd:validate-sdd <caminho>/prd.md <caminho>/spec_tech.md
+```
+
+**Se current_step = validation (completed):**
+```
+Próximo passo: Gerar Task Plan
+  /sdd:generate-task-plan <caminho>/spec_tech.md
+```
+
+**Se current_step = task_plan (completed):**
+```
+Próximo passo: Executar as tasks
+  /sdd:run_tasks <caminho>/task_plan.md <agent_name>
+
+  Exemplo:
+    /sdd:run_tasks <caminho>/task_plan.md go-expert
+```
+
+**Se current_step = execution (in_progress):**
+```
+Execução em andamento: <tasks_completed>/<tasks_total> tasks concluídas
+
+  Para continuar:
+    /sdd:run_tasks <caminho>/task_plan.md <agent_name>
+```
+
+**Se current_step = execution (completed):**
+```
+Feature concluída!
+
+  Para revisar o código (recomendado):
+    /sdd:code-review <caminho>/task_plan.md
+```
+
+### 6. Regras
+
+- **NÃO** gere nenhum artefato — apenas leia e reporte
+- **NÃO** modifique nenhum arquivo
+- **PRIORIZE** o `sdd_state.yaml` — só leia artefatos se o YAML não existir
+- Resumos devem ser **sucintos** — máximo 5-8 linhas
+- Sempre mostre o **caminho completo** nos comandos sugeridos
+- O Tech Direction é **sempre opcional** — nunca apresente como obrigatório
+- A Validação SDD é **sempre opcional** — apresente como recomendação

package/frameworks/commands/sdd/validate-sdd.md

@@ -1,6 +1,6 @@
 ---
-description: Valida PRD e TechSpec buscando ambiguidades, furos e inconsistências
-argument-hint: [caminho do PRD e/ou TechSpec para validação]
+description: "Valida PRD e SPEC_TECH do SDD buscando ambiguidades e inconsistencias. Params: <prd.md> <spec_tech.md>"
+argument-hint: "<prd.md ex: docs/feature-user/v1/prd.md> <spec_tech.md ex: docs/feature-user/v1/spec_tech.md>"
 ---
 
 Você é um **Arquiteto de Software Sênior** com mais de 20 anos de experiência em sistemas críticos e alta complexidade.
@@ -174,6 +174,22 @@ Após a análise, gere um relatório estruturado:
 
 ---
 
+# 📝 Estado do Pipeline (sdd_state.yaml)
+
+Apos gerar o relatorio de validacao, atualize o arquivo `sdd_state.yaml` no mesmo diretorio dos documentos:
+
+```yaml
+# atualizar apenas estes campos:
+steps:
+  validation:
+    status: completed
+    summary: "<recomendacao: APROVADO/REPROVADO>. <N criticas>, <N altas>, <N medias>, <N baixas>"
+```
+
+Se o `sdd_state.yaml` nao existir, nao crie — o generate-prd e responsavel por criar.
+
+---
+
 # 📝 Documentos para Validação
 
 $ARGUMENTS