@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

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

@@ -1,499 +1,515 @@
----
-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, AskUserQuestion, Agent
-cliVersion: "4.10.6"
----
-
-# MORPH Design — Phase 2
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Schema-first interactive design: read the real schema, validate with user, generate blueprint, produce artifacts through a quality loop.
-
-## Prerequisites
-
-- [ ] Phase 1 (Setup) completed
-- [ ] Phase 1.5 (UI/UX) completed OR skipped
-- [ ] Proposal approved by the user
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
-> **Ref:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
-> **Ref:** `references/spec-authoring-guide.md` — section structure for spec.md.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| 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: 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` | — |
-| Dispatch tech leads | **Agent** for each active agent from dispatch config | — |
-| Research library | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Render contracts VSA | **Bash** `npx morph-spec template render dotnet-contracts-vsa ...` | — |
-| Render contracts DDD | **Bash** `npx morph-spec template render dotnet-contracts-level{N} ...` | — |
-| Render spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
-| Render decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
-| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS <type>` | — |
-
-**Anti-patterns:**
-- Do not generate contracts before reading the real schema — guessed field names corrupt the entire design
-- Do not present a Blueprint without validating with the user first
-- Do not ask questions as plain text — always use `AskUserQuestion`
-- Do not ignore `config.architecture.style` — always detect it before CHECKPOINT 2
-
----
-
-## PRE-FLIGHT
-
-**STEP 0 (BEFORE any reads or writes) — Ensure phase is design:**
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "design"`** → phase is correct, proceed.
-
-**If `"phase": "proposal"`** → execute in sequence:
-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)
-
-**If `"phase": "setup"`** → execute:
-1. `npx 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.
-
----
-
-Read in parallel:
-```
-Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
-    + Read: .morph/config/config.json          ← detect architecture.style
-    + Read: .morph/context/README.md
-```
-
-**Detect architecture style:**
-
-| 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) |
-
-If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode** before continuing.
-
----
-
-## CHECKPOINT 1 — Real Schema (MANDATORY before any generation)
-
-> **Rule:** Never assume field names. Every generated DTO must have a traceable origin in the schema.
-
-### 1.1 Read real schema
-
-Execute in parallel according to the stack detected in `config.json`:
-
-**Supabase (preferred if available):**
-```
-Supabase MCP: list_tables() → get_table_schema(table) for each relevant table
-            + get_relationships() → RLS policies if applicable
-```
-
-**EF Core (.NET):**
-```
-Glob: **/Entities/**/*.cs  →  Read each entity file
-Glob: **/*DbContext.cs     →  Read to see DbSet<> and relations
-Grep: "DbSet<"             →  confirm mapped entities
-```
-
-**TypeScript/Next.js:**
-```
-Glob: src/**/types/**/*.ts, src/**/models/**/*.ts
-Grep: "export interface|export type" → Read found files
-```
-
-### 1.2 Generate schema-analysis.md
-
-Write `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` with:
-
-```markdown
-# Schema Analysis — {Feature}
-
-## Relevant Entities
-
-### {EntityName}
-| Field | DB Type | C#/TS Type | Nullable | Notes |
-|-------|---------|-----------|----------|-------|
-| id    | uuid    | Guid      | No       | PK    |
-| ...   | ...     | ...       | ...      | ...   |
-
-## Relationships
-- {Entity A} 1—N {Entity B} via {FK field}
-
-## JSONB / Complex Fields
-- {field}: internal structure {known keys}
-
-## Fields Not Referenced in Proposal
-- {field}: present in schema but no reference in the proposal
-```
-
-### 1.3 Validate with user
-
-Use `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "header": "Schema OK?",
-    "question": "Found these entities and fields in the schema. Are they correct before generating contracts?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Confirm and continue", "description": "Schema mapped correctly" },
-      { "label": "I have corrections",   "description": "Use Other to describe what's wrong" }
-    ]
-  }]
-}
-```
-
-- **"Confirm"** → proceed to Checkpoint 2
-- **"I have corrections" / Other** → apply corrections to schema-analysis.md and repeat 1.3
-
----
-
-## CHECKPOINT 2 — Architecture Blueprint (MANDATORY before generating contracts)
-
-> Use the path corresponding to the style detected in PRE-FLIGHT.
-
----
-
-### CHECKPOINT 2-VSA — Vertical Slice Architecture
-
-#### 2-VSA.1 Dispatch vsa-architect
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS design
-```
-
-Use the `taskPrompt` from the `vsa-architect` agent in the result. Call:
-
-```
-Agent(subagent_type=vsa-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md>)
-```
-
-The agent produces a VSA Blueprint with:
-- Entity fields (based on the schema validated in 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 per field
-
-**Parallelize** with other active agents from the dispatch config.
-
-#### 2-VSA.2 Validate Blueprint with user
-
-Present the generated blueprint in a readable format and use `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "header": "Blueprint OK?",
-    "question": "Planned these slices and operations 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 VSA generation
-- **"Need adjustments" / Other** → update blueprint and repeat 2-VSA.2
-
----
-
-### 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
-npx 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
-
-With schema validated (Checkpoint 1) and blueprint confirmed (Checkpoint 2):
-
-### Generate spec.md
-
-> Detailed structure: `references/spec-authoring-guide.md`
-
-Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/1-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
-
-**Mandatory source:** fields from `schema-analysis.md` + operations from the 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}}"
-  }'
-```
-
-After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
-
-**Mandatory VSA patterns:**
-- `sealed` on handlers, endpoints, validators, records
-- `Guid.CreateVersion7()` for IDs
-- `result.Match()` in endpoints
-- `{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):
-npx 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).
-
-### Generate decisions.md
-
-```bash
-npx morph-spec template render docs/decisions \
-  .morph/features/$ARGUMENTS/1-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.
-
----
-
-## Quality Scoring System
-
-After generating artifacts, evaluate the design with the **Quality Score (0–100)**:
-
-| Dimension | Pts | Maximum score criteria |
-|-----------|-----|----------------------|
-| **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 |
-| **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 |
-
-**Thresholds:**
-
-| Score | Action |
-|-------|--------|
-| ≥ 85 | Design satisfactory. Offer to close or optionally refine |
-| 70–84 | Continue. Focus on the weakest dimensions |
-| < 70 | Continue. Open technical questions block implementation |
-
----
-
-## Quality Loop
-
-**Repeat until: score ≥ 85 OR user approves.**
-
-### A. Calculate score
-
-Score each dimension based on the generated artifacts. Identify the most impactful gaps.
-
-### B. Identify open questions
-
-Typical questions by dimension:
-
-| Weak dimension | Example questions |
-|----------------|-------------------|
-| 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?" |
-
-### C. Ask via AskUserQuestion
-
-Maximum 3 technical questions per call. In the last call of each round, always include:
-
-```json
-{
-  "header": "Continue?",
-  "question": "Continue refining or finalize the design?",
-  "multiSelect": false,
-  "options": [
-    { "label": "Continue refining",   "description": "More open questions identified" },
-    { "label": "Finalize design",     "description": "Proceed to Clarify with current design" }
-  ]
-}
-```
-
-> If score ≥ 85, adjust: `"Continue (optional)"` with description `"Score {N}/100 — design is satisfactory"`
-
-### D. Incorporate answers
-
-Update spec.md, contracts, and decisions.md with the answers received. Recalculate the score.
-
-### E. Exit condition
-
-- User chose **"Finalize design"** → exit loop
-- Score ≥ 85 AND no new questions → exit loop
-
----
-
-## Post-Loop: Update 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
-```
-
-If Azure costs were estimated:
-```bash
-npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
-```
-
-## MANDATORY PAUSE
-
-```json
-{
-  "questions": [{
-    "header": "Approval",
-    "question": "Design generated. Approve to continue to Clarify?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Approve and continue", "description": "Advance to Clarify phase" },
-      { "label": "I have feedback",      "description": "Describe what to change (Other)" }
-    ]
-  }]
-}
-```
-
-- **"Approve and continue"** →
-  ```bash
-  npx morph-spec approve $ARGUMENTS design
-  npx morph-spec phase advance $ARGUMENTS
-  ```
-- **"I have feedback" / Other** → apply feedback and repeat PAUSE
-
-## 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
-
-## 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] Quality score ≥ 85 OR user finalized
-- [x] All field names in contracts traceable to schema-analysis.md
-- [x] State updated
-- [x] User approved at MANDATORY PAUSE
-
----
-
-<!-- morph-outputs:design -->
-| Output | Path |
-|--------|------|
-| `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 -->
-
-Continue automatically to Phase 3 (Clarify) after approval.
+---
+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, AskUserQuestion, Agent
+cliVersion: "4.10.8"
+---
+
+# MORPH Design — Phase 2
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Schema-first interactive design: read the real schema, validate with user, generate blueprint, produce artifacts through a quality loop.
+
+## Prerequisites
+
+- [ ] Phase 1 (Setup) completed
+- [ ] Phase 1.5 (UI/UX) completed OR skipped
+- [ ] Proposal approved by the user
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
+> **Ref:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+> **Ref:** `references/spec-authoring-guide.md` — section structure for spec.md.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| 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: 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` | — |
+| Dispatch tech leads | **Agent** for each active agent from dispatch config | — |
+| Research library | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Render contracts VSA | **Bash** `npx morph-spec template render dotnet-contracts-vsa ...` | — |
+| Render contracts DDD | **Bash** `npx morph-spec template render dotnet-contracts-level{N} ...` | — |
+| Render spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
+| Render decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
+| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS <type>` | — |
+
+**Anti-patterns:**
+- Do not generate contracts before reading the real schema — guessed field names corrupt the entire design
+- Do not present a Blueprint without validating with the user first
+- Do not ask questions as plain text — always use `AskUserQuestion`
+- Do not ignore `config.architecture.style` — always detect it before CHECKPOINT 2
+
+---
+
+## PRE-FLIGHT
+
+### Create session tasks for visibility
+
+```
+TaskCreate: "Pre-flight validation"       → activeForm: "Validating pre-flight"
+TaskCreate: "Schema analysis"             → activeForm: "Analyzing schema"
+TaskCreate: "Architecture blueprint"      → activeForm: "Designing architecture"
+TaskCreate: "Generate spec.md"            → activeForm: "Writing spec"
+TaskCreate: "Generate contracts"          → activeForm: "Writing contracts"
+TaskCreate: "Generate decisions.md"       → activeForm: "Documenting decisions"
+TaskCreate: "Design approval"             → activeForm: "Awaiting design approval"
+```
+
+Update each to `in_progress` before starting and `completed` after finishing.
+
+---
+
+**STEP 0 (BEFORE any reads or writes) — Ensure phase is design:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field in the output:
+
+**If `"phase": "design"`** → phase is correct, proceed.
+
+**If `"phase": "proposal"`** → execute in sequence:
+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)
+
+**If `"phase": "setup"`** → execute:
+1. `npx 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.
+
+---
+
+Read in parallel:
+```
+Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
+    + Read: .morph/config/config.json          ← detect architecture.style
+    + Read: .morph/context/README.md
+```
+
+**Detect architecture style:**
+
+| 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) |
+
+If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode** before continuing.
+
+---
+
+## CHECKPOINT 1 — Real Schema (MANDATORY before any generation)
+
+> **Rule:** Never assume field names. Every generated DTO must have a traceable origin in the schema.
+
+### 1.1 Read real schema
+
+Execute in parallel according to the stack detected in `config.json`:
+
+**Supabase (preferred if available):**
+```
+Supabase MCP: list_tables() → get_table_schema(table) for each relevant table
+            + get_relationships() → RLS policies if applicable
+```
+
+**EF Core (.NET):**
+```
+Glob: **/Entities/**/*.cs  →  Read each entity file
+Glob: **/*DbContext.cs     →  Read to see DbSet<> and relations
+Grep: "DbSet<"             →  confirm mapped entities
+```
+
+**TypeScript/Next.js:**
+```
+Glob: src/**/types/**/*.ts, src/**/models/**/*.ts
+Grep: "export interface|export type" → Read found files
+```
+
+### 1.2 Generate schema-analysis.md
+
+Write `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` with:
+
+```markdown
+# Schema Analysis — {Feature}
+
+## Relevant Entities
+
+### {EntityName}
+| Field | DB Type | C#/TS Type | Nullable | Notes |
+|-------|---------|-----------|----------|-------|
+| id    | uuid    | Guid      | No       | PK    |
+| ...   | ...     | ...       | ...      | ...   |
+
+## Relationships
+- {Entity A} 1—N {Entity B} via {FK field}
+
+## JSONB / Complex Fields
+- {field}: internal structure {known keys}
+
+## Fields Not Referenced in Proposal
+- {field}: present in schema but no reference in the proposal
+```
+
+### 1.3 Validate with user
+
+Use `AskUserQuestion`:
+
+```json
+{
+  "questions": [{
+    "header": "Schema OK?",
+    "question": "Found these entities and fields in the schema. Are they correct before generating contracts?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Confirm and continue", "description": "Schema mapped correctly" },
+      { "label": "I have corrections",   "description": "Use Other to describe what's wrong" }
+    ]
+  }]
+}
+```
+
+- **"Confirm"** → proceed to Checkpoint 2
+- **"I have corrections" / Other** → apply corrections to schema-analysis.md and repeat 1.3
+
+---
+
+## CHECKPOINT 2 — Architecture Blueprint (MANDATORY before generating contracts)
+
+> Use the path corresponding to the style detected in PRE-FLIGHT.
+
+---
+
+### CHECKPOINT 2-VSA — Vertical Slice Architecture
+
+#### 2-VSA.1 Dispatch vsa-architect
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+Use the `taskPrompt` from the `vsa-architect` agent in the result. Call:
+
+```
+Agent(subagent_type=vsa-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md>)
+```
+
+The agent produces a VSA Blueprint with:
+- Entity fields (based on the schema validated in 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 per field
+
+**Parallelize** with other active agents from the dispatch config.
+
+#### 2-VSA.2 Validate Blueprint with user
+
+Present the generated blueprint in a readable format and use `AskUserQuestion`:
+
+```json
+{
+  "questions": [{
+    "header": "Blueprint OK?",
+    "question": "Planned these slices and operations 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 VSA generation
+- **"Need adjustments" / Other** → update blueprint and repeat 2-VSA.2
+
+---
+
+### 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
+npx 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
+
+With schema validated (Checkpoint 1) and blueprint confirmed (Checkpoint 2):
+
+### Generate spec.md
+
+> Detailed structure: `references/spec-authoring-guide.md`
+
+Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/1-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
+
+**Mandatory source:** fields from `schema-analysis.md` + operations from the 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}}"
+  }'
+```
+
+After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
+
+**Mandatory VSA patterns:**
+- `sealed` on handlers, endpoints, validators, records
+- `Guid.CreateVersion7()` for IDs
+- `result.Match()` in endpoints
+- `{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):
+npx 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).
+
+### Generate decisions.md
+
+```bash
+npx morph-spec template render docs/decisions \
+  .morph/features/$ARGUMENTS/1-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.
+
+---
+
+## Quality Scoring System
+
+After generating artifacts, evaluate the design with the **Quality Score (0–100)**:
+
+| Dimension | Pts | Maximum score criteria |
+|-----------|-----|----------------------|
+| **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 |
+| **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 |
+
+**Thresholds:**
+
+| Score | Action |
+|-------|--------|
+| ≥ 85 | Design satisfactory. Offer to close or optionally refine |
+| 70–84 | Continue. Focus on the weakest dimensions |
+| < 70 | Continue. Open technical questions block implementation |
+
+---
+
+## Quality Loop
+
+**Repeat until: score ≥ 85 OR user approves.**
+
+### A. Calculate score
+
+Score each dimension based on the generated artifacts. Identify the most impactful gaps.
+
+### B. Identify open questions
+
+Typical questions by dimension:
+
+| Weak dimension | Example questions |
+|----------------|-------------------|
+| 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?" |
+
+### C. Ask via AskUserQuestion
+
+Maximum 3 technical questions per call. In the last call of each round, always include:
+
+```json
+{
+  "header": "Continue?",
+  "question": "Continue refining or finalize the design?",
+  "multiSelect": false,
+  "options": [
+    { "label": "Continue refining",   "description": "More open questions identified" },
+    { "label": "Finalize design",     "description": "Proceed to Clarify with current design" }
+  ]
+}
+```
+
+> If score ≥ 85, adjust: `"Continue (optional)"` with description `"Score {N}/100 — design is satisfactory"`
+
+### D. Incorporate answers
+
+Update spec.md, contracts, and decisions.md with the answers received. Recalculate the score.
+
+### E. Exit condition
+
+- User chose **"Finalize design"** → exit loop
+- Score ≥ 85 AND no new questions → exit loop
+
+---
+
+## Post-Loop: Update 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
+```
+
+If Azure costs were estimated:
+```bash
+npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
+```
+
+## MANDATORY PAUSE
+
+```json
+{
+  "questions": [{
+    "header": "Approval",
+    "question": "Design generated. Approve to continue to Clarify?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Approve and continue", "description": "Advance to Clarify phase" },
+      { "label": "I have feedback",      "description": "Describe what to change (Other)" }
+    ]
+  }]
+}
+```
+
+- **"Approve and continue"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS design
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"I have feedback" / Other** → apply feedback and repeat PAUSE
+
+## 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
+
+## 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] Quality score ≥ 85 OR user finalized
+- [x] All field names in contracts traceable to schema-analysis.md
+- [x] State updated
+- [x] User approved at MANDATORY PAUSE
+
+---
+
+<!-- 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 -->
+
+Continue automatically to Phase 3 (Clarify) after approval.