@polymorphism-tech/morph-spec 4.8.7 → 4.8.9

package/framework/hooks/claude-code/pre-compact/save-morph-context.js

@@ -1,20 +1,47 @@
 #!/usr/bin/env node
 
 /**
- * PreCompact Hook: Save Context Before Compaction
+ * PreCompact Hook: Inject MORPH Context into Compact Summary
  *
  * Event: PreCompact
  *
- * Snapshots current morph-spec state to .morph/memory/ before context is lost
- * to compaction. The SessionStart hook can use this to restore awareness.
+ * Injects a rich morph-spec state snapshot as additionalContext so that
+ * Claude's compacted summary includes feature state, task progress, outputs,
+ * and next steps. Ensures the session resumes with full morph awareness
+ * without having to re-read all the spec files.
+ *
+ * Also saves snapshot to .morph/memory/ for SessionStart to reference.
  *
  * Fail-open: exits 0 on any error.
  */
 
-import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { stateExists, loadState, getActiveFeature } from '../../shared/state-reader.js';
-import { pass } from '../../shared/hook-response.js';
+import {
+  stateExists, loadState, getActiveFeature,
+  derivePhaseForFeature, getPendingGates, getOutputs,
+} from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+const DECISIONS_MAX_CHARS = 1500;
+const MAX_PENDING_TASKS   = 8;
+
+const PHASE_POSITIONS = {
+  proposal: 1, setup: 1,
+  uiux: 2, design: 2,
+  clarify: 3,
+  tasks: 4,
+  implement: 5, sync: 5,
+};
+const PIPELINE_TOTAL = 5;
+
+const NEXT_STEP_HINT = {
+  proposal:  (n) => `Continue spec pipeline: /morph-proposal ${n}`,
+  design:    (n) => `Approve design gate: morph-spec approve ${n} design`,
+  uiux:      (n) => `Approve UI gate: morph-spec approve ${n} uiux`,
+  tasks:     (n) => `Approve tasks gate: morph-spec approve ${n} tasks`,
+  implement: (n) => `Continue implementation: morph-spec task next ${n}`,
+};
 
 try {
   if (!stateExists()) pass();
@@ -23,39 +50,130 @@ try {
   if (!state) pass();
 
   const active = getActiveFeature();
+  const cwd    = process.cwd();
 
+  // ── Disk snapshot (for SessionStart restore) ──────────────────────────────
   const snapshot = {
-    timestamp: new Date().toISOString(),
-    event: 'pre-compact',
+    timestamp:     new Date().toISOString(),
+    event:         'pre-compact',
     activeFeature: active ? active.name : null,
-    features: {}
+    features:      {},
   };
 
-  // Save minimal feature summaries
   for (const [name, feature] of Object.entries(state.features || {})) {
     snapshot.features[name] = {
-      phase: feature.phase,
-      status: feature.status,
+      phase:    feature.phase || derivePhaseForFeature(name),
+      status:   feature.status,
       workflow: feature.workflow,
-      tasks: feature.tasks,
+      tasks:    feature.tasks,
       approvalGates: Object.fromEntries(
         Object.entries(feature.approvalGates || {}).map(([gate, data]) => [gate, data.approved])
-      )
+      ),
     };
   }
 
-  // Save to .morph/memory/
-  const memoryDir = join(process.cwd(), '.morph', 'memory');
-  if (!existsSync(memoryDir)) {
-    mkdirSync(memoryDir, { recursive: true });
+  const memoryDir = join(cwd, '.morph', 'memory');
+  if (!existsSync(memoryDir)) mkdirSync(memoryDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  writeFileSync(join(memoryDir, `pre-compact-${ts}.json`), JSON.stringify(snapshot, null, 2), 'utf-8');
+
+  // ── Nothing more to inject if no active feature ───────────────────────────
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const phase = derivePhaseForFeature(name);
+  const pos   = PHASE_POSITIONS[phase];
+  const phaseLabel = pos ? `${phase} (${pos}/${PIPELINE_TOTAL})` : phase;
+
+  const lines = [
+    '=== MORPH-SPEC COMPACT CONTEXT ===',
+    `Preserve this section verbatim in the compact summary.`,
+    '',
+    `Feature : ${name}`,
+    `Phase   : ${phaseLabel}`,
+    `Status  : ${feature.status}  |  Workflow: ${feature.workflow || 'auto'}`,
+  ];
+
+  // Task progress
+  const tasks = feature.tasks || {};
+  const done  = tasks.completed || 0;
+  const total = tasks.total     || 0;
+  if (total > 0) {
+    const pct = Math.round(done / total * 100);
+    lines.push(`Tasks   : ${done}/${total} completed (${pct}%)`);
+  }
+
+  // In-progress + next pending tasks from taskList
+  const taskList  = Array.isArray(feature.taskList) ? feature.taskList : [];
+  const inProg    = taskList.filter(t => t.status === 'in_progress');
+  const pending   = taskList.filter(t => t.status === 'pending').slice(0, MAX_PENDING_TASKS);
+
+  if (inProg.length > 0) {
+    lines.push('');
+    lines.push('In progress:');
+    for (const t of inProg) lines.push(`  [${t.id}] ${t.title}`);
+  }
+  if (pending.length > 0) {
+    lines.push('');
+    lines.push('Next pending tasks:');
+    for (const t of pending) lines.push(`  [${t.id}] ${t.title}`);
+    if (taskList.filter(t => t.status === 'pending').length > MAX_PENDING_TASKS) {
+      lines.push(`  ... (use morph-spec task next ${name} for full list)`);
+    }
+  }
+
+  // Created outputs
+  const outputs  = getOutputs(name) || {};
+  const created  = Object.entries(outputs).filter(([, o]) => o.created);
+  const missing  = Object.entries(outputs).filter(([, o]) => !o.created);
+  if (created.length > 0) {
+    lines.push('');
+    lines.push('Created outputs:');
+    for (const [type, o] of created) lines.push(`  ✓ ${type}: ${o.path}`);
+  }
+  if (missing.length > 0) {
+    lines.push('Pending outputs:');
+    for (const [type, o] of missing) lines.push(`  ✗ ${type}: ${o.path}`);
+  }
+
+  // Active agents
+  const agents = feature.activeAgents || [];
+  if (agents.length > 0) {
+    lines.push('');
+    lines.push(`Active agents: ${agents.join(', ')}`);
+  }
+
+  // Pending approval gates
+  const pendingGates = getPendingGates(name);
+  if (pendingGates.length > 0) {
+    lines.push(`Pending approvals: ${pendingGates.join(', ')}`);
+  }
+
+  // Key decisions (truncated to stay within context budget)
+  const decisionsPath = join(cwd, `.morph/features/${name}/1-design/decisions.md`);
+  if (existsSync(decisionsPath)) {
+    try {
+      const raw = readFileSync(decisionsPath, 'utf-8');
+      const content = raw.length > DECISIONS_MAX_CHARS
+        ? raw.slice(0, DECISIONS_MAX_CHARS) + '\n[... truncated — full file at decisions.md]'
+        : raw;
+      lines.push('');
+      lines.push('Key decisions (decisions.md):');
+      lines.push(content);
+    } catch { /* non-blocking */ }
+  }
+
+  // Next step
+  const hintFn = NEXT_STEP_HINT[phase];
+  if (hintFn) {
+    lines.push('');
+    lines.push(`Next step: ${hintFn(name)}`);
   }
 
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const snapshotPath = join(memoryDir, `pre-compact-${timestamp}.json`);
-  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+  lines.push('');
+  lines.push('=== END MORPH CONTEXT ===');
 
-  pass();
+  injectContext(lines.join('\n'));
 } catch {
-  // Fail-open
   process.exit(0);
 }

package/framework/hooks/claude-code/statusline.py

@@ -544,18 +544,6 @@ def main():
                 line += f" ({toks})"
             parts2.append(line + suffix)
 
-        # Token breakdown from JSONL (session totals: input / output / cached)
-        if entries:
-            tok = get_token_metrics(entries)
-            tok_parts = []
-            if tok['input']:
-                tok_parts.append(f"in:{format_tokens(tok['input'])}")
-            if tok['output']:
-                tok_parts.append(f"out:{format_tokens(tok['output'])}")
-            if tok['cached']:
-                tok_parts.append(f"↩{format_tokens(tok['cached'])}")
-            if tok_parts:
-                parts2.append(f"{GRAY}{' '.join(tok_parts)}{R}")
 
         # Git info (branch + diff stats)
         git = get_git_info(cwd)

package/framework/hooks/claude-code/statusline.sh

@@ -1,7 +1,11 @@
 #!/usr/bin/env bash
 # morph-spec statusline — installed globally to ~/.claude/statusline.sh
 # Claude Code invokes this with JSON via stdin after each response.
-# Requires: Python 3 available as `python3` on PATH.
+# Requires: Python 3 available as `python3` or `python` on PATH.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
+if command -v python3 &>/dev/null; then
+  python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
+elif command -v python &>/dev/null; then
+  python "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
+fi

package/framework/hooks/claude-code/stop/validate-completion.js

@@ -1,23 +1,36 @@
 #!/usr/bin/env node
 
 /**
- * Stop Hook: Validate Completion (Advisory)
+ * Stop Hook: Validate Completion + Phase Transition Alerts
  *
  * Event: Stop
  *
- * When Claude stops, checks for incomplete work:
- *   - In implement phase: checks uncompleted tasks
- *   - In spec phases: checks required outputs still created: false
- *   - Returns additionalContext with what remains (advisory, not blocking)
+ * 1. Detects transitions into the `implement` phase and recommends /compact
+ *    before starting — ensures Claude has a clean context for writing code.
+ * 2. Checks for incomplete work (tasks, missing outputs, pending gates).
+ *
+ * Phase transition tracking: stores last-seen phase per feature in
+ * .morph/memory/phase-watch.json so the alert fires exactly once,
+ * the first Stop after the transition occurs.
  *
  * Uses stop_hook_active env check to prevent infinite loops.
  *
  * Fail-open: exits 0 on any error.
  */
 
-import { stateExists, getActiveFeature, getMissingOutputs } from '../../shared/state-reader.js';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import {
+  stateExists, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
+} from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 
+// Phases where compaction is strongly recommended before starting
+const COMPACT_TRIGGER_PHASES = new Set(['implement']);
+
+// Phases where compaction is suggested when arriving from a heavy spec phase
+const HEAVY_SOURCE_PHASES = new Set(['tasks', 'design', 'clarify', 'uiux']);
+
 try {
   // Prevent infinite loop
   if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
@@ -28,10 +41,48 @@ try {
   if (!active) pass();
 
   const { name, feature } = active;
+  const cwd  = process.cwd();
   const warnings = [];
 
-  // Check for incomplete tasks during implement phase
-  if (feature.phase === 'implement' && feature.tasks) {
+  // ── Phase transition detection ────────────────────────────────────────────
+  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
+
+  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
+  let phaseWatch  = {};
+  try {
+    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
+  } catch { /* corrupt file — start fresh */ }
+
+  const lastPhase = phaseWatch[name];
+
+  // Update stored phase (always, so the alert only fires once per transition)
+  try {
+    phaseWatch[name] = currentPhase;
+    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
+  } catch { /* non-blocking */ }
+
+  // Alert when entering implement from a heavy spec phase
+  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
+  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
+  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
+
+  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
+    warnings.push(
+      `⚡ Phase advanced: ${lastPhase} → implement`,
+      ``,
+      `💡 Recommended before starting implementation:`,
+      `   Run /compact to free up context — the spec, design and task files`,
+      `   loaded during planning take significant space. A compact now gives`,
+      `   Claude a clean slate focused on writing code.`,
+      ``,
+      `   After /compact, resume with: morph-spec task next ${name}`,
+    );
+  }
+
+  // ── Incomplete work checks ────────────────────────────────────────────────
+
+  // Incomplete tasks during implement phase
+  if (currentPhase === 'implement' && feature.tasks) {
     const remaining = (feature.tasks.total || 0) - (feature.tasks.completed || 0);
     if (remaining > 0) {
       warnings.push(`${remaining} task(s) remaining for feature '${name}'`);
@@ -41,11 +92,11 @@ try {
     }
   }
 
-  // Check for missing outputs in spec phases
-  if (['proposal', 'design', 'clarify', 'tasks', 'uiux'].includes(feature.phase)) {
+  // Missing outputs in spec phases
+  if (['proposal', 'design', 'clarify', 'tasks', 'uiux'].includes(currentPhase)) {
     const missing = getMissingOutputs(name);
     if (missing.length > 0) {
-      warnings.push(`Missing outputs for '${name}' (${feature.phase} phase):`);
+      warnings.push(`Missing outputs for '${name}' (${currentPhase} phase):`);
       for (const output of missing.slice(0, 5)) {
         warnings.push(`  - ${output.type}: ${output.path}`);
       }
@@ -55,34 +106,30 @@ try {
     }
   }
 
-  // Check pending approval gates
+  // Pending approval gates
   if (feature.approvalGates) {
     const pendingGates = Object.entries(feature.approvalGates)
       .filter(([, gate]) => !gate.approved && !gate.timestamp)
-      .map(([name]) => name);
+      .map(([gateName]) => gateName);
 
-    // Only warn about gates relevant to current/past phases
-    const relevantGates = pendingGates.filter(gate => {
-      const gatePhaseMap = { proposal: 'proposal', uiux: 'uiux', design: 'design', tasks: 'tasks' };
-      return gatePhaseMap[gate] !== undefined;
-    });
+    const gatePhaseMap = { proposal: 'proposal', uiux: 'uiux', design: 'design', tasks: 'tasks' };
+    const relevant = pendingGates.filter(gate => gatePhaseMap[gate] !== undefined);
 
-    if (relevantGates.length > 0) {
-      warnings.push(`Pending approvals: ${relevantGates.join(', ')}`);
+    if (relevant.length > 0) {
+      warnings.push(`Pending approvals: ${relevant.join(', ')}`);
     }
   }
 
   if (warnings.length === 0) pass();
 
   const message = [
-    'MORPH-SPEC: Incomplete work detected:',
+    'MORPH-SPEC:',
     ...warnings.map(w => `  ${w}`),
     '',
-    'Resume with: morph-spec status ' + name
+    `Status: morph-spec status ${name}`,
   ].join('\n');
 
   injectContext(message);
 } catch {
-  // Fail-open
   process.exit(0);
 }

package/framework/hooks/dev/guard-version-numbers.js

@@ -7,7 +7,7 @@
  * Scope: Framework codebase only (dev hook)
  *
  * Blocks Write/Edit to files that contain hardcoded version patterns
- * like "MORPH-SPEC v4.8.7". Version should only be in package.json.
+ * like "MORPH-SPEC v4.8.9". Version should only be in package.json.
  *
  * Checked extensions: .md, .cs, .css, .js (covers templates + source)
  * Exceptions: CHANGELOG.md, node_modules/, test/, package.json, package-lock.json

package/framework/skills/level-0-meta/morph-init/SKILL.md

@@ -111,6 +111,9 @@ Gather evidence to build a stack map. Run these in parallel:
 | `Glob` | `database/migrations/**` | Supabase local dev |
 | `Glob` | `supabase/**` | Supabase project config |
 | `Glob` | `**/*.razor` | Blazor |
+| `Glob` | `**/Abstractions/IHandler.cs` | VSA pattern (KanaiyaKatarmal) |
+| `Glob` | `**/Pipelines/ValidationDecorator.cs` | VSA pipeline |
+| `Glob` | `**/Features/**/*Feature` | VSA feature folder suffix |
 | `Read` | `.env.example` | Env vars reveal integrations |
 | `Read` | `README.md` | Existing project description |
 | `Grep` | `@supabase/supabase-js` | Supabase dep in any package.json |
@@ -120,14 +123,20 @@ Gather evidence to build a stack map. Run these in parallel:
 Read each found `package.json` for dependency names. Build an **evidence map**:
 
 ```
-stack:         [nextjs, dotnet, ...]
-integrations:  [supabase, docker, clerk, ...]
-uiLibrary:     shadcn | fluent-ui | mudblazor | null
-monorepo:      true | false
-frontendPath:  src/frontend (if monorepo)
-backendPath:   src/backend (if monorepo)
+stack:             [nextjs, dotnet, ...]
+integrations:      [supabase, docker, clerk, ...]
+uiLibrary:         shadcn | fluent-ui | mudblazor | null
+monorepo:          true | false
+frontendPath:      src/frontend (if monorepo)
+backendPath:       src/backend (if monorepo)
+architectureStyle: vertical-slice | null   ← novo
 ```
 
+**VSA detection:** `architectureStyle: "vertical-slice"` se qualquer um destes existir:
+- `Abstractions/IHandler.cs` encontrado pelo Glob
+- `Pipelines/ValidationDecorator.cs` encontrado pelo Glob
+- 2+ pastas com sufixo `Feature` em `Features/` (ex: `BookFeature`, `OrderFeature`)
+
 ---
 
 ## Step 4 — Ask Targeted Questions
@@ -195,6 +204,35 @@ Read `.morph/config/config.json` and merge into `project`:
 }
 ```
 
+**Se `architectureStyle: "vertical-slice"` foi detectado no Step 3**, adicione também:
+
+```json
+{
+  "architecture": {
+    "style": "vertical-slice"
+  }
+}
+```
+
+E informe o usuário:
+
+```
+✓ Detected: Vertical Slice Architecture (IHandler.cs / *Feature folders)
+  → config.json: architecture.style = "vertical-slice"
+  → morph-spec will use vsa-architect + contracts-vsa.cs for features
+```
+
+> Esta key é o que ativa o `vsa-architect` em vez do `domain-architect` durante `/morph-proposal`.
+
+**Se o projeto ainda não existe (novo projeto VSA do zero)**, informe também:
+
+```
+Para criar um novo projeto VSA:
+   dotnet new install https://github.com/polymorphism-tech/Morph_Template_VerticalSliceArchitecture
+   dotnet new vsa -n MyProject
+   cd MyProject && npx morph-spec init
+```
+
 ---
 
 ## Step 7 — Configure MCPs

package/framework/skills/level-0-meta/tool-usage-guide/SKILL.md

@@ -34,18 +34,52 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
                      └──┬──────────────┬────────┘
                         │ YES          │ NO
                         ▼              ▼
-                   Use MCP tool   ┌──────────────────┐
-                   (+ fallback)   │ Does it require   │
-                                  │ MULTI-STEP        │
-                                  │ exploration of     │
-                                  │ many files?        │
-                                  └──┬──────────┬─────┘
-                                     │ YES      │ NO
-                                     ▼          ▼
-                                 Use Task     Do it
-                                 (subagent)   directly
+                   Use MCP tool   ┌──────────────────────────────┐
+                   (+ fallback)   │ Does it involve MULTIPLE      │
+                                  │ independent specialist tasks  │
+                                  │ (domain analysis + schema,   │
+                                  │ backend + frontend tasks)?   │
+                                  └──┬───────────────┬───────────┘
+                                     │ YES           │ NO
+                                     ▼               ▼
+                              Dispatch parallel  ┌──────────────────┐
+                              Task subagents     │ Does it require   │
+                              (see below)        │ MULTI-STEP        │
+                                                 │ exploration of    │
+                                                 │ many files?       │
+                                                 └──┬──────────┬─────┘
+                                                    │ YES      │ NO
+                                                    ▼          ▼
+                                                Use Task     Do it
+                                                (subagent)   directly
 ```
 
+### When to use Task subagents for agent dispatch
+
+Dispatch specialist agents as **Task subagents** when ALL conditions are met:
+- Phase is `design`, `tasks`, or `implement`
+- Feature has **2+ active specialist agents** (check `activeAgents` in state.json)
+- Work can be divided into **independent parallel tasks** with clear outputs
+
+```
+Feature with multiple active agents?
+   │
+   ├─ design phase    → Dispatch domain-architect (complexity analysis)
+   │                    + tech leads (spec validation) — in PARALLEL
+   │
+   ├─ tasks phase     → Dispatch per-domain task planners (if spec has 50+ reqs
+   │                    OR 3+ independent domains detected)
+   │
+   └─ implement phase → Dispatch per-domain implementers when tasks.total ≥ 6
+                        AND feature spans multiple domains (backend + frontend,
+                        or backend + infra, etc.)
+```
+
+**Key principle (from real-world usage):** Define subagents by **TASK**, not by **ROLE**.
+- ✅ "Analyze this proposal for DDD complexity and return level + blueprint" (task)
+- ✅ "Implement backend tasks T001-T005 for feature X" (task)
+- ❌ "Be a domain architect" (vague role assignment — poor results)
+
 ---
 
 ## Tools Per Phase
@@ -80,18 +114,19 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Action | Tool | Why |
 |--------|------|-----|
 | Verify feature state | **Bash** `npx morph-spec state get {feature}` | CLI command |
-| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent {f} {id}` per match | No CLI command — read agents.json directly |
+| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx 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** `npx morph-spec dispatch-agents {feature} design` | Shows which agents will be dispatched in design phase |
 | Update state | **Bash** `npx 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 (read agents.json and match keywords inline)
+- ❌ Task agent to detect project stack inline (keyword matching is fast enough directly)
 - ❌ WebSearch for project info (it's local, use Read/Glob)
 
 ---
@@ -132,6 +167,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Action | Tool | Why |
 |--------|------|-----|
 | Read proposal + UI specs | **Read** output files | Single known files |
+| **Get dispatch config** | **Bash** `npx 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 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 |
@@ -149,11 +187,14 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 **MCPs used:** Supabase (schema analysis), 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.
+
 **Anti-patterns:**
 - ❌ Guessing field names without checking schema (use MCP or Grep first!)
-- ❌ Task agent to read a single spec file (just use Read)
+- ❌ Task agent to read a single spec file (use Read directly)
 - ❌ WebSearch for database schema (use Supabase MCP 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)
 
 ---
 
@@ -189,8 +230,10 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Action | Tool | Why |
 |--------|------|-----|
 | Read spec + contracts + decisions | **Read** all output files | Full context needed |
+| **Get dispatch config** | **Bash** `npx morph-spec dispatch-agents {feature} tasks` | Which domain experts to consult |
 | Analyze implementation complexity | **Grep** patterns in existing code | Estimate effort from codebase size |
 | Count existing similar patterns | **Glob** `**/Services/**/*.cs` | Understand scope |
+| **Dispatch domain experts** (when spec is complex) | **Task** subagents per domain | Parallel per-domain task planning |
 | Look up implementation patterns | **Context7 MCP** `query_docs()` | Estimate task complexity accurately |
 | Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | Sync tasks to project management |
 | **Fallback:** Create issues via CLI | **Bash** `gh issue create ...` | When no GitHub MCP |
@@ -200,8 +243,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 **MCPs used:** Context7 (complexity estimation), GitHub (issue creation).
 
 **Anti-patterns:**
-- ❌ Task agent to break down a simple spec (do it directly, specs are already structured)
-- ✅ Task agent for complex specs with 50+ requirements (legitimate multi-step work)
+- ❌ Task agent to break down a simple 1-domain spec (do it directly)
+- ✅ Task agent for complex multi-domain specs (backend + frontend + infra = 3 independent planners)
+- ✅ Task agent when spec has 20+ requirements across multiple bounded contexts
 - ❌ Manually writing tasks.json without reading all outputs first
 
 ---
@@ -213,6 +257,8 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Action | Tool | Why |
 |--------|------|-----|
 | Read task details | **Read** tasks.json, spec.md, contracts.cs | Implementation reference |
+| **Check parallelization viability** | **Bash** `npx morph-spec dispatch-agents {feature} implement` | Whether to dispatch parallel implementers |
+| **Dispatch per-domain implementers** (when viable) | **Task** subagents — one per domain group | Backend tasks + frontend tasks run in parallel |
 | 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 |
@@ -228,17 +274,22 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Smoke test feature no browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual testing |
 | Verificar erros de console | **Playwright MCP** `browser_console_messages()` | Browser DevTools |
 | Screenshot para recap.md | **Playwright MCP** `browser_take_screenshot()` | Manual screenshot |
-| Multi-file refactoring | **Task** (subagent) | Complex parallel changes |
 | Update state | **Bash** `npx morph-spec state set ...` | CLI command |
 
 **MCPs used:** Supabase (migrations, RLS), 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
+- Each subagent gets its own task group (backend T001-T005, frontend T006-T009) with isolated file scope
+
 **Anti-patterns:**
 - ❌ Task agent for a single file edit (use Edit directly)
 - ✅ Task agent for implementing a full service layer across 5+ files
+- ✅ Task agent for each domain group when feature has 6+ tasks across multiple domains
 - ❌ Bash `cat` to create files (use Write tool)
 - ❌ Bash `sed` to modify code (use Edit tool)
 - ❌ Implementing without reading contracts.cs first (contracts are the source of truth)
+- ❌ Implementing backend and frontend tasks sequentially when they have no cross-dependencies
 
 ---
 

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, gene
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.7"
+cliVersion: "4.8.9"
 ---
 
 # MORPH Clarify - FASE 3