@polymorphism-tech/morph-spec 4.11.1 → 4.13.0

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

@@ -1,13 +1,13 @@
 ---
 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.
+description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/Supabase/DB, validates findings with user, then generates VSA Blueprint based on config.architecture.style, producing spec.md, contracts.cs, schema-analysis.md, and decisions.md through a unified quality + clarification loop (score 0-100). Use after proposal 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, AskUserQuestion, Agent
-cliVersion: "4.11.1"
+cliVersion: "4.13.0"
 ---
 
-# MORPH Design — Phase 2
+# MORPH Design — Phase 3
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
 
@@ -15,9 +15,8 @@ Schema-first interactive design: read the real schema, validate with user, gener
 
 ## Prerequisites
 
-- [ ] Phase 1 (Setup) completed
-- [ ] Phase 1.5 (UI/UX) completed OR skipped
 - [ ] Proposal approved by the user
+- [ ] Phase 2 (UI/UX) completed OR skipped
 
 ## Recommended Tools
 
@@ -29,16 +28,14 @@ Schema-first interactive design: read the real schema, validate with user, gener
 |--------|------|-------------|
 | Read proposal + UI specs | **Read** output files | — |
 | **Detect architecture** | **Read** `.morph/config/config.json` → check `architecture.style` | **Bash** `grep` |
-| **Schema: Supabase** | **Supabase MCP** `list_tables()`, `get_table_schema()`, `get_relationships()` | — |
+| **Schema: Supabase** | **Bash** `npx supabase status` → `npx supabase db dump --local` / `psql <DB_URL>` | **Grep** `.from(` in code |
 | **Schema: EF Core** | **Glob** `**/Entities/**/*.cs` + **Glob** `**/*Context.cs` → **Read** | **Grep** `DbSet<` |
 | **Schema: Next.js/TS** | **Glob** `src/**/types/**/*.ts` + **Grep** `interface\|type.*=` | — |
-| Schema: RLS policies | **Supabase MCP** `query()` with `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` | — |
+| Schema: RLS policies | **Bash** `psql <DB_URL> -c "SELECT ... FROM pg_policies"` | **Read** policy files |
+| Dispatch dotnet-senior | **Agent** `subagent_type="morph-dotnet-senior"` — agent .md file provides the prompt | — |
 | Dispatch tech leads | **Agent** for each active agent from dispatch config | — |
 | Research library | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
 | Render contracts VSA | **Bash** `morph-spec template render dotnet-contracts-vsa ...` | — |
-| Render contracts DDD | **Bash** `morph-spec template render dotnet-contracts-level{N} ...` | — |
 | Render spec.md | **Bash** `morph-spec template render docs/spec ...` | — |
 | Render decisions.md | **Bash** `morph-spec template render docs/decisions ...` | — |
 | Update state | **Bash** `morph-spec state mark-output $ARGUMENTS <type>` | — |
@@ -53,6 +50,16 @@ Schema-first interactive design: read the real schema, validate with user, gener
 
 ## PRE-FLIGHT
 
+## Pre-flight — Tool Availability
+
+Check session context lines for tool readiness:
+- `docker ✓` + `supabase ✓` → Supabase CLI method for schema analysis
+- `docker ✗` or `supabase ✗` → Static code analysis fallback (Grep/Read)
+- `context7 ✓` → Use for library docs when writing spec.md
+- `context7 ✗` → WebSearch + WebFetch fallback
+
+---
+
 ## MANDATORY: Session Tasks
 
 > **BEFORE starting any design work**, analyze the workflow below and create session tasks.
@@ -75,15 +82,11 @@ Check the `"phase"` field in the output:
 
 **If `"phase": "proposal"`** → execute in sequence:
 1. `morph-spec state mark-output $ARGUMENTS proposal`
-2. `morph-spec phase advance $ARGUMENTS` (→ setup)
-3. `morph-spec phase advance $ARGUMENTS` (→ design)
-
-**If `"phase": "setup"`** → execute:
-1. `morph-spec phase advance $ARGUMENTS` (→ design)
+2. `morph-spec phase advance $ARGUMENTS` (→ design)
 
 **Any other value** → do not proceed — inconsistent state, report to user.
 
-> **Rule:** Never write to `1-design/` while the phase is not `design`. The hook will block and the sequence will be corrupted.
+> **Rule:** Never write to `2-design/` while the phase is not `design`. The hook will block and the sequence will be corrupted.
 
 ---
 
@@ -99,7 +102,7 @@ Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
 | Value of `config.architecture.style` | Path |
 |--------------------------------------|------|
 | `"vertical-slice"` | → **VSA** (CHECKPOINT 2-VSA + VSA contracts) |
