@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

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

@@ -1,3 +1,12 @@
+---
+name: phase-design
+description: >
+  MORPH-SPEC Phase 2 (Design). Expands the approved proposal into spec.md, contracts.cs, decisions.md, and schema-analysis.md. Called by /morph-proposal after setup completes.
+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.
@@ -10,6 +19,38 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 - [ ] 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.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| 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.cs | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | — |
+| 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.cs do zero (use template render)
+
+---
+
 ## Workflow
 
 ### Passo 1: Carregar Contexto e Standards
@@ -17,7 +58,7 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 **Obtenha feature state e standards context:**
 
 ```bash
-npx morph-spec state get {feature-name}
+npx morph-spec state get $ARGUMENTS
 ```
 
 Parse o JSON para obter `activeAgents`, então use standards context (já carregado na FASE 1):
@@ -25,24 +66,215 @@ Parse o JSON para obter `activeAgents`, então use standards context (já carreg
 - Padrões já incluem project overrides + inferred learnings
 
 **Leia outputs existentes:**
-1. `.morph/project/outputs/{feature}/proposal.md` - Proposta inicial
-2. `.morph/project/outputs/{feature}/ui-*.md` - UI/UX specs (se existirem)
+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.cs patterns
 - Azure standards → determinam Infrastructure Requirements
 
-### Passo 2: Gerar `spec.md`
+### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
+
+**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts.cs`. Previne geração de DTOs com nomes de campos errados.
+
+#### 2.1. Detectar Se Análise É Necessária
+
+A análise de código é necessária se:
+- Feature interage com banco de dados existente
+- Feature usa APIs ou serviços existentes
+- Projeto tem código frontend/backend que será integrado
+
+**Pule este passo apenas se:**
+- Feature é 100% nova (sem dependências em código existente)
+- Não há banco de dados ou APIs envolvidas
+
+#### 2.2. Tentar MCP Tools Primeiro (Preferencial)
+
+**Se MCP Supabase disponível:**
+
+```javascript
+// Verificar se MCP está disponível (procure por ferramentas mcp__supabase__*)
+// Se disponível, use para obter schema real:
+
+// 1. Listar todas as tabelas
+await mcp__supabase__list_tables();
+
+// 2. Para cada tabela relevante, obter schema completo
+await mcp__supabase__get_table_schema({ table: 'leads' });
+await mcp__supabase__get_table_schema({ table: 'users' });
+
+// 3. Obter relacionamentos
+await mcp__supabase__get_relationships({ table: 'leads' });
+
+// 4. Documentar findings em SCHEMA-ANALYSIS.md
+```
+
+**Se MCP Database/ORM disponível:**
+- Use ferramentas MCP equivalentes para PostgreSQL, MySQL, EF Core, etc.
+- Obtenha schema diretamente do banco
+
+#### 2.3. Fallback: Análise Manual de Código
+
+**Se MCP não disponível, use análise estática:**
+
+**Passo A: Encontrar Queries no Código**
+
+```bash
+# Use Grep tool para encontrar todas as queries:
+pattern: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|ef\.Database\."
+type: "ts,tsx,js,jsx,cs"
+output_mode: "files_with_matches"
+```
+
+**Passo B: Ler Arquivos de Query**
+
+Para cada arquivo encontrado, use Read tool para extrair:
+- **Nomes de tabelas:** `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- **Nomes de colunas:** `.select('fullname, phonenumber')`, `l.FullName`, `SELECT full_name`
+- **Tipos de dados:** TypeScript interfaces, C# DTOs, column types
+- **Relacionamentos:** JOIN clauses, navigation properties, foreign keys
+
+**Passo C: Encontrar Type Definitions**
+
+```bash
+# TypeScript/JavaScript projects:
+Glob: "src/**/types/**/*.ts"
+Glob: "src/**/*.d.ts"
+Glob: "src/**/interfaces/*.ts"
+
+# .NET projects:
+Glob: "**/*Dto.cs"
+Glob: "**/Entities/**/*.cs"
+Glob: "**/Models/**/*.cs"
+```
+
+Leia cada arquivo e mapeie:
+- Interface/Type → Database Table
+- Property names → Column names
+- Data types → SQL types
+
+**Passo D: Inferir Schema Real**
+
+Com base nos arquivos lidos, criar um mapa:
+
+```markdown
+| Frontend/Code | Database | Type | Notes |
+|--------------|----------|------|-------|
+| user.name | users.fullname | string | MISMATCH! |
+| lead.phone | leads.phonenumber | string | MISMATCH! |
+| order.metadata | orders.metadata | JSONB | Complex type |
+| user.orders | users → orders (1:N) | relation | Foreign key: orders.user_id |
+```
+
+#### 2.4. Criar SCHEMA-ANALYSIS.md
+
+Documente os findings em `.morph/features/$ARGUMENTS/1-design/schema-analysis.md`:
+
+```markdown
+# Schema Analysis - {Feature Name}
+
+**Date:** {DATE}
+**Method:** {MCP Supabase / Manual Code Analysis}
+
+## Tables Analyzed
+
+### Table: leads
+
+**Source:**
+- MCP: supabase.list_tables()
+- Code: src/lib/database/queries.ts
+
+**Columns:**
+| Column Name | Type | Nullable | Default | Notes |
+|------------|------|----------|---------|-------|
+| id | uuid | NO | gen_random_uuid() | Primary key |
+| fullname | varchar(255) | NO | - | NOT 'name'! |
+| phonenumber | varchar(20) | YES | - | NOT 'phone'! |
+| metadata | jsonb | YES | {} | Complex object |
+| created_at | timestamptz | NO | now() | Auto-generated |
+| user_id | uuid | YES | - | FK to users table |
+
+**Relationships:**
+- leads.user_id → users.id (N:1)
+- leads.id ← roulette_spins.lead_id (1:N)
+
+**Indexes:**
+- PRIMARY KEY (id)
+- INDEX idx_leads_user_id ON (user_id)
+
+### Table: users
+{Repetir para cada tabela}
 
-Crie `.morph/project/outputs/{feature}/spec.md` com:
+## ⚠️ CRITICAL FINDINGS
 
-#### 2.1. Overview
+**Field Name Mismatches (MUST FIX):**
+- ❌ Use `fullname`, NOT `name` (column doesn't exist!)
+- ❌ Use `phonenumber`, NOT `phone` (column doesn't exist!)
+
+**Type Mismatches:**
+- ⚠️ `metadata` is JSONB, not `Record<string, string>` (use proper type)
+
+**Relationship Corrections:**
+- ✅ Lead → User is N:1 (NOT 1:1)
+- ✅ Lead → RouletteSpins is 1:N (NOT 1:1)
+
+## Recommendations for contracts.cs
+
+Based on real schema, DTOs should use:
+\`\`\`csharp
+public record LeadDto(
+    Guid Id,
+    string Fullname,        // NOT 'Name'!
+    string? Phonenumber,    // NOT 'Phone'! Nullable!
+    JsonObject? Metadata,   // NOT Record<string,string>!
+    Guid? UserId,           // Nullable FK
+    DateTime CreatedAt
+);
+\`\`\`
+```
+
+#### 2.5. CHECKPOINT OBRIGATÓRIO: Revisar Schema Analysis
+
+**⏸️ PAUSE - Validar findings antes de continuar:**
+
+Apresente ao usuário:
+- [ ] Analisei {N} arquivos de código
+- [ ] Identifiquei {N} tabelas: {lista}
+- [ ] Encontrei {N} field name mismatches
+- [ ] Encontrei {N} type mismatches
+- [ ] Mapeei {N} relacionamentos
+- [ ] Criei `schema-analysis.md` com todos os findings
+
+**Perguntas ao usuário:**
+1. "O schema analysis está correto?"
+2. "Encontrei field mismatches (fullname vs name). Confirma?"
+3. "Posso prosseguir para gerar contracts.cs com base nesse schema real?"
+
+**❌ Se usuário responder "Não" ou encontrar erros:**
+→ VOLTAR e revisar análise
+→ Corrigir schema-analysis.md
+→ Re-apresentar para aprovação
+
+**✅ Se usuário aprovar:**
+→ Prosseguir para Passo 3 (Gerar spec.md)
+
+#### 2.6. Atualizar State
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS schema-analysis
+```
+
+### 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?
 
-#### 2.2. Functional Requirements
+#### 3.2. Functional Requirements
 Lista detalhada de requisitos funcionais:
 ```markdown
 ### FR001: {Requisito}
@@ -53,24 +285,24 @@ Lista detalhada de requisitos funcionais:
 **Priority:** High/Medium/Low
 ```
 
-#### 2.3. Non-Functional Requirements
+#### 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)
 
-#### 2.4. Technical Architecture
+#### 3.4. Technical Architecture
 - **Camadas:** (Presentation, Application, Domain, Infrastructure)
 - **Patterns:** (Repository, CQRS, DI, etc.)
 - **Dependências:** Bibliotecas/serviços externos necessários
 
-#### 2.5. Data Model
+#### 3.5. Data Model
 - Entities principais
 - Relacionamentos (1:1, 1:N, N:N)
 - Campos obrigatórios vs opcionais
 - Validações de negócio
 
-#### 2.6. Infrastructure Requirements
+#### 3.6. Infrastructure Requirements
 Se houver recursos Azure:
 - Banco de dados (Azure SQL, Cosmos DB)
 - Storage (Blob Storage)
@@ -79,87 +311,91 @@ Se houver recursos Azure:
 
 **SEMPRE usar Bicep para infra!**
 
-### Passo 3: Gerar `contracts.cs`
+### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
 
-Crie `.morph/project/outputs/{feature}/contracts.cs` com:
+**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs corretos!
 
-```csharp
-// Interfaces, DTOs, Enums, Value Objects
+**Renderizar template:**
 
-namespace {ProjectName}.Features.{FeatureName};
-
-// DTOs (Data Transfer Objects)
-public record {Feature}CreateDto(
-    string Name,
-    DateTime Date
-);
+```bash
+# Use o template de contracts com dados do schema-analysis.md:
+npx morph-spec template render \
+  code/dotnet/contracts/contracts.cs \
+  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "NAMESPACE": "{ProjectNamespace}",
+    "dtos": [...], # Extrair de schema-analysis.md
+    "interfaces": [...],
+    "enums": [...],
+    "valueObjects": [...]
+  }'
+```
 
-public record {Feature}ResponseDto(
-    Guid Id,
-    string Name,
-    DateTime Date,
-    DateTime CreatedAt
-);
+**OU use Read tool para ler template:**
 
-// Interfaces
-public interface I{Feature}Service
-{
-    Task<{Feature}ResponseDto> CreateAsync({Feature}CreateDto dto, CancellationToken ct);
-    Task<{Feature}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct);
-}
-
-// Enums
-public enum {Feature}Status
-{
-    Pending,
-    Active,
-    Completed
-}
+```bash
+# Leia o template base:
+Read: .morph/framework/templates/code/dotnet/contracts/contracts.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:**
+**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
 
-### Passo 4: Iniciar `decisions.md`
-
-Crie `.morph/project/outputs/{feature}/decisions.md` com ADRs relevantes:
-
-```markdown
-# Architectural Decision Records (ADRs)
-
-## ADR-001: {Decisão Arquitetural}
-
-**Status:** Proposed/Accepted/Deprecated
-
-**Context:**
-{Por que esta decisão foi necessária}
-
-**Decision:**
-{O que foi decidido}
+**⚠️ 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?
 
