@polymorphism-tech/morph-spec 4.8.14 → 4.8.16

package/framework/skills/level-0-meta/terminal-title/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: terminal-title
+description: Manually set the terminal window title for the current task. Use when you need to override the automatic title set by the hook, or to set a specific descriptive title for the current work context.
+argument-hint: "[title]"
+user-invocable: true
+allowed-tools: Bash
+---
+
+# Terminal Title
+
+## Overview
+
+Manually sets the terminal window title. The hook `set-terminal-title.js` sets titles automatically on every prompt — use this skill only for manual overrides.
+
+## When to Use
+
+- Override the automatic title with something more descriptive
+- Set a custom title at the start of a focused work session
+- Invoke explicitly: `/terminal-title`
+
+## Title Format
+
+```
+[Action]: [Specific Focus]
+```
+
+**Good titles (max 40 chars):**
+- `Fix: Auth Login Bug`
+- `Build: Dashboard UI`
+- `Refactor: Payment Module`
+- `DB Migration: Users Table`
+- `Test: Checkout Flow`
+
+The script (`set_title.sh`) prepends the current directory name automatically:
+```
+morph-spec-framework | Fix: Auth Login Bug
+```
+
+The hook (`set-terminal-title.js`) sets the task title directly, without a directory prefix:
+```
+Fix: Auth Login Bug
+```
+
+## Implementation
+
+Run the title script with the desired title:
+
+```bash
+bash .claude/skills/terminal-title/scripts/set_title.sh "Fix: Auth Login Bug"
+```
+
+No confirmation needed — executes silently in the background.
+
+## Optional Custom Prefix
+
+Set `CLAUDE_TITLE_PREFIX` in your environment to add a custom prefix:
+
+```bash
+export CLAUDE_TITLE_PREFIX="🤖"
+# Results in: 🤖 morph-spec-framework | Fix: Auth Login Bug
+```

package/framework/skills/level-0-meta/terminal-title/scripts/set_title.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Set terminal window title
+# Usage: ./set_title.sh "Your Title Here"
+#
+# The script automatically prefixes the title with the current directory name
+# (usually the repo/project name) for easy identification across multiple terminals.
+#
+# Optional: Set CLAUDE_TITLE_PREFIX environment variable for additional custom prefix
+# Example: export CLAUDE_TITLE_PREFIX="🤖"
+#          Results in: "🤖 my-project | Your Title"
+
+# Exit silently if no title provided (fail-safe behavior)
+if [ -z "$1" ]; then
+    exit 0
+fi
+
+# Validate and sanitize input
+# Remove control characters (0x00-0x1F) and limit length to 80 characters
+TITLE=$(echo "$1" | tr -d '\000-\037' | head -c 80)
+
+# Ensure title is not empty after sanitization
+if [ -z "$TITLE" ]; then
+    exit 0
+fi
+
+# Get the current directory name (usually the repo/project name)
+DIR_NAME=$(basename "$PWD")
+
+# Build the final title with directory prefix and optional custom prefix
+if [ -n "$CLAUDE_TITLE_PREFIX" ]; then
+    # Sanitize prefix as well
+    PREFIX=$(echo "$CLAUDE_TITLE_PREFIX" | tr -d '\000-\037' | head -c 20)
+    if [ -n "$PREFIX" ]; then
+        FINAL_TITLE="${PREFIX} ${DIR_NAME} | ${TITLE}"
+    else
+        FINAL_TITLE="${DIR_NAME} | ${TITLE}"
+    fi
+else
+    FINAL_TITLE="${DIR_NAME} | ${TITLE}"
+fi
+
+# Store the title in a file that shell hooks can read
+# This allows precmd hooks (like update_terminal_cwd) to preserve the title
+# Use atomic write to prevent race conditions
+TITLE_FILE="${HOME}/.claude/terminal_title"
+mkdir -p "${HOME}/.claude"
+
+# Atomic write using temp file + rename
+TEMP_FILE="${TITLE_FILE}.tmp.$$"
+echo "$FINAL_TITLE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$TITLE_FILE" 2>/dev/null || rm -f "$TEMP_FILE"
+
+# Set the terminal title using ANSI escape sequences
+# Detect terminal type and set title accordingly
+case "$TERM" in
+    xterm*|rxvt*|screen*|tmux*)
+        # Standard xterm-compatible terminals
+        printf '\033]0;%s\007' "$FINAL_TITLE"
+        ;;
+    *)
+        # Fallback: try anyway, suppress errors
+        # This works for iTerm2, Alacritty, and most modern terminals
+        printf '\033]0;%s\007' "$FINAL_TITLE" 2>/dev/null
+        ;;
+esac

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

