@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

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

@@ -1,339 +1,340 @@
----
-name: phase-design
-description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts-level{N}.cs, 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
----
-
-# 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 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 (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)
-
----
-
-## Workflow
-
-### Passo 1: Carregar Contexto e Standards
-
-**Obtenha feature state e standards context:**
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Parse o JSON para obter `activeAgents`, então use standards context (já carregado na FASE 1):
-- Standards relevantes estão em `standardsSummary` do detect-agents
-- Padrões já incluem project overrides + inferred learnings
-
-**Leia outputs existentes:**
-1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
-2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
-
-**Use standards context ao gerar spec.md:**
-- Architecture standards → guiam Technical Architecture section
-- Coding standards → definem contracts-level{N}.cs patterns
-- Azure standards → determinam Infrastructure Requirements
-
-### Passo 1.5: Detectar Nível de Domínio (domain-architect)
-
-**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato.
-
-**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
-
-O `domain-architect` analisa a `proposal.md` e responde às seguintes perguntas:
-
-```
-1. A entidade principal tem estados com transições? (Draft → Confirmed → Shipped)
-2. Existem invariants de negócio? ("só cancela se estiver Ativo")
-3. Cálculos derivados existem? (Total, Saldo, Desconto)
-4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores)
-5. O usuário declarou explicitamente Bounded Context na proposta?
-
-→ Nenhuma acima: Nível 1 (CRUD)
-→ 1-4 verdadeiros: Nível 2 (Business Logic)
-→ 5 verdadeiro OU múltiplos domínios com modelos conflitantes: Nível 3 (BC)
-```
-
-**Documente no spec.md** (seção `## Domain Complexity`) antes de continuar para o Passo 3.
-
-**Template a usar no Passo 4 (contracts-level{N}.cs):**
-
-| Nível | Template |
-|-------|----------|
-| 1 | `code/dotnet/contracts/contracts-level1.cs` |
-| 2 | `code/dotnet/contracts/contracts-level2.cs` |
-| 3 | `code/dotnet/contracts/contracts-level3.cs` |
-
-**Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md antes de gerar contracts-level{N}.cs.
-
-**Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template.
-
----
-
-### 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`
-
-Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:
-
-#### 3.1. Overview
-- **Objetivo:** Resumo de 1-2 parágrafos
-- **Usuários afetados:** Quem vai usar?
-- **Problema resolvido:** Qual dor/necessidade?
-
-#### 3.2. Functional Requirements
-Lista detalhada de requisitos funcionais:
-```markdown
-### FR001: {Requisito}
-**Description:** {O que deve fazer}
-**Acceptance Criteria:**
-- [ ] Critério 1
-- [ ] Critério 2
-**Priority:** High/Medium/Low
-```
-
-#### 3.3. Non-Functional Requirements
-- Performance (tempos de resposta esperados)
-- Segurança (autenticação, autorização)
-- Escalabilidade (volume de dados/usuários)
-- Disponibilidade (uptime esperado)
-
-#### 3.4. Technical Architecture
-- **Camadas:** (Presentation, Application, Domain, Infrastructure)
-- **Patterns:** (Repository, CQRS, DI, etc.)
-- **Dependências:** Bibliotecas/serviços externos necessários
-
-#### 3.5. Data Model
-- Entities principais
-- Relacionamentos (1:1, 1:N, N:N)
-- Campos obrigatórios vs opcionais
-- Validações de negócio
-
-#### 3.6. Infrastructure Requirements
-Se houver recursos Azure:
-- Banco de dados (Azure SQL, Cosmos DB)
-- Storage (Blob Storage)
-- Compute (Container Apps, App Service)
-- Monitoring (App Insights)
-
-**SEMPRE usar Bicep para infra!**
-
-### Passo 4: Gerar `contracts-level{N}.cs` (BASEADO NO SCHEMA REAL!)
-
-**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs corretos!
-
-**Renderizar template:**
-
-```bash
-# Use o template de contracts com dados do schema-analysis.md:
-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": [...], # Extrair de schema-analysis.md
-    "interfaces": [...],
-    "enums": [...],
-    "valueObjects": [...]
-  }'
-```
-
-**OU use Read tool para ler template:**
-
-```bash
-# Leia o template base:
-Read: .morph/framework/templates/code/dotnet/contracts/contracts-level{N}.cs.hbs
-
-# Preencha manualmente usando dados de schema-analysis.md
-# Template contém placeholders para:
-# - {{FEATURE_NAME_PASCAL}}
-# - {{NAMESPACE}}
-# - {{#each dtos}}...{{/each}}
-# - {{#each interfaces}}...{{/each}}
-# - {{#each enums}}...{{/each}}
-```
-
-**Padrões obrigatórios (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
-
-**⚠️ 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 set $ARGUMENTS phase design
-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: phase-design
+description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts-level{N}.cs, 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.1"
+---
+
+# 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 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 (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)
+
+---
+
+## Workflow
+
+### Passo 1: Carregar Contexto e Standards
+
+**Obtenha feature state e standards context:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Parse o JSON para obter `activeAgents`, então carregue os standards context da FASE 1:
+- Standards relevantes estão em `.morph/framework/standards/` por agente ativo (paths em `agents.json`)
+- Prioridade: `.morph/context/*.md` > `.morph/framework/standards/` > `framework/standards/`
+
+**Leia outputs existentes:**
+1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
+2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
+
+**Use standards context ao gerar spec.md:**
+- Architecture standards → guiam Technical Architecture section
+- Coding standards → definem contracts-level{N}.cs patterns
+- Azure standards → determinam Infrastructure Requirements
+
+### Passo 1.5: Detectar Nível de Domínio (domain-architect)
+
+**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato.
+
+**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
+
+O `domain-architect` analisa a `proposal.md` e responde às seguintes perguntas:
+
+```
+1. A entidade principal tem estados com transições? (Draft → Confirmed → Shipped)
+2. Existem invariants de negócio? ("só cancela se estiver Ativo")
+3. Cálculos derivados existem? (Total, Saldo, Desconto)
+4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores)
+5. O usuário declarou explicitamente Bounded Context na proposta?
+
+→ Nenhuma acima: Nível 1 (CRUD)
+→ 1-4 verdadeiros: Nível 2 (Business Logic)
+→ 5 verdadeiro OU múltiplos domínios com modelos conflitantes: Nível 3 (BC)
+```
+
+**Documente no spec.md** (seção `## Domain Complexity`) antes de continuar para o Passo 3.
+
+**Template a usar no Passo 4 (contracts-level{N}.cs):**
+
+| Nível | Template |
+|-------|----------|
+| 1 | `code/dotnet/contracts/contracts-level1.cs` |
+| 2 | `code/dotnet/contracts/contracts-level2.cs` |
+| 3 | `code/dotnet/contracts/contracts-level3.cs` |
+
+**Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md antes de gerar contracts-level{N}.cs.
+
+**Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template.
+
+---
+
+### 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`
+
+Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:
+
+#### 3.1. Overview
+- **Objetivo:** Resumo de 1-2 parágrafos
+- **Usuários afetados:** Quem vai usar?
+- **Problema resolvido:** Qual dor/necessidade?
+
+#### 3.2. Functional Requirements
+Lista detalhada de requisitos funcionais:
+```markdown
+### FR001: {Requisito}
+**Description:** {O que deve fazer}
+**Acceptance Criteria:**
+- [ ] Critério 1
+- [ ] Critério 2
+**Priority:** High/Medium/Low
+```
+
+#### 3.3. Non-Functional Requirements
+- Performance (tempos de resposta esperados)
+- Segurança (autenticação, autorização)
+- Escalabilidade (volume de dados/usuários)
+- Disponibilidade (uptime esperado)
+
+#### 3.4. Technical Architecture
+- **Camadas:** (Presentation, Application, Domain, Infrastructure)
+- **Patterns:** (Repository, CQRS, DI, etc.)
+- **Dependências:** Bibliotecas/serviços externos necessários
+
+#### 3.5. Data Model
+- Entities principais
+- Relacionamentos (1:1, 1:N, N:N)
+- Campos obrigatórios vs opcionais
+- Validações de negócio
+
+#### 3.6. Infrastructure Requirements
+Se houver recursos Azure:
+- Banco de dados (Azure SQL, Cosmos DB)
+- Storage (Blob Storage)
+- Compute (Container Apps, App Service)
+- Monitoring (App Insights)
+
+**SEMPRE usar Bicep para infra!**
+
+### Passo 4: Gerar `contracts-level{N}.cs` (BASEADO NO SCHEMA REAL!)
+
+**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs corretos!
+
+**Renderizar template:**
+
+```bash
+# Use o template de contracts com dados do schema-analysis.md:
+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": [...], # Extrair de schema-analysis.md
+    "interfaces": [...],
+    "enums": [...],
+    "valueObjects": [...]
+  }'
+```
+
+**OU use Read tool para ler template:**
+
+```bash
+# Leia o template base:
+Read: .morph/framework/templates/code/dotnet/contracts/contracts-level{N}.cs.hbs
+
+# Preencha manualmente usando dados de schema-analysis.md
+# Template contém placeholders para:
+# - {{FEATURE_NAME_PASCAL}}
+# - {{NAMESPACE}}
+# - {{#each dtos}}...{{/each}}
+# - {{#each interfaces}}...{{/each}}
+# - {{#each enums}}...{{/each}}
+```
+
+**Padrões obrigatórios (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
+
+**⚠️ 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 set $ARGUMENTS phase design
+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.