-**Consequences:**
-**Pros:**
-- Pro 1
+### Passo 5: Iniciar `decisions.md`
 
-**Cons:**
-- Con 1
+**Renderizar template:**
 
-**Alternatives Considered:**
-- Alternativa 1: {Por que foi rejeitada}
-
-**Date:** {YYYY-MM-DD}
+```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 5: Estimar Custos
+### Passo 6: Estimar Custos
 
 Se houver recursos Azure na spec:
 
@@ -171,24 +407,26 @@ Se houver recursos Azure na spec:
 Documente custos em `decisions.md` e atualize state:
 
 ```bash
-npx morph-spec state set {feature-name} costs.estimated {X.XX}
-npx morph-spec state set {feature-name} costs.approved {true/false}
+npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
+npx morph-spec state set $ARGUMENTS costs.approved {true/false}
 ```
 
-### Passo 6: Atualizar State
+### Passo 7: Atualizar State
 
 ```bash
-npx morph-spec state set {feature-name} phase design
-npx morph-spec state mark-output {feature-name} spec
-npx morph-spec state mark-output {feature-name} contracts
-npx morph-spec state mark-output {feature-name} decisions
+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/project/outputs/{feature}/spec.md` - Especificação técnica completa
-- `.morph/project/outputs/{feature}/contracts.cs` - Interfaces, DTOs, Enums
-- `.morph/project/outputs/{feature}/decisions.md` - ADRs (novo ou atualizado)
+- `.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
@@ -210,4 +448,28 @@ Apresente ao usuário 3 ações sugeridas:
 
 ---
 
-Continuar automaticamente para FASE 3 (Clarify) após aprovação.
+## 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.