-| any other value or absent | → **DDD** (CHECKPOINT 2-DDD + DDD contracts) |
+| any other value or absent | → **Standard** design flow (no architecture-specific blueprint) |
 
 If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode** before continuing.
 
@@ -113,10 +116,18 @@ If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode
 
 Execute in parallel according to the stack detected in `config.json`:
 
-**Supabase (preferred if available):**
+**Supabase (local Docker via CLI):**
+
+> **Supabase CLI:** Run `npx supabase status` to get the local DB URL (port may vary across instances).
+> Then use `npx supabase db dump --local` for full schema export, or `psql <DB_URL>` for targeted queries.
+> Always query the **local Docker instance** — never production. Cross-reference existing schema with the proposal to avoid duplicating tables or missing foreign keys to existing data.
+> If local Supabase is not running, rely on EF Core/TypeScript entity scanning as described below.
+
 ```
-Supabase MCP: list_tables() → get_table_schema(table) for each relevant table
-            + get_relationships() → RLS policies if applicable
+Bash: npx supabase status → extract DB URL
+    + npx supabase db dump --local | grep -A20 "CREATE TABLE relevant_table"
+    + psql <DB_URL> -c "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'X'"
+    + psql <DB_URL> -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"
 ```
 
 **EF Core (.NET):**
@@ -134,7 +145,7 @@ Grep: "export interface|export type" → Read found files
 
 ### 1.2 Generate schema-analysis.md
 
-Write `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` with:
+Write `.morph/features/$ARGUMENTS/2-design/schema-analysis.md` with:
 
 ```markdown
 # Schema Analysis — {Feature}
@@ -188,16 +199,16 @@ Use `AskUserQuestion`:
 
 ### CHECKPOINT 2-VSA — Vertical Slice Architecture
 
-#### 2-VSA.1 Dispatch vsa-architect
+#### 2-VSA.1 Dispatch dotnet-senior (VSA mode)
 
 ```bash
 morph-spec dispatch-agents $ARGUMENTS design
 ```
 
-Use the `taskPrompt` from the `vsa-architect` agent in the result. Call:
+Use the `recommended` field to find the dotnet-senior agent. The agent `.md` file is self-contained. Call:
 
 ```
-Agent(subagent_type=vsa-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md>)
+Agent(subagent_type="morph-dotnet-senior", prompt="Design VSA blueprint for feature {feature}. Read .morph/features/{feature}/0-proposal/proposal.md and schema-analysis.md for context.")
 ```
 
 The agent produces a VSA Blueprint with:
@@ -232,60 +243,6 @@ Present the generated blueprint in a readable format and use `AskUserQuestion`:
 
 ---
 
-### CHECKPOINT 2-DDD — Domain-Driven Design
-
-#### 2-DDD.1 Determine Complexity Level
-
-Read the proposal and evaluate using the 5 detection questions in `framework/standards/architecture/ddd/complexity-levels.md`:
-
-| Level | When to use |
-|-------|-------------|
-| **Level 1 (CRUD)** | Simple entities, no complex business rules, basic CRUD |
-| **Level 2 (Business Logic)** | Domain invariants, business workflows, multiple related entities |
-| **Level 3 (Bounded Context)** | Context isolation, integration events, distributed systems |
-
-> If uncertain, assume Level 1 and use `AskUserQuestion` to confirm.
-
-#### 2-DDD.2 Dispatch domain-architect
-
-```bash
-morph-spec dispatch-agents $ARGUMENTS design
-```
-
-Use the `taskPrompt` from the `domain-architect` agent in the result. Call:
-
-```
-Agent(subagent_type=domain-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md + detected level>)
-```
-
-The agent produces an Architecture Blueprint with:
-- **Level 1:** Entities, repositories, services, DTOs
-- **Level 2:** AggregateRoot, Value Objects, Domain Events, CQRS handlers
-- **Level 3:** BC setup, Integration Events, Anti-corruption layer
-
-**Parallelize** with other active agents from the dispatch config.
-
-#### 2-DDD.3 Validate Blueprint with user
-
-Present the generated blueprint in a readable format and use `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "header": "Blueprint OK?",
-    "question": "Planned this domain architecture for the feature. Confirm before generating spec and contracts?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Confirm blueprint",  "description": "Generate spec.md and contracts with this blueprint" },
-      { "label": "Need adjustments",   "description": "Use Other to describe what to change" }
-    ]
-  }]
-}
-```
-
-- **"Confirm"** → proceed to DDD generation
-- **"Need adjustments" / Other** → update blueprint and repeat 2-DDD.3
-
 ---
 
 ## Artifact Generation
@@ -296,11 +253,12 @@ With schema validated (Checkpoint 1) and blueprint confirmed (Checkpoint 2):
 
 > Detailed structure: `references/spec-authoring-guide.md`
 
-Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/1-design/spec.md` with:
+> **MCP:** Before writing spec.md, use **Context7 MCP** (`resolve-library-id` → `query-docs`) to fetch current API docs for libraries referenced in the proposal (e.g., FluentValidation, MediatR, TanStack Query). This ensures spec references correct method signatures and patterns. If Context7 is not available, use **WebSearch** + **WebFetch** to look up the official documentation.
+
+Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/2-design/spec.md` with:
 - Overview, Functional Requirements (FR001...) with measurable acceptance criteria
 - Non-Functional Requirements, Data Model
 - **VSA:** section `## Architecture Style: Vertical Slice` with slices and operations
