@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

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

@@ -0,0 +1,507 @@
+---
+name: morph:phase-design
+description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/Supabase/DB, validates findings with user, then routes to VSA Blueprint or DDD Architecture Blueprint based on config.architecture.style, producing spec.md, contracts.cs, schema-analysis.md, and decisions.md through a quality loop (score 0-100). Use after setup phase to create technical specifications grounded in the real database schema.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.10.0"
+---
+
+# MORPH Design - FASE 2
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Design técnico interativo: schema primeiro, blueprint validado, artefatos gerados com loop de qualidade.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] FASE 1.5 (UI/UX) concluída OU pulada
+- [ ] Proposta aprovada pelo usuário
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler proposal + UI specs | **Read** output files | — |
+| **Detectar arquitetura** | **Bash** `cat .morph/config/config.json \| grep -A3 '"architecture"'` | **Read** config.json |
+| **Schema: Supabase** | **Supabase MCP** `list_tables()`, `get_table_schema()`, `get_relationships()` | — |
+| **Schema: EF Core** | **Glob** `**/Entities/**/*.cs` + **Glob** `**/*Context.cs` → **Read** | **Grep** `DbSet<` |
+| **Schema: Next.js/TS** | **Glob** `src/**/types/**/*.ts` + **Grep** `interface\|type.*=` | — |
+| Schema: políticas RLS | **Supabase MCP** `query()` com `pg_policies` | **Read** policy files |
+| Dispatch vsa-architect | **Agent** `subagent_type=vsa-architect` + `prompt=agent.taskPrompt` | — |
+| Dispatch domain-architect | **Agent** `subagent_type=domain-architect` + `prompt=agent.taskPrompt` | — |
+| Dispatch tech leads | **Agent** para cada agente ativo do dispatch config | — |
+| Research biblioteca | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Renderizar contracts VSA | **Bash** `npx morph-spec template render dotnet-contracts-vsa ...` | — |
+| Renderizar contracts DDD | **Bash** `npx morph-spec template render dotnet-contracts-level{N} ...` | — |
+| Renderizar spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
+| Renderizar decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS <type>` | — |
+
+**Anti-padrões:**
+- ❌ Gerar contratos antes de ler o schema real — campos adivinhados corrompem todo o design
+- ❌ Apresentar Blueprint sem validar com o usuário primeiro
+- ❌ Perguntas como texto simples — sempre use `AskUserQuestion`
+- ❌ Executar schema analysis e blueprint em sequência — são independentes, paralelize
+- ❌ Ignorar `config.architecture.style` — sempre detecte antes do CHECKPOINT 2
+
+---
+
+## ✅ PRÉ-VOO
+
+**PASSO 0 (ANTES de qualquer leitura ou escrita) — Garantir fase design:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+
+**Se `"phase": "design"`** → ✅ fase correta, prossiga.
+
+**Se `"phase": "proposal"`** → execute em sequência:
+1. `npx morph-spec state mark-output $ARGUMENTS proposal`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ setup)
+3. `npx morph-spec phase advance $ARGUMENTS` (→ design)
+
+**Se `"phase": "setup"`** → execute:
+1. `npx morph-spec phase advance $ARGUMENTS` (→ design)
+
+**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+
+> **Regra:** Nunca escreva em `1-design/` enquanto a fase não for `design`. O hook bloqueará e a sequência ficará corrompida.
+
+---
+
+Leia em paralelo:
+```
+Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
+    + Read: .morph/config/config.json          ← detectar architecture.style
+    + Read: .morph/context/README.md
+```
+
+**Detectar estilo de arquitetura:**
+
+```bash
+cat .morph/config/config.json | grep -A3 '"architecture"'
+```
+
+| Valor de `config.architecture.style` | Caminho |
+|--------------------------------------|---------|
+| `"vertical-slice"` | → **VSA** (CHECKPOINT 2-VSA + contratos VSA) |
+| qualquer outro valor ou ausente | → **DDD** (CHECKPOINT 2-DDD + contratos DDD) |
+
+Se escopo ≥ 20 tasks ou refactor toca ≥ 5 arquivos de domínio → **EnterPlanMode** antes de continuar.
+
+Crie tasks de sessão:
+```
+TaskCreate: "Analisar schema"         → activeForm: "Lendo schema real"
+TaskCreate: "Validar Blueprint"       → activeForm: "Gerando blueprint"
+TaskCreate: "Gerar spec + contracts"  → activeForm: "Gerando artefatos"
+TaskCreate: "Loop de qualidade"       → activeForm: "Refinando design"
+```
+
+---
+
+## CHECKPOINT 1 — Schema Real (OBRIGATÓRIO antes de qualquer geração)
+
+> **Regra:** Nunca assuma nomes de campos. Todo DTO gerado deve ter origem rastreável no schema.
+
+### 1.1 Ler schema real
+
+Execute em paralelo conforme o stack detectado em `config.json`:
+
+**Supabase (preferencial se disponível):**
+```
+Supabase MCP: list_tables() → get_table_schema(table) para cada tabela relevante
+            + get_relationships() → políticas RLS se aplicável
+```
+
+**EF Core (.NET):**
+```
+Glob: **/Entities/**/*.cs  →  Read cada arquivo de entidade
+Glob: **/*DbContext.cs     →  Read para ver DbSet<> e relações
+Grep: "DbSet<"             →  confirmar entidades mapeadas
+```
+
+**TypeScript/Next.js:**
+```
+Glob: src/**/types/**/*.ts, src/**/models/**/*.ts
+Grep: "export interface|export type" → Read arquivos encontrados
+```
+
+### 1.2 Gerar schema-analysis.md
+
+Escreva `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` com:
+
+```markdown
+# Schema Analysis — {Feature}
+
+## Entidades Relevantes
+
+### {EntityName}
+| Campo | Tipo DB | Tipo C#/TS | Nullable | Notas |
+|-------|---------|-----------|----------|-------|
+| id    | uuid    | Guid      | No       | PK    |
+| ...   | ...     | ...       | ...      | ...   |
+
+## Relacionamentos
+- {Entity A} 1—N {Entity B} via {campo FK}
+
+## Campos JSONB / Complexos
+- {campo}: estrutura interna {chaves conhecidas}
+
+## Campos sem uso identificado
+- {campo}: presente no schema mas sem referência na proposta
+```
+
+### 1.3 Validar com usuário
+
+Use `AskUserQuestion`:
+
+```json
+{
+  "questions": [{
+    "header": "Schema OK?",
+    "question": "Encontrei estas entidades e campos no schema. Estão corretos antes de gerar os contratos?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Confirmar e continuar", "description": "Schema mapeado corretamente" },
+      { "label": "Tenho correções",       "description": "Use Other para descrever o que está errado" }
+    ]
+  }]
+}
+```
+
+- **"Confirmar"** → prosseguir para Checkpoint 2
+- **"Tenho correções" / Other** → aplicar correções no schema-analysis.md e repetir 1.3
+
+---
+
+## CHECKPOINT 2 — Blueprint de Arquitetura (OBRIGATÓRIO antes de gerar contracts)
+
+> Use o caminho correspondente ao estilo detectado no PRÉ-VOO.
+
+---
+
+### CHECKPOINT 2-VSA — Vertical Slice Architecture
+
+#### 2-VSA.1 Dispatch vsa-architect
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+Use o `taskPrompt` do agente `vsa-architect` do resultado. Chame:
+
+```
+Agent(subagent_type=vsa-architect, prompt=<taskPrompt + conteúdo de proposal.md + schema-analysis.md>)
+```
+
+O agente produz um VSA Blueprint com:
+- Entity fields (baseados no schema validado no Checkpoint 1)
+- Operations (GetAll, GetById, Create, Update, Delete + custom)
+- Routes (`GET /api/{feature}s`, `POST /api/{feature}s`, etc.)
+- Error types (`{Entity}Errors.NotFound`, `{Entity}Errors.AlreadyExists`, etc.)
+- Validation rules por campo
+
+**Paralelize** com outros agentes ativos do dispatch config.
+
+#### 2-VSA.2 Validar Blueprint com usuário
+
+Apresente o blueprint gerado de forma legível e use `AskUserQuestion`:
+
+```json
+{
+  "questions": [{
+    "header": "Blueprint OK?",
+    "question": "Planejei estes slices e operações para a feature. Confirmar antes de gerar spec e contracts?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Confirmar blueprint",  "description": "Gerar spec.md e contracts-vsa.cs com este blueprint" },
+      { "label": "Preciso ajustar",      "description": "Use Other para descrever o que mudar no blueprint" }
+    ]
+  }]
+}
+```
+
+- **"Confirmar"** → prosseguir para geração VSA
+- **"Preciso ajustar" / Other** → atualizar blueprint e repetir 2-VSA.2
+
+---
+
+### CHECKPOINT 2-DDD — Domain-Driven Design
+
+#### 2-DDD.1 Determinar Nível de Complexidade
+
+Leia a proposta e avalie com base nas 5 perguntas de detecção em `framework/standards/architecture/ddd/complexity-levels.md`:
+
+| Nível | Quando usar |
+|-------|-------------|
+| **Nível 1 (CRUD)** | Entidades simples, sem regras de negócio complexas, CRUD básico |
+| **Nível 2 (Business Logic)** | Invariantes de domínio, workflows de negócio, múltiplas entidades relacionadas |
+| **Nível 3 (Bounded Context)** | Isolamento de contexto, eventos de integração, sistemas distribuídos |
+
+> Se incerto, assuma Nível 1 e use `AskUserQuestion` para confirmar.
+
+#### 2-DDD.2 Dispatch domain-architect
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+Use o `taskPrompt` do agente `domain-architect` do resultado. Chame:
+
+```
+Agent(subagent_type=domain-architect, prompt=<taskPrompt + conteúdo de proposal.md + schema-analysis.md + nível detectado>)
+```
+
+O agente produz um Architecture Blueprint com:
+- **Nível 1:** Entidades, repositórios, services, DTOs
+- **Nível 2:** AggregateRoot, Value Objects, Domain Events, CQRS handlers
+- **Nível 3:** BC setup, Integration Events, Anti-corruption layer
+
+**Paralelize** com outros agentes ativos do dispatch config.
+
+#### 2-DDD.3 Validar Blueprint com usuário
+
+Apresente o blueprint gerado de forma legível e use `AskUserQuestion`:
+
+```json
+{
+  "questions": [{
+    "header": "Blueprint OK?",
+    "question": "Planejei esta arquitetura de domínio para a feature. Confirmar antes de gerar spec e contracts?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Confirmar blueprint",  "description": "Gerar spec.md e contracts-level{N}.cs com este blueprint" },
+      { "label": "Preciso ajustar",      "description": "Use Other para descrever o que mudar no blueprint" }
+    ]
+  }]
+}
+```
+
+- **"Confirmar"** → prosseguir para geração DDD
+- **"Preciso ajustar" / Other** → atualizar blueprint e repetir 2-DDD.3
+
+---
+
+## Geração de Artefatos
+
+Com schema validado (Checkpoint 1) e blueprint confirmado (Checkpoint 2):
+
+### Gerar spec.md
+
+> Estrutura detalhada: `references/spec-authoring-guide.md`
+
+Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:
+- Overview, Functional Requirements (FR001...) com critérios de aceitação mensuráveis
+- Non-Functional Requirements, Data Model
+- **VSA:** seção `## Architecture Style: Vertical Slice` com slices e operações
+- **DDD:** seção `## Domain Complexity` com nível (1/2/3) e justificativa
+- Infrastructure Requirements (se aplicável)
+
+### Gerar contracts.cs — VSA
+
+**Fonte obrigatória:** campos do `schema-analysis.md` + operações do VSA Blueprint.
+
+```bash
+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": "{{TODAY}}"
+  }'
+```
+
+Após renderizar, preencha os `// placeholder:` com os campos reais do schema-analysis.md.
+
+**Padrões obrigatórios (VSA):**
+- `sealed` em handlers, endpoints, validators, records
+- `Guid.CreateVersion7()` para IDs
+- `result.Match()` nos endpoints
+- `{Entity}Errors` estático compartilhado por todos os slices
+- CancellationToken em todos os métodos async
+
+### Gerar contracts.cs — DDD
+
+**Fonte obrigatória:** campos do `schema-analysis.md` + componentes do DDD Blueprint.
+
+```bash
+# Substituir {N} pelo nível detectado (1, 2 ou 3):
+npx morph-spec template render \
+  dotnet-contracts-level{N} \
+  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "NAMESPACE": "{ProjectNamespace}",
+    "DATE": "{{TODAY}}"
+  }'
+```
+
+Após renderizar, preencha os `// placeholder:` com os campos reais do schema-analysis.md.
+
+**Padrões obrigatórios (DDD):**
+- Nível 1: interfaces de repositório + service com métodos mapeados
+- Nível 2: AggregateRoot com invariantes + Value Objects imutáveis + Domain Events
+- Nível 3: adiciona Integration Events + Bounded Context boundary
+
+### Gerar decisions.md
+
+```bash
+npx morph-spec template render docs/decisions \
+  .morph/features/$ARGUMENTS/1-design/decisions.md \
+  '{"FEATURE_NAME": "$ARGUMENTS", "DATE": "{{TODAY}}", "decisions": []}'
+```
+
+ADRs obrigatórios: escolha de arquitetura (VSA vs DDD + justificativa), biblioteca UI (se UI/UX executou), integrações externas, recursos Azure com estimativa de custos.
+
+---
+
+## Sistema de Pontuação de Qualidade
+
+Após gerar os artefatos, avalie o design com o **Quality Score (0–100)**:
+
+| Dimensão | Pts | Critério de máxima pontuação |
+|----------|-----|------------------------------|
+| **Fidelidade ao schema** | 25 | Todos os campos em contracts.cs têm origem rastreável no schema-analysis.md — zero adivinhados |
+| **Cobertura funcional** | 20 | Todos os FRs da proposta estão no spec com critérios de aceitação mensuráveis |
+| **Blueprint completo** | 20 | **VSA:** todos os slices têm handler, validator (exceto GetAll), endpoint e errors \| **DDD:** todas as entidades/aggregates/services têm componentes do nível detectado |
+| **Integrações externas** | 20 | APIs/services com payload, error format e retry policy documentados |
+| **Infra / custos** | 15 | Azure resources estimados com custo, ou "N/A" explícito documentado |
+
+**Thresholds:**
+
+| Score | Ação |
+|-------|------|
+| ≥ 85 | Design satisfatório. Oferecer encerrar ou refinar opcionalmente |
+| 70–84 | Continuar. Focar nas dimensões mais fracas |
+| < 70 | Continuar. Questões técnicas abertas bloqueam implementação |
+
+---
+
+## Loop de Qualidade
+
+**Repita até: score ≥ 85 OU usuário aprova.**
+
+### A. Calcular score
+
+Pontue cada dimensão com base nos artefatos gerados. Identifique as lacunas mais impactantes.
+
+### B. Identificar questões abertas
+
+Perguntas típicas por dimensão:
+
+| Dimensão fraca | Exemplos de questões |
+|----------------|----------------------|
+| Schema fidelity | "O campo `metadata` (JSONB) tem estrutura definida? Quais chaves?" |
+| Cobertura funcional | "FR003 diz 'notificar usuário' — por email, push ou ambos?" |
+| Blueprint VSA | "O slice CreateOrder deve disparar um job de email ou é síncrono?" |
+| Blueprint DDD | "O método `Place()` do OrderAggregate deve emitir `OrderPlacedEvent`?" |
+| Integrações | "A API de pagamento usa webhook ou polling para confirmar?" |
+| Infra/custos | "Este feature precisa de storage Azure? Qual tier?" |
+
+### C. Perguntar via AskUserQuestion
+
+Máximo 3 questões técnicas por chamada. Na última chamada de cada round, inclua sempre:
+
+```json
+{
+  "header": "Encerrar?",
+  "question": "Deseja encerrar o design agora ou continuar refinando?",
+  "multiSelect": false,
+  "options": [
+    { "label": "Continuar refinando",   "description": "Claude identificou mais questões abertas" },
+    { "label": "Encerrar design",       "description": "Prosseguir para Clarify com o design atual" }
+  ]
+}
+```
+
+> Se score ≥ 85, ajuste: `"Continuar (opcional)"` com description `"Score {N}/100 — design está satisfatório"`
+
+### D. Incorporar respostas
+
+Atualize spec.md, contracts.cs e decisions.md com as respostas recebidas. Recalcule o score.
+
+### E. Condição de saída
+
+- Usuário escolheu **"Encerrar design"** → sair do loop
+- Score ≥ 85 E sem questões novas → sair do loop
+
+---
+
+## Pós-Loop: 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
+```
+
+Se houver custos Azure estimados:
+```bash
+npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
+```
+
+## PAUSA OBRIGATÓRIA
+
+```json
+{
+  "questions": [{
+    "header": "Aprovação",
+    "question": "Design gerado. Aprovar para continuar para Clarify?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Aprovar e continuar", "description": "Avançar para fase Clarify" },
+      { "label": "Tenho feedback",      "description": "Digite o que deseja mudar (Other)" }
+    ]
+  }]
+}
+```
+
+- **"Aprovar e continuar"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS design
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"Tenho feedback" / Other** → aplicar feedback e repetir PAUSA
+
+## Outputs Gerados
+
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Schema real mapeado e validado
+- `.morph/features/$ARGUMENTS/1-design/spec.md` — Especificação técnica completa
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs` — Contracts baseados no schema real (VSA ou DDD)
+- `.morph/features/$ARGUMENTS/1-design/decisions.md` — ADRs documentados
+
+## Critérios de Avanço
+
+- [x] Estilo de arquitetura detectado em `config.architecture.style`
+- [x] Schema validado pelo usuário (Checkpoint 1)
+- [x] Blueprint confirmado pelo usuário (Checkpoint 2-VSA ou 2-DDD)
+- [x] Score de qualidade ≥ 85 OU usuário encerrou
+- [x] Todos os field names em contracts.cs rastreáveis ao schema-analysis.md
+- [x] State atualizado
+- [x] Usuário aprovou na PAUSA OBRIGATÓRIA
+
+---
+
+<!-- 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` |
+| `contractsTs` | `.morph/features/{feature}/1-design/contracts.ts` |
+| `contractsVsa` | `.morph/features/{feature}/1-design/contracts-vsa.cs` |
+| `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
+<!-- /morph:outputs -->
+
+Continuar automaticamente para FASE 3 (Clarify) após aprovação.