@polymorphism-tech/morph-spec 4.8.18 → 4.9.0

package/framework/skills/level-1-workflows/phase-design/SKILL.md

@@ -1,366 +1,383 @@
----
-name: phase-design
-description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts.cs (contracts-vsa.cs for VSA or contracts-level{N}.cs for DDD), schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.18"
----
-
-# MORPH Design - FASE 2
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Expanda a proposta em especificação técnica completa, contracts, decisões arquiteturais e estimativa de custos.
-
-## Pré-requisitos
-
-- [ ] FASE 1 (Setup) concluída
-- [ ] FASE 1.5 (UI/UX) concluída OU pulada (se não houver front-end)
-- [ ] Proposta aprovada pelo usuário
-
-## Ferramentas Recomendadas
-
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
-> **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Ler proposal + UI specs | **Read** output files | — |
-| Obter dispatch config | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS design` | Agentes a disparar + prompts de task |
-| **Dispatch domain-architect** (paralelo) | **Task** subagent com prompt do dispatch config | Análise de complexidade independente |
-| **Dispatch tech leads ativos** (paralelo) | **Task** subagents (dotnet-senior, nextjs-expert…) | Validação de arquitetura independente |
-| Obter schema do banco | **Supabase MCP** `list_tables()`, `get_table_schema()` | **Grep** queries + **Read** types |
-| Obter relacionamentos de FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK no código |
-| Obter políticas RLS | **Supabase MCP** `query()` com pg_policies | **Read** arquivos de políticas |
-| Encontrar arquivos de query (fallback) | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
-| Encontrar definições de tipo (fallback) | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
-| Ler arquivos de query/tipos (fallback) | **Read** cada arquivo encontrado | — |
-| Pesquisar biblioteca para ADR | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Buscar padrões no código | **GitHub MCP** `search_code()` | **Grep** padrões no projeto |
-| Renderizar template contracts (VSA) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-vsa.cs ...` | — |
-| Renderizar template contracts (DDD nível detectado) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` onde N = nível detectado no Passo 1.5 | — |
-| Renderizar template spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
-| Renderizar template decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
-| Criar schema-analysis.md | **Write** no diretório de outputs | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
-
-**MCPs desta fase:** Supabase (schema analysis — **PRIORITÁRIO**), Context7 (research), GitHub (code search).
-
-**Anti-padrões:**
-- ❌ Adivinhar nomes de campos sem verificar schema (use MCP ou Grep primeiro!)
-- ❌ Task agent para ler um único arquivo spec (use Read direto)
-- ❌ WebSearch para schema do banco (use Supabase MCP ou análise de código)
-- ❌ Escrever contracts-level{N}.cs do zero (use template render)
-- ❌ Executar análise de domínio e análise de schema sequencialmente (são independentes — paralelize!)
-- ❌ Fazer análise de domínio inline no contexto principal quando 2+ agentes estão ativos (use Task dispatch)
-
----
-
-## ✅ PRÉ-VOO OBRIGATÓRIO (antes de gerar qualquer artefato)
-
-### 1. Verificar contexto injetado pelo SessionStart
-
-O hook já injetou o estado atual. Confirme que você leu:
-- Feature ativa, fase, status de approvals
-- Task progress e pending gates
-- Spec snippet (se disponível)
-
-### 2. Ler todos os prerequisitos em PARALELO
-
-```
-# Uma única chamada, não sequencial:
-Read: .morph/features/{feature}/0-proposal/proposal.md
-    + Read: .morph/config/config.json   (→ architecture.style)
-    + Read: .morph/context/README.md    (→ project context)
-    + Read: framework/agents.json       (→ activeAgents do feature)
-```
-
-### 3. Avaliar escopo → EnterPlanMode se necessário
-
-Se QUALQUER uma das condições abaixo for verdadeira:
-- [ ] Refactor toca ≥5 arquivos existentes de domínio
-- [ ] Estimativa de tasks ≥20
-- [ ] Mudança de arquitetura (ex: migrar de DDD Level 1 → Level 2)
-
-→ **USE EnterPlanMode** antes de gerar contratos. Explore o codebase, apresente opções, aguarde aprovação.
-
-### 4. Dispatch paralelo de subagents para artefatos independentes
-
-Os 4 artefatos de design são **independentes entre si**. Dispatch em paralelo:
-
-```
-# Executar todos ao mesmo tempo (uma mensagem, múltiplos Task tool calls):
-Task(subagent=general): gerar spec.md (endpoints, regras de negócio)
-Task(subagent=general): gerar contracts-vsa.cs ou contracts-levelN.cs
-Task(subagent=general): gerar decisions.md (ADRs)
-Task(subagent=general): gerar tasks.md skeleton
-```
-
-Ou obter config de dispatch:
-```bash
-npx morph-spec dispatch-agents {feature} design --table
-```
-
-### 5. Criar tasks de sessão para visibilidade
-
-```
-TaskCreate: "Gerar spec.md"          → activeForm: "Gerando spec.md"
-TaskCreate: "Gerar contracts.cs"     → activeForm: "Gerando contracts.cs"
-TaskCreate: "Gerar decisions.md"     → activeForm: "Gerando decisions.md"
-TaskCreate: "Avanço de fase"         → activeForm: "Avançando fase"
-```
-
----
-
-## Workflow
-
-### Passo 1: Carregar Contexto, Agentes e Dispatch Config
-
-**Obtenha feature state e dispatch config:**
-
-```bash
-npx morph-spec state get $ARGUMENTS
-npx morph-spec dispatch-agents $ARGUMENTS design
-```
-
-O primeiro comando retorna `activeAgents`. O segundo retorna os agentes a disparar e seus prompts de task.
-
-**Leia outputs existentes em paralelo (Read direto):**
-1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
-2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
-
-**Standards context** (carregue para o contexto principal os standards dos agentes ativos):
-- Paths dos standards em `agents.json[activeAgent].standards[]`
-- Prioridade: `.morph/context/*.md` > `.morph/framework/standards/` > `framework/standards/`
-- Architecture standards → guiam Technical Architecture section
-- Coding standards → definem contracts-level{N}.cs patterns
-
-### Passo 1.5: Análise de Domínio via Task Dispatch
-
-**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato. Use **Task tool** para isolar esta análise do contexto principal.
-
-> Para os prompts completos de análise de arquitetura, veja `references/architecture-analysis-guide.md`
-
-O arquiteto ativo (lido do dispatch config no Passo 1) pode ser `domain-architect` (DDD) ou `vsa-architect` (VSA) — o prompt vem do dispatch config retornado por `dispatch-agents`.
-
-**Paralelização:** Este Task dispatch pode iniciar SIMULTANEAMENTE com o Passo 2 (schema analysis).
-
-#### Caminho A: `domain-architect` ativo (DDD)
-
-Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). O agente responde às 5 perguntas de complexidade DDD e retorna o nível (1, 2 ou 3) com justificativa.
-
-**Após receber o resultado:**
-- Documente no spec.md (seção `## Domain Complexity`)
-- **Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md
-- **Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template
-
-#### Caminho B: `vsa-architect` ativo (VSA)
-
-Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). O agente produz um VSA Blueprint com entity fields, operations, routes, error types e validation rules.
-
-**Após receber o resultado:** Documente no spec.md (seção `## Architecture Style: Vertical Slice`).
-
----
-
-### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
-
-**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts-level{N}.cs`. Previne geração de DTOs com nomes de campos errados.
-
-**Delegate para skill dedicada:**
-
-> **Ref:** `framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md` — workflow completo de análise de schema (MCP Supabase → fallback análise estática → SCHEMA-ANALYSIS.md → checkpoint de aprovação)
-
-Execute o workflow de `phase-codebase-analysis.md` para:
-1. Detectar se análise é necessária
-2. Tentar MCP Supabase (preferencial) ou análise estática (fallback)
-3. Mapear field name mismatches e type mismatches
-4. Gerar `schema-analysis.md` com findings reais
-5. Apresentar checkpoint ao usuário e aguardar aprovação
-
-**Pule se:**
-- Feature é 100% nova (sem dependências em código existente)
-- Não há banco de dados ou APIs envolvidas
-
-### Passo 3: Gerar `spec.md`
-
-> Para estrutura detalhada de cada seção, veja `references/spec-authoring-guide.md`
-
-Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com as seções: Overview, Functional Requirements (FR001...), Non-Functional Requirements, Technical Architecture, Data Model, e Infrastructure Requirements (se aplicável).
-
-### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
-
-**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs/campos corretos!
-
-**Selecione o template baseado no arquiteto ativo:**
-
-| Arquiteto ativo | Template |
-|-----------------|---------|
-| `vsa-architect` | `code/dotnet/contracts/contracts-vsa.cs` |
-| `domain-architect` (Nível 1) | `code/dotnet/contracts/contracts-level1.cs` |
-| `domain-architect` (Nível 2) | `code/dotnet/contracts/contracts-level2.cs` |
-| `domain-architect` (Nível 3) | `code/dotnet/contracts/contracts-level3.cs` |
-
-**Renderizar template:**
-
-```bash
-# Para projetos VSA:
-npx morph-spec template render \
-  dotnet-contracts-vsa \
-  .morph/features/$ARGUMENTS/1-design/contracts.cs \
-  '{
-    "FEATURE_NAME": "$ARGUMENTS",
-    "NAMESPACE": "{ProjectNamespace}",
-    "ROUTE": "/api/{kebabCase FEATURE_NAME}s",
-    "DATE": "{{DATE}}"
-  }'
-
-# Para projetos DDD (substituir N pelo nível detectado):
-npx morph-spec template render \
-  code/dotnet/contracts/contracts-level{N}.cs \
-  .morph/features/$ARGUMENTS/1-design/contracts.cs \
-  '{
-    "FEATURE_NAME": "$ARGUMENTS",
-    "NAMESPACE": "{ProjectNamespace}",
-    "dtos": [...],
-    "interfaces": [...],
-    "enums": [...],
-    "valueObjects": [...]
-  }'
-```
-
-**Após renderizar (VSA):** Preencha os campos marcados com `// placeholder:` no template gerado com os campos reais da entidade, validators e mapeamentos do VSA Blueprint (Passo 1.5 Caminho B).
-
-**Padrões obrigatórios (DDD — já incluídos no template):**
-- Records para DTOs (immutable)
-- Interfaces para serviços
-- CancellationToken em métodos async
-- Nullable reference types habilitados
-- **USAR NOMES DE CAMPOS REAIS DO SCHEMA** (NÃO assumir!)
-- XML documentation comments
-- Value objects para complex types
-
-**Padrões obrigatórios (VSA — já incluídos no template):**
-- Request + Response records no mesmo arquivo do Handler
-- `sealed` em handlers, endpoints, validators, records
-- `Guid.CreateVersion7()` para IDs
-- `result.Match()` nos endpoints
-- `{Entity}Errors` estático compartilhado por todos os slices da feature
-
-**⚠️ CHECKPOINT: Verificar contra schema-analysis.md**
-- [ ] Todos os field names correspondem ao schema real?
-- [ ] Tipos de dados corretos (JSONB → JsonObject, não string)?
-- [ ] Nullability correta (campo opcional no banco → nullable no DTO)?
-- [ ] Relacionamentos mapeados corretamente?
-- [ ] Template foi renderizado corretamente?
-
-### Passo 5: Iniciar `decisions.md`
-
-**Renderizar template:**
-
-```bash
-# Use o template de decisions:
-Read: .morph/framework/templates/feature/decisions.md
-
-# OU renderize via CLI:
-npx morph-spec template render \
-  feature/decisions \
-  .morph/features/$ARGUMENTS/1-design/decisions.md \
-  '{
-    "FEATURE_NAME": "$ARGUMENTS",
-    "DATE": "{{DATE}}",
-    "decisions": []
-  }'
-```
-
-**Template contém estrutura para ADRs (Architecture Decision Records):**
-- Status, Context, Decision, Consequences
-- Pros/Cons analysis
-- Alternatives Considered section
-- Date tracking
-
-**ADRs obrigatórios:**
-- Escolha de biblioteca UI (se FASE 1.5 executou)
-- Padrões arquiteturais (CQRS, Repository, etc.)
-- Recursos Azure (se houver infra)
-- Integrações externas (APIs, webhooks, etc.)
-- Análise de custos (se houver recursos pagos)
-
-### Passo 6: Estimar Custos
-
-Se houver recursos Azure na spec:
-
-**Limites configuráveis** (em config.json):
-- `costs.limits.freeTierOnly`: $0 (apenas free tier)
-- `costs.limits.withApproval`: $10 (requer confirmação do usuário)
-- `costs.limits.requiresADR`: $10 (requer ADR documentado)
-
-Documente custos em `decisions.md` e atualize state:
-
-```bash
-npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
-npx morph-spec state set $ARGUMENTS costs.approved {true/false}
-```
-
-### Passo 7: Atualizar State
-
-```bash
-npx morph-spec state mark-output $ARGUMENTS schema-analysis
-npx morph-spec state mark-output $ARGUMENTS spec
-npx morph-spec state mark-output $ARGUMENTS contracts
-npx morph-spec state mark-output $ARGUMENTS decisions
-```
-
-## Outputs Gerados
-
-- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` - **NOVO!** Análise do schema real
-- `.morph/features/$ARGUMENTS/1-design/spec.md` - Especificação técnica completa
-- `.morph/features/$ARGUMENTS/1-design/contracts.cs` - Interfaces, DTOs, Enums (baseados no schema real!)
-- `.morph/features/$ARGUMENTS/1-design/decisions.md` - ADRs (novo ou atualizado)
-- State atualizado com custos estimados
-
-## PAUSA OBRIGATÓRIA
-
-Apresente ao usuário 3 ações sugeridas:
-
-1. **Aprovar design e continuar para clarificação**
-2. **Ajustar escopo/complexidade** - Revisar spec.md
-3. **Modificar contracts** - Ajustar interfaces/DTOs
-
-## Critérios de Avanço
-
-- [x] `spec.md` completo com todos os requisitos
-- [x] `contracts-level{N}.cs` com interfaces e DTOs
-- [x] `decisions.md` com ADRs relevantes
-- [x] Custos estimados e documentados (se houver infra)
-- [x] State atualizado
-- [x] Usuário aprovou design
-
----
-
-## Integração com Superpowers
-
-> Disponível quando o plugin `superpowers` está instalado.
-
-| Skill | Quando Usar | Invocação |
-|-------|-------------|-----------|
-| `writing-plans` | Após spec aprovado, para estruturar abordagem de implementação | `Skill(superpowers:writing-plans)` |
-| `brainstorming` | Para explorar alternativas de arquitetura (use morph-spec version) | Use `brainstorming` (morph-spec version) |
-
----
-
-## Outputs desta Fase
-
-<!-- morph:outputs:design -->
-| Output | Caminho |
-|--------|---------|
-| `schemaAnalysis` | `.morph/features/{feature}/1-design/schema-analysis.md` |
-| `spec` | `.morph/features/{feature}/1-design/spec.md` |
-| `contracts` | `.morph/features/{feature}/1-design/contracts.cs` |
-| `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
-<!-- /morph:outputs -->
-
----
-
+---
+name: morph:phase-design
+description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts.cs (contracts-vsa.cs for VSA or contracts-level{N}.cs for DDD), schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.9.0"
+---
+
+# MORPH Design - FASE 2
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Expanda a proposta em especificação técnica completa, contracts, decisões arquiteturais e estimativa de custos.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] FASE 1.5 (UI/UX) concluída OU pulada (se não houver front-end)
+- [ ] Proposta aprovada pelo usuário
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler proposal + UI specs | **Read** output files | — |
+| Obter dispatch config | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS design` | Agentes a disparar + prompts de task |
+| **Dispatch domain-architect** (paralelo) | **Agent** `subagent_type=domain-architect` (ou `vsa-architect`) + `prompt=agent.taskPrompt` do dispatch config | Análise de complexidade independente |
+| **Dispatch tech leads ativos** (paralelo) | **Agent** `subagent_type=<agent.id>` para cada agente ativo — o `id` do dispatch config é o `name` do subagente nativo em `.claude/agents/` | Análise de domínio independente |
+| Obter schema do banco | **Supabase MCP** `list_tables()`, `get_table_schema()` | **Grep** queries + **Read** types |
+| Obter relacionamentos de FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK no código |
+| Obter políticas RLS | **Supabase MCP** `query()` com pg_policies | **Read** arquivos de políticas |
+| Encontrar arquivos de query (fallback) | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar definições de tipo (fallback) | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos de query/tipos (fallback) | **Read** cada arquivo encontrado | — |
+| Pesquisar biblioteca para ADR | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Buscar padrões no código | **GitHub MCP** `search_code()` | **Grep** padrões no projeto |
+| Renderizar template contracts (VSA) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-vsa.cs ...` | — |
+| Renderizar template contracts (DDD nível detectado) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` onde N = nível detectado no Passo 1.5 | — |
+| Renderizar template spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
+| Renderizar template decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
+| Criar schema-analysis.md | **Write** no diretório de outputs | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
+
+**MCPs desta fase:** Supabase (schema analysis — **PRIORITÁRIO**), Context7 (research), GitHub (code search).
+
+**Anti-padrões:**
+- ❌ Adivinhar nomes de campos sem verificar schema (use MCP ou Grep primeiro!)
+- ❌ Task agent para ler um único arquivo spec (use Read direto)
+- ❌ WebSearch para schema do banco (use Supabase MCP ou análise de código)
+- ❌ Escrever contracts-level{N}.cs do zero (use template render)
+- ❌ Executar análise de domínio e análise de schema sequencialmente (são independentes — paralelize!)
+- ❌ Fazer análise de domínio inline no contexto principal quando 2+ agentes estão ativos (use Task dispatch)
+
+---
+
+## ✅ PRÉ-VOO OBRIGATÓRIO (antes de gerar qualquer artefato)
+
+### 1. Verificar contexto injetado pelo SessionStart
+
+O hook já injetou o estado atual. Confirme que você leu:
+- Feature ativa, fase, status de approvals
+- Task progress e pending gates
+- Spec snippet (se disponível)
+
+### 2. Ler todos os prerequisitos em PARALELO
+
+```
+# Uma única chamada, não sequencial:
+Read: .morph/features/{feature}/0-proposal/proposal.md
+    + Read: .morph/config/config.json   (→ architecture.style)
+    + Read: .morph/context/README.md    (→ project context)
+    + Read: framework/agents.json       (→ activeAgents do feature)
+```
+
+### 3. Avaliar escopo → EnterPlanMode se necessário
+
+Se QUALQUER uma das condições abaixo for verdadeira:
+- [ ] Refactor toca ≥5 arquivos existentes de domínio
+- [ ] Estimativa de tasks ≥20
+- [ ] Mudança de arquitetura (ex: migrar de DDD Level 1 → Level 2)
+
+→ **USE EnterPlanMode** antes de gerar contratos. Explore o codebase, apresente opções, aguarde aprovação.
+
+### 4. Dispatch paralelo de subagents para artefatos independentes
+
+Os 4 artefatos de design são **independentes entre si**. Obtenha o config de dispatch e despache em paralelo:
+
+```bash
+npx morph-spec dispatch-agents {feature} design --table
+```
+
+Para cada agente em `config.agents` (excluindo o arquiteto já despachado no Passo 1.5), use o `id` como `subagent_type` no Agent tool:
+
+```
+# Exemplo com agentes típicos detectados (uma mensagem, múltiplos Agent tool calls):
+Agent(subagent_type=dotnet-senior,    prompt=<agent.taskPrompt>)   # → spec.md + contracts.cs
+Agent(subagent_type=nextjs-expert,    prompt=<agent.taskPrompt>)   # → frontend spec
+Agent(subagent_type=standards-architect, prompt=<agent.taskPrompt>) # → decisões + ADRs
+```
+
+> **Regra de mapeamento:** `agent.id` do dispatch config = `name:` no frontmatter do arquivo em `.claude/agents/` = `subagent_type` do Agent tool. Ex: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert)`.
+
+**Se `config.shouldDispatch === false`** (1 agente ou nenhum): execute os passos abaixo diretamente, sem dispatch.
+
+### 5. Criar tasks de sessão para visibilidade
+
+```
+TaskCreate: "Gerar spec.md"          → activeForm: "Gerando spec.md"
+TaskCreate: "Gerar contracts.cs"     → activeForm: "Gerando contracts.cs"
+TaskCreate: "Gerar decisions.md"     → activeForm: "Gerando decisions.md"
+TaskCreate: "Avanço de fase"         → activeForm: "Avançando fase"
+```
+
+---
+
+## Workflow
+
+### Passo 1: Carregar Contexto, Agentes e Dispatch Config
+
+**Obtenha feature state e dispatch config:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+O primeiro comando retorna `activeAgents`. O segundo retorna os agentes a disparar e seus prompts de task.
+
+**Leia outputs existentes em paralelo (Read direto):**
+1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
+2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
+
+**Standards context** (carregue para o contexto principal os standards dos agentes ativos):
+- Paths dos standards em `agents.json[activeAgent].standards[]`
+- Prioridade: `.morph/context/*.md` > `.morph/framework/standards/` > `framework/standards/`
+- Architecture standards → guiam Technical Architecture section
+- Coding standards → definem contracts-level{N}.cs patterns
+
+### Passo 1.5: Análise de Domínio via Task Dispatch
+
+**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato. Use **Task tool** para isolar esta análise do contexto principal.
+
+> Para os prompts completos de análise de arquitetura, veja `references/architecture-analysis-guide.md`
+
+O arquiteto ativo (lido do dispatch config no Passo 1) pode ser `domain-architect` (DDD) ou `vsa-architect` (VSA) — o prompt vem do dispatch config retornado por `dispatch-agents`.
+
+**Paralelização:** Este Task dispatch pode iniciar SIMULTANEAMENTE com o Passo 2 (schema analysis).
+
+#### Caminho A: `domain-architect` ativo (DDD)
+
+Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). Chame o Agent tool usando o `id` do dispatch config como `subagent_type`:
+
+```
+# agent.id do dispatch config = subagent_type do Agent tool
+Agent(subagent_type=domain-architect, prompt=<agent.taskPrompt + conteúdo de proposal.md>)
+```
+
+O agente responde às 5 perguntas de complexidade DDD e retorna o nível (1, 2 ou 3) com justificativa.
+
+**Após receber o resultado:**
+- Documente no spec.md (seção `## Domain Complexity`)
+- **Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md
+- **Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template
+
+#### Caminho B: `vsa-architect` ativo (VSA)
+
+Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). Chame o Agent tool:
+
+```
+Agent(subagent_type=vsa-architect, prompt=<agent.taskPrompt + conteúdo de proposal.md>)
+```
+
+O agente produz um VSA Blueprint com entity fields, operations, routes, error types e validation rules.
+
+**Após receber o resultado:** Documente no spec.md (seção `## Architecture Style: Vertical Slice`).
+
+---
+
+### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
+
+**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts-level{N}.cs`. Previne geração de DTOs com nomes de campos errados.
+
+**Delegate para skill dedicada:**
+
+> **Ref:** `framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md` — workflow completo de análise de schema (MCP Supabase → fallback análise estática → SCHEMA-ANALYSIS.md → checkpoint de aprovação)
+
+Execute o workflow de `phase-codebase-analysis.md` para:
+1. Detectar se análise é necessária
+2. Tentar MCP Supabase (preferencial) ou análise estática (fallback)
+3. Mapear field name mismatches e type mismatches
+4. Gerar `schema-analysis.md` com findings reais
+5. Apresentar checkpoint ao usuário e aguardar aprovação
+
+**Pule se:**
+- Feature é 100% nova (sem dependências em código existente)
+- Não há banco de dados ou APIs envolvidas
+
+### Passo 3: Gerar `spec.md`
+
+> Para estrutura detalhada de cada seção, veja `references/spec-authoring-guide.md`
+
+Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com as seções: Overview, Functional Requirements (FR001...), Non-Functional Requirements, Technical Architecture, Data Model, e Infrastructure Requirements (se aplicável).
+
+### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
+
+**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs/campos corretos!
+
+**Selecione o template baseado no arquiteto ativo:**
+
+| Arquiteto ativo | Template |
+|-----------------|---------|
+| `vsa-architect` | `code/dotnet/contracts/contracts-vsa.cs` |
+| `domain-architect` (Nível 1) | `code/dotnet/contracts/contracts-level1.cs` |
+| `domain-architect` (Nível 2) | `code/dotnet/contracts/contracts-level2.cs` |
+| `domain-architect` (Nível 3) | `code/dotnet/contracts/contracts-level3.cs` |
+
+**Renderizar template:**
+
+```bash
+# Para projetos VSA:
+npx morph-spec template render \
+  dotnet-contracts-vsa \
+  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "NAMESPACE": "{ProjectNamespace}",
+    "ROUTE": "/api/{kebabCase FEATURE_NAME}s",
+    "DATE": "{{DATE}}"
+  }'
+
+# Para projetos DDD (substituir N pelo nível detectado):
+npx morph-spec template render \
+  code/dotnet/contracts/contracts-level{N}.cs \
+  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "NAMESPACE": "{ProjectNamespace}",
+    "dtos": [...],
+    "interfaces": [...],
+    "enums": [...],
+    "valueObjects": [...]
+  }'
+```
+
+**Após renderizar (VSA):** Preencha os campos marcados com `// placeholder:` no template gerado com os campos reais da entidade, validators e mapeamentos do VSA Blueprint (Passo 1.5 Caminho B).
+
+**Padrões obrigatórios (DDD — já incluídos no template):**
+- Records para DTOs (immutable)
+- Interfaces para serviços
+- CancellationToken em métodos async
+- Nullable reference types habilitados
+- **USAR NOMES DE CAMPOS REAIS DO SCHEMA** (NÃO assumir!)
+- XML documentation comments
+- Value objects para complex types
+
+**Padrões obrigatórios (VSA — já incluídos no template):**
+- Request + Response records no mesmo arquivo do Handler
+- `sealed` em handlers, endpoints, validators, records
+- `Guid.CreateVersion7()` para IDs
+- `result.Match()` nos endpoints
+- `{Entity}Errors` estático compartilhado por todos os slices da feature
+
+**⚠️ CHECKPOINT: Verificar contra schema-analysis.md**
+- [ ] Todos os field names correspondem ao schema real?
+- [ ] Tipos de dados corretos (JSONB → JsonObject, não string)?
+- [ ] Nullability correta (campo opcional no banco → nullable no DTO)?
+- [ ] Relacionamentos mapeados corretamente?
+- [ ] Template foi renderizado corretamente?
+
+### Passo 5: Iniciar `decisions.md`
+
+**Renderizar template:**
+
+```bash
+# Use o template de decisions:
+Read: .morph/framework/templates/feature/decisions.md
+
+# OU renderize via CLI:
+npx morph-spec template render \
+  feature/decisions \
+  .morph/features/$ARGUMENTS/1-design/decisions.md \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "DATE": "{{DATE}}",
+    "decisions": []
+  }'
+```
+
+**Template contém estrutura para ADRs (Architecture Decision Records):**
+- Status, Context, Decision, Consequences
+- Pros/Cons analysis
+- Alternatives Considered section
+- Date tracking
+
+**ADRs obrigatórios:**
+- Escolha de biblioteca UI (se FASE 1.5 executou)
+- Padrões arquiteturais (CQRS, Repository, etc.)
+- Recursos Azure (se houver infra)
+- Integrações externas (APIs, webhooks, etc.)
+- Análise de custos (se houver recursos pagos)
+
+### Passo 6: Estimar Custos
+
+Se houver recursos Azure na spec:
+
+**Limites configuráveis** (em config.json):
+- `costs.limits.freeTierOnly`: $0 (apenas free tier)
+- `costs.limits.withApproval`: $10 (requer confirmação do usuário)
+- `costs.limits.requiresADR`: $10 (requer ADR documentado)
+
+Documente custos em `decisions.md` e atualize state:
+
+```bash
+npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
+npx morph-spec state set $ARGUMENTS costs.approved {true/false}
+```
+
+### Passo 7: Atualizar State
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS schema-analysis
+npx morph-spec state mark-output $ARGUMENTS spec
+npx morph-spec state mark-output $ARGUMENTS contracts
+npx morph-spec state mark-output $ARGUMENTS decisions
+```
+
+## Outputs Gerados
+
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` - **NOVO!** Análise do schema real
+- `.morph/features/$ARGUMENTS/1-design/spec.md` - Especificação técnica completa
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs` - Interfaces, DTOs, Enums (baseados no schema real!)
+- `.morph/features/$ARGUMENTS/1-design/decisions.md` - ADRs (novo ou atualizado)
+- State atualizado com custos estimados
+
+## PAUSA OBRIGATÓRIA
+
+Apresente ao usuário 3 ações sugeridas:
+
+1. **Aprovar design e continuar para clarificação**
+2. **Ajustar escopo/complexidade** - Revisar spec.md
+3. **Modificar contracts** - Ajustar interfaces/DTOs
+
+## Critérios de Avanço
+
+- [x] `spec.md` completo com todos os requisitos
+- [x] `contracts-level{N}.cs` com interfaces e DTOs
+- [x] `decisions.md` com ADRs relevantes
+- [x] Custos estimados e documentados (se houver infra)
+- [x] State atualizado
+- [x] Usuário aprovou design
+
+---
+
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `writing-plans` | Após spec aprovado, para estruturar abordagem de implementação | `Skill(superpowers:writing-plans)` |
+| `brainstorming` | Para explorar alternativas de arquitetura (use morph-spec version) | Use `brainstorming` (morph-spec version) |
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:design -->
+| Output | Caminho |
+|--------|---------|
+| `schemaAnalysis` | `.morph/features/{feature}/1-design/schema-analysis.md` |
+| `spec` | `.morph/features/{feature}/1-design/spec.md` |
+| `contracts` | `.morph/features/{feature}/1-design/contracts.cs` |
+| `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
+<!-- /morph:outputs -->
+
+---
+
 Continuar automaticamente para FASE 3 (Clarify) após aprovação.