adi_dev_workflow 1.0.0 → 1.1.0

package/frameworks/commands/ministack/run-ministack-withlinear.md

@@ -1,30 +1,29 @@
 ---
-description: Executa tasks do miniStack com rastreamento no Linear
-argument-hint: [caminho da feature] [team no linear] [agente opcional]
+description: "Executa tasks do miniStack com rastreamento no Linear. Params: <task_plan.md> <team-linear> <agent_name>"
+argument-hint: "<caminho task_plan.md ex: docs/carrinho-compra/v1/task_plan.md> <team-linear ex: Backend> <agent_name ex: go-expert>"
 ---
 
-Use a skill **ministack-expert** para executar as TASKS (ETAPA 5) e use o comando `/sync-tasks-to-linear` para sincronizar com o Linear.
+Voce e um **Coordenador de Sub-agentes** com rastreamento no Linear. Seu papel e **orquestrar**, nao executar diretamente.
 
-## Contexto
-
-Voce deve seguir as regras e o processo da **ETAPA 5: EXECUCAO** definida na skill ministack-expert, com rastreamento automatico no Linear.
+Siga **todas as regras, gates e fluxo de validacao** definidos no comando `/ministack:run-ministack-tasks`, com as seguintes adicoes para integracao com Linear.
 
 ## Argumentos
 
 O `$ARGUMENTS` deve conter:
 
-1. **Caminho da feature** (obrigatorio) - Ex: `docs/nome-feature/v1`
+1. **task_plan_path** (obrigatorio) - Caminho do task_plan.md (ex: `docs/carrinho-compra/v1/task_plan.md`)
 2. **Team no Linear** (obrigatorio) - Nome ou ID do time no Linear
-3. **Agente/Subagente** (opcional) - Nome do agente a ser usado para execucao
+3. **Agente executor** (obrigatorio) - Nome do sub-agente executor
 
 **Formatos aceitos:**
-- `docs/minha-feature/v1 Backend` - Pasta com team
-- `docs/minha-feature/v1 Backend go-backend-implementer` - Com agente especifico
+- `docs/minha-feature/v1/task_plan.md Backend go-expert` - task_plan + team + agente
 
 ## Fluxo de Execucao
 
 ### Fase 1: Descoberta e Validacao
-- Ler intent.md, scope.md, tasks.md
+- Ler o task_plan.md fornecido
+- Extrair caminhos de Intent e Scope da secao 1 (Identificacao) do task_plan
+- Ler cada tasks/T[N].md no diretorio-base
 - Extrair nome da feature e lista de tasks
 - Validar contexto e dependencias
 
