@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,291 +0,0 @@
----
-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.21.0"
----
-
-# 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
-
-- [ ] Design phase completed and approved
-- [ ] `spec.md` exists and approved
-- [ ] Plan phase completed
-
-## 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** `morph-spec template render docs/tasks ...` | — |
-| Update state with task count | **Bash** `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 generic layer 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
-morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field:
-
-**If `"phase": "tasks"`** → correct phase, proceed.
-
-**If `"phase": "plan"`** → run:
-1. `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.
-
----
-
-## MANDATORY: Session Tasks
-
-> **BEFORE reading any files**, analyze the task breakdown workflow and create session tasks.
->
-> **Rules:** Minimum 2 tasks, typically 3-4. Mark `in_progress` before starting, `completed` after.
->
-> **Typical tasks:** spec analysis and task definition, tasks.md generation, state update and approval
-
-### 1. Read all prerequisites in PARALLEL
-
-```
-# Single parallel call, not sequential:
-Read: .morph/features/{feature}/2-design/spec.md
-    + Read: .morph/features/{feature}/2-design/contracts.cs  (or contracts.ts for TypeScript projects)
-    + Read: .morph/features/{feature}/2-design/decisions.md
-    + Read: .morph/features/{feature}/2-design/schema-analysis.md  (if exists)
-    + Read: .morph/config/config.json                               (→ architecture.style)
-```
-
----
-
-### 2. 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
-morph-spec state get $ARGUMENTS
-morph-spec approval-status $ARGUMENTS
-```
-
----
-
-## Workflow
-
-### Step 0: Detect Architecture Style
-
-Before anything else, determine the architecture style:
-
-```bash
-cat .morph/config/config.json | grep -A3 '"architecture"'
-```
-
-**If `config.architecture.style === "vertical-slice"`** → follow **Step 0.5 (VSA)**.
-**Otherwise** → proceed to **Step 1 (Analyze Spec)** with standard layer-based task breakdown.
-
----
-
-### Step 0.5: VSA Task Plan
-
-> For VSA task patterns, 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/2-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 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/2-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
-morph-spec state set $ARGUMENTS tasks.total {N}
-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
-  morph-spec approve $ARGUMENTS tasks
-  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 (VSA categories or standard layers)
-- [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."

package/framework/skills/level-1-workflows/morph-phase-tasks/references/task-planning-patterns.md

@@ -1,143 +0,0 @@
-# Task Planning Patterns — VSA
-
-> Padrões detalhados de task planning para Vertical Slice Architecture.
-> Referenciado pelos Passos 0.5 e 0.6 de `phase-tasks/SKILL.md`.
-
----
-
-## Padrão VSA (Vertical Slice Architecture)
-
-**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
-### Categorias de tasks VSA
-
-Uma task por slice — Handler + Validator + Endpoint juntos:
-
-| Categoria | Descrição | Arquivo(s) |
-|-----------|-----------|------------|
-| **entity** | Entity class + DbSet no ApplicationDbContext | `Entities/{Entity}.cs`, `Database/ApplicationDbContext.cs` |
-| **errors** | `{Entity}Errors` static class com factory methods | `Features/{Entity}Feature/{Entity}Errors.cs` |
-| **tags** | Constante em ApiTags (se tag nova) | `Constants/ApiTags.cs` |
-| **migration** | `dotnet ef migrations add` + `database update` | `Migrations/...` |
-| **slice** | Slice completo: Handler (+ Request + Response records) + Validator + Endpoint | `Features/{Entity}Feature/{Op}/{Op}Handler.cs`, `...Validator.cs`, `...Endpoint.cs` |
-| **tests** | Unit tests dos handlers | `Tests/Features/{Entity}Feature/...` |
-| **docs** | README, Swagger, comentários | — |
-
-### Ordem obrigatória (bottom-up VSA)
-
-```
-T001: Entity + DbContext DbSet
-   ↓
-T002: {Entity}Errors (factory methods)
-   ↓
-T003: ApiTags constant (se tag ainda não existe)
-   ↓
-T004: Migration (Add{Entity} + database update)
-   ↓
-T005: Slice Create{Entity}     ← Handler+Validator+Endpoint = 1 task
-T006: Slice GetAll{Entity}s    ← Handler+Endpoint = 1 task (sem Validator)
-T007: Slice Get{Entity}ById    ← Handler+Validator+Endpoint = 1 task
-T008: Slice Update{Entity}     ← Handler+Validator+Endpoint = 1 task
-T009: Slice Delete{Entity}     ← Handler+Validator+Endpoint = 1 task
-   ↓
-T010+: Slices customizados (operações extra do VSA Blueprint)
-   ↓
-T0NN: Tests
-```
-
-### Regras VSA para tasks
-
-- 1 task = 1 slice completo (Handler + Validator + Endpoint num único task)
-- `GetAll` NÃO tem Validator — mencionar explicitamente no task
-- Cada task de slice lista os 3 arquivos que devem ser criados no campo `files`
-- Entity task deve incluir a linha `DbSet<{Entity}>` no `ApplicationDbContext`
-- Migration task é separada da entity task (pode rodar em paralelo com errors + tags)
-
-### Exemplos de tasks VSA
-
-```json
-{ "id": "T001", "title": "Criar Entity Book + registrar DbSet no ApplicationDbContext",
-  "category": "entity", "dependencies": [],  "estimatedMinutes": 20,
-  "files": ["Entities/Book.cs", "Database/ApplicationDbContext.cs"] }
-
-{ "id": "T002", "title": "Criar BookErrors (NotFound + outros factory methods)",
-  "category": "errors", "dependencies": ["T001"], "estimatedMinutes": 10,
-  "files": ["Features/BookFeature/BookErrors.cs"] }
-
-{ "id": "T003", "title": "Adicionar ApiTags.Books em Constants/ApiTags.cs",
-  "category": "tags", "dependencies": [], "estimatedMinutes": 5,
-  "files": ["Constants/ApiTags.cs"] }
-
-{ "id": "T004", "title": "Criar migration AddBook + aplicar ao banco",
-  "category": "migration", "dependencies": ["T001"], "estimatedMinutes": 10,
-  "files": ["Migrations/...AddBook.cs"] }
-
-{ "id": "T005", "title": "Implementar slice CreateBook (Handler + Validator + Endpoint)",
-  "category": "slice", "dependencies": ["T001", "T002", "T003", "T004"],
-  "estimatedMinutes": 45,
-  "files": [
-    "Features/BookFeature/CreateBook/CreateBookHandler.cs",
-    "Features/BookFeature/CreateBook/CreateBookValidator.cs",
-    "Features/BookFeature/CreateBook/CreateBookEndpoint.cs"
-  ] }
-
-{ "id": "T006", "title": "Implementar slice GetAllBooks (Handler + Endpoint, sem Validator)",
-  "category": "slice", "dependencies": ["T001", "T004"], "estimatedMinutes": 25,
-  "files": [
-    "Features/BookFeature/GetAllBooks/GetAllBooksHandler.cs",
-    "Features/BookFeature/GetAllBooks/GetAllBooksEndpoint.cs"
-  ] }
-```
-
----
-
-## Estrutura de Task (formato JSON)
-
-```json
-{
-  "id": "T001",
-  "title": "Criar Entity {Nome}",
-  "description": "Implementar entity {Nome} com propriedades X, Y, Z seguindo padrões EF Core",
-  "category": "entity",
-  "dependencies": [],
-  "estimatedMinutes": 30,
-  "status": "pending",
-  "specSections": ["## Domain Model", "## Business Rules"],
-  "contractInterfaces": ["I{Nome}Repository"],
-  "files": [
-    "Entities/{Nome}.cs",
-    "Database/ApplicationDbContext.cs"
-  ]
-}
-```
-
-## Categorias de Tasks (VSA)
-
-| Categoria | Descrição | Exemplos |
-|-----------|-----------|----------|
-| **entity** | Entities, Enums | Entity class, DbSet registration |
-| **errors** | Error factory classes | `{Entity}Errors.cs` |
-| **tags** | API endpoint tags | `ApiTags.cs` constants |
-| **migration** | DB migrations | EF migrations |
-| **slice** | Complete VSA slice | Handler + Validator + Endpoint |
-| **tests** | Unit tests, Integration tests | Handler tests, API tests |
-| **infra** | Docker, Migrations, Scripts | docker-compose, PostgreSQL migrations |
-| **docs** | README, API docs | OpenAPI spec, README update |
-
-## Ordem de Implementação Bottom-Up (VSA)
-
-```
-1. Entity + DbContext registration
-   ↓
-2. Errors + ApiTags
-   ↓
-3. Migrations
-   ↓
-4. Slices (Handler + Validator + Endpoint per operation)
-   ↓
-5. Tests (Unit → Integration)
-   ↓
-6. Infra (Docker, PostgreSQL migrations)
-   ↓
-7. Docs (README, Swagger)
-```