@polymorphism-tech/morph-spec 4.10.0 → 4.10.2

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

@@ -4,145 +4,137 @@ description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan
 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 Plan - FASE 4
+# MORPH Plan — Phase 4
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
 
-Gere um plano de implementacao detalhado com paths exatos, codigo TDD e estrategia de execucao.
+Generate a detailed implementation plan with exact paths, TDD code, and execution strategy.
 
-## Pre-requisitos
+## Prerequisites
 
-- [ ] FASE 3 (Clarify) concluida
-- [ ] `spec.md` atualizado com clarificacoes
-- [ ] `contracts.cs` ou `contracts.ts` definidos
+- [ ] Phase 3 (Clarify) completed
+- [ ] `spec.md` updated with clarifications
+- [ ] `contracts.cs` or `contracts.ts` defined
 
-## Ferramentas Recomendadas
+## Recommended Tools
 
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
 
-| Acao | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Ler spec + contracts + decisions | **Read** todos os outputs | --- |
-| Analisar codebase existente | **Glob** + **Grep** padroes | --- |
-| Consultar docs de libs | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Dispatch agents para analise | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS plan` | --- |
-| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS plan` | --- |
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read spec + contracts + decisions | **Read** all outputs | — |
+| Analyze existing codebase | **Glob** + **Grep** patterns | — |
+| Look up library docs | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Dispatch agents for analysis | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS plan` | — |
+| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS plan` | — |
 
-**Anti-padroes:**
-- :x: Gerar plano sem ler contracts.cs (contracts sao a fonte de verdade!)
-- :x: Paths genericos ("adicione o arquivo") -- sempre paths exatos
-- :x: Codigo incompleto no plano ("adicione validacao") -- sempre codigo completo
-- :x: Pular analise de codebase existente (padroes existentes guiam o plano)
-- :x: Ignorar `config.architecture.style` -- VSA e DDD tem estruturas diferentes
+**Anti-patterns:**
+- Generating plan without reading contracts (contracts are the source of truth!)
+- 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
 
 ---
 
-## PRE-VOO OBRIGATORIO
+## Pre-flight
 
-### 0. Garantir fase plan
+### 0. Ensure plan phase
 
 ```bash
 npx morph-spec state get $ARGUMENTS
 ```
 
-Verifique o campo `"phase"` no output:
-- `"phase": "plan"` -> fase correta, prossiga
-- qualquer outro valor -> execute `npx morph-spec phase advance $ARGUMENTS` e volte a verificar
+Check the `"phase"` field:
+- `"phase": "plan"` → correct phase, proceed
+- any other value → run `npx morph-spec phase advance $ARGUMENTS` and re-check
 
-> **Regra:** Nunca escreva em `3-plan/` enquanto a fase nao for `plan`.
+> **Rule:** Never write to `3-plan/` until the phase is `plan`.
 
-### 1. Ler todos os prerequisitos em PARALELO
+### 1. Read all prerequisites in PARALLEL
 
 ```
 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)
     + 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  (se existir)
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
     + Read: .morph/config/config.json
 ```
 
-### 2. Criar tasks de sessao
-
-```
-TaskCreate: "Analisar spec e planejar"        -> activeForm: "Analisando spec"
-TaskCreate: "Gerar plan.md"                   -> activeForm: "Gerando plano"
-TaskCreate: "Avanco de fase"                  -> activeForm: "Avancando fase"
-```
-
 ---
 
 ## Workflow
 
-### Passo 1: Analisar Feature para Contexto
+### Step 1: Analyze Feature for Context
 
-1. **Ler codebase existente** -- Glob para encontrar arquivos que serao modificados/criados
-2. **Identificar padroes** -- Grep por padroes similares ao que sera implementado
-3. **Verificar libs/frameworks** -- Context7 para docs das dependencias
-4. **Detectar arquitetura:**
+1. **Scan existing codebase** — Glob to find files that will be modified/created
+2. **Identify patterns** — Grep for patterns similar to what will be implemented
+3. **Check library docs** — Context7 for dependency documentation
+4. **Detect architecture:**
 
 ```bash
 cat .morph/config/config.json | grep -A3 '"architecture"'
 ```
 
