@polymorphism-tech/morph-spec 4.3.7 → 4.5.0

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

@@ -0,0 +1,335 @@
+---
+name: tool-usage-guide
+description: >
+  Decision guide for selecting the right Claude Code tool (Read, Grep, Glob, Bash, Task) for each situation in MORPH-SPEC workflows. Reference when unsure which tool to use.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Tool Usage Guide for MORPH Workflows
+
+> Operational guide for selecting the correct Claude Code tools and MCP tools at each morph-spec phase. Each phase uses a distinct set of tools optimized for its goals.
+>
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for detailed MCP examples.
+
+---
+
+## Decision Flowchart
+
+```
+┌──────────────────────────────┐
+│ I need to complete an action │
+└──────────────┬───────────────┘
+               │
+               ▼
+┌───────────────────────────────────────┐
+│ Is it a SEARCH for a specific file,   │
+│ keyword, or function?                 │
+└──────┬──────────────────┬─────────────┘
+       │ YES              │ NO
+       ▼                  ▼
+  Use Glob/Grep     ┌─────────────────────────┐
+  or Read            │ Does it need STRUCTURED  │
+                     │ external data (schema,   │
+                     │ API docs, design tokens)?│
+                     └──┬──────────────┬────────┘
+                        │ YES          │ NO
+                        ▼              ▼
+                   Use MCP tool   ┌──────────────────┐
+                   (+ fallback)   │ Does it require   │
+                                  │ MULTI-STEP        │
+                                  │ exploration of     │
+                                  │ many files?        │
+                                  └──┬──────────┬─────┘
+                                     │ YES      │ NO
+                                     ▼          ▼
+                                 Use Task     Do it
+                                 (subagent)   directly
+```
+
+---
+
+## 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 | **Bash** `npx morph-spec detect-agents --json "..."` | CLI command |
+| 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 | **Bash** `npx morph-spec detect-agents --json "..."` | CLI command, returns JSON with standards |
+| 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) |
+| Update state | **Bash** `npx morph-spec state set ...` | CLI command |
+
+**MCPs used:** GitHub (optional — for repo metadata).
+
+**Anti-patterns:**
+- ❌ Task agent to detect project stack (detect-agents CLI does this)
+- ❌ WebSearch for project info (it's local, use Read/Glob)
+- ❌ Manual parsing of agents.json (detect-agents handles it)
+
+---
+
+### 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.cs, decisions.md
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read proposal + UI specs | **Read** output files | Single known files |
+| 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 | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | 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).
+
+**Anti-patterns:**
+- ❌ Guessing field names without checking schema (use MCP or Grep first!)
+- ❌ Task agent to read a single spec file (just use Read)
+- ❌ WebSearch for database schema (use Supabase MCP or code analysis)
+- ❌ Manually writing contracts.cs from scratch (use template render)
+
+---
+
+### 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 |
+| Analyze implementation complexity | **Grep** patterns in existing code | Estimate effort from codebase size |
+| Count existing similar patterns | **Glob** `**/Services/**/*.cs` | Understand scope |
+| 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 spec (do it directly, specs are already structured)
+- ✅ Task agent for complex specs with 50+ requirements (legitimate multi-step work)
+- ❌ 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 |
+| 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 |
+| 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).
+
+**Anti-patterns:**
+- ❌ Task agent for a single file edit (use Edit directly)
+- ✅ Task agent for implementing a full service layer across 5+ files
+- ❌ 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)
+
+---
+
+## Tool Selection Rules
+
+### Claude Code Native Tools
+
+| Tool | When to Use | When NOT to Use |
+|------|-------------|-----------------|
+| **Read** | Read 1-3 specific known files | Don't use for searching |
+| **Glob** | Find files by name pattern | Don't use Bash `find` |
+| **Grep** | Search content across files | Don't use Bash `grep` or `rg` |
+| **Edit** | Modify existing files | Don't use Bash `sed` or `awk` |
+| **Write** | Create new files | Don't use Bash `echo >` or heredoc |
+| **Bash** | CLI commands, build, test, git | Don't use for file read/write/search |
+| **WebSearch** | Current external information | Don't use for local codebase info |
+| **WebFetch** | Specific URL content | Don't use for authenticated services |
+| **Task** (subagent) | Multi-file exploration, complex analysis | Don't use for single-file operations |
+
+### MCP Tools
+
+| MCP | When to Use | Fallback |
+|-----|-------------|----------|
+| **Supabase** | Schema analysis, migrations, RLS | Grep + Read code files |
+| **GitHub** | Issues, PRs, repo metadata, code search | Bash `gh` CLI |
+| **Figma** | Design tokens, component specs | Read CSS/SCSS files |
+| **Context7** | Library documentation lookups | WebSearch + WebFetch |
+| **Playwright** | Browser automation, screenshots, page inspection, smoke tests | WebFetch (read-only), Manual testing |
+| **Azure** | Cloud resource management | Bash `az` CLI |
+| **Docker** | Container management | Bash `docker` CLI |
+
+### The 3-Question Test
+
+Before choosing a tool, ask:
+
+1. **Is the data local or external?**
+   - Local → Read/Grep/Glob
+   - External structured → MCP
+   - External unstructured → WebSearch/WebFetch
+
+2. **Am I reading or writing?**
+   - Reading → Read/Grep/Glob/MCP
+   - Writing → Write/Edit/Bash (for CLI)
+
+3. **How many files are involved?**
+   - 1-3 files → Direct tools (Read, Edit, Write)
+   - 4+ files of known names → Parallel Read calls
+   - Unknown files needing exploration → Glob/Grep, then Read
+   - Complex multi-step analysis → Task subagent
+
+---
+
+## MCP Registry
+
+For the canonical list of MCPs, their tools, phase relevance, and fallbacks, see:
+
+**`framework/skills/level-0-meta/mcp-registry.json`**
+
+### Phase → MCP Quick Reference
+
+| Phase | Primary MCPs | Fallback |
+|-------|-------------|----------|
+| Proposal | Context7 | WebSearch |
+| Setup | GitHub | `gh` CLI |
+| UI/UX | Playwright, Figma, Context7 | WebFetch, Read CSS |
+| Design | Supabase, Context7, GitHub | Grep + Read code |
+| Clarify | Context7, GitHub | WebSearch |
+| Tasks | Context7, GitHub | WebSearch, `gh` CLI |
+| Implement | Supabase, Context7, Playwright, GitHub | CLI tools |
+
+### Detected Plugins & MCPs
+
+If `morph-spec init` was run with Claude Code environment detection, check `.morph/config/integrations.json` for the detected plugins and MCPs available in this project.
+
+---
+
+## Superpowers Integration
+
+When the `superpowers` plugin is installed, additional skills enhance each phase:
+
+| Phase | Superpowers Skill | Purpose |
+|-------|------------------|---------|
+| Setup | `using-git-worktrees` | Isolate feature work |
+| Design | `writing-plans`, `brainstorming` | Structure approach, explore alternatives |
+| Clarify | `systematic-debugging` | Investigate technical ambiguities |
+| Tasks | `writing-plans`, `executing-plans` | Plan and execute implementation |
+| Implement | `test-driven-development`, `systematic-debugging`, `requesting-code-review` | TDD, debug failures, review |
+
+See each phase skill for detailed integration instructions.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -0,0 +1,145 @@
+---
+name: verification-before-completion
+description: Morph-spec-aware verification checklist before claiming any work is complete. Runs validation, checks outputs, and confirms with evidence.
+---
+
+# Verification Before Completion — MORPH-SPEC Integrated
+
+> Never claim work is complete without running verification. Evidence before assertions.
+
+## When to Use
+
+- Before marking any task as done (`morph-spec task done`)
+- Before advancing to the next phase
+- Before claiming a feature is complete
+- Before creating a PR or commit
+
+---
+
+## Phase-Specific Checklists
+
+### Phase 0 — Proposal
+
+- [ ] `proposal.md` exists in `.morph/features/{feature}/0-proposal/`
+- [ ] Proposal contains: Goal, Scope, Constraints, Success Criteria
+- [ ] `morph-spec state get {feature}` shows `phase: proposal`
+- [ ] `morph-spec state mark-output {feature} proposal` was called
+
+### Phase 1 — Setup
+
+- [ ] `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
+- [ ] `morph-spec validate-feature {feature} --phase uiux` passes
+
+### Phase 2 — Design
+
+- [ ] `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
+- [ ] `morph-spec validate-feature {feature} --phase design` passes
+
+### Phase 3 — Clarify
+
+- [ ] All clarification questions answered by user
+- [ ] `spec.md` updated with Clarifications section
+- [ ] No unresolved ambiguities in spec
+
+### Phase 4 — Tasks
+
+- [ ] `tasks.md` or `tasks.json` exists
+- [ ] All tasks have: ID, title, description, dependencies
+- [ ] Checkpoints defined (every 3 tasks)
+- [ ] `morph-spec state set {feature} tasks.total N` called
+
+### Phase 5 — Implement
+
+- [ ] All tasks marked as completed
+- [ ] Build succeeds (`npm run build` or `dotnet build`)
+- [ ] Tests pass (`npm test` or `dotnet test`)
+- [ ] `recap.md` generated with implementation summary
+- [ ] `morph-spec validate-feature {feature}` passes all checks
+
+---
+
+## Verification Commands
+
+```bash
+# Run content-aware validation
+npx morph-spec validate-feature {feature-name}
+
+# Run with specific phase
+npx morph-spec validate-feature {feature-name} --phase design
+
+# Check feature status
+npx morph-spec status {feature-name} --verbose
+
+# Run full project validation
+npx morph-spec validate
+```
+
+---
+
+## Integration with Task Done
+
+Before running `morph-spec task done`:
+
+1. **Run the relevant test** for the task being completed
+2. **Run `morph-spec validate-feature`** if completing a checkpoint task
+3. **Read the task spec** and verify all acceptance criteria are met
+4. **Check for build errors** — run build command
+
+```bash
+# Verify before marking done
+npx morph-spec validate-feature {feature} --phase implement
+npx morph-spec task done {feature} T001
+```
+
+---
+
+## Integration with Checkpoints
+
+Every 3 tasks, run full checkpoint validation:
+
+```bash
+npx morph-spec checkpoint-save {feature}
+npx morph-spec validate-feature {feature}
+```
+
+If validation fails:
+1. **Do NOT mark the task as done**
+2. **Fix the issues** identified by validation
+3. **Re-run validation** until it passes
+4. **Then** mark the task as done
+
+---
+
+## Integration with Superpowers
+
+> Available when the `superpowers` plugin is installed.
+
+This skill replaces `superpowers:verification-before-completion` within morph-spec workflows. It adds:
+- Phase-specific checklists (not just generic verification)
+- `morph-spec validate-feature` integration
+- Checkpoint system integration
+- State tracking verification
+
+For verification **outside** morph-spec workflows, the original `superpowers:verification-before-completion` skill remains available.
+
+---
+
+## Anti-patterns
+
+- Never claim "tests pass" without actually running them
+- Never skip validation because "the change is small"
+- Never mark a task done if build is broken
+- Never advance phases without checking the phase checklist
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/morph-replicate.md

