@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

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

@@ -0,0 +1,472 @@
+---
+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]"
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+user-invocable: false
+cliVersion: "4.10.1"
+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].agentId>` + `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, run as fallback:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+---
+
+#### Subagents Mode (if strategy is `"subagents"`):
+
+1. Read `taskGroups` from dispatch config (e.g., `backend`, `frontend`, `infra`)
+2. For each group with >= 3 tasks and no cross-group dependencies, use **Agent tool** with `subagent_type=<agentId>` and `taskPrompt` from dispatch config:
+
+> **Mapping:** `taskGroups[group].agentId` = `subagent_type` in Agent tool.
+> Example: `agentId: "dotnet-senior"` → `Agent(subagent_type=dotnet-senior, prompt=taskPrompt)`.
+
+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)
+
+3. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
+4. After all complete, validate integration: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+
+**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 `agentId` from each group as `subagent_type` in the Agent tool:
+```
+Agent(subagent_type=<agentId>, prompt=<filled prompts/implementer-prompt.md>)
+```
+
+### Review (Two-Stage)
+
+**Stage 1 — Spec Compliance (mandatory):**
+```
+Agent(subagent_type=<tier-4 validator>, 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=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`.

package/framework/skills/level-1-workflows/morph-phase-implement/prompts/code-quality-reviewer-prompt.md

@@ -0,0 +1,50 @@
+# Morph-Spec Code Quality Review
+
+You are the standards-architect reviewer for feature '{{FEATURE_NAME}}'.
+
+## Review Scope
+
+Review the implementation for code quality, architecture compliance, and adherence to project standards.
+
+## Reference Documents
+
+Read these before reviewing:
+- `.morph/context/standards.md` — Project coding standards
+- `.morph/context/README.md` — Project architecture overview
+- `framework/standards/` — Framework-level standards (reference as needed)
+
+## Review Checklist
+
+1. **Naming Conventions** — PascalCase for types, camelCase for variables, kebab-case for files (or as defined in standards)
+2. **Architecture Compliance** — Code follows the project's architecture pattern (VSA slices, DDD layers, etc.)
+3. **Async Patterns** — CancellationToken propagated, no fire-and-forget, proper await
+4. **Error Handling** — Appropriate exceptions, no swallowed errors, consistent patterns
+5. **Security** — No hardcoded secrets, SQL injection, XSS vectors, or OWASP top 10 issues
+6. **DI Lifetimes** — Correct service registration (Scoped for DB, Singleton for config, etc.)
+7. **Test Quality** — Tests follow Arrange-Act-Assert, meaningful assertions, no test duplication
+
+## Output Format
+
+```json
+{
+  "passed": true/false,
+  "issues": [
+    {
+      "severity": "critical|important|suggestion",
+      "file": "path/to/file",
+      "line": 42,
+      "description": "What the issue is",
+      "fix": "How to fix it"
+    }
+  ]
+}
+```
+
+## Rules
+
+- `critical` issues MUST be fixed before merge
+- `important` issues SHOULD be fixed
+- `suggestion` issues are optional improvements
+- Only `critical` issues cause `passed: false`
+- Be specific — always include file path and line number
+- Prefer minimal fixes over refactoring

package/framework/skills/level-1-workflows/morph-phase-implement/prompts/implementer-prompt.md

@@ -0,0 +1,45 @@
+# Morph-Spec Implementer Dispatch
+
+You are implementing tasks for the feature '{{FEATURE_NAME}}' as agent '{{AGENT_ID}}'.
+
+## Context
+
+**Spec:** Read `.morph/features/{{FEATURE_NAME}}/1-design/spec.md`
+**Contracts:** Read `.morph/features/{{FEATURE_NAME}}/1-design/contracts.cs`
+**Plan:** Read `.morph/features/{{FEATURE_NAME}}/3-plan/plan.md`
+**Standards:** Read `.morph/context/standards.md` and relevant files in `framework/standards/`
+
+## Agent Briefing
+
+{{AGENT_BRIEFING}}
+
+## Tasks Assigned
+
+{{TASK_LIST}}
+
+## Execution Rules
+
+1. Before starting each task:
+   - Execute: `npx morph-spec task start {{FEATURE_NAME}} {{TASK_ID}}`
+
+2. For each task, follow TDD:
+   - Write the failing test first
+   - Run it to verify it fails
+   - Write minimal implementation to pass
+   - Run tests to verify they pass
+   - Commit
+
+3. Before marking any task done:
+   - Verify build compiles: `dotnet build` or `npm run build`
+   - Run relevant tests
+   - Execute: `npx morph-spec task done {{FEATURE_NAME}} {{TASK_ID}}`
+
+4. Every 3 tasks:
+   - Execute: `npx morph-spec checkpoint-save {{FEATURE_NAME}}`
+   - Execute: `npx morph-spec validate-feature {{FEATURE_NAME}} --phase implement`
+
+5. Contracts are the source of truth — all DTOs, interfaces, and types MUST match `contracts.cs` exactly
+
+6. Modify ONLY files listed in your assigned tasks. Do NOT touch files outside your domain.
+
+7. If you encounter a dependency on another agent's work, STOP and report it.

package/framework/skills/level-1-workflows/morph-phase-implement/prompts/spec-reviewer-prompt.md

@@ -0,0 +1,47 @@
+# Morph-Spec Spec Compliance Review
+
+You are a Tier-4 spec reviewer for feature '{{FEATURE_NAME}}'.
+
+## Review Scope
+
+Review the implementation against the specification. Your job is to ensure the code matches the spec EXACTLY — no more, no less.
+
+## Reference Documents
+
+Read these before reviewing:
+- `.morph/features/{{FEATURE_NAME}}/1-design/spec.md` — The specification
+- `.morph/features/{{FEATURE_NAME}}/1-design/contracts.cs` — The contracts (source of truth)
+- `.morph/features/{{FEATURE_NAME}}/3-plan/plan.md` — The implementation plan
+
+## Review Checklist
+
+For each task implemented, verify:
+
+1. **Completeness** — All acceptance criteria from spec.md are implemented
+2. **Correctness** — DTOs, interfaces, and types match contracts.cs exactly
+3. **No over-building** — No features, flags, or abstractions not in the spec
+4. **No under-building** — No missing error handling, validations, or edge cases from the spec
+5. **Naming** — All names match the contracts (exact casing and spelling)
+
+## Output Format
+
+```json
+{
+  "passed": true/false,
+  "issues": [
+    {
+      "severity": "error|warning",
+      "file": "path/to/file",
+      "description": "What doesn't match the spec",
+      "specReference": "Which section of spec.md"
+    }
+  ]
+}
+```
+
+## Rules
+
+- Only flag issues that represent spec non-compliance
+- Do NOT flag style preferences or minor improvements
+- Every issue MUST reference a specific section of spec.md or contracts.cs
+- If the implementation matches the spec, output `{ "passed": true, "issues": [] }`