-| Valor de `config.architecture.style` | Caminho |
-|--------------------------------------|---------|
-| `"vertical-slice"` | -> Estrutura VSA: `Features/{Entity}Feature/{Op}/` |
-| qualquer outro valor | -> Estrutura DDD por layer |
+| `config.architecture.style` value | Path structure |
+|------------------------------------|---------------|
+| `"vertical-slice"` | VSA: `Features/{Entity}Feature/{Operation}/` |
+| any other value | DDD by layer |
 
-### Passo 2: Determinar Estrategia de Execucao
+### Step 2: Determine Execution Strategy
 
-Execute a analise:
+Run the dispatch analysis:
 
 ```bash
 npx morph-spec dispatch-agents $ARGUMENTS plan
 ```
 
-**Fatores para recomendacao:**
+**Factors for recommendation:**
 
-| Fator | Calculo |
-|-------|---------|
-| `taskCount` | Numero de requisitos funcionais + componentes tecnicos no spec |
-| `domainCount` | Dominios distintos nos activeAgents (backend, frontend, infra) |
-| `agentCount` | Total de activeAgents |
-| `independence` | % de tasks sem dependencias cross-domain |
+| Factor | Calculation |
+|--------|-------------|
+| `taskCount` | Number of functional requirements + technical components in spec |
+| `domainCount` | Distinct domains in activeAgents (backend, frontend, infra) |
+| `agentCount` | Total activeAgents |
+| `independence` | % of tasks without cross-domain dependencies |
 
-**Decisao:**
+**Decision:**
 
-| Cenario | Recomendacao |
-|---------|--------------|
-| `taskCount < 8` AND `domainCount <= 2` | **Single session** -- implementacao direta |
-| `taskCount 8-20` AND `domainCount 2-3` | **Subagent-Driven** -- um subagent morph por grupo |
-| `taskCount > 20` OR `domainCount > 3` | **Agent Teams** -- coordenacao multi-dominio |
+| Scenario | Recommendation |
+|----------|----------------|
+| `taskCount < 8` AND `domainCount <= 2` | **Single session** — direct sequential implementation |
+| `taskCount 8-20` AND `domainCount 2-3` | **Subagent-Driven** — one subagent per task group |
+| `taskCount > 20` OR `domainCount > 3` | **Agent Teams** — multi-domain coordination |
 
-### Passo 3: Gerar `plan.md`
+### Step 3: Generate `plan.md`
 
-Crie `.morph/features/$ARGUMENTS/3-plan/plan.md` com a estrutura:
+Create `.morph/features/$ARGUMENTS/3-plan/plan.md` with this structure:
 
 ```markdown
 # {Feature Name} Implementation Plan
 
 > **For Claude:** Use morph:phase-implement to execute this plan.
 
-**Goal:** {Uma frase descrevendo o que sera construido}
+**Goal:** {One sentence describing what will be built}
 
-**Architecture:** {2-3 frases sobre a abordagem}
+**Architecture:** {2-3 sentences about the approach}
 
-**Tech Stack:** {Tecnologias chave}
+**Tech Stack:** {Key technologies}
 
 **Execution Strategy:** {single | subagents | agent-teams} (Recommended)
 
 ---
 
-## GROUP {A} --- {Nome do Grupo}
+## GROUP {A} — {Group Name}
 
-{Padrao e contexto do grupo}
+{Pattern and context for the group}
 
-### {A1} --- {Nome da task}
+### {A1} — {Task Name}
 
 **Files:**
 - Create: `exact/path/to/file.cs`
@@ -151,36 +143,36 @@ Crie `.morph/features/$ARGUMENTS/3-plan/plan.md` com a estrutura:
 
 **Step 1: Write the failing test**
 
-(Codigo completo do teste)
+(Complete test code)
 
 **Step 2: Run test to verify it fails**
 
-Run: `{comando exato}`
-Expected: FAIL with "{mensagem}"
+Run: `{exact command}`
+Expected: FAIL with "{message}"
 
 **Step 3: Write minimal implementation**
 
-(Codigo completo da implementacao)
+(Complete implementation code)
 
 **Step 4: Run test to verify it passes**
 
-Run: `{comando exato}`
+Run: `{exact command}`
 Expected: PASS
 
 **Step 5: Commit**
 
 git add {files}
-git commit -m "{mensagem}"
+git commit -m "{message}"
 ```
 