-- **DDD:** section `## Domain Complexity` with level (1/2/3) and justification
 - Infrastructure Requirements (if applicable)
 
 ### Generate contracts — VSA
@@ -310,7 +268,7 @@ Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/1-d
 ```bash
 morph-spec template render \
   dotnet-contracts-vsa \
-  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  .morph/features/$ARGUMENTS/2-design/contracts.cs \
   '{
     "FEATURE_NAME": "$ARGUMENTS",
     "NAMESPACE": "{ProjectNamespace}",
@@ -328,42 +286,19 @@ After rendering, fill in the `// placeholder:` sections with real fields from sc
 - `{Entity}Errors` static shared across all slices
 - CancellationToken in all async methods
 
-### Generate contracts — DDD
-
-**Mandatory source:** fields from `schema-analysis.md` + components from the DDD Blueprint.
-
-```bash
-# Replace {N} with the detected level (1, 2, or 3):
-morph-spec template render \
-  dotnet-contracts-level{N} \
-  .morph/features/$ARGUMENTS/1-design/contracts.cs \
-  '{
-    "FEATURE_NAME": "$ARGUMENTS",
-    "NAMESPACE": "{ProjectNamespace}",
-    "DATE": "{{TODAY}}"
-  }'
-```
-
-After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
-
-**Mandatory DDD patterns:**
-- Level 1: repository interfaces + service with mapped methods
-- Level 2: AggregateRoot with invariants + immutable Value Objects + Domain Events
-- Level 3: adds Integration Events + Bounded Context boundary
-
 ### Stack adaptation for contracts
 
-For TypeScript/Next.js projects, generate `contracts.ts` instead of `contracts.cs`. Use TypeScript interfaces with the same DDD/VSA patterns adapted to the language (e.g., `readonly` fields for Value Objects, union types for status enums, typed event interfaces for Domain Events).
+For TypeScript/Next.js projects, generate `contracts.ts` instead of `contracts.cs`. Use TypeScript interfaces with the same VSA patterns adapted to the language (e.g., `readonly` fields, union types for status enums, typed event interfaces).
 
 ### Generate decisions.md
 
 ```bash
 morph-spec template render docs/decisions \
-  .morph/features/$ARGUMENTS/1-design/decisions.md \
+  .morph/features/$ARGUMENTS/2-design/decisions.md \
   '{"FEATURE_NAME": "$ARGUMENTS", "DATE": "{{TODAY}}", "decisions": []}'
 ```
 
-Mandatory ADRs: architecture choice (VSA vs DDD + justification), UI library (if UI/UX phase ran), external integrations, Azure resources with cost estimates.
+Mandatory ADRs: architecture choice (VSA + justification), UI library (if UI/UX phase ran), external integrations, Azure resources with cost estimates.
 
 ---
 
