@polymorphism-tech/morph-spec 4.10.0 → 4.10.2

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

@@ -4,305 +4,309 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
 argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.10.0"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.2"
 ---
 
-# MORPH Tasks - FASE 4
+# MORPH Tasks — Phase 4
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
 
-Quebre a especificação em tasks executáveis, defina ordem de execução e estabeleça checkpoints.
+Break the approved specification into executable tasks, define execution order, and establish checkpoints.
 
-## Pré-requisitos
+## Prerequisites
 
-- [ ] FASE 3 (Clarify) concluída
-- [ ] `spec.md` atualizado com clarificações
-- [ ] Todos os edge cases documentados
+- [ ] Phase 3 (Clarify) completed
+- [ ] `spec.md` updated with clarifications
+- [ ] All edge cases documented
 
-## Ferramentas Recomendadas
+## Recommended Tools
 
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **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.
 
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Ler spec + contracts + decisions | **Read** todos os outputs | — |
-| Analisar complexidade de implementação | **Grep** padrões no código existente | — |
-| Contar padrões similares existentes | **Glob** `**/Services/**/*.cs` | — |
-| Consultar padrões de implementação | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Criar issues no GitHub a partir das tasks | **GitHub MCP** `create_issue()` | **Bash** `gh issue create ...` |
-| Renderizar template de tasks | **Bash** `npx morph-spec template render docs/tasks ...` | — |
-| Atualizar state com total de tasks | **Bash** `npx morph-spec state set ... tasks.total N` | — |
-
-**MCPs desta fase:** Context7 (estimar complexidade), GitHub (criar issues).
-
-**Anti-padrões:**
-- ❌ Task agent para quebrar spec simples de 1 domínio (faça diretamente)
-- ✅ Task agent para specs multi-domínio (backend + frontend + infra = 3 planners em paralelo)
-- ✅ Task agent quando spec tem 20+ requisitos em múltiplos bounded contexts
-- ❌ Criar tasks.json sem ler todos os outputs primeiro
-- ❌ **(VSA)** Criar tasks separadas para Handler, Validator e Endpoint — um slice = uma task
-- ❌ **(VSA)** Usar categorias DDD (`domain`, `application`, `infrastructure`) em projetos VSA
-- ❌ **(VSA)** Criar task de "Implementar Service layer" — não existe em VSA
+| 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)
 
 ---
 
-## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar breakdown de tasks)
+## Pre-flight (before starting task breakdown)
 
-### 0. Garantir fase tasks
+### 0. Ensure tasks phase
 
 ```bash
 npx morph-spec state get $ARGUMENTS
 ```
 
-Verifique o campo `"phase"` no output:
+Check the `"phase"` field:
 
-**Se `"phase": "tasks"`** → ✅ fase correta, prossiga.
+**If `"phase": "tasks"`** → correct phase, proceed.
 
-**Se `"phase": "clarify"`** → execute em sequência:
+**If `"phase": "clarify"`** → run in sequence:
 1. `npx morph-spec state mark-output $ARGUMENTS clarifications`
 2. `npx morph-spec phase advance $ARGUMENTS` (→ tasks)
 
-**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+**Any other value** → STOP — inconsistent state, report to user.
 
-> **Regra:** Nunca escreva em `4-tasks/` enquanto a fase não for `tasks`. O hook bloqueará a escrita.
+> **Rule:** Never write to `4-tasks/` until the phase is `tasks`. The hook will block writes.
 
 ---
 
-### 1. Ler todos os prerequisitos em PARALELO
+### 1. Read all prerequisites in PARALLEL
 
 ```
-# Uma única chamada, não sequencial:
+# Single parallel call, not sequential:
 Read: .morph/features/{feature}/1-design/spec.md
-    + Read: .morph/features/{feature}/1-design/contracts.cs
+    + 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  (se existir)
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
     + Read: .morph/config/config.json                               (→ architecture.style)
 ```
 
-### 2. Criar tasks de sessão para visibilidade
+### 2. Create session tasks for visibility
 
 ```
-TaskCreate: "Analisar spec e definir tasks"   → activeForm: "Analisando spec"
-TaskCreate: "Gerar tasks.md"                  → activeForm: "Gerando tasks.md"
-TaskCreate: "Avanço de fase"                  → activeForm: "Avançando fase"
+TaskCreate: "Analyze spec and define tasks" → activeForm: "Analyzing spec"
+TaskCreate: "Generate tasks.md"             → activeForm: "Generating tasks.md"
+TaskCreate: "Phase advance"                 → activeForm: "Advancing phase"
 ```
 
-> **Nota:** As tasks individuais T001-T00N serão criadas como native tasks durante a fase de implementação (`phase-implement`). Aqui mantemos apenas as 3 tasks de alto nível desta sessão de planejamento.
+> **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.
 
 ---
 
-## Workflow
-
-### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
+### 3. Entry checkpoint — verify prerequisites
 
-**⏸️ PAUSE - Antes de iniciar o breakdown de tasks:**
+Before starting the breakdown:
 
