@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

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

@@ -1,311 +1,317 @@
----
-name: morph-phase-tasks
-description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ordered implementation tasks (T001...TXXX) with dependencies, checkpoints every 3 tasks, and effort estimates, producing tasks.md. Use after design and clarification phases to create a structured implementation plan before coding starts.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
----
-
-# MORPH Tasks — Phase 4
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Break the approved specification into executable tasks, define execution order, and establish checkpoints.
-
-## Prerequisites
-
-- [ ] Phase 3 (Clarify) completed
-- [ ] `spec.md` updated with clarifications
-- [ ] All edge cases documented
-
-## 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/tasks-example.md` — filled-in tasks.md showing expected granularity and format.
-> **Script:** `scripts/validate-tasks.mjs` — validates tasks.md structure, T### IDs, and required fields.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Read spec + contracts + decisions | **Read** all outputs | — |
-| Analyze implementation complexity | **Grep** patterns in existing code | — |
-| Count similar existing patterns | **Glob** `**/Services/**/*.cs` | — |
-| Look up implementation patterns | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | **Bash** `gh issue create ...` |
-| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | — |
-| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | — |
-
-**Phase MCPs:** Context7 (estimate complexity), GitHub (create issues).
-
-**Anti-patterns:**
-- Task agent to break down a simple single-domain spec (do it directly)
-- Creating tasks without reading all design outputs first
-- **(VSA)** Creating separate tasks for Handler, Validator, and Endpoint — one slice = one task
-- **(VSA)** Using DDD categories (`domain`, `application`, `infrastructure`) in VSA projects — use VSA categories: `entity`, `errors`, `tags`, `migration`, `slice`, `frontend`, `tests`
-- **(VSA)** Creating a "Implement Service layer" task — there is no Service layer in VSA
-- Using vague effort labels ("Low", "Medium", "S/M") — always use specific minute estimates
-- Using non-standard task IDs (TASK-001, T01) — always use **T001** format (T + 3 digits)
-
----
-
-## Pre-flight (before starting task breakdown)
-
-### 0. Ensure tasks phase
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field:
-
-**If `"phase": "tasks"`** → correct phase, proceed.
-
-**If `"phase": "clarify"`** → run in sequence:
-1. `npx morph-spec state mark-output $ARGUMENTS clarifications`
-2. `npx morph-spec phase advance $ARGUMENTS` (→ tasks)
-
-**Any other value** → STOP — inconsistent state, report to user.
-
-> **Rule:** Never write to `4-tasks/` until the phase is `tasks`. The hook will block writes.
-
----
-
-### 1. Read all prerequisites in PARALLEL
-
-```
-# Single parallel call, not sequential:
-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}/1-design/decisions.md
-    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
-    + Read: .morph/config/config.json                               (→ architecture.style)
-```
-
-### 2. Create session tasks for visibility
-
-```
-TaskCreate: "Analyze spec and define tasks" → activeForm: "Analyzing spec"
-TaskCreate: "Generate tasks.md"             → activeForm: "Generating tasks.md"
-TaskCreate: "Phase advance"                 → activeForm: "Advancing phase"
-```
-
-> **Note:** Individual T001-T00N tasks are created as native tasks during the implementation phase (`phase-implement`). Here we only keep the 3 high-level tasks for this planning session.
-
----
-
-### 3. Entry checkpoint — verify prerequisites
-
-Before starting the breakdown:
-
-- [ ] `spec.md` exists and approved by user?
-- [ ] `contracts.cs`/`.ts` exists and matches real schema?
-- [ ] `schema-analysis.md` validated (if applicable)?
-- [ ] `decisions.md` contains ADRs for all critical choices?
-- [ ] Design gate (`morph-spec approve $ARGUMENTS design`) approved?
-- [ ] Clarifications (Phase 3) resolved and spec updated?
-
-If any checkbox is NOT checked → return to corresponding phase and resolve.
-
-```bash
-npx morph-spec state get $ARGUMENTS
-npx morph-spec approval-status $ARGUMENTS
-```
-
----
-
-## Workflow
-
-### Step 0: Detect Architecture Style
-
-Before anything else, determine if the project is VSA or DDD:
-
-```bash
-cat .morph/config/config.json | grep -A3 '"architecture"'
-```
-
-**If `config.architecture.style === "vertical-slice"`** → follow **Step 0.5 (VSA)** and skip DDD path.
-**Otherwise** → follow **Step 0.6 (DDD)** below.
-
----
-
-### Step 0.5: VSA Task Plan
-
-> For VSA task patterns and DDD-level mappings, see `references/task-planning-patterns.md`
-
-Read the `## Architecture Style: Vertical Slice` section from spec.md for the **VSA Blueprint**:
-
-```bash
-grep -A30 "## Architecture Style" ".morph/features/$ARGUMENTS/1-design/spec.md"
-```
-
-Create one task per slice following this order: entity → errors → tags → migration → CRUD slices → custom slices → frontend → tests. Each slice = Handler + Validator + Endpoint in a **single task**. `GetAll` operations do NOT have a Validator (no input parameters to validate).
-
-Use VSA-specific categories: `entity`, `errors`, `tags`, `migration`, `slice`, `frontend`, `tests`.
-
-**After defining VSA tasks, skip directly to Step 3 (Dependencies).**
-
----
-
-### Step 0.6: Read Domain Level — DDD
-
-Read the `## Domain Complexity` section from spec.md:
-
-```bash
-grep -A15 "## Domain Complexity" ".morph/features/$ARGUMENTS/1-design/spec.md"
-```
-
-> If the section doesn't exist, assume **Level 1 (CRUD)**.
-
-Use the level to constrain categories:
-- **Level 1**: domain → infrastructure → application → presentation → tests
-- **Level 2**: adds AggregateRoot, ValueObjects, DomainEvents, CQRS handlers
-- **Level 3**: adds BC setup, Integration Events
-
-See `references/task-planning-patterns.md` for the complete table.
-
----
-
-### Step 1: Analyze Spec
-
-> **VSA:** If coming from Step 0.5, the task breakdown was already defined — use the generated examples as a base and skip to Step 3 (Dependencies).
-
-Read `.morph/features/$ARGUMENTS/1-design/spec.md` and identify:
-
-1. **Functional requirements** (FR001, FR002, ...)
-2. **Technical components** (Entities, Services/Slices, Controllers/Endpoints, Pages)
-3. **Infrastructure** (Bicep, migrations, configs)
-4. **Tests** (Unit tests, integration tests)
-
-### Step 2: Break Into Tasks
-
-> For structure, categories, and implementation order, see `references/task-planning-patterns.md`
-
-Create tasks using the **T{NNN}** format (T001, T002, ...) following bottom-up order: domain → infrastructure → application → presentation → tests → infra → docs.
-
-The T### format is mandatory — it is used by `morph-spec task start/done` commands and the validate-tasks script. Do not use TASK-001, T01, or other formats.
-
-### Step 3: Define Dependencies
-
-For each task, specify dependencies:
-
-```json
-{
-  "id": "T005",
-  "title": "Create {Name}Service",
-  "dependencies": ["T001", "T002"],
-  "status": "pending"
-}
-```
-
-**Rule:** A task can only be executed when all its dependencies are `completed`.
-
-### Step 4: Establish Checkpoints
-
-Define checkpoints after every **3 tasks** — this cadence matches the implementation phase's checkpoint-save frequency. Regular checkpoints catch integration issues early rather than at the end.
-
-```json
-{
-  "id": "CHECKPOINT_001",
-  "title": "Domain Layer Complete",
-  "afterTasks": ["T001", "T002", "T003"],
-  "validations": [
-    "All entities created",
-    "Migrations applied",
-    "Domain tests passing"
-  ]
-}
-```
-
-### Step 5: Estimate Effort
-
-For each task, estimate time **in minutes** (not vague labels like "Low/Medium"). Specific estimates help the plan phase determine execution strategy and parallelization.
-
-| Complexity | Estimated Time |
-|------------|----------------|
-| Trivial (basic CRUD) | 15-30 min |
-| Simple (Service, Controller) | 30-60 min |
-| Medium (Business logic, validations) | 60-120 min |
-| Complex (Integrations, AI) | 120-240 min |
-
-### Step 6: Generate `tasks.md`
-
-Create `.morph/features/$ARGUMENTS/4-tasks/tasks.md` with the complete task structure, checkpoints, and estimates.
-
-### Step 7: Include IaC Tasks (if needed)
-
-If there are Azure resources, add Bicep and migration tasks.
-
-### Step 8: Update State
-
-```bash
-npx morph-spec state set $ARGUMENTS tasks.total {N}
-npx morph-spec state mark-output $ARGUMENTS tasks
-```
-
-## Outputs
-
-- `.morph/features/$ARGUMENTS/4-tasks/tasks.md` — Complete task breakdown
-
-## Mandatory Approval Pause
-
-Use `AskUserQuestion` to capture explicit approval before advancing. This gate prevents implementation from starting with an unapproved task list.
-
-```json
-{
-  "questions": [{
-    "header": "Approval",
-    "question": "Tasks generated. Approve to start implementation?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Approve and implement", "description": "Advance to implementation phase" },
-      { "label": "I have feedback",       "description": "Type what you want to change" }
-    ]
-  }]
-}
-```
-
-- **"Approve and implement"** →
-  ```bash
-  npx morph-spec approve $ARGUMENTS tasks
-  npx morph-spec phase advance $ARGUMENTS
-  ```
-- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
-
-## Completion Criteria
-
-- [x] `tasks.md` created with all tasks
-- [x] Tasks use T### format (T001, T002, ...) consistently
-- [x] Tasks categorized correctly (DDD layers or VSA categories)
-- [x] Dependencies mapped
-- [x] Checkpoints defined (every 3 tasks)
-- [x] Effort estimated in minutes per task
-- [x] Execution order clear
-- [x] IaC tasks included (if applicable)
-- [x] State updated with total tasks (`state set tasks.total`)
-- [x] User approved breakdown via `AskUserQuestion`
-
----
-
-## Superpowers Integration
-
-> Available when the `superpowers` plugin is installed.
-
-| Skill | When to Use | Invocation |
-|-------|-------------|-----------|
-| `writing-plans` | After task breakdown, to plan implementation sequence | `Skill(superpowers:writing-plans)` |
-| `executing-plans` | To execute the task plan in a separate session | `Skill(superpowers:executing-plans)` |
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:tasks -->
-| Output | Path |
-|--------|------|
-| `tasks` | `.morph/features/{feature}/4-tasks/tasks.md` |
-<!-- /morph-outputs -->
-
----
-
-After approval: "Planning complete! Run `/morph-apply $ARGUMENTS` to start implementation."
+---
+name: morph-phase-tasks
+description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ordered implementation tasks (T001...TXXX) with dependencies, checkpoints every 3 tasks, and effort estimates, producing tasks.md. Use after design and clarification phases to create a structured implementation plan before coding starts.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.8"
+---
+
+# MORPH Tasks — Phase 4
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Break the approved specification into executable tasks, define execution order, and establish checkpoints.
+
+## Prerequisites
+
+- [ ] Phase 3 (Clarify) completed
+- [ ] `spec.md` updated with clarifications
+- [ ] All edge cases documented
+
+## 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/tasks-example.md` — filled-in tasks.md showing expected granularity and format.
+> **Script:** `scripts/validate-tasks.mjs` — validates tasks.md structure, T### IDs, and required fields.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read spec + contracts + decisions | **Read** all outputs | — |
+| Analyze implementation complexity | **Grep** patterns in existing code | — |
+| Count similar existing patterns | **Glob** `**/Services/**/*.cs` | — |
+| Look up implementation patterns | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | **Bash** `gh issue create ...` |
+| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | — |
+| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | — |
+
+**Phase MCPs:** Context7 (estimate complexity), GitHub (create issues).
+
+**Anti-patterns:**
+- Task agent to break down a simple single-domain spec (do it directly)
+- Creating tasks without reading all design outputs first
+- **(VSA)** Creating separate tasks for Handler, Validator, and Endpoint — one slice = one task
+- **(VSA)** Using DDD categories (`domain`, `application`, `infrastructure`) in VSA projects — use VSA categories: `entity`, `errors`, `tags`, `migration`, `slice`, `frontend`, `tests`
+- **(VSA)** Creating a "Implement Service layer" task — there is no Service layer in VSA
+- Using vague effort labels ("Low", "Medium", "S/M") — always use specific minute estimates
+- Using non-standard task IDs (TASK-001, T01) — always use **T001** format (T + 3 digits)
+
+---
+
+## Pre-flight (before starting task breakdown)
+
+### 0. Ensure tasks phase
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field:
+
+**If `"phase": "tasks"`** → correct phase, proceed.
+
+**If `"phase": "clarify"`** → run in sequence:
+1. `npx morph-spec state mark-output $ARGUMENTS clarifications`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ tasks)
+
+**Any other value** → STOP — inconsistent state, report to user.
+
+> **Rule:** Never write to `4-tasks/` until the phase is `tasks`. The hook will block writes.
+
+---
+
+### 1. Read all prerequisites in PARALLEL
+
+```
+# Single parallel call, not sequential:
+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}/1-design/decisions.md
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
+    + Read: .morph/config/config.json                               (→ architecture.style)
+```
+
+### 2. Create session tasks for visibility
+
+After detecting `activeAgents` from state, create tasks with agent context:
+
+```
+TaskCreate: "Analyze spec and define tasks"
+  → description: "Active agents: {activeAgents.join(', ')}"
+  → activeForm: "Analyzing spec"
+TaskCreate: "Generate tasks.md"
+  → description: "Architecture: {config.architecture.style}"
+  → activeForm: "Generating tasks.md"
+TaskCreate: "Phase advance"  → activeForm: "Awaiting tasks approval + advancing phase"
+```
+
+> **Note:** Individual T001-T00N tasks are created as native tasks during the implementation phase (`phase-implement`). Here we only keep the 3 high-level tasks for this planning session.
+
+---
+
+### 3. Entry checkpoint — verify prerequisites
+
+Before starting the breakdown:
+
+- [ ] `spec.md` exists and approved by user?
+- [ ] `contracts.cs`/`.ts` exists and matches real schema?
+- [ ] `schema-analysis.md` validated (if applicable)?
+- [ ] `decisions.md` contains ADRs for all critical choices?
+- [ ] Design gate (`morph-spec approve $ARGUMENTS design`) approved?
+- [ ] Clarifications (Phase 3) resolved and spec updated?
+
+If any checkbox is NOT checked → return to corresponding phase and resolve.
+
+```bash
+npx morph-spec state get $ARGUMENTS
+npx morph-spec approval-status $ARGUMENTS
+```
+
+---
+
+## Workflow
+
+### Step 0: Detect Architecture Style
+
+Before anything else, determine if the project is VSA or DDD:
+
+```bash
+cat .morph/config/config.json | grep -A3 '"architecture"'
+```
+
+**If `config.architecture.style === "vertical-slice"`** → follow **Step 0.5 (VSA)** and skip DDD path.
+**Otherwise** → follow **Step 0.6 (DDD)** below.
+
+---
+
+### Step 0.5: VSA Task Plan
+
+> For VSA task patterns and DDD-level mappings, see `references/task-planning-patterns.md`
+
+Read the `## Architecture Style: Vertical Slice` section from spec.md for the **VSA Blueprint**:
+
+```bash
+grep -A30 "## Architecture Style" ".morph/features/$ARGUMENTS/1-design/spec.md"
+```
+
+Create one task per slice following this order: entity → errors → tags → migration → CRUD slices → custom slices → frontend → tests. Each slice = Handler + Validator + Endpoint in a **single task**. `GetAll` operations do NOT have a Validator (no input parameters to validate).
+
+Use VSA-specific categories: `entity`, `errors`, `tags`, `migration`, `slice`, `frontend`, `tests`.
+
+**After defining VSA tasks, skip directly to Step 3 (Dependencies).**
+
+---
+
+### Step 0.6: Read Domain Level — DDD
+
+Read the `## Domain Complexity` section from spec.md:
+
+```bash
+grep -A15 "## Domain Complexity" ".morph/features/$ARGUMENTS/1-design/spec.md"
+```
+
+> If the section doesn't exist, assume **Level 1 (CRUD)**.
+
+Use the level to constrain categories:
+- **Level 1**: domain → infrastructure → application → presentation → tests
+- **Level 2**: adds AggregateRoot, ValueObjects, DomainEvents, CQRS handlers
+- **Level 3**: adds BC setup, Integration Events
+
+See `references/task-planning-patterns.md` for the complete table.
+
+---
+
+### Step 1: Analyze Spec
+
+> **VSA:** If coming from Step 0.5, the task breakdown was already defined — use the generated examples as a base and skip to Step 3 (Dependencies).
+
+Read `.morph/features/$ARGUMENTS/1-design/spec.md` and identify:
+
+1. **Functional requirements** (FR001, FR002, ...)
+2. **Technical components** (Entities, Services/Slices, Controllers/Endpoints, Pages)
+3. **Infrastructure** (Bicep, migrations, configs)
+4. **Tests** (Unit tests, integration tests)
+
+### Step 2: Break Into Tasks
+
+> For structure, categories, and implementation order, see `references/task-planning-patterns.md`
+
+Create tasks using the **T{NNN}** format (T001, T002, ...) following bottom-up order: domain → infrastructure → application → presentation → tests → infra → docs.
+
+The T### format is mandatory — it is used by `morph-spec task start/done` commands and the validate-tasks script. Do not use TASK-001, T01, or other formats.
+
+### Step 3: Define Dependencies
+
+For each task, specify dependencies:
+
+```json
+{
+  "id": "T005",
+  "title": "Create {Name}Service",
+  "dependencies": ["T001", "T002"],
+  "status": "pending"
+}
+```
+
+**Rule:** A task can only be executed when all its dependencies are `completed`.
+
+### Step 4: Establish Checkpoints
+
+Define checkpoints after every **3 tasks** — this cadence matches the implementation phase's checkpoint-save frequency. Regular checkpoints catch integration issues early rather than at the end.
+
+```json
+{
+  "id": "CHECKPOINT_001",
+  "title": "Domain Layer Complete",
+  "afterTasks": ["T001", "T002", "T003"],
+  "validations": [
+    "All entities created",
+    "Migrations applied",
+    "Domain tests passing"
+  ]
+}
+```
+
+### Step 5: Estimate Effort
+
+For each task, estimate time **in minutes** (not vague labels like "Low/Medium"). Specific estimates help the plan phase determine execution strategy and parallelization.
+
+| Complexity | Estimated Time |
+|------------|----------------|
+| Trivial (basic CRUD) | 15-30 min |
+| Simple (Service, Controller) | 30-60 min |
+| Medium (Business logic, validations) | 60-120 min |
+| Complex (Integrations, AI) | 120-240 min |
+
+### Step 6: Generate `tasks.md`
+
+Create `.morph/features/$ARGUMENTS/4-tasks/tasks.md` with the complete task structure, checkpoints, and estimates.
+
+### Step 7: Include IaC Tasks (if needed)
+
+If there are Azure resources, add Bicep and migration tasks.
+
+### Step 8: Update State
+
+```bash
+npx morph-spec state set $ARGUMENTS tasks.total {N}
+npx morph-spec state mark-output $ARGUMENTS tasks
+```
+
+## Outputs
+
+- `.morph/features/$ARGUMENTS/4-tasks/tasks.md` — Complete task breakdown
+
+## Mandatory Approval Pause
+
+Use `AskUserQuestion` to capture explicit approval before advancing. This gate prevents implementation from starting with an unapproved task list.
+
+```json
+{
+  "questions": [{
+    "header": "Approval",
+    "question": "Tasks generated. Approve to start implementation?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Approve and implement", "description": "Advance to implementation phase" },
+      { "label": "I have feedback",       "description": "Type what you want to change" }
+    ]
+  }]
+}
+```
+
+- **"Approve and implement"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS tasks
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
+
+## Completion Criteria
+
+- [x] `tasks.md` created with all tasks
+- [x] Tasks use T### format (T001, T002, ...) consistently
+- [x] Tasks categorized correctly (DDD layers or VSA categories)
+- [x] Dependencies mapped
+- [x] Checkpoints defined (every 3 tasks)
+- [x] Effort estimated in minutes per task
+- [x] Execution order clear
+- [x] IaC tasks included (if applicable)
+- [x] State updated with total tasks (`state set tasks.total`)
+- [x] User approved breakdown via `AskUserQuestion`
+
+---
+
+## Superpowers Integration
+
+> Available when the `superpowers` plugin is installed.
+
+| Skill | When to Use | Invocation |
+|-------|-------------|-----------|
+| `writing-plans` | After task breakdown, to plan implementation sequence | `Skill(superpowers:writing-plans)` |
+| `executing-plans` | To execute the task plan in a separate session | `Skill(superpowers:executing-plans)` |
+
+---
+
+## Phase Outputs
+
+<!-- morph-outputs:tasks -->
+| Output | Caminho |
+|--------|---------|
+| `tasks` | `.morph/features/{feature}/4-tasks/tasks.md` |
+<!-- /morph-outputs -->
+
+---
+
+After approval: "Planning complete! Run `/morph-apply $ARGUMENTS` to start implementation."