@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

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

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.12.0"
+cliVersion: "4.13.0"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -73,33 +73,76 @@ If any check fails → **STOP**. Do not start any task. Report what's missing:
 
 ---
 
-## Pre-flight MCP — Connection Validation
+## Pre-flight — Tool Availability
 
-Before starting tasks, verify that MCPs needed for the implement phase are working.
+Before starting tasks, verify that CLIs and MCPs needed for this phase are available. The `inject-morph-context` hook reports both at session start.
 
-**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
+**1. Check CLIs (from session context `CLIs:` line):**
 
-**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:
+| CLI | Required for | If missing |
+|-----|-------------|------------|
+| `docker` | Container services (Supabase, Redis) | Start Docker Desktop |
+| `supabase` | Migrations, schema, RLS | `npm install -g supabase` |
+| `psql` | Direct DB queries | Included with Supabase CLI or install PostgreSQL client |
+| `az` | Azure resource management | `winget install Microsoft.AzureCLI` |
+| `gh` | GitHub PRs, issues | `winget install GitHub.cli` |
 
-| Result | Action |
-|--------|--------|
-| **Success** | `✓ {MCP} — ready` |
-| **Tool not found** | `○ {MCP} — needs restart` |
-| **Error** | → **AskUserQuestion** (below) |
+If a critical CLI shows `✗`, use `AskUserQuestion` to ask the user:
+- **Install now** — provide the install command
+- **Continue without it** — use fallback (e.g., WebSearch instead of `az`)
+- **Stop implementation** — user must fix and re-run
 
-**On error — ask the user:**
+**2. Check MCPs (from session context `MCPs:` line):**
 
-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`.
+For each MCP showing `✗ (recommended)`:
 
-> **Design:** This check is fail-open — consistent with morph-spec philosophy. The user gets explicit choice instead of tasks failing silently.
+| MCP | Fallback |
+|-----|----------|
+| **Context7** | WebSearch + WebFetch |
+| **Playwright** | `curl` / WebFetch (limited — no JS rendering) |
+| **GitHub** | `gh` CLI |
+| **Vercel** | `vercel` CLI |
+
+> **Design:** This check is fail-open — consistent with morph-spec philosophy. Missing tools are warnings, not blockers (except `docker` for Supabase projects).
+
+---
+
+## Scaffold & Code Templates (MANDATORY before first task)
+
+Before writing any implementation code, scaffold the feature structure using the CLI.
+
+### For .NET backend tasks (VSA):
+
+**Scaffold all CRUD slices for the feature:**
+```bash
+morph-spec scaffold dotnet $ENTITY create-$ENTITY
+morph-spec scaffold dotnet $ENTITY get-${ENTITY}-by-id
+morph-spec scaffold dotnet $ENTITY get-all-${ENTITY}s
+morph-spec scaffold dotnet $ENTITY update-$ENTITY
+morph-spec scaffold dotnet $ENTITY delete-$ENTITY
+```
+
+> Entity and errors are generated with the first slice and auto-skipped on subsequent ones.
+> After scaffolding, customize: fill in request/response properties, validation rules, and handler logic per contracts.cs.
+
+### For Next.js frontend tasks:
+
+**Scaffold the feature page:**
+```bash
+morph-spec scaffold nextjs $FEATURE
+```
+
+> After scaffolding, customize: add columns to DataTable, form fields, and Zod schema.
+
+### Template reference (for manual adjustments):
+```bash
+cat .morph/framework/templates/code/dotnet/feature/endpoint.cs.hbs
+cat .morph/framework/templates/frontend/nextjs/page.tsx.hbs
+```
+
+> **Rule:** All code MUST follow the patterns in these templates. Scaffold guarantees this. Do not invent different patterns.
+
+See `.morph/framework/templates/` for the full template index (abstractions, extensions, pipelines, jobs, tests).
 
 ---
 
@@ -111,14 +154,13 @@ Use `AskUserQuestion` with header `"{MCP}"` and options:
 
 | Action | Tool | Alternative |
 |--------|------|-------------|
-| Check execution mode (single/subagents/agent-teams) | **Bash** `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 | — |
+| Get dispatch recommendation | **Bash** `morph-spec dispatch-agents $ARGUMENTS implement` | Agent recommendations + task routing |
+| **Dispatch implementers by domain** | **Agent** `subagent_type=<recommended[group][0]>` — agent .md file provides the prompt | Backend + frontend + infra in parallel |
 | 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 ...` |
+| Run migrations | **Bash** `npx supabase migration up --local` | `psql <DB_URL>` for verification |
 | Build project | **Bash** `dotnet build` or `npm run build` | — |
 | Run tests | **Bash** `dotnet test` or `npm test` | — |
 | Checkpoint validation | **Bash** `morph-spec validate-feature ...` | — |
@@ -130,12 +172,13 @@ Use `AskUserQuestion` with header `"{MCP}"` and options:
 | Create PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
 | Update state | **Bash** `morph-spec state set ...` | — |
 
-**Phase MCPs:** Supabase (migrations, RLS), Context7 (API lookup), Playwright (smoke test), GitHub (PRs), Vercel (deploy, logs, env vars).
+**Phase tools:** Docker CLI (container health, logs), Supabase CLI (migrations, RLS — local Docker), Context7 (API lookup), Playwright (smoke test), GitHub (PRs), Vercel (deploy, logs, env vars).
+
+> **Supabase CLI:** When creating or running database migrations, use `npx supabase migration new <name>` to create, then `npx supabase migration up --local` to apply against the local Docker instance. Verify with `npx supabase db dump --local --schema public` or `psql` against local instance (get DB URL from `npx supabase status`).
 
 **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)
+- Subagents for single-domain features (sequential suffices)
 - `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!)