-- [ ] `spec.md` existe e foi aprovado pelo usuário?
-- [ ] `contracts.cs` existe e corresponde ao schema real?
-- [ ] `schema-analysis.md` foi validado (se aplicável)?
-- [ ] `decisions.md` contém ADRs para todas as escolhas críticas?
-- [ ] Design gate (`morph-spec approve $ARGUMENTS design`) foi aprovado?
-- [ ] Clarificações (FASE 3) foram resolvidas e spec atualizado?
+- [ ] `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?
 
-**❌ Se alguma checkbox NÃO estiver marcada:**
-→ Voltar para a fase correspondente e resolver
-
-**✅ Se TODAS as checkboxes estiverem marcadas:**
-→ Prosseguir para análise e breakdown
+If any checkbox is NOT checked → return to corresponding phase and resolve.
 
 ```bash
-# Verificar estado atual:
 npx morph-spec state get $ARGUMENTS
-# Verificar se design foi aprovado:
 npx morph-spec approval-status $ARGUMENTS
 ```
 
 ---
 
-### Passo 0: Detectar Estilo de Arquitetura
+## Workflow
+
+### Step 0: Detect Architecture Style
 
-Antes de tudo, determine se o projeto é VSA ou DDD:
+Before anything else, determine if the project is VSA or DDD:
 
 ```bash
 cat .morph/config/config.json | grep -A3 '"architecture"'
 ```
 
-**Se `config.architecture.style === "vertical-slice"`** → siga o **Passo 0.5 (VSA)** e pule o Passo 0 DDD.
-**Caso contrário** → siga o **Passo 0.6 (DDD)** abaixo.
+**If `config.architecture.style === "vertical-slice"`** → follow **Step 0.5 (VSA)** and skip DDD path.
+**Otherwise** → follow **Step 0.6 (DDD)** below.
 
 ---
 
-### Passo 0.5: Plano de Tasks — VSA
+### Step 0.5: VSA Task Plan
 
-> Para padrões de tarefas VSA e mapeamento DDD por nível, veja `references/task-planning-patterns.md`
+> For VSA task patterns and DDD-level mappings, see `references/task-planning-patterns.md`
 
-Leia a seção `## Architecture Style: Vertical Slice` do spec.md para o **VSA Blueprint**:
+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"
 ```
 
-Crie uma task por slice (entity → errors → tags → migration → slices CRUD → slices custom → tests). Cada slice = Handler + Validator + Endpoint numa única task. `GetAll` não tem Validator.
+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`.
 
-**Após definir tasks VSA, pule direto para o Passo 3 (Dependências).**
+**After defining VSA tasks, skip directly to Step 3 (Dependencies).**
 
 ---
 
-### Passo 0.6: Ler Nível de Domínio — DDD
+### Step 0.6: Read Domain Level — DDD
 
-Leia a seção `## Domain Complexity` do spec.md:
+Read the `## Domain Complexity` section from spec.md:
 
 ```bash
 grep -A15 "## Domain Complexity" ".morph/features/$ARGUMENTS/1-design/spec.md"
 ```
 
-> Se a seção não existir, assuma **Nível 1 (CRUD)**.
+> If the section doesn't exist, assume **Level 1 (CRUD)**.
 
-Use o nível para restringir categorias (Nível 1: domain→infra→application→presentation→tests; Nível 2: adiciona AggregateRoot, ValueObjects, DomainEvents, CQRS handlers; Nível 3: adiciona BC setup, Integration Events). Ver `references/task-planning-patterns.md` para tabela completa.
+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.
 
 ---
 
-### Passo 1: Analisar Spec
+### 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).
 
-> **VSA:** Se veio do Passo 0.5, o breakdown de tasks já foi definido — use os exemplos gerados como base e pule para o Passo 3 (Dependências).
+Read `.morph/features/$ARGUMENTS/1-design/spec.md` and identify:
 
-Leia `.morph/features/$ARGUMENTS/1-design/spec.md` e identifique:
+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)
 
-1. **Requisitos funcionais** (FR001, FR002, ...)
-2. **Componentes técnicos** (Entities, Services/Slices, Controllers/Endpoints, Pages)
-3. **Infraestrutura** (Bicep, migrations, configs)
-4. **Testes** (Unit tests, integration tests)
+### Step 2: Break Into Tasks
 
-### Passo 2: Quebrar em Tasks
+> For structure, categories, and implementation order, see `references/task-planning-patterns.md`
 
-> Para estrutura JSON, categorias e ordem de implementação, veja `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.
 
-Crie tasks no formato **T{NNN}** seguindo bottom-up: 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.
 
-### Passo 3: Definir Dependências
+### Step 3: Define Dependencies
 
-Para cada task, especifique dependências:
+For each task, specify dependencies:
 
 ```json
 {
   "id": "T005",
-  "title": "Criar {Nome}Service",
+  "title": "Create {Name}Service",
   "dependencies": ["T001", "T002"],
   "status": "pending"
 }
 ```
 
-**Regra:** Task só pode ser executada quando todas as dependências estão `completed`.
+**Rule:** A task can only be executed when all its dependencies are `completed`.
 
-### Passo 4: Estabelecer Checkpoints
+### Step 4: Establish Checkpoints
 
-Defina checkpoints a cada **3 tasks** ou **marcos significativos**:
+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 Completo",
+  "title": "Domain Layer Complete",
   "afterTasks": ["T001", "T002", "T003"],
   "validations": [
-    "Todas as entities criadas",
-    "Migrations aplicadas",
-    "Testes de domain passando"
+    "All entities created",
+    "Migrations applied",
+    "Domain tests passing"
   ]
 }
 ```
 
