@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, gene
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.15"
 ---
 
 # MORPH Clarify - FASE 3
@@ -35,8 +35,8 @@ Identifique ambiguidades na especificação e faça perguntas de clarificação
 | Pesquisar edge cases externos | **WebSearch** | — |
 | Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
 | Atualizar spec com clarificações | **Edit** spec.md | — |
-| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications ...` | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output ... clarifications` | — |
+| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications .morph/features/$ARGUMENTS/2-clarify/clarifications.md` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
 
 **MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
 
@@ -157,16 +157,13 @@ Documente no spec como lidar com cada edge case identificado:
 
 ### Passo 7: Atualizar State
 
-```bash
-npx morph-spec state set $ARGUMENTS phase clarify
-```
-
 ## Outputs Gerados/Atualizados
 
 - `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
   - Seção "Clarifications" com perguntas e respostas
   - Edge cases documentados
   - Requisitos mais específicos
+- `.morph/features/$ARGUMENTS/2-clarify/clarifications.md` - Novo arquivo com Q&A estruturado
 
 ## Critérios de Avanço
 

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

@@ -3,7 +3,7 @@ name: phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.15"
 ---
 
 # MORPH Codebase Analysis - Sub-fase de DESIGN

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produce
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.15"
 ---
 
 # MORPH Design - FASE 2
@@ -58,6 +58,62 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 
 ---
 
+## ✅ 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
@@ -85,77 +141,24 @@ O primeiro comando retorna `activeAgents`. O segundo retorna os agentes a dispar
 
 **⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato. Use **Task tool** para isolar esta análise do contexto principal.
 
-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`.
+> Para os prompts completos de análise de arquitetura, veja `references/architecture-analysis-guide.md`
 
-> **Paralelização:** Este Task dispatch pode iniciar SIMULTANEAMENTE com o Passo 2 (schema analysis), pois ambos são independentes. Use dois Task calls em paralelo quando o schema analysis também for necessário.
-
-#### Caminho A: `domain-architect` ativo (config sem `architecture.style: "vertical-slice"`)
-
-**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
-
-**Obtenha o taskPrompt do dispatch config** e use o Task tool:
-
-```
-[Task tool — domain-architect]
-Prompt (do dispatch config, enriquecido com conteúdo da proposta):
-
-Você é o Domain Architect da feature '$ARGUMENTS'.
-
-Proposta da feature:
-[conteúdo de .morph/features/$ARGUMENTS/0-proposal/proposal.md]
-
-Standards de referência:
-[.morph/framework/standards/architecture/ddd/complexity-levels.md]
-
-Sua tarefa — responda cada ponto com "SIM" ou "NÃO" e cite trecho da proposta:
-1. A entidade principal tem estados com transições? (ex: Draft → Confirmed → Shipped)
-2. Existem invariants de negócio que impedem operações? (ex: "só cancela se Ativo")
-3. Há cálculos derivados sobre a entidade? (ex: Total, Saldo, Desconto)
-4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores reais)
-5. A proposta declara explicitamente Bounded Context ou múltiplos domínios conflitantes?
-
-Regra de decisão:
-→ Todas "NÃO": Nível 1 (CRUD simples)
-→ Alguma de 1-4 "SIM": Nível 2 (Business Logic com AggregateRoot)
-→ 5 "SIM" OU múltiplos domínios com modelos conflitantes: Nível 3 (Bounded Context)
-
-Retorne:
-- Nível detectado (1, 2 ou 3)
-- Justificativa com citações da proposta
-- Para Nível 2+: Aggregate Blueprint inicial (entidade principal, value objects, invariants)
-```
-
-**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 (config com `architecture.style: "vertical-slice"`)
-
-**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
-**Obtenha o taskPrompt do dispatch config** e use o Task tool:
+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`.
 
-```
-[Task tool — vsa-architect]
-Prompt (do dispatch config, enriquecido com conteúdo da proposta):
+**Paralelização:** Este Task dispatch pode iniciar SIMULTANEAMENTE com o Passo 2 (schema analysis).
 
-Você é o VSA Specialist da feature '$ARGUMENTS'.
+#### Caminho A: `domain-architect` ativo (DDD)
 
-Proposta da feature:
-[conteúdo de .morph/features/$ARGUMENTS/0-proposal/proposal.md]
+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.
 
-Standards de referência:
-[.morph/framework/standards/architecture/vertical-slice/vertical-slice.md]
+**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
 
-Produza um VSA Blueprint:
-1. ENTITY FIELDS: todos os campos com tipos C# corretos (sem AggregateRoot, sem Value Objects)
-2. OPERATIONS: slices necessários (Create, GetAll, GetById, Update, Delete + operações customizadas)
-3. ROUTES: HTTP method + rota por operação (ex: POST /api/products, GET /api/products/{id:guid})
-4. ERROR TYPES: Error factory methods para {Entity}Errors
-5. VALIDATION RULES: regras FluentValidation por campo por operação
+#### Caminho B: `vsa-architect` ativo (VSA)
 
-Não use AggregateRoot, DomainEvent, CQRS formal, MediatR, Application Service layer.
-```
+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`).
 
@@ -182,49 +185,9 @@ Execute o workflow de `phase-codebase-analysis.md` para:
 
 ### 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)
+> Para estrutura detalhada de cada seção, veja `references/spec-authoring-guide.md`
 
-**SEMPRE usar Bicep para infra!**
+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!)
 
@@ -267,7 +230,7 @@ npx morph-spec template render \
   }'
 ```
 