-**Regras obrigatorias:**
-- Paths exatos SEMPRE (nunca genericos)
-- Codigo COMPLETO no plano (nunca "adicione validacao")
-- Comandos exatos com output esperado
-- DRY, YAGNI, TDD, commits frequentes
-- Cada step e uma acao de 2-5 minutos
+**Mandatory rules:**
+- 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)
+- Each task follows the TDD 5-step cycle above — this is what makes the plan actionable
+- Keep each step to a 2-5 minute action
 
-### Passo 4: Atualizar State
+### Step 4: Update State
 
 ```bash
 npx morph-spec state mark-output $ARGUMENTS plan
@@ -188,67 +180,67 @@ npx morph-spec state mark-output $ARGUMENTS plan
 
 ---
 
-## PAUSA OBRIGATORIA
+## Mandatory Approval Pause
 
-Use `AskUserQuestion` para capturar aprovacao:
+Use `AskUserQuestion` to capture approval before advancing. This gate prevents task breakdown from starting with an unapproved plan.
 
 ```json
 {
   "questions": [
     {
-      "header": "Aprovacao",
-      "question": "Plano de implementacao gerado. Aprovar para iniciar task breakdown?",
+      "header": "Approval",
+      "question": "Implementation plan generated. Approve to start task breakdown?",
       "multiSelect": false,
       "options": [
-        { "label": "Aprovar plano", "description": "Avancar para fase de task breakdown" },
-        { "label": "Tenho feedback", "description": "Digite o que deseja mudar no campo abaixo (Other)" }
+        { "label": "Approve plan", "description": "Advance to task breakdown phase" },
+        { "label": "I have feedback", "description": "Type what you want to change" }
       ]
     },
     {
-      "header": "Execucao",
-      "question": "Qual estrategia de execucao para implementacao?",
+      "header": "Execution",
+      "question": "Which execution strategy for implementation?",
       "multiSelect": false,
       "options": [
-        { "label": "{Recomendacao} (Recommended)", "description": "{Justificativa baseada na analise do Passo 2}" },
-        { "label": "{Alternativa 1}", "description": "{Descricao}" },
-        { "label": "{Alternativa 2}", "description": "{Descricao}" }
+        { "label": "{Recommendation} (Recommended)", "description": "{Justification from Step 2 analysis}" },
+        { "label": "{Alternative 1}", "description": "{Description}" },
+        { "label": "{Alternative 2}", "description": "{Description}" }
       ]
     }
   ]
 }
 ```
 
-> A primeira opcao de "Execucao" deve ser a recomendacao context-aware calculada no Passo 2. As alternativas sao as outras estrategias.
+> The first "Execution" option should be the context-aware recommendation from Step 2. Alternatives are the other strategies.
 
-- **"Aprovar plano"** -> execute:
-```bash
-npx morph-spec approve $ARGUMENTS plan
-npx morph-spec phase advance $ARGUMENTS
-```
-- **"Tenho feedback" ou "Other"** -> aplique o feedback recebido e repita esta PAUSA
+- **"Approve plan"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS plan
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
 
 ---
 
-## Outputs desta Fase
+## Phase Outputs
 
 <!-- morph:outputs:plan -->
-| Output | Caminho |
-|--------|---------|
+| Output | Path |
+|--------|------|
 | `plan` | `.morph/features/{feature}/3-plan/plan.md` |
 <!-- /morph:outputs -->
 
 ---
 
-## Criterios de Avanco
+## Advancement Criteria
 
-- [x] `plan.md` criado com todos os grupos e tasks
-- [x] Paths exatos para todos os arquivos
-- [x] Codigo completo em cada step
-- [x] Comandos de teste com output esperado
-- [x] Estrategia de execucao definida e aprovada
-- [x] State atualizado (`mark-output plan`)
-- [x] Usuario aprovou plano
+- [x] `plan.md` created with all groups and tasks
+- [x] Exact paths for all files
+- [x] Complete code in each step
+- [x] Test commands with expected output
+- [x] Execution strategy defined and approved
+- [x] State updated (`mark-output plan`)
+- [x] User approved plan via `AskUserQuestion`
 
 ---
 
-Apos aprovacao: prosseguir automaticamente para FASE 5 (Tasks).
+After approval: proceed automatically to Phase 5 (Tasks).