@@ -129,212 +129,19 @@ Critério: se a leitura de arquivo B não depende do CONTEÚDO de arquivo A, lei
 
 ## Tools Per Phase
 
-### Phase 0 — Proposal
-
-**Goal:** Understand the feature request and create proposal.md
-
-| Action | Tool | Why |
-|--------|------|-----|
-| Read project context | **Read** `.morph/context/README.md` | Single known file |
-| Read config | **Read** `.morph/config.json` | Single known file |
-| Find existing features | **Glob** `.morph/features/*/0-proposal/proposal.md` | Pattern search |
-| Detect project stack | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | agents.json is the source of truth |
-| Research external requirement | **WebSearch** | Current information needed |
-| Render proposal template | **Bash** `npx morph-spec template render docs/proposal ...` | CLI command |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
-
-**MCPs used:** None typically. GitHub MCP if feature comes from an issue.
-
-**Anti-patterns:**
-- ❌ Task agent to read proposal template (just use Read)
-- ❌ Bash `cat` to read files (use Read tool)
-- ❌ Bash `find` to locate files (use Glob tool)
-
----
-
-### Phase 1 — Setup
-
-**Goal:** Load context, detect stack, activate agents
-
-| 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 | 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 inline (keyword matching is fast enough directly)
-- ❌ WebSearch for project info (it's local, use Read/Glob)
-
----
-
-### Phase 1.5 — UI/UX Design
-
-**Goal:** Create UI mockups, design system, component specs, user flows
-
-| Action | Tool | Why |
-|--------|------|-----|
-| Check existing design system | **Read** `.morph/context/design-system.md` | Single file |
-| Read user-provided screenshots | **Read** (image files) | Claude Code reads images natively |
-| Search for existing CSS variables | **Grep** `--root:` or `--color-` in `*.css,*.scss` | Find existing design tokens |
-| Find existing UI components | **Glob** `**/Components/**/*.razor` or `**/components/**/*.tsx` | Existing patterns |
-| Get Figma design tokens | **Figma MCP** `get_file({ fileKey })` | Extract colors, typography from Figma |
-| Look up component library API | **Context7 MCP** `query_docs({ libraryId, query })` | Accurate component props/events |
-| Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
-| Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
-| Testar layout responsivo | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
-| Search for design references | **WebSearch** + **WebFetch** | External inspiration |
-| Render UI templates | **Bash** `npx morph-spec template render docs/ui-mockups ...` | CLI command |
-| Generate design system from CSS | **Bash** `npx morph-spec generate design-system --scan` | CLI command |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
-
-**MCPs used:** Figma (design tokens), Playwright (live preview, page inspection), Context7 (component docs).
-
-**Anti-patterns:**
-- ❌ WebSearch for MudBlazor docs (use Context7 MCP — more accurate)
-- ❌ Task agent to read a single screenshot (just use Read tool on the image)
-- ❌ Manually guessing component props (use Context7 to get real API)
-
----
-
-### Phase 2 — Design (Technical Spec)
-
-**Goal:** Analyze schema, create spec.md, contracts-level{N}.cs, decisions.md
-
-| 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 |
-| **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 |
-| Look up library for ADR | **Context7 MCP** `query_docs()` | Compare library capabilities |
-| Check existing code patterns | **GitHub MCP** `search_code()` | Find patterns in large repos |
-| **Fallback:** Search codebase | **Grep** patterns across project | When no GitHub MCP |
-| Render contracts template (detected level) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` where N = level detected | CLI command |
-| Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
-| Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
-| Create schema-analysis.md | **Write** to output directory | Document findings |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
-
-**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 (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)
-
----
-
-### 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** `npx morph-spec template render docs/clarifications ...` | Use template |
-| Update state | **Bash** `npx morph-spec state mark-output ... 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
-
-**Goal:** Break spec into tasks, define dependencies, set checkpoints
-
-| 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 |
-| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | CLI command |
-| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | CLI command |
-
-**MCPs used:** Context7 (complexity estimation), GitHub (issue creation).
-
-**Anti-patterns:**
-- ❌ 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
-
----
-
-### Phase 5 — Implement
-
-**Goal:** Implement tasks, checkpoint every 3, create recap
-
-| 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 |
-| Run database migrations | **Supabase MCP** `query()` | DDL statements directly |
-| **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** `npx morph-spec checkpoint ...` | Every 3 tasks |
-| Create RLS policies | **Supabase MCP** `query()` | Security policies |
-| 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** `npx morph-spec task done T001` | State tracking |
-| 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 |
-| 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
+> Para detalhes de ferramentas por fase, veja `references/tools-per-phase.md`
+
+**Resumo rápido por fase:**
+
+| Fase | MCPs principais | Dispatch subagents? |
+|------|----------------|---------------------|
+| Proposal | GitHub (opcional) | Não |
+| Setup | GitHub (opcional) | Não |
+| UI/UX | Playwright, Figma, Context7 | Não |
+| Design | Supabase, Context7, GitHub | Sim (domain-architect + schema em paralelo) |
+| Clarify | Context7, GitHub | Não |
+| Tasks | Context7, GitHub | Sim (quando spec tem 20+ reqs ou 3+ domínios) |
+| Implement | Supabase, Context7, Playwright, GitHub | Sim (quando tasks.total ≥ 6 e 2+ domínios) |
 
 ---
 

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

@@ -0,0 +1,213 @@
+# Tools Per Phase — Detailed Reference
+
+> Detailed tool selection tables for each MORPH-SPEC phase.
+> For the decision flowchart and selection rules, see the main `SKILL.md`.
+
+---
+
+## Phase 0 — Proposal
+
+**Goal:** Understand the feature request and create proposal.md
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read project context | **Read** `.morph/context/README.md` | Single known file |
+| Read config | **Read** `.morph/config.json` | Single known file |
+| Find existing features | **Glob** `.morph/features/*/0-proposal/proposal.md` | Pattern search |
+| Detect project stack | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | agents.json is the source of truth |
+| Research external requirement | **WebSearch** | Current information needed |
+| Render proposal template | **Bash** `npx morph-spec template render docs/proposal ...` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**MCPs used:** None typically. GitHub MCP if feature comes from an issue.
+
+**Anti-patterns:**
+- ❌ Task agent to read proposal template (just use Read)
+- ❌ Bash `cat` to read files (use Read tool)
+- ❌ Bash `find` to locate files (use Glob tool)
+
+---
+
+## Phase 1 — Setup
+
+**Goal:** Load context, detect stack, activate agents
+
+| 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 | 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 inline (keyword matching is fast enough directly)
+- ❌ WebSearch for project info (it's local, use Read/Glob)
+
+---
+
+## Phase 1.5 — UI/UX Design
+
+**Goal:** Create UI mockups, design system, component specs, user flows
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Check existing design system | **Read** `.morph/context/design-system.md` | Single file |
+| Read user-provided screenshots | **Read** (image files) | Claude Code reads images natively |
+| Search for existing CSS variables | **Grep** `--root:` or `--color-` in `*.css,*.scss` | Find existing design tokens |
+| Find existing UI components | **Glob** `**/Components/**/*.razor` or `**/components/**/*.tsx` | Existing patterns |
+| Get Figma design tokens | **Figma MCP** `get_file({ fileKey })` | Extract colors, typography from Figma |
+| Look up component library API | **Context7 MCP** `query_docs({ libraryId, query })` | Accurate component props/events |
+| Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
+| Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
+| Testar layout responsivo | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
+| Search for design references | **WebSearch** + **WebFetch** | External inspiration |
+| Render UI templates | **Bash** `npx morph-spec template render docs/ui-mockups ...` | CLI command |
+| Generate design system from CSS | **Bash** `npx morph-spec generate design-system --scan` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**MCPs used:** Figma (design tokens), Playwright (live preview, page inspection), Context7 (component docs).
+
+**Anti-patterns:**
+- ❌ WebSearch for MudBlazor docs (use Context7 MCP — more accurate)
+- ❌ Task agent to read a single screenshot (just use Read tool on the image)
+- ❌ Manually guessing component props (use Context7 to get real API)
+
+---
+
+## Phase 2 — Design (Technical Spec)
+
+**Goal:** Analyze schema, create spec.md, contracts-level{N}.cs, decisions.md
+
+| 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 |
+| **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 |
+| Look up library for ADR | **Context7 MCP** `query_docs()` | Compare library capabilities |
+| Check existing code patterns | **GitHub MCP** `search_code()` | Find patterns in large repos |
+| **Fallback:** Search codebase | **Grep** patterns across project | When no GitHub MCP |
+| Render contracts template (detected level) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` where N = level detected | CLI command |
+| Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
+| Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
+| Create schema-analysis.md | **Write** to output directory | Document findings |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**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 (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)
+
+---
+
+## 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** `npx morph-spec template render docs/clarifications ...` | Use template |
+| Update state | **Bash** `npx morph-spec state mark-output ... 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
+
+**Goal:** Break spec into tasks, define dependencies, set checkpoints
+
+| 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 |
+| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | CLI command |
+| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | CLI command |
+
+**MCPs used:** Context7 (complexity estimation), GitHub (issue creation).
+
+**Anti-patterns:**
+- ❌ 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
+
+---
+
+## Phase 5 — Implement
+
+**Goal:** Implement tasks, checkpoint every 3, create recap
+
+| 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 |
+| Run database migrations | **Supabase MCP** `query()` | DDL statements directly |
+| **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** `npx morph-spec checkpoint ...` | Every 3 tasks |
+| Create RLS policies | **Supabase MCP** `query()` | Security policies |
+| 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** `npx morph-spec task done T001` | State tracking |
+| 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 |
+| 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-0-meta/verification-before-completion/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: verification-before-completion
 description: Phase-specific verification checklists and morph-spec validation commands for confirming MORPH-SPEC outputs are complete and correct. Use before marking any task done, before advancing to the next phase, before committing, or before creating PRs.
+user-invocable: true
+argument-hint: "[feature-name] [phase?]"
 ---
 
 # Verification Before Completion — MORPH-SPEC Integrated

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.14"
+cliVersion: "4.8.16"
 ---
 
 # MORPH Clarify - FASE 3
@@ -35,8 +35,8 @@ Identifique ambiguidades na especificação e faça perguntas de clarificação
 | Pesquisar edge cases externos | **WebSearch** | — |
 | Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
 | Atualizar spec com clarificações | **Edit** spec.md | — |
-| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications ...` | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output ... clarifications` | — |
+| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications .morph/features/$ARGUMENTS/2-clarify/clarifications.md` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
 
 **MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
 
@@ -157,16 +157,13 @@ Documente no spec como lidar com cada edge case identificado:
 
 ### Passo 7: Atualizar State
 
-```bash
-npx morph-spec state set $ARGUMENTS phase clarify
-```
-
 ## Outputs Gerados/Atualizados
 
 - `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
   - Seção "Clarifications" com perguntas e respostas
   - Edge cases documentados
   - Requisitos mais específicos
+- `.morph/features/$ARGUMENTS/2-clarify/clarifications.md` - Novo arquivo com Q&A estruturado
 
 ## Critérios de Avanço
 

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

@@ -3,7 +3,7 @@ name: 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
-cliVersion: "4.8.14"
+cliVersion: "4.8.16"
 ---
 
 # MORPH Codebase Analysis - Sub-fase de DESIGN