@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

package/framework/skills/level-0-meta/morph-tool-usage-guide/references/tools-per-phase.md

@@ -28,31 +28,9 @@
 
 ---
 
-## Phase 1 — Setup
-
-**Goal:** Load context, detect stack, activate agents
-
-| Action | Tool | Why |
-|--------|------|-----|
-| Verify feature state | **Bash** `morph-spec state get {feature}` | CLI command |
-| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `morph-spec state add-agent {f} {id}` per match | Keyword matching is fast inline |
-| Read project context | **Read** `.morph/context/README.md` | Single file |
-| Read config | **Read** `.morph/config.json` | Single file |
-| Scan project structure | **Glob** `src/**/*.{ts,tsx,cs}` | Understand codebase layout |
-| Get repo metadata | **GitHub MCP** `get_repo()` | Structured repo info (if MCP available) |
-| Get dispatch config for next phases | **Bash** `morph-spec dispatch-agents {feature} design` | Shows which agents will be dispatched in design phase |
-| Update state | **Bash** `morph-spec state set ...` | CLI command |
-
-**MCPs used:** GitHub (optional — for repo metadata).
-
-**Anti-patterns:**
-- ❌ Calling `detect-agents` CLI (it doesn't exist — read `.morph/framework/agents.json` directly)
-- ❌ Task agent to detect project stack inline (keyword matching is fast enough directly)
-- ❌ WebSearch for project info (it's local, use Read/Glob)
-
 ---
 
-## Phase 1.5 — UI/UX Design
+## Phase 2 — UI/UX Design
 
 **Goal:** Create UI mockups, design system, component specs, user flows
 
@@ -80,7 +58,7 @@
 
 ---
 
-## Phase 2 — Design (Technical Spec)
+## Phase 3 — Design (Technical Spec)
 
 **Goal:** Analyze schema, create spec.md, contracts-level{N}.cs, decisions.md
 
@@ -88,11 +66,11 @@
 |--------|------|-----|
 | Read proposal + UI specs | **Read** output files | Single known files |
 | **Get dispatch config** | **Bash** `morph-spec dispatch-agents {feature} design` | Which agents to spawn + their task prompts |
-| **Dispatch domain-architect** (parallel) | **Task** subagent with prompt from dispatch config | Analyze DDD complexity independently |
+| **Dispatch architecture analyst** (parallel) | **Task** subagent with prompt from dispatch config | Analyze architecture complexity independently |
 | **Dispatch tech leads** (parallel) | **Task** subagents (dotnet-senior, nextjs-expert, etc.) | Validate architecture independently |
-| Get database schema | **Supabase MCP** `list_tables()`, `get_table_schema()` | **PREFERRED** — real schema data |
-| Get table relationships | **Supabase MCP** `get_relationships()` | Real FK/constraint data |
-| Get RLS policies | **Supabase MCP** `query()` with pg_policies | Security analysis |
+| Get database schema | **Bash** `npx supabase db dump --local` or `psql <DB_URL>` | **PREFERRED** — real local schema |
+| Get table relationships | **Bash** `psql <DB_URL>` FK queries | Real FK/constraint data |
+| Get RLS policies | **Bash** `psql <DB_URL>` pg_policies query | Security analysis |
 | **Fallback:** Find query files | **Grep** `\.from\(` or `\.select\(` in `*.ts,*.tsx,*.js,*.cs` | When no DB MCP available |
 | **Fallback:** Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | When no DB MCP available |
 | **Fallback:** Read query/type files | **Read** each matched file | Extract field names manually |
@@ -105,45 +83,22 @@
 | Create schema-analysis.md | **Write** to output directory | Document findings |
 | Update state | **Bash** `morph-spec state mark-output {feature} schemaAnalysis && morph-spec state mark-output {feature} spec && morph-spec state mark-output {feature} contracts && morph-spec state mark-output {feature} decisions` | CLI command |
 
-**MCPs used:** Supabase (schema analysis), Context7 (library research), GitHub (code search).
+**Tools used:** Supabase CLI / psql (schema analysis — local Docker), Context7 (library research), GitHub (code search).
 
-**Parallel dispatch opportunity:** Domain complexity analysis (domain-architect) and schema analysis (phase-codebase-analysis) are **independent** — run them as parallel Task subagents to cut design phase time.
+**Parallel dispatch opportunity:** Architecture complexity analysis and schema analysis (phase-codebase-analysis) are **independent** — run them as parallel Task subagents to cut design phase time.
 
 **Anti-patterns:**
 - ❌ Guessing field names without checking schema (use MCP or Grep first!)
 - ❌ Task agent to read a single spec file (use Read directly)
-- ❌ WebSearch for database schema (use Supabase MCP or code analysis)
+- ❌ WebSearch for database schema (use Supabase CLI/psql or code analysis)
 - ❌ Manually writing contracts-level{N}.cs from scratch (use template render)
 - ❌ Running domain analysis and schema analysis sequentially (they're independent — run in parallel)
 
 ---
 
-## Phase 3 — Clarify
-
-**Goal:** Identify ambiguities, ask clarification questions, update spec
-
-| Action | Tool | Why |
-|--------|------|-----|
-| Read spec.md in detail | **Read** spec.md | Full content analysis |
-| Read contracts.cs | **Read** contracts.cs | Check contract consistency |
-| Read schema-analysis.md | **Read** schema-analysis.md | Cross-reference with spec |
-| Verify library capabilities | **Context7 MCP** `query_docs()` | Confirm feasibility of spec requirements |
-| Check known issues/limitations | **GitHub MCP** `search_issues()` | Library bugs affecting design |
-| Research edge case behavior | **WebSearch** | External knowledge for edge cases |
-| Update spec with clarifications | **Edit** spec.md | Preserve existing content, add sections |
-| Create clarifications.md | **Bash** `morph-spec template render docs/clarifications ...` | Use template |
-| Update state | **Bash** `morph-spec state mark-output {feature} clarifications` | CLI command |
-
-**MCPs used:** Context7 (validate feasibility), GitHub (known issues).
-
-**Anti-patterns:**
-- ❌ Task agent to read spec (just Read it directly)
-- ❌ Rewriting spec from scratch (use Edit to update sections)
-- ❌ Skipping schema-analysis.md cross-reference (critical for accuracy)
-
 ---
 
-## Phase 4 — Tasks
+## Phase 6 — Tasks
 
 **Goal:** Break spec into tasks, define dependencies, set checkpoints
 
@@ -171,7 +126,7 @@
 
 ---
 
-## Phase 5 — Implement
+## Phase 7 — Implement
 
 **Goal:** Implement tasks, checkpoint every 3, create recap
 
@@ -183,12 +138,13 @@
 | Create new files | **Write** new source files | New entities, services, pages |
 | Modify existing files | **Edit** existing source files | Add features to existing code |
 | Look up API during coding | **Context7 MCP** `query_docs()` | Accurate library usage |
-| Run database migrations | **Supabase MCP** `query()` | DDL statements directly |
+| Run database migrations | **Bash** `npx supabase migration up --local` | DDL via psql |
 | **Fallback:** Run migrations | **Bash** `npx supabase migration ...` or `dotnet ef ...` | CLI tools |
 | Build project | **Bash** `dotnet build` or `npm run build` | Verify compilation |
 | Run tests | **Bash** `dotnet test` or `npm test` | Verify implementation |
 | Checkpoint validation | **Bash** `morph-spec checkpoint ...` | Every 3 tasks |
-| Create RLS policies | **Supabase MCP** `query()` | Security policies |
+| Create RLS policies | **Bash** write SQL migration + `npx supabase migration up --local` | Security policies |
+| Manage containers | **Bash** `docker ps`, `docker logs`, `docker compose` | Container health + debugging |
 | Create infrastructure | **Bash** `az bicep ...` or Bicep files via Write | IaC |
 | Create PR | **GitHub MCP** `create_pull_request()` or **Bash** `gh pr create` | Ship code |
 | Mark task done | **Bash** `morph-spec task done T001` | State tracking |
@@ -197,7 +153,7 @@
 | Screenshot para recap.md | **Playwright MCP** `browser_take_screenshot()` | Manual screenshot |
 | Mark recap output | **Bash** `morph-spec state mark-output {feature} recap` | CLI command |
 
-**MCPs used:** Supabase (migrations, RLS), Context7 (API lookup), GitHub (PRs), Playwright (smoke test, verification).
+**Tools used:** Supabase CLI (migrations, RLS — local Docker), Context7 (API lookup), GitHub (PRs), Playwright (smoke test, verification).
 
 **Parallel dispatch threshold:**
 - `tasks.total ≥ 6` AND feature spans 2+ domains (e.g. `dotnet-senior` + `nextjs-expert`) → dispatch parallel implementers

package/framework/skills/level-0-meta/morph-verification-before-completion/SKILL.md

@@ -30,16 +30,10 @@ allowed-tools: Read, Bash, Glob, Grep
 - [ ] `morph-spec state get {feature}` shows `phase: proposal`
 - [ ] `morph-spec state mark-output {feature} proposal` was called
 
-### Phase 1 — Setup
+### Phase 1 — UI/UX (if applicable)
 
-- [ ] `morph-spec state get {feature}` shows `activeAgents` populated
-- [ ] Stack and architecture confirmed in context
-- [ ] State updated to `phase: setup`
-
-### Phase 1.5 — UI/UX (if applicable)
-
-- [ ] `ui-design-system.md` exists with color tokens, typography, spacing
-- [ ] `ui-mockups.md` exists with wireframes/ASCII mockups
+- [ ] `design-system.md` exists with color tokens, typography, spacing
+- [ ] `mockups.md` exists with wireframes/ASCII mockups
 - [ ] `morph-spec validate-feature {feature} --phase uiux` passes
 
 ### Phase 2 — Design
@@ -47,16 +41,10 @@ allowed-tools: Read, Bash, Glob, Grep
 - [ ] `spec.md` contains: Overview, Functional Requirements, Technical Architecture, Data Model
 - [ ] `contracts.cs` exists with DTOs matching `schema-analysis.md`
 - [ ] `decisions.md` contains at least 1 ADR
+- [ ] Quality + satisfaction score ≥ 85 (or user finalized)
 - [ ] `morph-spec validate-feature {feature} --phase design` passes
 
-### Phase 3 — Clarify
-
-- [ ] All clarification questions answered by user
-- [ ] `spec.md` updated with Clarifications section
-- [ ] `clarifications.md` exists in `1-design/`
-- [ ] No unresolved ambiguities in spec
-
-### Phase 4 — Plan
+### Phase 3 — Plan
 
 - [ ] `plan.md` exists in `.morph/features/{feature}/3-plan/`
 - [ ] Plan contains: Goal, Architecture, Execution Strategy, Task Groups
@@ -65,14 +53,14 @@ allowed-tools: Read, Bash, Glob, Grep
 - [ ] `morph-spec state mark-output {feature} plan` was called
 - [ ] User approved plan via `morph-spec approve {feature} plan`
 
-### Phase 5 — Tasks
+### Phase 6 — Tasks
 
 - [ ] `tasks.md` exists
 - [ ] All tasks have: ID, title, description, dependencies
 - [ ] Checkpoints defined (every 3 tasks)
 - [ ] `morph-spec state set {feature} tasks.total N` called
 
-### Phase 6 — Implement
+### Phase 7 — Implement
 
 - [ ] All tasks marked as completed
 - [ ] Build succeeds (`npm run build` or `dotnet build`)

package/framework/skills/level-0-meta/morph-verification-before-completion/scripts/check-phase-outputs.mjs

@@ -23,16 +23,16 @@ const PHASE_OUTPUTS = {
     { file: '0-proposal/proposal.md', required: true },
   ],
   design: [
-    { file: '1-design/spec.md', required: true },
-    { file: '1-design/contracts.cs', required: true },
-    { file: '1-design/decisions.md', required: true },
-    { file: '1-design/schema-analysis.md', required: false },
+    { file: '2-design/spec.md', required: true },
+    { file: '2-design/contracts.cs', required: true },
+    { file: '2-design/decisions.md', required: true },
+    { file: '2-design/schema-analysis.md', required: false },
   ],
   uiux: [
-    { file: '2-ui/design-system.md', required: true },
-    { file: '2-ui/mockups.md', required: true },
-    { file: '2-ui/components.md', required: true },
-    { file: '2-ui/flows.md', required: false },
+    { file: '1-ui/design-system.md', required: true },
+    { file: '1-ui/mockups.md', required: true },
+    { file: '1-ui/components.md', required: true },
+    { file: '1-ui/flows.md', required: false },
   ],
   tasks: [
     { file: '4-tasks/tasks.md', required: true },

package/framework/skills/level-1-workflows/README.md

@@ -4,4 +4,4 @@ Phase orchestration and workflow management.
 
 **Purpose:** Skills that implement MORPH workflow phases (FASE 0-6).
 
-**Examples:** phase-setup, phase-design, phase-uiux
+**Examples:** phase-design, phase-uiux, phase-plan, phase-implement

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

@@ -3,7 +3,7 @@ name: morph-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, AskUserQuestion
-cliVersion: "4.12.0"
+cliVersion: "4.13.0"
 ---
 
 # MORPH Codebase Analysis - Design Sub-phase
@@ -15,7 +15,7 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
 
 ## Prerequisites
 
-- [ ] Phase 1 (Setup) completed
+- [ ] Proposal phase completed
 - [ ] Feature has approved `proposal.md`
 - [ ] Project context loaded (stack, agents)
 
@@ -26,17 +26,17 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
 
 | Action | Tool | Alternative |
 |------|------------|-------------|
-| List database tables | **Supabase MCP** `list_tables()` | **Grep** `.from(` in code |
-| Get table schema | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
-| Get FK relationships | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
-| Get RLS policies | **Supabase MCP** `query()` | **Read** policy files |
+| List database tables | **Bash** `npx supabase db dump --local` or `psql <DB_URL>` | **Grep** `.from(` in code |
+| Get table schema | **Bash** `psql <DB_URL> -c "SELECT ... FROM information_schema.columns"` | **Read** type definitions |
+| Get FK relationships | **Bash** `psql <DB_URL> -c "SELECT ... FROM information_schema.table_constraints"` | **Grep** JOIN/FK patterns |
+| Get RLS policies | **Bash** `psql <DB_URL> -c "SELECT ... FROM pg_policies"` | **Read** policy files |
 | Find queries in code | **Grep** `\.from\(` in `*.ts,*.tsx,*.js,*.cs` | — |
 | Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | — |
 | Read found files | **Read** each file | — |
 | Complex multi-file analysis | **Task** (subagent Explore) | Read individual |
 | Generate schema-analysis.md | **Write** using template | **Bash** template render |
 
-**MCPs for this phase:** Supabase (schema — **PRIORITY**), Generic database MCPs.
+**Tools for this phase:** Supabase CLI / psql (schema — **PRIORITY**, local Docker), Generic database CLIs.
 
 ---
 
@@ -48,57 +48,56 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
 Verify first with a test call before attempting to use it.
 
 ```
-1. IF Supabase MCP configured in settings.json:
-   → Try mcp__supabase__list_tables() with implicit timeout
-   → IF returns valid data (array of tables with content):
-      → Use Method A (direct MCP)
-   → IF returns error, timeout, empty array, or inaccessible data:
-      → Log: "Supabase MCP configured but inaccessible (CloudSQL? Auth? Permissions?)"
-      → Use Method B (static code analysis)
-
-2. IF Database MCP (other) configured:
-   → Test connectivity with trivial query before using
-   → IF OK: Use adapted Method A
-   → IF fails: Use Method B
-
-3. IF no MCP available:
+0. **Docker health check:** Run `docker info --format '{{.ServerVersion}}'` to verify Docker is running.
+   → IF Docker is not running → warn user: "Docker Desktop not running — Supabase local requires Docker."
+   → Ask user via AskUserQuestion: start Docker or fall back to Method B.
+
+1. IF Supabase project detected (supabase/ dir exists OR config.json stack includes supabase):
+   → Run `npx supabase status` to verify local Docker is running
+   → IF running (exit 0): extract DB URL from output → Use Method A (direct CLI/psql)
+   → IF not running (exit non-zero):
+      → Log: "Supabase local not running — run `npx supabase start`"
+      → Ask user via AskUserQuestion: start it or fall back to Method B
+
+2. IF no Supabase detected:
    → Use Method B (static code analysis)
 ```
 
-**Signs of inaccessible MCP:**
-- Empty response or `[]` from `list_tables()`
-- Authentication error / permission denied
-- Returned schema doesn't match code (e.g., tables exist in code but not in MCP)
+**Signs of unavailable local Supabase:**
+- `npx supabase status` exits with non-zero code
+- Docker not running or Supabase containers stopped
 - Project uses database other than Supabase (CloudSQL, RDS, Azure SQL, etc.)
 
-### Step 2A: MCP Method (Preferred)
+### Step 2A: CLI Method (Preferred — Local Docker)
 
-**Tools:** Supabase MCP
+**Tools:** Bash (Supabase CLI + psql)
 
-```javascript
-// 1. List all tables
-const tables = await mcp__supabase__list_tables();
+```bash
+# 0. Get local DB URL (port may vary per instance)
+npx supabase status
+# → Extract "DB URL" line, e.g.: postgresql://postgres:postgres@127.0.0.1:54322/postgres
 
-// 2. For each feature-relevant table:
-for (const table of relevantTables) {
-  // 2a. Complete schema
-  const schema = await mcp__supabase__get_table_schema({ table: table.name });
-  // → column_name, data_type, is_nullable, column_default
+# 1. List all tables
+npx supabase db dump --local --schema public 2>/dev/null | grep "CREATE TABLE"
 
-  // 2b. Relationships
-  const rels = await mcp__supabase__get_relationships({ table: table.name });
-  // → foreign_table, foreign_column, constraint_type
+# 2. For each feature-relevant table:
 
-  // 2c. Indexes
-  const indexes = await mcp__supabase__query({
-    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
-  });
+# 2a. Complete schema
+psql $DB_URL -c "SELECT column_name, data_type, is_nullable, column_default \
+  FROM information_schema.columns WHERE table_name = 'TABLE_NAME' ORDER BY ordinal_position"
 
-  // 2d. RLS policies (security)
-  const policies = await mcp__supabase__query({
-    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
-  });
-}
+# 2b. Relationships (FK)
+psql $DB_URL -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table, \
+  ccu.column_name AS foreign_column FROM information_schema.table_constraints tc \
+  JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name \
+  JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name \
+  WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'TABLE_NAME'"
+
+# 2c. Indexes
+psql $DB_URL -c "SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'TABLE_NAME'"
+
+# 2d. RLS policies (security)
+psql $DB_URL -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'TABLE_NAME'"
 ```
 
 ### Step 2B: Static Analysis Method (Fallback)
@@ -155,7 +154,7 @@ The template is at `framework/templates/docs/schema-analysis.md`. Use it via:
 
 ```bash
 morph-spec template render docs/schema-analysis \
-  .morph/features/{feature}/1-design/schema-analysis.md \
+  .morph/features/{feature}/2-design/schema-analysis.md \
   '{
     "FEATURE_NAME": "{feature}",
     "FEATURE_NAME_TITLE": "{Feature Display Name}",
@@ -214,7 +213,7 @@ Use the template at `framework/templates/docs/schema-analysis.md`:
 
 ```bash
 morph-spec template render docs/schema-analysis \
-  .morph/features/{feature-name}/1-design/schema-analysis.md \
+  .morph/features/{feature-name}/2-design/schema-analysis.md \
   '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
 ```
 
@@ -230,7 +229,7 @@ morph-spec state mark-output {feature-name} schema-analysis
 
 ## Outputs
 
-- `.morph/features/{feature}/1-design/schema-analysis.md`
+- `.morph/features/{feature}/2-design/schema-analysis.md`
 - State updated with `schemaAnalysis` output
 
 ## CHECKPOINT