@@ -45,19 +44,20 @@ O `$ARGUMENTS` deve conter:
    blockedBy: [dependencias]
    ```
 
-### Fase 3: Execucao (Paralelo/Sequencial)
+### Fase 3: Execucao com Gates (mesmo fluxo do run-ministack-tasks)
 
-1. Atualizar issue da feature para "In Progress"
-2. Para cada task:
-   - Atualizar issue para "In Progress"
-   - Executar a task
-   - Validar criterio de conclusao
-   - Atualizar issue para "Done"
-3. Atualizar issue da feature para "Done"
+Para cada task:
+1. Atualizar issue para "In Progress"
+2. Delegar ao executor (agent_name)
+3. **Gate 1: qa-staff-engineer** (VALIDAR_IMPLEMENTACAO)
+4. **Gate 2: tech-review-conformance** (apos QA aprovado)
+5. Se aprovado: atualizar issue para "Done", marcar como `Concluido` em tasks/T[N].md e task_plan.md
+6. Se rejeitado: loop de correcao (max 3 tentativas)
+7. Se bloqueado: atualizar issue para "Blocked", marcar como `Bloqueado` em tasks/T[N].md e task_plan.md
 
 ### Fase 4: Relatorio Final
 
-Mostrar resumo de tasks executadas, issues no Linear, arquivos modificados e validacoes.
+Mostrar resumo: tasks executadas, issues no Linear, arquivos modificados, vereditos QA e Tech Review.
 
 ## Tratamento de Bloqueios
 
@@ -66,6 +66,7 @@ Se encontrar bloqueio:
 2. Atualizar issue da task para "Blocked"
 3. Atualizar issue da feature para "Blocked"
 4. Gerar relatorio parcial
+5. Escalar ao usuario
 
 ## Comandos Linear MCP Utilizados
 
@@ -83,12 +84,12 @@ Se encontrar bloqueio:
 |-----------------|---------------|
 | Aguardando | Todo / Backlog |
 | Em execucao | In Progress |
-| Concluido | Done / Completed |
+| Concluido (QA + Review aprovados) | Done / Completed |
 | Bloqueado | Blocked |
 | Cancelado | Canceled |
 
 ## Entrada
 
-**Formato:** `[caminho-feature] [team-linear] [agente-opcional]`
+**Formato:** `[task_plan_path] [team-linear] [agente-executor]`
 
 $ARGUMENTS

package/frameworks/commands/ministack/status.md

@@ -0,0 +1,153 @@
+---
+description: "Mostra o status do pipeline miniStack 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/carrinho-compra/v1)"
+---
+
+# Comando: miniStack Status
+
+Você é um **Status Reporter** do framework miniStack. 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 ministack_state.yaml (fonte primária)
+
+Verifique se existe `ministack_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 ministack_state.yaml não existir)
+
+Verifique a existência dos seguintes arquivos:
+
+| Artefato | Arquivo |
+|----------|---------|
+| INTENT | `intent.md` |
+| Tech Direction | `tech_direction.md` |
+| SCOPE | `scope.md` |
+| Task Plan | `task_plan.md` |
+| Tasks | `tasks/T*.md` |
+| Code Review | resultado do code-review |
+
+Se for preciso gerar resumo sem o YAML, leia o último artefato gerado e extraia:
+
+**INTENT:** nome da feature, objetivo (1 linha), escopo IN/OUT
+**Tech Direction:** decisões técnicas principais
+**SCOPE:** resumo técnico, componentes, tabelas de banco, endpoints
+**Task Plan:** total de tasks, fases, paralelizáveis vs sequenciais
+
+### 4. Apresentar o status
+
+```
+═══════════════════════════════════════════════
+  miniStack STATUS: <nome da feature>
+  Pasta: <caminho>
+═══════════════════════════════════════════════
+
+  Artefatos:
+    INTENT           ✓ intent.md
+    Tech Direction   — (opcional, não gerado)
+    SCOPE            ✓ scope.md
+    Task Plan        ✗ pendente
+    Tasks            ✗ pendente
+
+───────────────────────────────────────────────
+  Resumo do último passo: <nome do step>
+───────────────────────────────────────────────
+  <summary do ministack_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 a INTENT
+  /ministack:generate-intent '<breve descrição da feature>'
+```
+
+**Se current_step = intent (completed):**
+```
+Próximo passo: Você tem duas opções
+
+  Caminho direto (recomendado):
+    /ministack:generate-scope <caminho>/intent.md
+
+  Caminho com Tech Direction (opcional):
+    /ministack:generate-tech-direction <caminho>/intent.md
+```
+
+**Se current_step = tech_direction (completed):**
+```
+Próximo passo: Gerar o SCOPE
+  /ministack:generate-scope <caminho>/intent.md
+  (o tech_direction.md será consumido automaticamente)
+```
+
+**Se current_step = scope (completed):**
+```
+Próximo passo: Gerar as Tasks
+  /ministack:generate-tasks <caminho>/intent.md <caminho>/scope.md
+```
+
+**Se current_step = task_plan (completed):**
+```
+Próximo passo: Executar as tasks
+  /ministack:run-ministack-tasks <caminho>/task_plan.md <agent_name>
+
+  Exemplo:
+    /ministack:run-ministack-tasks <caminho>/task_plan.md go-expert
+
+  Code Review antes de executar (opcional):
+    /ministack:code-review <caminho>/task_plan.md
+
+  Com rastreamento Linear (opcional):
+    /ministack:run-ministack-withlinear <caminho>/task_plan.md <team-linear> <agent_name>
+```
+
+**Se current_step = execution (in_progress):**
+```
+Execução em andamento: <tasks_completed>/<tasks_total> tasks concluídas
+
+  Para continuar:
+    /ministack:run-ministack-tasks <caminho>/task_plan.md <agent_name>
+```
+
+**Se current_step = execution (completed):**
+```
+Feature concluída!
+
+  Para revisar o código (recomendado):
+    /ministack:code-review <caminho>/task_plan.md
+```
+
+### 6. Regras
+
+- **NÃO** gere nenhum artefato — apenas leia e reporte
+- **NÃO** modifique nenhum arquivo
+- **PRIORIZE** o `ministack_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
+- O Code Review é **sempre opcional** — apresente como recomendação

package/frameworks/commands/sdd/code-review.md

@@ -1,6 +1,6 @@
 ---
-description: Executa code review validando PRD, TechSpec e Tasks da feature
-argument-hint: [caminho da pasta da feature ex: docs/auth/]
+description: "Code review do SDD validando PRD, SPEC_TECH e Tasks. Param: caminho do task_plan.md"
+argument-hint: "<task_plan.md ex: docs/feature-user/v1/task_plan.md>"
 ---
 
 Voce e um **Engenheiro de Software Senior** com mais de 20 anos de experiencia, atuando tambem como **QA Lead** e **Security Specialist**.
@@ -36,15 +36,15 @@ Voce e **criterioso, meticuloso e implacavel**. Voce nao aceita:
 
 ## Fase 1: Coleta de Contexto
 
-1. **Localize a pasta da feature**:
-   - O argumento fornecido e o caminho da pasta da feature (ex: `docs/auth/`, `docs/login/`)
-   - Esta pasta contem todos os documentos relacionados a feature
+1. **Leia o task_plan.md** fornecido no argumento
+2. **Extraia os caminhos** de **SPEC_TECH** e **PRD** da secao 1 (Identificacao) do task_plan.md
+3. **Derive o diretorio-base** a partir do task_plan.md (diretorio pai)
 
-2. **Identifique os documentos a analisar** (APENAS ESTES):
-   - **PRD**: `<pasta_feature>/prd.md`
-   - **TechSpec**: `<pasta_feature>/spec_tech.md`
-   - **Task Plan**: `<pasta_feature>/task_plan.md`
-   - **Tasks**: `<pasta_feature>/tasks/*.md` (todos os arquivos da pasta tasks)
+4. **Identifique os documentos a analisar** (APENAS ESTES):
+   - **PRD**: caminho extraido do task_plan (campo PRD)
+   - **TechSpec**: caminho extraido do task_plan (campo SPEC_TECH)
+   - **Task Plan**: o arquivo fornecido como argumento
+   - **Tasks**: `[diretorio-base]/tasks/*.md` (todos os arquivos da pasta tasks)
 
 3. **NAO ANALISE outros arquivos**:
    - NAO leia arquivos de codigo fonte implementados

package/frameworks/commands/sdd/generate-prd.md

@@ -1,6 +1,6 @@
 ---
-description: Gera um PRD completo a partir de uma ideia ou rascunho inicial
-argument-hint: [descrição da feature ou ideia inicial]
+description: "Gera PRD completo do SDD a partir de uma ideia. Param: descricao da feature (ex: 'modulo de autenticacao com JWT')"
+argument-hint: "<descricao da feature em texto livre>"
 ---
 
 Use a skill **sdd-prd-expert** para gerar o PRD.
@@ -17,6 +17,36 @@ Voce deve atuar como um **Product Owner / Product Manager** especialista e segui
 - Faca **UMA pergunta por vez**, aguardando a resposta antes de avancar
 - Numere as User Stories com formato **US-XX** e os Criterios de Aceite com **CA-XX**
 - **SEMPRE** salve o arquivo fisico antes de apresentar ao usuario
+- Apos o usuario aprovar o PRD, pergunte: **"Voce tem pontos especificos de definicao tecnica que deseja registrar antes do SPEC_TECH?"**
+- Se sim, crie o arquivo `tech_direction.md` na mesma pasta do PRD usando o template da skill (sem preencher) e avise o usuario para preencher
+- Se nao, encerre normalmente
+
+## Estado do Pipeline (sdd_state.yaml)
+
+Apos salvar o PRD com sucesso, voce DEVE criar/atualizar o arquivo `sdd_state.yaml` no mesmo diretorio do PRD.
+
+Se o arquivo **nao existir**, crie-o com a estrutura completa:
+
+```yaml
+feature: "<nome da feature extraido da secao 1 do PRD>"
+current_step: prd
+steps:
+  prd:
+    status: completed
+    summary: "<US count> US, <CA count> CA. <objetivo em 1 frase curta>"
+  tech_direction:
+    status: pending
+  spec_tech:
+    status: pending
+  validation:
+    status: pending
+  task_plan:
+    status: pending
+  execution:
+    status: pending
+```
+
+Se o arquivo **ja existir** (ex: revisao do PRD), atualize apenas o bloco `prd` e resete os steps posteriores para `pending`.
 
 ## Entrada
 

package/frameworks/commands/sdd/generate-task-plan.md

@@ -1,6 +1,6 @@
 ---
-description: Gera um TASK PLAN completo com tasks individuais a partir de um SPEC_TECH aprovado
-argument-hint: [caminho do SPEC_TECH aprovado ou nome da feature]
+description: "Gera TASK PLAN + tasks individuais do SDD a partir de SPEC_TECH aprovado. Param: caminho do spec_tech.md"
+argument-hint: "<spec_tech.md ex: docs/feature-user/v1/spec_tech.md>"
 ---
 
 Use a skill **sdd-task-plan-expert** para gerar o TASK PLAN e as tasks individuais.
@@ -10,7 +10,9 @@ Use a skill **sdd-task-plan-expert** para gerar o TASK PLAN e as tasks individua
 Voce deve atuar como um **Engenheiro de Software Senior** especializado em decomposicao de tarefas e seguir todo o processo interativo definido na skill sdd-task-plan-expert.
 
 O $ARGUMENTS deve conter:
-1. **SPEC_TECH aprovado** ou caminho para o arquivo (obrigatorio)
+1. **caminho do spec_tech.md** (obrigatorio) — ex: `docs/feature-user/v1/spec_tech.md`
+
+O task_plan.md e as tasks individuais serao gerados no mesmo diretorio do spec_tech.md. O PRD sera localizado a partir de referencia interna no spec_tech.md.
 
 ## Regras Adicionais
 
@@ -18,10 +20,202 @@ O $ARGUMENTS deve conter:
 - **NUNCA** deduza escopo ou invente informacoes — na **DUVIDA PERGUNTE AO USUARIO**
 - Somente o **COMO** tecnico — nunca inclua o **O QUE** de produto
 - Liste **TODOS** os arquivos envolvidos e as acoes (criar/modificar/referencia) em cada task — economiza tokens e scans
-- A secao de **testes** (secao 6) de cada task deve ser delegada a um **subagente QA especializado** em contexto isolado, conforme definido na skill
-- Preencha a tabela de **rastreabilidade User Stories → Tasks** para garantir cobertura completa
+- Preencha a tabela de **rastreabilidade User Stories -> Tasks** para garantir cobertura completa
 - Ofereca **2-4 opcoes** de abordagem tecnica quando houver duvida
 
+---
+
+## Delegacao QA — Secao 6 de cada Task (Testes)
+
+A **secao 6 (Testes)** de cada task NAO deve ser preenchida pelo engenheiro de tarefas. Voce DEVE delegar para o subagente **qa-staff-engineer** que retorna um JSON estruturado. Depois, voce converte o JSON em markdown no formato checklist da secao 6.
+
+### Quando executar
+
+Para **cada task**, apos preencher as secoes 1-5 e 7-8, **ANTES de salvar o arquivo da task**. Se varias tasks estao sendo criadas, voce pode disparar subagentes QA em **paralelo** para maximizar eficiencia.
+
+### Passo 1: Preparar a lista de arquivos
+
+Monte a lista de `arquivos` que o subagente deve ler para CADA task. Inclua:
+
+- **PRD aprovado**: `docs/[nome-feature]/vN/prd.md`
+- **SPEC_TECH aprovado**: `docs/[nome-feature]/vN/spec_tech.md`
+- **Regras do projeto**: `CLAUDE.md`, `.claude/rules/*.md`
+- **Migracoes**: `internal/db/migrations/*.sql` (relacionadas a task)
+- **Queries SQLC**: `internal/db/queries/*.sql` (relacionadas a task)
+- **Testes existentes**: busque arquivos `*_test.go` relacionados aos arquivos impactados pela task
+- **Codigo-fonte existente**: arquivos listados na secao 5 da task (a criar ou modificar)
+
+### Passo 2: Preparar as instrucoes
+
+Monte o campo `instrucoes` com:
+
+1. O conteudo completo da **task parcial (secoes 1-5)** que voce montou ate o momento
+2. Os **criterios de aceite tecnico** da task (secao 4)
+3. Os **arquivos impactados** pela task (secao 5) — para o QA saber quais camadas testar
+4. O **tipo da task** (cria handler, cria service, cria repository, cria migracao, etc.)
+5. Qualquer contexto adicional relevante para o QA
+
+### Passo 3: Disparar o subagente
+
+Lance o subagente usando a ferramenta `Agent` com:
+
+- **subagent_type**: `qa-staff-engineer`
+- **description**: "QA gerar testes task TN"
+- **prompt**: Monte o prompt com os 3 parametros obrigatorios:
+
+```
+Voce foi invocado com os seguintes parametros:
+
+1. **modo**: GERAR_TESTES
+2. **arquivos**: [lista de caminhos dos arquivos preparados no Passo 1]
+3. **instrucoes**: [conteudo preparado no Passo 2]
+```
+
+### Passo 4: Converter JSON em Markdown (secao 6)
+
+O subagente retorna um JSON com `casos_teste[]`. Voce DEVE converter para o formato **checklist** da secao 6 usando o mapeamento abaixo:
+
+#### Mapeamento de tipos
+
+| Campo `tipo` no JSON | Subsecao destino |
+|---------------------|-----------------|
+| `UNITARIO` | **6.1 Testes Unitarios** |
+| `INTEGRACAO` | **6.2 Testes de Integracao** |
+| `E2E` | **6.3 Testes E2E** |
+| `SEGURANCA` | **6.4 Cenarios de Erro** |
+| `PERFORMANCE` | **6.4 Cenarios de Erro** |
+
+#### Mapeamento de categorias para 6.4
+
+Alem dos testes tipo `SEGURANCA` e `PERFORMANCE`, inclua em 6.4 todos os `casos_teste` com `categoria` igual a:
+- `tratamento_erro`
+- `caso_extremo`
+- `fronteira` (quando o teste foca em comportamento de erro)
+
+#### Formato de saida por subsecao
+
+O formato de saida DEVE seguir o **formato tabular** identico ao da secao 14 do SPEC_TECH. Isso garante consistencia entre os dois documentos e facilita a validacao visual.
+
+Infira o nome do arquivo de teste a partir do componente testado:
+- Handler → `[nome]_handler_test.go`
+- Service → `[nome]_service_test.go`
+- Repository → `[nome]_repository_test.go`
+
+Infira o nome da funcao de teste a partir do titulo do CT:
+- Use formato `TestNomeMetodo_CenarioDescritivo` (Go convention)
+
+**6.1 Testes Unitarios** — formato tabular agrupado por componente:
+
+```markdown
+#### [Camada]: [NomeComponente] (`arquivo_test.go`)
+
+Mock: [interfaces mockadas]
+
+| CT | Teste | CA | Objetivo | Input | Expected | Mock |
+|----|-------|----|----------|-------|----------|------|
+| CT-XX | TestMetodo_Cenario | CA-XX | Verificar que [comportamento] quando [condicao] | dados entrada | resultado esperado | dependencias mockadas |
+```
+
+**6.2 Testes de Integracao** — formato tabular com Setup acima:
+
+```markdown
+#### [CamadaA + CamadaB] (`arquivo_test.go`)
+
+Setup: [banco in-memory, migracoes, fixtures]
+
+| CT | Teste | CA | Objetivo | Fluxo | Validacao |
+|----|-------|----|----------|-------|-----------|
+| CT-XX | TestIntegracao_Cenario | CA-XX | Verificar que [comportamento] quando [condicao] | Passos do fluxo | Assertions esperadas |
+```
+
+**6.3 Testes E2E** — formato descritivo por fluxo:
+
+```markdown
+#### Fluxo: [Nome do Fluxo] (CT-XX)
+- **CA**: CA-XX, CA-YY
+- **Objetivo**: (1 frase descrevendo o que este fluxo E2E valida de ponta a ponta)
+- **Pre-condicoes**: (estado inicial do sistema)
+- **Passos**:
+  1. Passo 1
+  2. Passo 2
+- **Validacoes**: (assertions sobre dados e estado final)
+```
+
+**6.4 Cenarios de Erro** — formato tabular:
+
+```markdown
+| Cenario | CA | Objetivo | Trigger | Codigo/Status | Log Esperado |
+|---------|----|----------|---------|---------------|-------------|
+| Descricao do cenario | CA-XX | Verificar que [constraint] impede [operacao] | Acao trigger | Codigo erro | Mensagem log |
+```
+
+#### Testes Existentes a Modificar
+
+Apos as subsecoes 6.1-6.4, adicione a tabela de testes existentes. Infira a partir de:
+- Campo `recomendacoes` do JSON (se mencionar testes existentes)
+- Arquivos de teste ja existentes para os componentes impactados pela task (secao 5.2 - Arquivos a Modificar)
+
+```markdown
+### Testes Existentes a Modificar
+| Arquivo | Motivo da Modificacao |
+|---------|----------------------|
+| [arquivo] | [motivo] |
+```
+
+Se nenhum teste existente precisa ser modificado: `> Nenhum teste existente impactado.`
+
+#### Informacoes adicionais do JSON
+
+- **`cenarios_nao_cobertos`**: adicione como nota apos a secao 6.4
+- **`recomendacoes`**: use para complementar testes ou identificar testes existentes a modificar
+- **`erros_leitura`**: se houver, mencione quais arquivos nao puderam ser lidos
+
+### Passo 5: Validar como engenheiro de tarefas
+
+Antes de integrar a secao 6 na task:
+
+1. Verifique **coerencia** com as secoes 1-5 da task (os componentes testados existem na secao 5?)
+2. Verifique que os testes cobrem os **criterios de aceite tecnico** da secao 4
+3. Ajuste nomenclatura de arquivos e funcoes de teste para seguir os padroes do projeto
+4. Para tasks que NAO envolvem codigo (ex: documentacao, configuracao), preencha "N/A — task nao envolve codigo testavel"
+
+### Passo 6: Integrar e salvar
+
+1. Insira a secao 6 convertida na task
+2. Salve o arquivo `tasks/TN.md`
+3. Apresente ao usuario para aprovacao
+
+**NAO peca aprovacao isolada da secao 6** — apresente a task completa para validacao.
+
+---
+
+## Estado do Pipeline (sdd_state.yaml)
+
+Apos salvar o task_plan.md e todas as tasks com sucesso, atualize o arquivo `sdd_state.yaml` no mesmo diretorio:
+
+```yaml
+# atualizar apenas estes campos:
+current_step: task_plan
+steps:
+  task_plan:
+    status: completed
+    summary: "<N tasks>, <M fases>, <P paralelizaveis>. US cobertas: <X/Y>"
+  execution:
+    status: pending
+    tasks_total: <N>
+    tasks_completed: 0
+```
+
+Se a validacao SDD nao foi executada, marque-a como `skipped`:
+
+```yaml
+steps:
+  validation:
+    status: skipped
+```
+
+Se o `sdd_state.yaml` nao existir, nao crie — o generate-prd e responsavel por criar.
+
 ## Entrada
 
 $ARGUMENTS

package/frameworks/commands/sdd/generate-tech-direction.md

@@ -0,0 +1,43 @@
+---
+description: "Gera TECH DIRECTION do SDD a partir de PRD aprovado. Param: caminho do prd.md"
+argument-hint: "<prd.md ex: docs/feature-user/v1/prd.md>"
+---
+
+Use a skill **sdd-tech-direction-expert** para gerar o tech_direction.md.
+
+## Contexto
+
+Voce deve atuar como um **Arquiteto de Software Senior** especializado em tomada de decisao tecnica e seguir todo o processo interativo definido na skill sdd-tech-direction-expert para construir um tech_direction completo.
+
+## Pre-requisito
+
+Antes de iniciar, verifique se `.claude/rules/project-profile.md` existe. Se NAO existir, interrompa e peca ao usuario para executar `/generate-project-profile` primeiro.
+
+## Regras Adicionais
+
+- **Claude Code**: use a ferramenta `AskUserQuestion` para esclarecer duvidas com o usuario
+- **NUNCA** deduza decisoes ou invente informacoes — na **DUVIDA PERGUNTE AO USUARIO**
+- Leia o **project-profile.md** para entender stack, padroes e convencoes do projeto
+- Pesquise o codebase ANTES de fazer perguntas (regras, padroes, libs)
+- Faca **UMA pergunta por vez**, aguardando a resposta antes de avancar
+- **SEMPRE** salve o arquivo fisico antes de apresentar ao usuario
+- O arquivo deve ser salvo no mesmo diretorio do PRD: `docs/[nome-feature]/vN/tech_direction.md`
+
+## Estado do Pipeline (sdd_state.yaml)
+
+Apos salvar o tech_direction.md com sucesso, atualize o arquivo `sdd_state.yaml` no mesmo diretorio:
+
+```yaml
+# atualizar apenas estes campos:
+current_step: tech_direction
+steps:
+  tech_direction:
+    status: completed
+    summary: "<listar as principais decisoes tecnicas em 1 frase>"
+```
+
+Se o `sdd_state.yaml` nao existir, nao crie — o generate-prd e responsavel por criar.
+
+## Entrada
+
+$ARGUMENTS