@@ -146,57 +189,24 @@ Use `AskUserQuestion` with header `"{MCP}"` and options:
 - **(VSA)** Using `Guid.NewGuid()` — use `Guid.CreateVersion7()`
 - Trying to fix a bug without invoking `systematic-debugging` first
 
+> **Docker CLI:** If a build or test fails with connection errors to local services (Supabase, Redis, etc.), check container health first: `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"`. For debugging: `docker logs <container> --tail 50` to see recent logs. To restart a stuck container: `docker restart <container>`.
+
 ---
 
 ## Context Loading
 
-## MANDATORY: Session Tasks
-
-> **You MUST create one native task per T001-T00N from tasks.md BEFORE starting implementation.**
-> After creating all tasks, wire dependencies using `addBlockedBy`.
-> Update each to `in_progress` before starting and `completed` after `task done` succeeds.
-
 ### 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/features/{feature}/2-design/spec.md
+    + Read: .morph/features/{feature}/2-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
+### 2. Detect architecture style
 
 ```bash
 cat .morph/config/config.json | grep architecture
@@ -215,129 +225,85 @@ Structure: `Features/{Entity}Feature/{Op}/` with Handler (+ Request/Response rec
 
 ## Workflow
 
-### Step 0.5: Plan Execution Mode
+### Step 0.5: Dispatch Recommendation
 
-**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:
+Get agent dispatch recommendation:
 
 ```bash
 morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
-Check the `mode` field in the JSON output to determine the execution strategy.
+The output is a JSON advisor — it recommends which agents to use and which tasks they handle:
+- `recommended`: `{ [group]: subagentType[] }` — maps groups to agent file names
+- `tasks`: `{ [group]: taskId[] }` — maps groups to task IDs from tasks.md
+- `shouldDispatch`: true if 2+ agents available (parallel dispatch beneficial)
 
----
-
-#### Subagents Mode (if strategy is `"subagents"`):
+**If `shouldDispatch` is true:**
 
-**Step 0.5a: Get dispatch config:**
+1. Read `recommended` — maps groups (backend, frontend, etc.) to agent subagentTypes
+2. Read `tasks` — maps groups to task IDs
+3. For each agent, verify `.claude/agents/{subagentType}.md` exists. If missing → **STOP** with: `"Agent file not found. Run: morph-spec setup-infra"`. Do NOT fall back to general-purpose agents.
+4. Dispatch each group in **parallel** using native Agent tool:
 
-```bash
-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
+Agent(subagent_type="morph-dotnet-senior", prompt="Implement tasks T001, T002 for feature {feature}. Read .morph/features/{feature}/4-tasks/tasks.md for task details and .morph/features/{feature}/2-design/ for contracts and spec. Follow the task loop: start → implement → verify → done. Checkpoint every 3 tasks. Domain isolation: modify ONLY files in your domain.")
 ```
 
-If missing → **STOP** with: `"Agent file .claude/agents/{subagentType}.md not found. Run: 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 from `recommended`. Do NOT use `general-purpose` agents when a `subagentType` is available.
 >
-> **MANDATORY:** Use the exact `subagentType` value. Do NOT use `general-purpose` agents when a `subagentType` is available.
+> The agent `.md` file contains the full expertise prompt, task routing, and key standards. No additional prompt injection needed — just provide the task assignment.
 
-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)
+5. After all subagents complete, validate integration: `morph-spec validate-feature $ARGUMENTS --phase implement`
 
-2. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
-3. After all complete, validate integration: `morph-spec validate-feature $ARGUMENTS --phase implement`
+**If `shouldDispatch` is false** → continue to sequential task loop (Step 2).
 
 **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: `morph-spec validate-feature $ARGUMENTS --phase implement`
-
 ---
 
 ### Step 2: Task Loop
 
-```bash
-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:**
+1. **Start task:**
    ```bash
    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`:**