-### Passo 5: Estimar Esforço
+### Step 5: Estimate Effort
 
-Para cada task, estime tempo em minutos:
+For each task, estimate time **in minutes** (not vague labels like "Low/Medium"). Specific estimates help the plan phase determine execution strategy and parallelization.
 
-| Complexidade | Tempo Estimado |
-|--------------|----------------|
-| Trivial (CRUD básico) | 15-30 min |
-| Simples (Service, Controller) | 30-60 min |
-| Média (Business logic, validações) | 60-120 min |
-| Complexa (Integrações, AI) | 120-240 min |
+| 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 |
 
-### Passo 6: Gerar `tasks.md`
+### Step 6: Generate `tasks.md`
 
-Crie `.morph/features/$ARGUMENTS/4-tasks/tasks.md` com a estrutura completa de tasks, checkpoints e estimativas.
+Create `.morph/features/$ARGUMENTS/4-tasks/tasks.md` with the complete task structure, checkpoints, and estimates.
 
-### Passo 7: Incluir Tasks de IaC (se necessário)
+### Step 7: Include IaC Tasks (if needed)
 
-Se houver recursos Azure, adicionar tasks de Bicep e migrations.
+If there are Azure resources, add Bicep and migration tasks.
 
-### Passo 8: Atualizar State
+### Step 8: Update State
 
 ```bash
 npx morph-spec state set $ARGUMENTS tasks.total {N}
 npx morph-spec state mark-output $ARGUMENTS tasks
 ```
 
-## Outputs Gerados
+## Outputs
 
-- `.morph/features/$ARGUMENTS/4-tasks/tasks.md` - Breakdown completo de tasks
+- `.morph/features/$ARGUMENTS/4-tasks/tasks.md` — Complete task breakdown
 
-## PAUSA OBRIGATÓRIA
+## Mandatory Approval Pause
 
-Use `AskUserQuestion` para capturar aprovação explícita antes de avançar:
+Use `AskUserQuestion` to capture explicit approval before advancing. This gate prevents implementation from starting with an unapproved task list.
 
 ```json
 {
   "questions": [{
-    "header": "Aprovação",
-    "question": "Tasks geradas. Aprovar para iniciar implementação?",
+    "header": "Approval",
+    "question": "Tasks generated. Approve to start implementation?",
     "multiSelect": false,
     "options": [
-      { "label": "Aprovar e implementar", "description": "Avançar para fase de implementação" },
-      { "label": "Tenho feedback",        "description": "Digite o que deseja mudar no campo abaixo (Other)" }
+      { "label": "Approve and implement", "description": "Advance to implementation phase" },
+      { "label": "I have feedback",       "description": "Type what you want to change" }
     ]
   }]
 }
 ```
 
-- **"Aprovar e implementar"** →
+- **"Approve and implement"** →
   ```bash
   npx morph-spec approve $ARGUMENTS tasks
   npx morph-spec phase advance $ARGUMENTS
   ```
-- **"Tenho feedback" ou "Other"** → aplique o feedback recebido e repita esta PAUSA
+- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
 
-## Critérios de Avanço
+## Completion Criteria
 
-- [x] `tasks.json` criado com todas as tasks
-- [x] Tasks categorizadas corretamente
-- [x] Dependências mapeadas
-- [x] Checkpoints definidos (a cada 3 tasks)
-- [x] Esforço estimado por task
-- [x] Ordem de execução clara
-- [x] Tasks de IaC incluídas (se aplicável)
-- [x] State atualizado com total de tasks
-- [x] Usuário aprovou breakdown
+- [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`
 
 ---
 
-## Integração com Superpowers
+## Superpowers Integration
 
-> Disponível quando o plugin `superpowers` está instalado.
+> Available when the `superpowers` plugin is installed.
 
-| Skill | Quando Usar | Invocação |
+| Skill | When to Use | Invocation |
 |-------|-------------|-----------|
-| `writing-plans` | Após breakdown de tasks, para planejar sequência de implementação | `Skill(superpowers:writing-plans)` |
-| `executing-plans` | Para executar o plano de tasks em sessão separada | `Skill(superpowers:executing-plans)` |
+| `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)` |
 
 ---
 
-## Outputs desta Fase
+## Phase Outputs
 
 <!-- morph:outputs:tasks -->
-| Output | Caminho |
-|--------|---------|
+| Output | Path |
+|--------|------|
 | `tasks` | `.morph/features/{feature}/4-tasks/tasks.md` |
 <!-- /morph:outputs -->
 
 ---
 
-Após aprovação: "Planejamento completo! Execute `/morph-apply $ARGUMENTS` para iniciar implementação."
+After approval: "Planning complete! Run `/morph-apply $ARGUMENTS` to start implementation."