@@ -1,3 +1,11 @@
+---
+name: morph-replicate
+description: >
+  Replicates a completed MORPH-SPEC feature into a new feature, copying and adapting phase outputs. Called when a user wants to clone an existing feature as a starting point.
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # Skill: /morph-replicate
 
 > Workflow simplificado para replicar prototipos HTML em Blazor.
@@ -210,4 +218,4 @@ Mapeamento HTML → Blazor:
 
 ---
 
-*MORPH-SPEC v2.2.0 by Polymorphism Tech*
+*MORPH-SPEC v2.2.0 by Polymorphism Tech*

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

@@ -1,3 +1,12 @@
+---
+name: phase-clarify
+description: >
+  MORPH-SPEC Phase 3 (Clarify). Resolves ambiguities from the design phase, producing clarifications.md and updating the spec. Called after design approval.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # MORPH Clarify - FASE 3
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
@@ -10,11 +19,38 @@ Identifique ambiguidades na especificação e faça perguntas de clarificação
 - [ ] `spec.md` aprovado pelo usuário
 - [ ] `contracts.cs` definidos
 
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler spec.md completo | **Read** spec.md | — |
+| Ler contracts.cs | **Read** contracts.cs | — |
+| Ler schema-analysis.md | **Read** schema-analysis.md | — |
+| Verificar viabilidade de requisito | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Verificar issues/limitações conhecidas | **GitHub MCP** `search_issues()` | **Bash** `gh issue list --search "..."` |
+| 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` | — |
+
+**MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
+
+**Anti-padrões:**
+- ❌ Task agent para ler spec (use Read direto)
+- ❌ Reescrever spec do zero (use Edit para atualizar seções)
+- ❌ Pular cross-reference com schema-analysis.md (crítico para precisão)
+
+---
+
 ## Workflow
 
 ### Passo 1: Analisar Spec
 
-Leia `.morph/project/outputs/{feature}/spec.md` em detalhes e identifique:
+Leia `.morph/features/$ARGUMENTS/1-design/spec.md` em detalhes e identifique:
 
 #### 1.1. Ambiguidades
 - Requisitos vagos ou genéricos
@@ -90,6 +126,21 @@ Após receber respostas do usuário, atualize o spec com:
 
 2. **Atualizar seções relevantes** com detalhes adicionados
 
+### CHECKPOINT: Validar Respostas Completas
+
+**⏸️ PAUSE - Antes de atualizar spec:**
+
+- [ ] Todas as perguntas foram respondidas pelo usuário?
+- [ ] Nenhuma resposta é ambígua ou contraditória?
+- [ ] Respostas são consistentes com `contracts.cs` existente?
+- [ ] Respostas são consistentes com `schema-analysis.md`?
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar e pedir esclarecimento adicional ao usuário
+
+**✅ Se TODAS as checkboxes estiverem marcadas:**
+→ Prosseguir para atualizar spec.md
+
 ### Passo 6: Validar Edge Cases
 
 Documente no spec como lidar com cada edge case identificado:
@@ -106,12 +157,12 @@ Documente no spec como lidar com cada edge case identificado:
 ### Passo 7: Atualizar State
 
 ```bash
-npx morph-spec state set {feature-name} phase clarify
+npx morph-spec state set $ARGUMENTS phase clarify
 ```
 
 ## Outputs Gerados/Atualizados
 
-- `.morph/project/outputs/{feature}/spec.md` - Atualizado com:
+- `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
   - Seção "Clarifications" com perguntas e respostas
   - Edge cases documentados
   - Requisitos mais específicos
@@ -128,4 +179,14 @@ npx morph-spec state set {feature-name} phase clarify
 
 ---
 
-Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `systematic-debugging` | Para investigar ambiguidades técnicas complexas | `Skill(superpowers:systematic-debugging)` |
+
+---
+
+Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.