@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

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

@@ -0,0 +1,499 @@
+---
+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.1"
+---
+
+# 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.

package/framework/skills/level-1-workflows/morph-phase-implement/.morph/logs/activity.json

@@ -0,0 +1,38 @@
+{
+  "sessionId": "",
+  "feature": "",
+  "phase": "",
+  "hooks": [
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:06:20"
+    },
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:12:07"
+    },
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:12:15"
+    },
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:12:15"
+    },
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:12:40"
+    }
+  ],
+  "skills": []
+}