@polymorphism-tech/morph-spec 4.10.7 → 4.10.8

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

@@ -1,500 +1,508 @@
----
-name: morph-phase-implement
-description: MORPH-SPEC Phase 5 (Implement). Executes feature tasks using TDD with checkpoint validation every 3 tasks, smoke tests via Playwright, and generates code + recap.md. Use after task list approval when starting feature implementation.
-argument-hint: "[feature-name]"
-context: fork
-agent: general-purpose
-user-invocable: false
-cliVersion: "4.10.7"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
----
-
-# MORPH Implement — Phase 5
-
-> INTERNAL: Workflow skill used by /morph-apply during automated phase orchestration. Not a user command.
-
-Implement the tasks defined in Phase 4, with checkpoints every 3 tasks and a final recap.
-
-## Prerequisites
-
-- [ ] Phase 4 (Tasks) completed
-- [ ] `tasks.md` approved by user
-- [ ] Tasks gate approved (`morph-spec approve $ARGUMENTS tasks`)
-- [ ] All design outputs exist (spec.md, contracts.cs/.ts, decisions.md)
-
-## Step 0: Ensure Implement Phase
-
-**Before any reads or writes — verify the current phase:**
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field:
-
-**If `"phase": "implement"`** → correct phase, proceed.
-
-**If `"phase": "tasks"`** → run in sequence:
-1. `npx morph-spec state mark-output $ARGUMENTS tasks`
-2. `npx morph-spec approve $ARGUMENTS tasks`
-3. `npx morph-spec phase advance $ARGUMENTS` (→ implement)
-
-**Any other value** → STOP — inconsistent state, report to user.
-
-> **Rule:** Never write to `5-implement/` until the phase is `implement`. The hook will block writes.
-
----
-
-## Pre-flight Validation (MANDATORY)
-
-Before any task work, validate that prior phases are truly complete. `state.json` may have been set manually — these commands verify actual filesystem artifacts.
-
-```bash
-# 1. Verify mandatory outputs from all prior phases
-npx morph-spec validate-feature $ARGUMENTS
-
-# 2. Confirm all approval gates passed
-npx morph-spec approval-status $ARGUMENTS
-
-# 3. Verify activeAgents are populated
-npx morph-spec state get $ARGUMENTS | grep -A5 activeAgents
-```
-
-If any check fails → **STOP**. Do not start any task. Report what's missing:
-
-| Problem | Resolution |
-|---------|-----------|
-| Missing output (spec.md, contracts, etc.) | Return to corresponding phase and generate it |
-| Gate not approved (design, plan, tasks) | `npx morph-spec approve $ARGUMENTS <gate>` |
-| Invalid phase | `npx morph-spec phase advance $ARGUMENTS` |
-| Empty activeAgents | Run `/phase-setup $ARGUMENTS` first |
-
-**This step is not optional.** Only proceed when all commands return without errors.
-
----
-
-## Pre-flight MCP — Connection Validation
-
-Before starting tasks, verify that MCPs needed for the implement phase are working.
-
-**1. Collect MCPs for the implement phase:**
-- Read `framework/skills/level-0-meta/mcp-registry.json` → `phaseMatrix.implement`
-- Read `.claude/settings.local.json` → identify configured MCPs
-
-**2. For each CONFIGURED MCP in `phaseMatrix.implement`:**
-1. Look for a tool matching `healthCheck.toolPattern`
-2. If found → run `healthCheck.testCall` with `healthCheck.testParams`
-3. Evaluate:
-
-| Result | Action |
-|--------|--------|
-| **Success** | `✓ {MCP} — ready` |
-| **Tool not found** | `○ {MCP} — needs restart` |
-| **Error** | → **AskUserQuestion** (below) |
-
-**On error — ask the user:**
-
-Use `AskUserQuestion` with header `"{MCP}"` and options:
-- **Continue without {MCP}** — Show `fallback` from registry. Implementation will use the fallback automatically.
-- **Reconfigure credentials** — Collect credentials and update `.claude/settings.local.json`. Re-test after reconfiguring.
-- **Stop implementation** — Abort. User must fix the MCP and re-run `/morph-apply`.
-
-> **Design:** This check is fail-open — consistent with morph-spec philosophy. The user gets explicit choice instead of tasks failing silently.
-
----
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
-> **Example:** `references/recap-example.md` — filled-in recap.md showing expected output quality.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Check execution mode (single/subagents/agent-teams) | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Task groups + subagent prompts |
-| **Dispatch implementers by domain** (subagents) | **Agent** `subagent_type=<taskGroups[group].subagentType>` + `prompt=taskPrompt` from dispatch config | Backend + frontend + infra in parallel |
-| **Create Agent Team** (critical multi-domain features) | Natural language — see Step 0.5b | — |
-| Read task details | **Read** tasks.md, spec.md, contracts.cs/.ts | — |
-| Create new files | **Write** source files | — |
-| Modify existing files | **Edit** source files | — |
-| Look up library API | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Run migrations | **Supabase MCP** `query()` | **Bash** `npx supabase migration ...` |
-| Build project | **Bash** `dotnet build` or `npm run build` | — |
-| Run tests | **Bash** `dotnet test` or `npm test` | — |
-| Checkpoint validation | **Bash** `npx morph-spec validate-feature ...` | — |
-| Mark task complete | **Bash** `npx morph-spec task done $ARGUMENTS T001` | — |
-| Smoke test in browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual |
-| Check console errors | **Playwright MCP** `browser_console_messages()` | — |
-| Screenshot for recap | **Playwright MCP** `browser_take_screenshot()` | — |
-| Deploy and logs Vercel | **Vercel MCP** `list_projects()`, `get_deployments()`, `manage_env_vars()` | **Bash** `vercel deploy` |
-| Create PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
-| Update state | **Bash** `npx morph-spec state set ...` | — |
-
-**Phase MCPs:** Supabase (migrations, RLS), Context7 (API lookup), Playwright (smoke test), GitHub (PRs), Vercel (deploy, logs, env vars).
-
-**Anti-patterns:**
-- Task agent for editing a single file (use Edit directly)
-- Agent Teams for single-domain features (subagents suffice)
-- Agent Teams without plan approval (creates risk of divergent implementations)
-- `Bash cat` to create files (use Write tool)
-- `Bash sed` to modify code (use Edit tool)
-- Implementing without reading contracts.cs/.ts first (contracts are the source of truth!)
-- Running backend and frontend tasks sequentially when they are independent
-- **(VSA)** Creating Application Service layer — handler accesses IRepository directly
-- **(VSA)** Manually registering handlers/endpoints in Program.cs — use auto-discovery via reflection
-- **(VSA)** Placing Request/Response in separate files from Handler
-- **(VSA)** Using `Guid.NewGuid()` — use `Guid.CreateVersion7()`
-- Trying to fix a bug without invoking `systematic-debugging` first
-
----
-
-## Context Loading
-
-### 1. Read full context in PARALLEL
-
-```
-# Single parallel call, not sequential:
-Read: .morph/features/{feature}/4-tasks/tasks.md
-    + Read: .morph/features/{feature}/1-design/spec.md
-    + Read: .morph/features/{feature}/1-design/contracts.cs  (or contracts.ts for TypeScript projects)
-    + Read: .morph/config/config.json                       (→ architecture.style)
-    + Read: .morph/features/{feature}/3-plan/plan.md
-```
-
-### 2. Create native tasks for each T001-T00N
-
-After reading `tasks.md`, create **one native task per task found**:
-
-```
-# For each task in tasks.md (T001, T002, ..., T00N):
-TaskCreate: "{T001}: {task title}"    → description: full description → activeForm: "Implementing T001"
-TaskCreate: "{T002}: {task title}"    → description: full description → activeForm: "Implementing T002"
-... (one TaskCreate per task)
-
-# Orchestral tasks always at the end:
-TaskCreate: "Checkpoints and validation" → activeForm: "Validating checkpoint"
-TaskCreate: "Generate recap.md"          → activeForm: "Generating recap"
-```
-
-**After creating all tasks, configure dependencies mirroring `tasks.md`:**
-```
-# For each task with `dependencies: [T00X, T00Y]` in tasks.md:
-TaskUpdate(taskId="<id of T003>", addBlockedBy=["<id of T001>", "<id of T002>"])
-```
-
-### 3. Detect architecture style
-
-```bash
-cat .morph/config/config.json | grep architecture
-```
-
-If `config.architecture.style === "vertical-slice"` → follow **Step 1.5** before implementing.
-Otherwise → go directly to the task loop.
-
-### Step 1.5: VSA Implementation Guide (only if `style: "vertical-slice"`)
-
-> For the complete slice structure and VSA rules, see `references/vsa-implementation-guide.md`
-
-Structure: `Features/{Entity}Feature/{Op}/` with Handler (+ Request/Response records) + Validator + Endpoint per slice. Everything `sealed`. `Guid.CreateVersion7()`. `result.Match()` in endpoints. No Application Service layer — handler accesses IRepository directly. Auto-discovery via reflection: do not manually register in Program.cs.
-
----
-
-## Workflow
-
-### Step 0.5: Plan Execution Mode
-
-**Read the plan's execution strategy:**
-```
-Read: .morph/features/{feature}/3-plan/plan.md → extract "Execution Strategy" field
-```
-
-The strategy was defined and approved in the Plan phase. Use it directly:
-
-| Strategy | Action |
-|----------|--------|
-| `"single"` | → Continue to the sequential task loop (Step 2) |
-| `"subagents"` | → Dispatch Task subagents in parallel (below) |
-| `"agent-teams"` | → Create Agent Team with plan approval (Step 0.5b) |
-
-If `plan.md` doesn't exist or the field is missing, auto-detect via dispatch-agents:
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement
-```
-
-Check the `mode` field in the JSON output to determine the execution strategy.
-
----
-
-#### Subagents Mode (if strategy is `"subagents"`):
-
-**Step 0.5a: Get dispatch config:**
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement
-```
-
-Parse the JSON output. Extract `taskGroups` and each group's `subagentType`.
-
-**Step 0.5b: Verify agent files exist:**
-
-For each group, verify `.claude/agents/{subagentType}.md` exists:
-
-```bash
-ls .claude/agents/{subagentType}.md
-```
-
-If missing → **STOP** with: `"Agent file .claude/agents/{subagentType}.md not found. Run: npx morph-spec setup-infra"`. Do NOT fall back to general-purpose agents for missing files.
-
-**Step 0.5c: Dispatch subagents:**
-
-1. For each group with >= 3 tasks and no cross-group dependencies, use **Agent tool** with `subagent_type` from dispatch config:
-
-> **Mapping:** `taskGroups[group].subagentType` = `subagent_type` in Agent tool.
-> Example: `subagentType: "morph-dotnet-senior"` → `Agent(subagent_type="morph-dotnet-senior", prompt=taskPrompt)`.
->
-> **MANDATORY:** Use the exact `subagentType` value. Do NOT use `general-purpose` agents when a `subagentType` is available.
-
-Each subagent receives a prompt with:
-- Full spec.md and contracts.cs/.ts content
-- The group's task list
-- Instructions to create native tasks, follow the task loop (start → implement → verify → done), checkpoint every 3 tasks
-- Domain isolation: modify ONLY files in their domain
-- **MANDATORY verification before every `task done`** (see Step 2, item 6b)
-
-2. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
-3. After all complete, validate integration: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
-
-**Fallback:** If `dispatch-agents` fails (non-zero exit or invalid JSON), log a warning and fall back to sequential single-agent mode (Step 2).
-
-**If strategy is `"single"`** → continue to sequential task loop below.
-
----
-
-#### Step 0.5b: Agent Teams (critical multi-domain features)
-
-**When:** strategy is `"agent-teams"`
-**Requirement:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.local.json`
-
-**Why Agent Teams over subagents:**
-Agent Teams have a shared TaskList, direct teammate messaging, and `TeammateIdle` hooks. Subagents are fire-and-forget. For features where backend and frontend need to coordinate API contracts, Agent Teams ensure frontend doesn't implement calls before backend stabilizes DTOs.
-
-Create the team with natural language specifying:
-- Backend teammate (dotnet-senior): backend/domain/application files only
-- Frontend teammate (blazor-builder or nextjs-expert): UI/components/pages files only
-- Quality teammate (standards-architect): review + validate-feature after each implementation
-- Enable **plan approval**: teammates must get plans approved before implementing
-- Gate: only approve plans matching contracts.cs/.ts and spec.md
-
-After all teammates complete: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
-
----
-
-### Step 2: Task Loop
-
-```bash
-npx morph-spec task next $ARGUMENTS
-```
-
-For each task (T001 → T00N):
-
-1. **Mark as in-progress (native task):**
-   ```
-   TaskUpdate(taskId="<native id>", status="in_progress")
-   ```
-2. **Start via CLI:**
-   ```bash
-   npx morph-spec task start $ARGUMENTS T001
-   ```
-3. **Read the task description** + contracts.cs/.ts for relevant DTOs/interfaces
-4. **Implement** using Write (new) or Edit (existing)
-5. **Verify** — build, lint, tests
-6. **MANDATORY — Verification before `task done`:**
-   Run `validate-feature` before marking ANY task as done. This is non-negotiable — it catches broken code, missing files, and spec violations before they compound across tasks.
-   ```bash
-   npx morph-spec validate-feature $ARGUMENTS --phase implement
-   ```
-   Only proceed to step 7 if verification passes. If it fails → fix before marking `task done`.
-7. **Mark as done via CLI:**
-   ```bash
-   npx morph-spec task done $ARGUMENTS T001
-   ```
-8. **If `task done` returns without error, mark native task as completed:**
-   ```
-   TaskUpdate(taskId="<native id>", status="completed")
-   ```
-   > `TaskUpdate(completed)` only happens if `task done` returns without error (validation passed).
-
-### Step 3: Checkpoint Every 3 Tasks
-
-**After every 3 completed tasks:**
-
-```bash
-# Save checkpoint
-npx morph-spec checkpoint-save $ARGUMENTS
-
-# Run validation
-npx morph-spec validate-feature $ARGUMENTS --phase implement
-```
-
-**If validation fails:**
-1. Do NOT advance to the next task
-2. Fix reported issues
-3. Re-run validation
-4. Only then proceed
-
-### Step 4: Test-Driven Development (Recommended)
-
-For each implementation task:
-
-1. **Write test first** (unit test for service/domain)
-2. **Run test** — should fail (RED)
-3. **Implement** the minimum to pass
-4. **Run test** — should pass (GREEN)
-5. **Refactor** if needed (REFACTOR)
-
-```bash
-# .NET
-dotnet test --filter "FullyQualifiedName~{TestClass}"
-
-# Node.js
-npm test -- test/path/to/test.js
-```
-
-### Step 5: Smoke Test with Playwright (if UI)
-
-After implementing visual components:
-
-```javascript
-// Navigate to the page
-await mcp__playwright__browser_navigate({ url: 'http://localhost:5000/feature-page' });
-
-// Capture page state
-await mcp__playwright__browser_snapshot();
-
-// Check console errors
-await mcp__playwright__browser_console_messages({ level: 'error' });
-
-// Screenshot for recap
-await mcp__playwright__browser_take_screenshot({ type: 'png' });
-```
-
-### Step 6: Generate `recap.md`
-
-After ALL tasks completed:
-
-```bash
-npx morph-spec generate recap $ARGUMENTS
-```
-
-> For the full recap format, see `references/recap-example.md`
-
-### Step 7: Update State
-
-```bash
-npx morph-spec state set $ARGUMENTS status done
-npx morph-spec state mark-output $ARGUMENTS recap
-```
-
-### Step 8: Post-Implementation Review (mandatory before PR)
-
-```bash
-/post-implementation $ARGUMENTS
-```
-
-Run the `post-implementation` skill before creating the PR. It orchestrates:
-- Automated scans (CRITICAL findings block PR)
-- Full test suite
-- Final `validate-feature`
-- Smoke test via Playwright (mandatory if dev server active)
-- Code review checklist (CRITICAL + HIGH)
-- **`morph-checklist`** — compliance (security, SEO, performance, accessibility, LGPD)
-- Checkpoint + final recap
-
-### Step 9: Frontend Review (NEXTJS/FULLSTACK)
-
-If stack is NEXTJS or FULLSTACK:
-
-```bash
-/frontend-review $ARGUMENTS
-```
-
-Complements `post-implementation` with: accessibility scan (static + axe-core runtime),
-responsive screenshots (mobile/tablet/desktop), and SEO metadata verification.
-
----
-
-## Morph-Native Dispatch
-
-morph-spec uses its own agents and validators for implementation, dispatch, and review.
-
-### Implementation
-
-Implementers are dispatched via `dispatch-agents`:
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement
-```
-
-Use the `subagentType` from each group in the Agent tool:
-```
-Agent(subagent_type=<subagentType>, prompt=<filled prompts/implementer-prompt.md>)
-```
-
-> The `subagentType` maps agent IDs to `.claude/agents/` filenames:
-> - Tier 1-3: `morph-{id}` (e.g., `morph-dotnet-senior`)
-> - Tier 4: `morph-validator-{id}` (e.g., `morph-validator-architecture-expert`)
-
-### Review (Two-Stage)
-
-**Stage 1 — Spec Compliance (mandatory):**
-```
-Agent(subagent_type=<validator subagentType>, prompt=<filled prompts/spec-reviewer-prompt.md>)
-```
-Use validators from `dispatch-agents --mode validate`. Spec compliance MUST pass before proceeding.
-
-**Stage 2 — Code Quality (mandatory):**
-```
-Agent(subagent_type=morph-standards-architect, prompt=<filled prompts/code-quality-reviewer-prompt.md>)
-```
-`critical` issues block. `important` issues must be fixed. `suggestion` is optional.
-
-### Prompt Templates
-
-| Template | Usage |
-|----------|-------|
-| `prompts/implementer-prompt.md` | Dispatch to implementer agents |
-| `prompts/spec-reviewer-prompt.md` | Spec compliance review |
-| `prompts/code-quality-reviewer-prompt.md` | Code quality review |
-
----
-
-## Outputs
-
-- Implemented source code (various files)
-- Unit and integration tests
-- `.morph/features/$ARGUMENTS/5-implement/recap.md` — Implementation summary
-
-## Completion Criteria
-
-- [x] All tasks completed
-- [x] Build compiles without errors
-- [x] Tests passing
-- [x] Validation pipeline passes
-- [x] `recap.md` generated
-- [x] State updated to `status: done`
-- [x] Checkpoints saved every 3 tasks
-- [x] `/post-implementation` executed without BLOCKs
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:implement -->
-| Output | Path |
-|--------|------|
-| `recap` | `.morph/features/{feature}/5-implement/recap.md` |
-<!-- /morph-outputs -->
-
----
-
-Feature complete! Consider creating a PR and running `morph-spec generate recap $ARGUMENTS`.
+---
+name: morph-phase-implement
+description: MORPH-SPEC Phase 5 (Implement). Executes feature tasks using TDD with checkpoint validation every 3 tasks, smoke tests via Playwright, and generates code + recap.md. Use after task list approval when starting feature implementation.
+argument-hint: "[feature-name]"
+context: fork
+agent: general-purpose
+user-invocable: false
+cliVersion: "4.10.8"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
+
+# MORPH Implement — Phase 5
+
+> INTERNAL: Workflow skill used by /morph-apply during automated phase orchestration. Not a user command.
+
+Implement the tasks defined in Phase 4, with checkpoints every 3 tasks and a final recap.
+
+## Prerequisites
+
+- [ ] Phase 4 (Tasks) completed
+- [ ] `tasks.md` approved by user
+- [ ] Tasks gate approved (`morph-spec approve $ARGUMENTS tasks`)
+- [ ] All design outputs exist (spec.md, contracts.cs/.ts, decisions.md)
+
+## Step 0: Ensure Implement Phase
+
+**Before any reads or writes — verify the current phase:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field:
+
+**If `"phase": "implement"`** → correct phase, proceed.
+
+**If `"phase": "tasks"`** → run in sequence:
+1. `npx morph-spec state mark-output $ARGUMENTS tasks`
+2. `npx morph-spec approve $ARGUMENTS tasks`
+3. `npx morph-spec phase advance $ARGUMENTS` (→ implement)
+
+**Any other value** → STOP — inconsistent state, report to user.
+
+> **Rule:** Never write to `5-implement/` until the phase is `implement`. The hook will block writes.
+
+---
+
+## Pre-flight Validation (MANDATORY)
+
+Before any task work, validate that prior phases are truly complete. `state.json` may have been set manually — these commands verify actual filesystem artifacts.
+
+```bash
+# 1. Verify mandatory outputs from all prior phases
+npx morph-spec validate-feature $ARGUMENTS
+
+# 2. Confirm all approval gates passed
+npx morph-spec approval-status $ARGUMENTS
+
+# 3. Verify activeAgents are populated
+npx morph-spec state get $ARGUMENTS | grep -A5 activeAgents
+```
+
+If any check fails → **STOP**. Do not start any task. Report what's missing:
+
+| Problem | Resolution |
+|---------|-----------|
+| Missing output (spec.md, contracts, etc.) | Return to corresponding phase and generate it |
+| Gate not approved (design, plan, tasks) | `npx morph-spec approve $ARGUMENTS <gate>` |
+| Invalid phase | `npx morph-spec phase advance $ARGUMENTS` |
+| Empty activeAgents | Run `/phase-setup $ARGUMENTS` first |
+
+**This step is not optional.** Only proceed when all commands return without errors.
+
+---
+
+## Pre-flight MCP — Connection Validation
+
+Before starting tasks, verify that MCPs needed for the implement phase are working.
+
+**1. Collect MCPs for the implement phase:**
+- Read `framework/skills/level-0-meta/mcp-registry.json` → `phaseMatrix.implement`
+- Read `.claude/settings.local.json` → identify configured MCPs
+
+**2. For each CONFIGURED MCP in `phaseMatrix.implement`:**
+1. Look for a tool matching `healthCheck.toolPattern`
+2. If found → run `healthCheck.testCall` with `healthCheck.testParams`
+3. Evaluate:
+
+| Result | Action |
+|--------|--------|
+| **Success** | `✓ {MCP} — ready` |
+| **Tool not found** | `○ {MCP} — needs restart` |
+| **Error** | → **AskUserQuestion** (below) |
+
+**On error — ask the user:**
+
+Use `AskUserQuestion` with header `"{MCP}"` and options:
+- **Continue without {MCP}** — Show `fallback` from registry. Implementation will use the fallback automatically.
+- **Reconfigure credentials** — Collect credentials and update `.claude/settings.local.json`. Re-test after reconfiguring.
+- **Stop implementation** — Abort. User must fix the MCP and re-run `/morph-apply`.
+
+> **Design:** This check is fail-open — consistent with morph-spec philosophy. The user gets explicit choice instead of tasks failing silently.
+
+---
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
+> **Example:** `references/recap-example.md` — filled-in recap.md showing expected output quality.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Check execution mode (single/subagents/agent-teams) | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Task groups + subagent prompts |
+| **Dispatch implementers by domain** (subagents) | **Agent** `subagent_type=<taskGroups[group].subagentType>` + `prompt=taskPrompt` from dispatch config | Backend + frontend + infra in parallel |
+| **Create Agent Team** (critical multi-domain features) | Natural language — see Step 0.5b | — |
+| Read task details | **Read** tasks.md, spec.md, contracts.cs/.ts | — |
+| Create new files | **Write** source files | — |
+| Modify existing files | **Edit** source files | — |
+| Look up library API | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Run migrations | **Supabase MCP** `query()` | **Bash** `npx supabase migration ...` |
+| Build project | **Bash** `dotnet build` or `npm run build` | — |
+| Run tests | **Bash** `dotnet test` or `npm test` | — |
+| Checkpoint validation | **Bash** `npx morph-spec validate-feature ...` | — |
+| Mark task complete | **Bash** `npx morph-spec task done $ARGUMENTS T001` | — |
+| Smoke test in browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual |
+| Check console errors | **Playwright MCP** `browser_console_messages()` | — |
+| Screenshot for recap | **Playwright MCP** `browser_take_screenshot()` | — |
+| Deploy and logs Vercel | **Vercel MCP** `list_projects()`, `get_deployments()`, `manage_env_vars()` | **Bash** `vercel deploy` |
+| Create PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
+| Update state | **Bash** `npx morph-spec state set ...` | — |
+
+**Phase MCPs:** Supabase (migrations, RLS), Context7 (API lookup), Playwright (smoke test), GitHub (PRs), Vercel (deploy, logs, env vars).
+
+**Anti-patterns:**
+- Task agent for editing a single file (use Edit directly)
+- Agent Teams for single-domain features (subagents suffice)
+- Agent Teams without plan approval (creates risk of divergent implementations)
+- `Bash cat` to create files (use Write tool)
+- `Bash sed` to modify code (use Edit tool)
+- Implementing without reading contracts.cs/.ts first (contracts are the source of truth!)
+- Running backend and frontend tasks sequentially when they are independent
+- **(VSA)** Creating Application Service layer — handler accesses IRepository directly
+- **(VSA)** Manually registering handlers/endpoints in Program.cs — use auto-discovery via reflection
+- **(VSA)** Placing Request/Response in separate files from Handler
+- **(VSA)** Using `Guid.NewGuid()` — use `Guid.CreateVersion7()`
+- Trying to fix a bug without invoking `systematic-debugging` first
+
+---
+
+## Context Loading
+
+### 1. Read full context in PARALLEL
+
+```
+# Single parallel call, not sequential:
+Read: .morph/features/{feature}/4-tasks/tasks.md
+    + Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs  (or contracts.ts for TypeScript projects)
+    + Read: .morph/config/config.json                       (→ architecture.style)
+    + Read: .morph/features/{feature}/3-plan/plan.md
+```
+
+### 2. Create native tasks for each T001-T00N
+
+Create one native task per task found in `tasks.md`, mirroring `tasks.md` exactly:
+
+```
+# one native task per task found — loop over every T001-T00N:
+TaskCreate: "T001: {title}"
+  → description: "{full task description from tasks.md}"
+  → activeForm: "Implementing T001"
+
+TaskCreate: "T002: {title}"
+  → activeForm: "Implementing T002"
+
+# ... repeat for each task ...
+
+# Orchestral tasks (always at the end):
+TaskCreate: "Checkpoints and validation" → activeForm: "Validating checkpoint"
+TaskCreate: "Generate recap.md"          → activeForm: "Generating recap"
+```
+
+**After creating all tasks, wire up dependencies using `addBlockedBy`**, mirroring `tasks.md` dependency fields:
+
+```
+# For each task with dependencies (e.g., T003 depends on T001, T002):
+TaskUpdate: taskId="{T003 native id}" addBlockedBy=["{T001 native id}", "{T002 native id}"]
+```
+
+> Map T-codes to native task IDs as you create them (keep a local `{ T001: id, T002: id, ... }` map).
+
+### 3. Detect architecture style
+
+```bash
+cat .morph/config/config.json | grep architecture
+```
+
+If `config.architecture.style === "vertical-slice"` → follow **Step 1.5** before implementing.
+Otherwise → go directly to the task loop.
+
+### Step 1.5: VSA Implementation Guide (only if `style: "vertical-slice"`)
+
+> For the complete slice structure and VSA rules, see `references/vsa-implementation-guide.md`
+
+Structure: `Features/{Entity}Feature/{Op}/` with Handler (+ Request/Response records) + Validator + Endpoint per slice. Everything `sealed`. `Guid.CreateVersion7()`. `result.Match()` in endpoints. No Application Service layer — handler accesses IRepository directly. Auto-discovery via reflection: do not manually register in Program.cs.
+
+---
+
+## Workflow
+
+### Step 0.5: Plan Execution Mode
+
+**Read the plan's execution strategy:**
+```
+Read: .morph/features/{feature}/3-plan/plan.md → extract "Execution Strategy" field
+```
+
+The strategy was defined and approved in the Plan phase. Use it directly:
+
+| Strategy | Action |
+|----------|--------|
+| `"single"` | → Continue to the sequential task loop (Step 2) |
+| `"subagents"` | → Dispatch Task subagents in parallel (below) |
+| `"agent-teams"` | → Create Agent Team with plan approval (Step 0.5b) |
+
+If `plan.md` doesn't exist or the field is missing, auto-detect via dispatch-agents:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+Check the `mode` field in the JSON output to determine the execution strategy.
+
+---
+
+#### Subagents Mode (if strategy is `"subagents"`):
+
+**Step 0.5a: Get dispatch config:**
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+Parse the JSON output. Extract `taskGroups` and each group's `subagentType`.
+
+**Step 0.5b: Verify agent files exist:**
+
+For each group, verify `.claude/agents/{subagentType}.md` exists:
+
+```bash
+ls .claude/agents/{subagentType}.md
+```
+
+If missing → **STOP** with: `"Agent file .claude/agents/{subagentType}.md not found. Run: npx morph-spec setup-infra"`. Do NOT fall back to general-purpose agents for missing files.
+
+**Step 0.5c: Dispatch subagents:**
+
+1. For each group with >= 3 tasks and no cross-group dependencies, use **Agent tool** with `subagent_type` from dispatch config:
+
+> **Mapping:** `taskGroups[group].subagentType` = `subagent_type` in Agent tool.
+> Example: `subagentType: "morph-dotnet-senior"` → `Agent(subagent_type="morph-dotnet-senior", prompt=taskPrompt)`.
+>
+> **MANDATORY:** Use the exact `subagentType` value. Do NOT use `general-purpose` agents when a `subagentType` is available.
+
+Each subagent receives a prompt with:
+- Full spec.md and contracts.cs/.ts content
+- The group's task list
+- Instructions to create native tasks, follow the task loop (start → implement → verify → done), checkpoint every 3 tasks
+- Domain isolation: modify ONLY files in their domain
+- **MANDATORY verification before every `task done`** (see Step 2, item 6b)
+
+2. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
+3. After all complete, validate integration: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+
+**Fallback:** If `dispatch-agents` fails (non-zero exit or invalid JSON), log a warning and fall back to sequential single-agent mode (Step 2).
+
+**If strategy is `"single"`** → continue to sequential task loop below.
+
+---
+
+#### Step 0.5b: Agent Teams (critical multi-domain features)
+
+**When:** strategy is `"agent-teams"`
+**Requirement:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.local.json`
+
+**Why Agent Teams over subagents:**
+Agent Teams have a shared TaskList, direct teammate messaging, and `TeammateIdle` hooks. Subagents are fire-and-forget. For features where backend and frontend need to coordinate API contracts, Agent Teams ensure frontend doesn't implement calls before backend stabilizes DTOs.
+
+Create the team with natural language specifying:
+- Backend teammate (dotnet-senior): backend/domain/application files only
+- Frontend teammate (blazor-builder or nextjs-expert): UI/components/pages files only
+- Quality teammate (standards-architect): review + validate-feature after each implementation
+- Enable **plan approval**: teammates must get plans approved before implementing
+- Gate: only approve plans matching contracts.cs/.ts and spec.md
+
+After all teammates complete: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+
+---
+
+### Step 2: Task Loop
+
+```bash
+npx morph-spec task next $ARGUMENTS
+```
+
+For each task (T001 → T00N):
+
+1. **Mark as in-progress (native task):**
+   ```
+   TaskUpdate(taskId="<native id>", status="in_progress")
+   ```
+2. **Start via CLI:**
+   ```bash
+   npx morph-spec task start $ARGUMENTS T001
+   ```
+3. **Read the task description** + contracts.cs/.ts for relevant DTOs/interfaces
+4. **Implement** using Write (new) or Edit (existing)
+5. **Verify** — build, lint, tests
+6. **MANDATORY — Verification before `task done`:**
+   Run `validate-feature` before marking ANY task as done. This is non-negotiable — it catches broken code, missing files, and spec violations before they compound across tasks.
+   ```bash
+   npx morph-spec validate-feature $ARGUMENTS --phase implement
+   ```
+   Only proceed to step 7 if verification passes. If it fails → fix before marking `task done`.
+7. **Mark as done via CLI:**
+   ```bash
+   npx morph-spec task done $ARGUMENTS T001
+   ```
+8. **If `task done` returns without error, update group task progress:**
+   - Increment completed count for the task's group
+   - `TaskUpdate(groupTaskId, subject="{Group} tasks ({first}-{last}) — {completed}/{total}")`
+   - If all tasks in the group are done: `TaskUpdate(groupTaskId, status="completed")`
+   > Progress update only happens if `task done` returns without error (validation passed).
+
+### Step 3: Checkpoint Every 3 Tasks
+
+**After every 3 completed tasks:**
+
+```bash
+# Save checkpoint
+npx morph-spec checkpoint-save $ARGUMENTS
+
+# Run validation
+npx morph-spec validate-feature $ARGUMENTS --phase implement
+```
+
+**If validation fails:**
+1. Do NOT advance to the next task
+2. Fix reported issues
+3. Re-run validation
+4. Only then proceed
+
+### Step 4: Test-Driven Development (Recommended)
+
+For each implementation task:
+
+1. **Write test first** (unit test for service/domain)
+2. **Run test** — should fail (RED)
+3. **Implement** the minimum to pass
+4. **Run test** — should pass (GREEN)
+5. **Refactor** if needed (REFACTOR)
+
+```bash
+# .NET
+dotnet test --filter "FullyQualifiedName~{TestClass}"
+
+# Node.js
+npm test -- test/path/to/test.js
+```
+
+### Step 5: Smoke Test with Playwright (if UI)
+
+After implementing visual components:
+
+```javascript
+// Navigate to the page
+await mcp__playwright__browser_navigate({ url: 'http://localhost:5000/feature-page' });
+
+// Capture page state
+await mcp__playwright__browser_snapshot();
+
+// Check console errors
+await mcp__playwright__browser_console_messages({ level: 'error' });
+
+// Screenshot for recap
+await mcp__playwright__browser_take_screenshot({ type: 'png' });
+```
+
+### Step 6: Generate `recap.md`
+
+After ALL tasks completed:
+
+```bash
+npx morph-spec generate recap $ARGUMENTS
+```
+
+> For the full recap format, see `references/recap-example.md`
+
+### Step 7: Update State
+
+```bash
+npx morph-spec state set $ARGUMENTS status done
+npx morph-spec state mark-output $ARGUMENTS recap
+```
+
+### Step 8: Post-Implementation Review (mandatory before PR)
+
+```bash
+/post-implementation $ARGUMENTS
+```
+
+Run the `post-implementation` skill before creating the PR. It orchestrates:
+- Automated scans (CRITICAL findings block PR)
+- Full test suite
+- Final `validate-feature`
+- Smoke test via Playwright (mandatory if dev server active)
+- Code review checklist (CRITICAL + HIGH)
+- **`morph-checklist`** — compliance (security, SEO, performance, accessibility, LGPD)
+- Checkpoint + final recap
+
+### Step 9: Frontend Review (NEXTJS/FULLSTACK)
+
+If stack is NEXTJS or FULLSTACK:
+
+```bash
+/frontend-review $ARGUMENTS
+```
+
+Complements `post-implementation` with: accessibility scan (static + axe-core runtime),
+responsive screenshots (mobile/tablet/desktop), and SEO metadata verification.
+
+---
+
+## Morph-Native Dispatch
+
+morph-spec uses its own agents and validators for implementation, dispatch, and review.
+
+### Implementation
+
+Implementers are dispatched via `dispatch-agents`:
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+Use the `subagentType` from each group in the Agent tool:
+```
+Agent(subagent_type=<subagentType>, prompt=<filled prompts/implementer-prompt.md>)
+```
+
+> The `subagentType` maps agent IDs to `.claude/agents/` filenames:
+> - Tier 1-3: `morph-{id}` (e.g., `morph-dotnet-senior`)
+> - Tier 4: `morph-validator-{id}` (e.g., `morph-validator-architecture-expert`)
+
+### Review (Two-Stage)
+
+**Stage 1 — Spec Compliance (mandatory):**
+```
+Agent(subagent_type=<validator subagentType>, prompt=<filled prompts/spec-reviewer-prompt.md>)
+```
+Use validators from `dispatch-agents --mode validate`. Spec compliance MUST pass before proceeding.
+
+**Stage 2 — Code Quality (mandatory):**
+```
+Agent(subagent_type=morph-standards-architect, prompt=<filled prompts/code-quality-reviewer-prompt.md>)
+```
+`critical` issues block. `important` issues must be fixed. `suggestion` is optional.
+
+### Prompt Templates
+
+| Template | Usage |
+|----------|-------|
+| `prompts/implementer-prompt.md` | Dispatch to implementer agents |
+| `prompts/spec-reviewer-prompt.md` | Spec compliance review |
+| `prompts/code-quality-reviewer-prompt.md` | Code quality review |
+
+---
+
+## Outputs
+
+- Implemented source code (various files)
+- Unit and integration tests
+- `.morph/features/$ARGUMENTS/5-implement/recap.md` — Implementation summary
+
+## Completion Criteria
+
+- [x] All tasks completed
+- [x] Build compiles without errors
+- [x] Tests passing
+- [x] Validation pipeline passes
+- [x] `recap.md` generated
+- [x] State updated to `status: done`
+- [x] Checkpoints saved every 3 tasks
+- [x] `/post-implementation` executed without BLOCKs
+
+---
+
+## Phase Outputs
+
+<!-- morph-outputs:implement -->
+| Output | Caminho |
+|--------|---------|
+| `recap` | `.morph/features/{feature}/5-implement/recap.md` |
+<!-- /morph-outputs -->
+
+---
+
+Feature complete! Consider creating a PR and running `morph-spec generate recap $ARGUMENTS`.