+2. **Read FR context** (MANDATORY — NON-NEGOTIABLE):
+   - Parse task's `[FR references]` from tasks.md (e.g., `### T001: Create user endpoint [FR001, FR003]`)
+   - **Read spec.md** → the sections for those specific FRs (functional requirements, acceptance criteria)
+   - **Read contracts.cs/.ts** → the DTOs/interfaces referenced by those FRs
+   - The spec is the source of truth. Code that doesn't match the spec is a bug.
+   > **MCP:** Before implementing, use **Context7 MCP** (`resolve-library-id` → `query-docs`) to verify the correct API of the libraries being used. If Context7 is not available, use **WebSearch** + **WebFetch** to check official docs.
+3. **Implement** using Write (new) or Edit (existing)
+4. **Verify** — build, lint, tests
+5. **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
    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:**
+   Only proceed to step 6 if verification passes. If it fails → fix before marking `task done`.
+6. **Mark as done via CLI:**
    ```bash
    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 2.5: Scope Escalation (when task is too complex)
+
+If during implementation a task reveals significantly more complexity than estimated:
+
+- **Low impact (1-3 subtasks):** Expand the task directly:
+  ```bash
+  morph-spec task expand $ARGUMENTS T001 --into "T001a: First sub" "T001b: Second sub"
+  ```
+  Then implement each subtask following the same loop above.
+
+- **Medium/High impact (4+ tasks or spec is wrong):** Run the scope escalation workflow:
+  ```bash
+  /morph-scope-escalation $ARGUMENTS
+  ```
+
+**Rule:** Never implement extra functionality within a task without registering it. If a task takes more than expected, expand it into subtasks — this ensures validation gates run for each piece and progress is tracked accurately.
 
 ### Step 3: Checkpoint Every 3 Tasks
 
@@ -377,6 +343,8 @@ npm test -- test/path/to/test.js
 
 ### Step 5: Smoke Test with Playwright (if UI)
 
+> **MCP:** After implementing an API endpoint or page, if **Playwright MCP** is available, immediately do a quick smoke test: navigate to the endpoint/page URL, call `browser_snapshot()` to verify it loads, and check `browser_console_messages({ level: 'error' })` for errors. Catch issues while context is fresh rather than waiting for post-implementation. If Playwright is not available, verify manually via `curl` or browser.
+
 After implementing visual components:
 
 ```javascript
@@ -444,17 +412,17 @@ morph-spec uses its own agents and validators for implementation, dispatch, and
 
 ### Implementation
 
-Implementers are dispatched via `dispatch-agents`:
+Get dispatch recommendation and use native Agent tool:
 ```bash
 morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
-Use the `subagentType` from each group in the Agent tool:
+Use `recommended[group]` subagentTypes directly:
 ```
-Agent(subagent_type=<subagentType>, prompt=<filled prompts/implementer-prompt.md>)
+Agent(subagent_type="morph-dotnet-senior", prompt="Implement tasks T001, T002 for feature X...")
 ```
 
-> The `subagentType` maps agent IDs to `.claude/agents/` filenames:
+> Agent `.md` files are self-contained — they include the expertise prompt, task routing, and key standards. The `subagentType` maps 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`)
 

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

@@ -4,10 +4,11 @@ You are implementing tasks for the feature '{{FEATURE_NAME}}' as agent '{{AGENT_
 
 ## Context
 
-**Spec:** Read `.morph/features/{{FEATURE_NAME}}/1-design/spec.md`
-**Contracts:** Read `.morph/features/{{FEATURE_NAME}}/1-design/contracts.cs`
+**Spec:** Read `.morph/features/{{FEATURE_NAME}}/2-design/spec.md`
+**Contracts:** Read `.morph/features/{{FEATURE_NAME}}/2-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/`
+**Standards:** Read relevant files in `.morph/framework/standards/`
+**Code Templates:** Read `.morph/framework/templates/code/dotnet/feature/` (endpoint, handler, validator) — follow these patterns exactly
 
 ## Agent Briefing
 

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

@@ -9,8 +9,8 @@ Review the implementation against the specification. Your job is to ensure the c
 ## 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}}/2-design/spec.md` — The specification