@@ -375,7 +310,7 @@ After generating artifacts, evaluate the design with the **Quality Score (0–10
 |-----------|-----|----------------------|
 | **Schema fidelity** | 25 | All fields in contracts have traceable origin in schema-analysis.md — zero guessed |
 | **Functional coverage** | 20 | All FRs from the proposal are in spec with measurable acceptance criteria |
-| **Blueprint complete** | 20 | **VSA:** all slices have handler, validator (except GetAll), endpoint and errors \| **DDD:** all entities/aggregates/services have components for the detected level |
+| **Blueprint complete** | 20 | **VSA:** all slices have handler, validator (except GetAll), endpoint and errors |
 | **External integrations** | 20 | APIs/services with payload, error format and retry policy documented |
 | **Infra / costs** | 15 | Azure resources estimated with cost, or "N/A" explicitly documented |
 
@@ -406,7 +341,6 @@ Typical questions by dimension:
 | Schema fidelity | "The `metadata` field (JSONB) — what is its structure? Which keys?" |
 | Functional coverage | "FR003 says 'notify user' — by email, push, or both?" |
 | Blueprint VSA | "Should the CreateOrder slice trigger an email job or is it synchronous?" |
-| Blueprint DDD | "Should `Place()` on OrderAggregate emit `OrderPlacedEvent`?" |
 | Integrations | "Does the payment API use webhook or polling to confirm?" |
 | Infra/costs | "Does this feature need Azure storage? Which tier?" |
 
@@ -421,7 +355,7 @@ Maximum 3 technical questions per call. In the last call of each round, always i
   "multiSelect": false,
   "options": [
     { "label": "Continue refining",   "description": "More open questions identified" },
-    { "label": "Finalize design",     "description": "Proceed to Clarify with current design" }
+    { "label": "Finalize design",     "description": "Proceed to Plan phase with current design" }
   ]
 }
 ```
@@ -459,10 +393,10 @@ morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 {
   "questions": [{
     "header": "Approval",
-    "question": "Design generated. Approve to continue to Clarify?",
+    "question": "Design generated. Approve to continue to Plan?",
     "multiSelect": false,
     "options": [
-      { "label": "Approve and continue", "description": "Advance to Clarify phase" },
+      { "label": "Approve and continue", "description": "Advance to Plan phase" },
       { "label": "I have feedback",      "description": "Describe what to change (Other)" }
     ]
   }]
@@ -478,16 +412,16 @@ morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 
 ## Generated Outputs
 
-- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Real schema mapped and validated
-- `.morph/features/$ARGUMENTS/1-design/spec.md` — Complete technical specification
-- `.morph/features/$ARGUMENTS/1-design/contracts.cs` (or `.ts` for TypeScript projects) — Contracts based on real schema (VSA or DDD)
-- `.morph/features/$ARGUMENTS/1-design/decisions.md` — Documented ADRs
+- `.morph/features/$ARGUMENTS/2-design/schema-analysis.md` — Real schema mapped and validated
+- `.morph/features/$ARGUMENTS/2-design/spec.md` — Complete technical specification
+- `.morph/features/$ARGUMENTS/2-design/contracts.cs` (or `.ts` for TypeScript projects) — Contracts based on real schema (VSA)
+- `.morph/features/$ARGUMENTS/2-design/decisions.md` — Documented ADRs
 
 ## Advancement Criteria
 
 - [x] Architecture style detected from `config.architecture.style`
 - [x] Schema validated by user (Checkpoint 1)
-- [x] Blueprint confirmed by user (Checkpoint 2-VSA or 2-DDD)
+- [x] Blueprint confirmed by user (Checkpoint 2-VSA)
 - [x] Quality score ≥ 85 OR user finalized
 - [x] All field names in contracts traceable to schema-analysis.md
 - [x] State updated
@@ -498,12 +432,12 @@ morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 <!-- 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` |
+| `schemaAnalysis` | `.morph/features/{feature}/2-design/schema-analysis.md` |
+| `spec` | `.morph/features/{feature}/2-design/spec.md` |
+| `contracts` | `.morph/features/{feature}/2-design/contracts.cs` |
+| `contractsTs` | `.morph/features/{feature}/2-design/contracts.ts` |
+| `contractsVsa` | `.morph/features/{feature}/2-design/contracts-vsa.cs` |
+| `decisions` | `.morph/features/{feature}/2-design/decisions.md` |
 <!-- /morph-outputs -->
 
-Continue automatically to Phase 3 (Clarify) after approval.
+Continue automatically to Plan phase after approval.

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

@@ -5,62 +5,17 @@
 
 ---
 
-## Caminho A: `domain-architect` (DDD)
+## Caminho: `dotnet-senior` (VSA)
 
-**Quando usar:** Config **sem** `architecture.style: "vertical-slice"`.
-
-**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
-
-**Obtenha o taskPrompt do dispatch config** (`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"`.
+**Quando usar:** Default architecture style (Vertical Slice Architecture).
 
 **Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
 
-**Obtenha o taskPrompt do dispatch config** e use o Task tool:
+**Use o Agent tool com o subagentType do dispatch recommendation:**
 
 ```
-[Task tool — vsa-architect]
-Prompt (do dispatch config, enriquecido com conteúdo da proposta):
+Agent(subagent_type="morph-dotnet-senior", prompt="...")
+Prompt (enriquecido com conteúdo da proposta):
 
 Você é o VSA Specialist da feature '$ARGUMENTS'.
 

package/framework/skills/level-1-workflows/morph-phase-design/references/spec-example.md

@@ -10,7 +10,7 @@
 | **Stack** | blazor-azure |
 | **Complexity** | Medium |
 | **Estimated Cost** | ~$5.50/month |
-| **Agents** | Core: All / Specialists: azure-architect, dotnet-senior, blazor-builder |
+| **Agents** | Core: All / Specialists: dotnet-senior, nextjs-expert, infra-architect |
 
 ---