-**Após renderizar (VSA):** Preencha os campos `TODO` no template gerado com os campos reais da entidade, validators e mapeamentos do VSA Blueprint (Passo 1.5 Caminho B).
+**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)
@@ -343,7 +306,6 @@ 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

package/framework/skills/level-1-workflows/phase-design/references/architecture-analysis-guide.md

@@ -0,0 +1,89 @@
+# Architecture Analysis Guide — Prompts de Dispatch
+
+> Prompts completos para os agentes de análise de arquitetura dispatch via Task tool.
+> Referenciado pelo Passo 1.5 de `phase-design/SKILL.md`.
+
+---
+
+## Caminho A: `domain-architect` (DDD)
+
+**Quando usar:** Config **sem** `architecture.style: "vertical-slice"`.
+
+**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
+
+**Obtenha o taskPrompt do dispatch config** (`npx morph-spec dispatch-agents $ARGUMENTS design`) e use o Task tool:
+
+```
+[Task tool — domain-architect]
+Prompt (do dispatch config, enriquecido com conteúdo da proposta):
+
+Você é o Domain Architect da feature '$ARGUMENTS'.
+
+Proposta da feature:
+[conteúdo de .morph/features/$ARGUMENTS/0-proposal/proposal.md]
+
+Standards de referência:
+[.morph/framework/standards/architecture/ddd/complexity-levels.md]
+
+Sua tarefa — responda cada ponto com "SIM" ou "NÃO" e cite trecho da proposta:
+1. A entidade principal tem estados com transições? (ex: Draft → Confirmed → Shipped)
+2. Existem invariants de negócio que impedem operações? (ex: "só cancela se Ativo")
+3. Há cálculos derivados sobre a entidade? (ex: Total, Saldo, Desconto)
+4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores reais)
+5. A proposta declara explicitamente Bounded Context ou múltiplos domínios conflitantes?
+
+Regra de decisão:
+→ Todas "NÃO": Nível 1 (CRUD simples)
+→ Alguma de 1-4 "SIM": Nível 2 (Business Logic com AggregateRoot)
+→ 5 "SIM" OU múltiplos domínios com modelos conflitantes: Nível 3 (Bounded Context)
+
+Retorne:
+- Nível detectado (1, 2 ou 3)
+- Justificativa com citações da proposta
+- Para Nível 2+: Aggregate Blueprint inicial (entidade principal, value objects, invariants)
+```
+
+**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` (VSA)
+
+**Quando usar:** Config com `architecture.style: "vertical-slice"`.
+
+**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
+
+**Obtenha o taskPrompt do dispatch config** e use o Task tool:
+
+```
+[Task tool — vsa-architect]
+Prompt (do dispatch config, enriquecido com conteúdo da proposta):
+
+Você é o VSA Specialist da feature '$ARGUMENTS'.
+
+Proposta da feature:
+[conteúdo de .morph/features/$ARGUMENTS/0-proposal/proposal.md]
+
+Standards de referência:
+[.morph/framework/standards/architecture/vertical-slice/vertical-slice.md]
+
+Produza um VSA Blueprint:
+1. ENTITY FIELDS: todos os campos com tipos C# corretos (sem AggregateRoot, sem Value Objects)
+2. OPERATIONS: slices necessários (Create, GetAll, GetById, Update, Delete + operações customizadas)
+3. ROUTES: HTTP method + rota por operação (ex: POST /api/products, GET /api/products/{id:guid})
+4. ERROR TYPES: Error factory methods para {Entity}Errors
+5. VALIDATION RULES: regras FluentValidation por campo por operação
+
+Não use AggregateRoot, DomainEvent, CQRS formal, MediatR, Application Service layer.
+```
+
+**Após receber o resultado:** Documente no spec.md (seção `## Architecture Style: Vertical Slice`).
+
+---
+
+## Nota sobre Paralelização
+
+Este Task dispatch pode iniciar **simultaneamente** com o Passo 2 (schema analysis), pois ambos são independentes. Use dois Task calls em paralelo quando o schema analysis também for necessário.

package/framework/skills/level-1-workflows/phase-design/references/spec-authoring-guide.md

@@ -0,0 +1,55 @@
+# Spec Authoring Guide — Seções do spec.md
+
+> Guia de referência para estrutura e conteúdo de cada seção do `spec.md`.
+> Referenciado pelo Passo 3 de `phase-design/SKILL.md`.
+
+---
+
+## 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!**