+- `.morph/features/{{FEATURE_NAME}}/2-design/contracts.cs` — The contracts (source of truth)
 - `.morph/features/{{FEATURE_NAME}}/3-plan/plan.md` — The implementation plan
 
 ## Review Checklist

package/framework/skills/level-1-workflows/morph-phase-implement/references/recap-example.md

@@ -10,7 +10,7 @@
 | **Completed** | 2025-01-22 |
 | **Total Tasks** | 11 / 11 |
 | **Time Spent** | ~9h |
-| **Agents Used** | dotnet-senior, azure-architect, blazor-builder |
+| **Agents Used** | dotnet-senior, nextjs-expert, infra-architect |
 | **Stack** | blazor-azure |
 
 ---

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

@@ -1,13 +1,13 @@
 ---
 name: morph-phase-plan
-description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan with exact file paths, TDD code blocks, and execution strategy analysis. Produces plan.md in 3-plan/. Use after clarify phase to create an actionable implementation plan before task breakdown.
+description: MORPH-SPEC Phase 3 (Plan). Generates a detailed implementation plan with exact file paths, TDD code blocks, and execution strategy analysis. Produces plan.md in 3-plan/. Use after design phase to create an actionable implementation plan before task breakdown.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.12.0"
+cliVersion: "4.13.0"
 ---
 
-# MORPH Plan — Phase 4
+# MORPH Plan — Phase 3
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
 
@@ -15,8 +15,8 @@ Generate a detailed implementation plan with exact paths, TDD code, and executio
 
 ## Prerequisites
 
-- [ ] Phase 3 (Clarify) completed
-- [ ] `spec.md` updated with clarifications
+- [ ] Phase 2 (Design) completed and approved
+- [ ] `spec.md` defined
 - [ ] `contracts.cs` or `contracts.ts` defined
 
 ## Recommended Tools
@@ -36,7 +36,7 @@ Generate a detailed implementation plan with exact paths, TDD code, and executio
 - Generic paths ("add the file") — always use exact paths
 - Incomplete code in plan ("add validation") — always include complete code
 - Skipping existing codebase analysis (existing patterns guide the plan)
-- Ignoring `config.architecture.style` — VSA and DDD have different structures
+- Ignoring `config.architecture.style` — VSA and standard architectures have different structures
 
 ---
 
@@ -65,11 +65,11 @@ Check the `"phase"` field:
 ### 1. Read all prerequisites in PARALLEL
 
 ```
-Read: .morph/features/{feature}/1-design/spec.md
-    + Read: .morph/features/{feature}/1-design/contracts.cs  (or contracts.ts)
-    + Read: .morph/features/{feature}/1-design/decisions.md
-    + Read: .morph/features/{feature}/1-design/clarifications.md
-    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
+Read: .morph/features/{feature}/2-design/spec.md
+    + Read: .morph/features/{feature}/2-design/contracts.cs  (or contracts.ts)
+    + Read: .morph/features/{feature}/2-design/decisions.md
+    + Read: .morph/features/{feature}/2-design/decisions.md
+    + Read: .morph/features/{feature}/2-design/schema-analysis.md  (if exists)
     + Read: .morph/config/config.json
 ```
 
@@ -91,7 +91,7 @@ cat .morph/config/config.json | grep -A3 '"architecture"'
 | `config.architecture.style` value | Path structure |
 |------------------------------------|---------------|
 | `"vertical-slice"` | VSA: `Features/{Entity}Feature/{Operation}/` |
-| any other value | DDD by layer |
+| any other value | Standard layer-based |
 
 ### Step 2: Determine Execution Strategy
 
@@ -141,7 +141,10 @@ Create `.morph/features/$ARGUMENTS/3-plan/plan.md` with this structure:
 
 {Pattern and context for the group}
 
-### {A1} — {Task Name}
+### {A1} — {Task Name} [FR001, FR003]
+
+**Spec refs:** FR001 (description), FR003 (description)
+**Contracts:** {RelevantRequest}, {RelevantResponse}, {ErrorType}
 
 **Files:**
 - Create: `exact/path/to/file.cs`
@@ -173,6 +176,7 @@ git commit -m "{message}"
 ```
 
 **Mandatory rules:**
+- **FR cross-references in EVERY task** — each task MUST reference the spec FRs it implements (e.g., `[FR001, FR003]`). Extract FR IDs from spec.md and map them to task groups. Include `Spec refs:` and `Contracts:` fields.
 - Exact paths ALWAYS (never "add the file somewhere")
 - COMPLETE code in each step (never "add validation later" or "implement here")
 - Exact test commands with expected output (pass/fail message)