@polymorphism-tech/morph-spec 4.8.18 → 4.9.0

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

@@ -1,450 +1,492 @@
----
-name: phase-implement
-description: MORPH-SPEC Phase 5 (Implement). Executes feature tasks using TDD with checkpoint validation every 3 tasks, smoke tests via Playwright, and generates code + recap.md. Use after task list approval when starting feature implementation.
-argument-hint: "[feature-name]"
-disable-model-invocation: true
-context: fork
-agent: general-purpose
-user-invocable: false
-cliVersion: "4.8.18"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# MORPH Implement - FASE 5
-
-> INTERNAL: Workflow skill used by /morph-apply during automated phase orchestration. Not a user command.
-
-Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap final.
-
-## Pré-requisitos
-
-- [ ] FASE 4 (Tasks) concluída
-- [ ] `tasks.md` ou `tasks.json` aprovado pelo usuário
-- [ ] Tasks gate (`morph-spec approve $ARGUMENTS tasks`) aprovado
-- [ ] Todos os outputs de design existem (spec.md, contracts.cs, decisions.md)
-
-## Ferramentas Recomendadas
-
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
-> **Example:** `references/recap-example.md` — filled-in recap.md showing expected output quality.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Verificar modo de execução (single/subagents/agent-teams) | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Grupos de tasks + prompts de subagents |
-| **Dispatch implementadores por domínio** (subagents) | **Task** subagents — um por grupo | Backend + frontend + infra em paralelo |
-| **Criar Agent Team** (features críticas multi-domínio) | Linguagem natural — veja Passo 0.5b | — |
-| Ler task details | **Read** tasks.json, spec.md, contracts.cs | — |
-| Criar novos arquivos | **Write** source files | — |
-| Modificar arquivos existentes | **Edit** source files | — |
-| Consultar API de biblioteca | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Executar migrations | **Supabase MCP** `query()` | **Bash** `npx supabase migration ...` |
-| Build do projeto | **Bash** `dotnet build` ou `npm run build` | — |
-| Rodar testes | **Bash** `dotnet test` ou `npm test` | — |
-| Checkpoint validation | **Bash** `npx morph-spec validate-feature ...` | — |
-| Marcar task concluída | **Bash** `npx morph-spec task done $ARGUMENTS T001` | — |
-| Smoke test no browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual |
-| Verificar erros de console | **Playwright MCP** `browser_console_messages()` | — |
-| Screenshot para recap | **Playwright MCP** `browser_take_screenshot()` | — |
-| Criar PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
-| Atualizar state | **Bash** `npx morph-spec state set ...` | — |
-
-**MCPs desta fase:** Supabase (migrations, RLS), Context7 (API lookup), Playwright (smoke test), GitHub (PRs).
-
-**Anti-padrões:**
-- ❌ Task agent para editar um único arquivo (use Edit direto)
-- ✅ Task agent para implementar service layer em 5+ arquivos (multi-file legítimo)
-- ✅ Task agents paralelos quando `tasks.total ≥ 6` e feature tem 2+ domínios ativos
-- ✅ Agent Teams quando backend e frontend precisam coordenar contratos de API
-- ❌ Agent Teams para features single-domain (subagents são suficientes)
-- ❌ Agent Teams sem plan approval (cria risco de implementações divergentes)
-- ❌ Bash `cat` para criar arquivos (use Write tool)
-- ❌ Bash `sed` para modificar código (use Edit tool)
-- ❌ Implementar sem ler contracts.cs primeiro (contracts são a fonte de verdade!)
-- ❌ Implementar tasks de backend e frontend sequencialmente quando são independentes
-- ❌ **(VSA)** Criar Application Service layer — handler acessa IRepository diretamente
-- ❌ **(VSA)** Registrar handlers/endpoints manualmente no Program.cs — auto-discovery via reflection
-- ❌ **(VSA)** Colocar Request/Response em arquivos separados do Handler
-- ❌ **(VSA)** Usar `Guid.NewGuid()` — use `Guid.CreateVersion7()`
-
----
-
-## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar implementação)
-
-### 1. Ler contexto completo em PARALELO
-
-```
-# Uma única chamada, não sequencial:
-Read: .morph/features/{feature}/3-tasks/tasks.md
-    + Read: .morph/features/{feature}/1-design/spec.md
-    + Read: .morph/features/{feature}/1-design/contracts.cs
-    + Read: .morph/config/config.json                       (→ architecture.style)
-```
-
-### 2. Criar native tasks individuais por T001-T00N
-
-Após ler `tasks.md` no passo 1, crie **uma native task por task encontrada**:
-
-```
-# Para cada task em tasks.md (T001, T002, ..., T00N):
-TaskCreate: "{T001}: {título da task}"    → description: descrição completa → activeForm: "Implementando T001"
-TaskCreate: "{T002}: {título da task}"    → description: descrição completa → activeForm: "Implementando T002"
-... (uma TaskCreate por task)
-
-# Tarefas orquestrais sempre ao final:
-TaskCreate: "Checkpoints e validação"     → activeForm: "Validando checkpoint"
-TaskCreate: "Gerar recap.md"              → activeForm: "Gerando recap"
-```
-
-**Após criar todas as tasks, configure dependências espelhando `tasks.md`:**
-```
-# Para cada task com `dependencies: [T00X, T00Y]` em tasks.md:
-TaskUpdate(taskId="<id de T003>", addBlockedBy=["<id de T001>", "<id de T002>"])
-```
-
-> Guarde o mapeamento `{T001 → taskId}` internamente para usar nos TaskUpdates do loop.
-
----
-
-## Workflow
-
-### Passo 0.5: Planejar Modo de Execução
-
-**Execute antes de qualquer implementação:**
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement
-```
-
-**O output inclui um campo `mode` que determina o caminho de execução:**
-
-| `mode` | Ação |
-|--------|------|
-| `"single"` | → Continue para o workflow sequencial normal (Passo 1) |
-| `"subagents"` | → Dispatch Task subagents em paralelo (abaixo) |
-| `"agent-teams"` | → Crie Agent Team com plan approval (Passo 0.5b) |
-
----
-
-#### Modo `"subagents"` (se `mode: "subagents"` no output):
-
-1. Leia os `taskGroups` retornados (ex: `backend`, `frontend`, `infra`)
-2. Para cada grupo com ≥ 3 tasks e sem dependências cruzadas, use **Task tool** com o `taskPrompt` do dispatch config:
-
-```
-[Task tool — grupo backend, por exemplo]
-Prompt do dispatch config enriquecido:
-
-Você é o implementador do grupo BACKEND da feature '$ARGUMENTS'.
-
-Contexto completo:
-- Spec: [conteúdo de .morph/features/$ARGUMENTS/1-design/spec.md]
-- Contracts: [conteúdo de .morph/features/$ARGUMENTS/1-design/contracts.cs]
-- Tasks do grupo: [lista de TXXX do grupo backend]
-
-# No início deste subagent (grupo BACKEND):
-# 1. Criar native task por task do grupo:
-#    TaskCreate: "{T00X}: {título}" → activeForm: "Implementando T00X"
-# 2. Configurar dependências do grupo via TaskUpdate:
-#    TaskUpdate(taskId="<id de T003>", addBlockedBy=["<id de T001>", "<id de T002>"])
-# Guarde o mapeamento {T00X → taskId} para usar no loop abaixo.
-
-Para cada task do grupo, em ordem:
-1. TaskUpdate(taskId="<native id de T00X>", status="in_progress")
-2. Execute: npx morph-spec task start $ARGUMENTS TXXX
-3. Leia a descrição completa da task
-4. Implemente os arquivos — use Write (novo) ou Edit (existente)
-5. Verifique build: [dotnet build / npm run build]
-6. Execute: npx morph-spec task done $ARGUMENTS TXXX
-7. Se task done retornar sem erro: TaskUpdate(taskId="<native id de T00X>", status="completed")
-
-A cada 3 tasks:
-- Execute: npx morph-spec checkpoint-save $ARGUMENTS
-- Execute: npx morph-spec validate-feature $ARGUMENTS --phase implement
-- Reporte qualquer falha de validação antes de continuar
-
-Restrições OBRIGATÓRIAS:
-- Modifique APENAS os arquivos listados nas tasks do grupo BACKEND
-- NÃO toque em arquivos de frontend, UI ou infra
-- Se encontrar dependência em outro grupo, pause e reporte
-```
-
-3. Dispare os Task subagents dos grupos em **paralelo** (quando sem dependências entre si)
-4. Após todos completarem, valide integração: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
-
-**Se `mode: "single"`** (feature pequena ou single-domain):
-→ Continue para o workflow sequencial normal abaixo.
-
----
-
-### Passo 0.5b: Agent Teams (features críticas multi-domínio)
-
-**Quando usar:** `mode: "agent-teams"` no output de `dispatch-agents`
-**Requisito:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` no `.claude/settings.local.json` (instalado pelo morph-spec)
-
-**Por que Agent Teams em vez de subagents:**
-Agent Teams têm TaskList compartilhada, mensagens diretas entre teammates e hooks `TeammateIdle`. Subagents são fire-and-forget. Para features onde backend e frontend precisam coordenar contratos de API, Agent Teams garantem que o frontend não implemente chamadas antes do backend estabilizar os DTOs.
-
-**1. Crie o Agent Team com linguagem natural:**
-
-```
-Crie um agent team para implementar a feature '$ARGUMENTS' com teammates:
-- Backend teammate (dotnet-senior): Implemente as tasks do grupo backend.
-  Contexto: .morph/features/$ARGUMENTS/1-design/spec.md, contracts.cs, standards/coding.md
-  Restrição: Modifique APENAS arquivos de backend/domain/application.
-  Antes de implementar interfaces compartilhadas, envie mensagem ao frontend teammate.
-- Frontend teammate (blazor-builder OU nextjs-expert): Implemente as tasks do grupo frontend.
-  Contexto: .morph/features/$ARGUMENTS/1-design/spec.md, design-system.md, standards/frontend/
-  Restrição: Modifique APENAS arquivos de UI/components/pages.
-  Aguarde confirmação do backend teammate antes de implementar chamadas de API.
-- Quality teammate (standards-architect): Revise o output de cada teammate e execute validate-feature.
-  Exija plan approval antes de cada implementação.
-  Só aprove planos que correspondam ao contracts.cs e spec.md.
-```
-
-**2. Protocolo de coordenação entre teammates:**
-
-- Backend deve completar definição de DTOs/interfaces ANTES do frontend implementar chamadas de API
-- Para qualquer interface compartilhada: backend envia mensagem ao frontend confirmando contratos estáveis
-- Se frontend precisar de um endpoint que não existe → instrua a enviar mensagem ao backend teammate
-- Conflitos de contratos → escalone ao quality teammate para resolver
-
-**3. Configurações obrigatórias ao criar o team:**
-
-- Habilite **plan approval**: "Require plan approval before each teammate implements"
-- Gate de qualidade: "Only approve plans that match contracts.cs and spec.md"
-- Restrição de domínio por teammate: cada um modifica APENAS arquivos do seu domínio
-
-**4. Após todos os teammates completarem:**
-
-```bash
-npx morph-spec validate-feature $ARGUMENTS --phase implement
-```
-
-Sintetize os resultados de todos os teammates no recap.md (Passo 6).
-
----
-
-### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
-
-**⏸️ Antes de iniciar implementação:**
-
-- [ ] `tasks.md` ou `tasks.json` existe e foi aprovado?
-- [ ] Tasks gate aprovado (`morph-spec approve $ARGUMENTS tasks`)?
-- [ ] `spec.md` atualizado com clarificações?
-- [ ] `contracts.cs` corresponde ao schema real?
-- [ ] Build base do projeto compila sem erros?
-
-```bash
-npx morph-spec state get $ARGUMENTS
-npx morph-spec approval-status $ARGUMENTS
-```
-
-**❌ Se alguma checkbox NÃO estiver marcada:**
-→ Voltar para a fase correspondente
-
----
-
-### Passo 1: Carregar Contexto Completo
-
-Leia todos os outputs antes de implementar:
-
-1. `.morph/features/$ARGUMENTS/3-tasks/tasks.md` — Lista de tasks
-2. `.morph/features/$ARGUMENTS/1-design/spec.md` — Especificação completa
-3. `.morph/features/$ARGUMENTS/1-design/contracts.cs` — Interfaces e DTOs
-4. `.morph/features/$ARGUMENTS/1-design/decisions.md` — ADRs
-5. `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Schema real (se existir)
-6. `.morph/features/$ARGUMENTS/2-ui/design-system.md` — Design tokens (se existir)
-
-**Detectar estilo de arquitetura:**
-```bash
-# Leia config para saber se é VSA ou DDD:
-cat .morph/config/config.json | grep architecture
-```
-
-Se `config.architecture.style === "vertical-slice"` → siga o **Passo 1.5** antes de implementar.
-Caso contrário → vá direto para o Passo 2.
-
-### Passo 1.5: Guia de Implementação VSA (somente se `style: "vertical-slice"`)
-
-> Para a estrutura completa de slices e regras VSA, veja `references/vsa-implementation-guide.md`
-
-Estrutura: `Features/{Entity}Feature/{Op}/` com Handler (+ Request/Response records) + Validator + Endpoint por slice. Tudo `sealed`. `Guid.CreateVersion7()`. `result.Match()` nos endpoints. Sem Application Service layer — handler acessa IRepository diretamente. Auto-discovery via reflection: não registrar manualmente no Program.cs.
-
-Após cada slice completo, verificar build:
-```bash
-dotnet build
-```
-
-### Passo 2: Iniciar Primeira Task
-
-```bash
-npx morph-spec task next $ARGUMENTS
-```
-
-Para cada task (T001 → T00N):
-
-1. **Marcar como em progresso (native task):**
-   ```
-   TaskUpdate(taskId="<native id de T001>", status="in_progress")
-   ```
-2. **Iniciar via CLI:**
-   ```bash
-   npx morph-spec task start $ARGUMENTS T001
-   ```
-3. **Ler a task description** completa
-4. **Ler contracts.cs** para DTOs/interfaces relevantes
-5. **Implementar** usando Write (novo) ou Edit (existente)
-6. **Verificar** — build, lint, testes
-7. **Marcar como done via CLI:**
-   ```bash
-   npx morph-spec task done $ARGUMENTS T001
-   ```
-8. **Se `task done` retornar sem erro, marcar native task como concluída:**
-   ```
-   TaskUpdate(taskId="<native id de T001>", status="completed")
-   ```
-   > **Nota:** `TaskUpdate(completed)` só ocorre se `task done` retornar sem erro (validação passou).
-
-### Passo 3: Checkpoint a Cada 3 Tasks
-
-**A cada 3 tasks completadas:**
-
-```bash
-# Save checkpoint
-npx morph-spec checkpoint-save $ARGUMENTS
-
-# Run validation
-npx morph-spec validate-feature $ARGUMENTS --phase implement
-```
-
-**Se validação falhar:**
-1. NÃO avançar para próxima task
-2. Corrigir issues reportados
-3. Re-rodar validação
-4. Só então prosseguir
-
-### Passo 4: Test-Driven Development (Recomendado)
-
-Para cada task de implementação:
-
-1. **Escrever teste primeiro** (unit test para service/domain)
-2. **Rodar teste** — deve falhar (RED)
-3. **Implementar** o mínimo para passar
-4. **Rodar teste** — deve passar (GREEN)
-5. **Refatorar** se necessário (REFACTOR)
-
-```bash
-# .NET
-dotnet test --filter "FullyQualifiedName~{TestClass}"
-
-# Node.js
-npm test -- test/path/to/test.js
-```
-
-### Passo 5: Smoke Test com Playwright (se UI)
-
-Após implementar componentes visuais:
-
-```javascript
-// Navegar para a página
-await mcp__playwright__browser_navigate({ url: 'http://localhost:5000/feature-page' });
-
-// Capturar estado da página
-await mcp__playwright__browser_snapshot();
-
-// Verificar erros de console
-await mcp__playwright__browser_console_messages({ level: 'error' });
-
-// Screenshot para recap
-await mcp__playwright__browser_take_screenshot({ type: 'png' });
-```
-
-### Passo 6: Gerar `recap.md`
-
-Após TODAS as tasks completadas:
-
-```bash
-npx morph-spec generate recap $ARGUMENTS
-```
-
-> Para o formato completo do recap, veja `references/recap-example.md`
-
-### Passo 7: Atualizar State
-
-```bash
-npx morph-spec state set $ARGUMENTS status done
-npx morph-spec state mark-output $ARGUMENTS recap
-```
-
-### Passo 8: Revisão Pós-Implementação (obrigatório antes do PR)
-
-```bash
-/post-implementation $ARGUMENTS
-```
-
-Execute o skill `post-implementation` antes de criar o PR. Ele orquestra:
-- Scans automáticos (CRITICAL findings bloqueiam PR)
-- Test suite completo
-- `validate-feature` final
-- Smoke test via Playwright (obrigatório se dev server ativo)
-- Checklist de code review (CRITICAL + HIGH)
-- Checkpoint + recap final
-
-### Passo 9: Frontend Review (NEXTJS/FULLSTACK)
-
-Se stack for NEXTJS ou FULLSTACK:
-
-```bash
-/frontend-review $ARGUMENTS
-```
-
-Complementa o `post-implementation` com: scan de acessibilidade (static + axe-core runtime),
-screenshots responsivos (mobile/tablet/desktop), e verificação de SEO metadata.
-
----
-
-## Integração com Superpowers
-
-> Disponível quando o plugin `superpowers` está instalado.
-
-| Skill | Quando Usar | Invocação |
-|-------|-------------|-----------|
-| `test-driven-development` | Para cada task de implementação | `Skill(superpowers:test-driven-development)` |
-| `systematic-debugging` | Quando testes falham ou erros inesperados | `Skill(superpowers:systematic-debugging)` |
-| `requesting-code-review` | Após implementação completa | `Skill(superpowers:requesting-code-review)` |
-| `verification-before-completion` | Antes de marcar feature como done | Use `verification-before-completion` (morph-spec version) |
-| `post-implementation` | Antes de criar o PR (scans + smoke test + review) | `/post-implementation {feature}` |
-
----
-
-## Outputs Gerados
-
-- Código fonte implementado (vários arquivos)
-- Testes unitários e de integração
-- `.morph/features/$ARGUMENTS/4-implement/recap.md` — Resumo da implementação
-
-## Critérios de Conclusão
-
-- [x] Todas as tasks completadas
-- [x] Build compila sem erros
-- [x] Testes passando
-- [x] Validation pipeline passa
-- [x] `recap.md` gerado
-- [x] State atualizado para `status: done`
-- [x] Checkpoints salvos a cada 3 tasks
-- [x] `/post-implementation` executado sem BLOCKs (smoke test, scans, code review)
-
----
-
-## Outputs desta Fase
-
-<!-- morph:outputs:implement -->
-| Output | Caminho |
-|--------|---------|
-| `recap` | `.morph/features/{feature}/4-implement/recap.md` |
-<!-- /morph:outputs -->
-
----
-
-Feature completa! Considere criar um PR e rodar `morph-spec session-summary $ARGUMENTS`.
+---
+name: morph:phase-implement
+description: MORPH-SPEC Phase 5 (Implement). Executes feature tasks using TDD with checkpoint validation every 3 tasks, smoke tests via Playwright, and generates code + recap.md. Use after task list approval when starting feature implementation.
+argument-hint: "[feature-name]"
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+user-invocable: false
+cliVersion: "4.9.0"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# MORPH Implement - FASE 5
+
+> INTERNAL: Workflow skill used by /morph-apply during automated phase orchestration. Not a user command.
+
+Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap final.
+
+## Pré-requisitos
+
+- [ ] FASE 4 (Tasks) concluída
+- [ ] `tasks.md` ou `tasks.json` aprovado pelo usuário
+- [ ] Tasks gate (`morph-spec approve $ARGUMENTS tasks`) aprovado
+- [ ] Todos os outputs de design existem (spec.md, contracts.cs, decisions.md)
+
+## Pre-flight — Validação Mecânica (OBRIGATÓRIO)
+
+Antes de qualquer task, valide que as fases anteriores estão realmente completas. O `state.json` pode ter sido setado manualmente — estes comandos verificam os artefatos reais no filesystem.
+
+```bash
+# 1. Verifica outputs obrigatórios de todas as fases anteriores
+npx morph-spec validate-feature $ARGUMENTS
+
+# 2. Confirma que todos os approval gates foram aprovados
+npx morph-spec approval-status $ARGUMENTS
+```
+
+Se qualquer check falhar → **STOP**. Não inicie nenhuma task. Reporte ao usuário o que está faltando e quais comandos rodar para resolver:
+
+| Problema | Comando de resolução |
+|----------|---------------------|
+| Output faltando (spec.md, contracts, etc.) | Volte à fase correspondente e gere o output |
+| Gate não aprovado (design, tasks) | `npx morph-spec approve $ARGUMENTS <gate>` |
+| Phase inválida | `npx morph-spec phase advance $ARGUMENTS` |
+
+**Esta etapa não é opcional.** Só prossiga quando ambos os comandos retornarem sem erros.
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Example:** `references/recap-example.md` — filled-in recap.md showing expected output quality.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Verificar modo de execução (single/subagents/agent-teams) | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Grupos de tasks + prompts de subagents |
+| **Dispatch implementadores por domínio** (subagents) | **Agent** `subagent_type=<taskGroups[grupo].agentId>` + `prompt=taskPrompt` do dispatch config | Backend + frontend + infra em paralelo |
+| **Criar Agent Team** (features críticas multi-domínio) | Linguagem natural — veja Passo 0.5b | — |
+| Ler task details | **Read** tasks.json, spec.md, contracts.cs | — |
+| Criar novos arquivos | **Write** source files | — |
+| Modificar arquivos existentes | **Edit** source files | — |
+| Consultar API de biblioteca | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Executar migrations | **Supabase MCP** `query()` | **Bash** `npx supabase migration ...` |
+| Build do projeto | **Bash** `dotnet build` ou `npm run build` | — |
+| Rodar testes | **Bash** `dotnet test` ou `npm test` | — |
+| Checkpoint validation | **Bash** `npx morph-spec validate-feature ...` | — |
+| Marcar task concluída | **Bash** `npx morph-spec task done $ARGUMENTS T001` | — |
+| Smoke test no browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual |
+| Verificar erros de console | **Playwright MCP** `browser_console_messages()` | — |
+| Screenshot para recap | **Playwright MCP** `browser_take_screenshot()` | — |
+| Criar PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
+| Atualizar state | **Bash** `npx morph-spec state set ...` | — |
+
+**MCPs desta fase:** Supabase (migrations, RLS), Context7 (API lookup), Playwright (smoke test), GitHub (PRs).
+
+**Anti-padrões:**
+- ❌ Task agent para editar um único arquivo (use Edit direto)
+- ✅ Task agent para implementar service layer em 5+ arquivos (multi-file legítimo)
+- ✅ Task agents paralelos quando `tasks.total ≥ 6` e feature tem 2+ domínios ativos
+- ✅ Agent Teams quando backend e frontend precisam coordenar contratos de API
+- ❌ Agent Teams para features single-domain (subagents são suficientes)
+- ❌ Agent Teams sem plan approval (cria risco de implementações divergentes)
+- ❌ Bash `cat` para criar arquivos (use Write tool)
+- ❌ Bash `sed` para modificar código (use Edit tool)
+- ❌ Implementar sem ler contracts.cs primeiro (contracts são a fonte de verdade!)
+- ❌ Implementar tasks de backend e frontend sequencialmente quando são independentes
+- ❌ **(VSA)** Criar Application Service layer — handler acessa IRepository diretamente
+- ❌ **(VSA)** Registrar handlers/endpoints manualmente no Program.cs — auto-discovery via reflection
+- ❌ **(VSA)** Colocar Request/Response em arquivos separados do Handler
+- ❌ **(VSA)** Usar `Guid.NewGuid()` — use `Guid.CreateVersion7()`
+- ❌ **Tentar corrigir um bug sem invocar `systematic-debugging` primeiro** — "a mudança é pequena" não é justificativa
+- ✅ Ao encontrar bug: `Skill(superpowers:systematic-debugging)` → causa raiz → fix mínimo → verificar
+
+---
+
+## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar implementação)
+
+### 1. Ler contexto completo em PARALELO
+
+```
+# Uma única chamada, não sequencial:
+Read: .morph/features/{feature}/3-tasks/tasks.md
+    + Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs
+    + Read: .morph/config/config.json                       (→ architecture.style)
+```
+
+### 2. Criar native tasks individuais por T001-T00N
+
+Após ler `tasks.md` no passo 1, crie **uma native task por task encontrada**:
+
+```
+# Para cada task em tasks.md (T001, T002, ..., T00N):
+TaskCreate: "{T001}: {título da task}"    → description: descrição completa → activeForm: "Implementando T001"
+TaskCreate: "{T002}: {título da task}"    → description: descrição completa → activeForm: "Implementando T002"
+... (uma TaskCreate por task)
+
+# Tarefas orquestrais sempre ao final:
+TaskCreate: "Checkpoints e validação"     → activeForm: "Validando checkpoint"
+TaskCreate: "Gerar recap.md"              → activeForm: "Gerando recap"
+```
+
+**Após criar todas as tasks, configure dependências espelhando `tasks.md`:**
+```
+# Para cada task com `dependencies: [T00X, T00Y]` em tasks.md:
+TaskUpdate(taskId="<id de T003>", addBlockedBy=["<id de T001>", "<id de T002>"])
+```
+
+> Guarde o mapeamento `{T001 → taskId}` internamente para usar nos TaskUpdates do loop.
+
+---
+
+## Workflow
+
+### Passo 0.5: Planejar Modo de Execução
+
+**Execute antes de qualquer implementação:**
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+**O output inclui um campo `mode` que determina o caminho de execução:**
+
+| `mode` | Ação |
+|--------|------|
+| `"single"` | → Continue para o workflow sequencial normal (Passo 1) |
+| `"subagents"` | → Dispatch Task subagents em paralelo (abaixo) |
+| `"agent-teams"` | → Crie Agent Team com plan approval (Passo 0.5b) |
+
+---
+
+#### Modo `"subagents"` (se `mode: "subagents"` no output):
+
+1. Leia os `taskGroups` retornados (ex: `backend`, `frontend`, `infra`)
+2. Para cada grupo com ≥ 3 tasks e sem dependências cruzadas, use o **Agent tool** com o `subagent_type=<agentId>` do grupo e o `taskPrompt` do dispatch config:
+
+> **Mapeamento:** `taskGroups[grupo].agentId` do dispatch config = `subagent_type` no Agent tool.
+> Exemplo: `agentId: "dotnet-senior"` → `Agent(subagent_type=dotnet-senior, prompt=taskPrompt)`.
+
+```
+[Task tool — grupo backend, por exemplo]
+Prompt do dispatch config enriquecido:
+
+Você é o implementador do grupo BACKEND da feature '$ARGUMENTS'.
+
+Contexto completo:
+- Spec: [conteúdo de .morph/features/$ARGUMENTS/1-design/spec.md]
+- Contracts: [conteúdo de .morph/features/$ARGUMENTS/1-design/contracts.cs]
+- Tasks do grupo: [lista de TXXX do grupo backend]
+
+# No início deste subagent (grupo BACKEND):
+# 1. Criar native task por task do grupo:
+#    TaskCreate: "{T00X}: {título}" → activeForm: "Implementando T00X"
+# 2. Configurar dependências do grupo via TaskUpdate:
+#    TaskUpdate(taskId="<id de T003>", addBlockedBy=["<id de T001>", "<id de T002>"])
+# Guarde o mapeamento {T00X → taskId} para usar no loop abaixo.
+
+Para cada task do grupo, em ordem:
+1. TaskUpdate(taskId="<native id de T00X>", status="in_progress")
+2. Execute: npx morph-spec task start $ARGUMENTS TXXX
+3. Leia a descrição completa da task
+4. Implemente os arquivos — use Write (novo) ou Edit (existente)
+5. Verifique build: [dotnet build / npm run build]
+5b. Invoke Skill(verification-before-completion) — só prossiga para o passo 6 se passar
+6. Execute: npx morph-spec task done $ARGUMENTS TXXX
+7. Se task done retornar sem erro: TaskUpdate(taskId="<native id de T00X>", status="completed")
+
+A cada 3 tasks:
+- Execute: npx morph-spec checkpoint-save $ARGUMENTS
+- Execute: npx morph-spec validate-feature $ARGUMENTS --phase implement
+- Reporte qualquer falha de validação antes de continuar
+
+Restrições OBRIGATÓRIAS:
+- Modifique APENAS os arquivos listados nas tasks do grupo BACKEND
+- NÃO toque em arquivos de frontend, UI ou infra
+- Se encontrar dependência em outro grupo, pause e reporte
+```
+
+3. Dispare os Task subagents dos grupos em **paralelo** (quando sem dependências entre si)
+4. Após todos completarem, valide integração: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+
+**Se `mode: "single"`** (feature pequena ou single-domain):
+→ Continue para o workflow sequencial normal abaixo.
+
+---
+
+### Passo 0.5b: Agent Teams (features críticas multi-domínio)
+
+**Quando usar:** `mode: "agent-teams"` no output de `dispatch-agents`
+**Requisito:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` no `.claude/settings.local.json` (instalado pelo morph-spec)
+
+**Por que Agent Teams em vez de subagents:**
+Agent Teams têm TaskList compartilhada, mensagens diretas entre teammates e hooks `TeammateIdle`. Subagents são fire-and-forget. Para features onde backend e frontend precisam coordenar contratos de API, Agent Teams garantem que o frontend não implemente chamadas antes do backend estabilizar os DTOs.
+
+**1. Crie o Agent Team com linguagem natural:**
+
+```
+Crie um agent team para implementar a feature '$ARGUMENTS' com teammates:
+- Backend teammate (dotnet-senior): Implemente as tasks do grupo backend.
+  Contexto: .morph/features/$ARGUMENTS/1-design/spec.md, contracts.cs, standards/coding.md
+  Restrição: Modifique APENAS arquivos de backend/domain/application.
+  Antes de implementar interfaces compartilhadas, envie mensagem ao frontend teammate.
+- Frontend teammate (blazor-builder OU nextjs-expert): Implemente as tasks do grupo frontend.
+  Contexto: .morph/features/$ARGUMENTS/1-design/spec.md, design-system.md, standards/frontend/
+  Restrição: Modifique APENAS arquivos de UI/components/pages.
+  Aguarde confirmação do backend teammate antes de implementar chamadas de API.
+- Quality teammate (standards-architect): Revise o output de cada teammate e execute validate-feature.
+  Exija plan approval antes de cada implementação.
+  Só aprove planos que correspondam ao contracts.cs e spec.md.
+```
+
+**2. Protocolo de coordenação entre teammates:**
+
+- Backend deve completar definição de DTOs/interfaces ANTES do frontend implementar chamadas de API
+- Para qualquer interface compartilhada: backend envia mensagem ao frontend confirmando contratos estáveis
+- Se frontend precisar de um endpoint que não existe → instrua a enviar mensagem ao backend teammate
+- Conflitos de contratos → escalone ao quality teammate para resolver
+
+**3. Configurações obrigatórias ao criar o team:**
+
+- Habilite **plan approval**: "Require plan approval before each teammate implements"
+- Gate de qualidade: "Only approve plans that match contracts.cs and spec.md"
+- Restrição de domínio por teammate: cada um modifica APENAS arquivos do seu domínio
+
+**4. Após todos os teammates completarem:**
+
+```bash
+npx morph-spec validate-feature $ARGUMENTS --phase implement
+```
+
+Sintetize os resultados de todos os teammates no recap.md (Passo 6).
+
+---
+
+### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
+
+**⏸️ Antes de iniciar implementação:**
+
+- [ ] `tasks.md` ou `tasks.json` existe e foi aprovado?
+- [ ] Tasks gate aprovado (`morph-spec approve $ARGUMENTS tasks`)?
+- [ ] `spec.md` atualizado com clarificações?
+- [ ] `contracts.cs` corresponde ao schema real?
+- [ ] Build base do projeto compila sem erros?
+- [ ] `activeAgents` estão populados? (`morph-spec state get $ARGUMENTS` → campo `activeAgents` não vazio)
+
+```bash
+npx morph-spec state get $ARGUMENTS
+npx morph-spec approval-status $ARGUMENTS
+# Se activeAgents estiver vazio → pare aqui e execute /phase-setup $ARGUMENTS primeiro
+npx morph-spec state get $ARGUMENTS | grep -A5 activeAgents
+```
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar para a fase correspondente
+
+**❌ Se `activeAgents` estiver vazio:**
+→ Execute o skill `phase-setup` primeiro: `/phase-setup $ARGUMENTS`
+→ Agentes não detectados = standards não carregados = implementação sem contexto correto
+
+---
+
+### Passo 1: Carregar Contexto Completo
+
+Leia todos os outputs antes de implementar:
+
+1. `.morph/features/$ARGUMENTS/3-tasks/tasks.md` — Lista de tasks
+2. `.morph/features/$ARGUMENTS/1-design/spec.md` — Especificação completa
+3. `.morph/features/$ARGUMENTS/1-design/contracts.cs` — Interfaces e DTOs
+4. `.morph/features/$ARGUMENTS/1-design/decisions.md` — ADRs
+5. `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Schema real (se existir)
+6. `.morph/features/$ARGUMENTS/2-ui/design-system.md` — Design tokens (se existir)
+
+**Detectar estilo de arquitetura:**
+```bash
+# Leia config para saber se é VSA ou DDD:
+cat .morph/config/config.json | grep architecture
+```
+
+Se `config.architecture.style === "vertical-slice"` → siga o **Passo 1.5** antes de implementar.
+Caso contrário → vá direto para o Passo 2.
+
+### Passo 1.5: Guia de Implementação VSA (somente se `style: "vertical-slice"`)
+
+> Para a estrutura completa de slices e regras VSA, veja `references/vsa-implementation-guide.md`
+
+Estrutura: `Features/{Entity}Feature/{Op}/` com Handler (+ Request/Response records) + Validator + Endpoint por slice. Tudo `sealed`. `Guid.CreateVersion7()`. `result.Match()` nos endpoints. Sem Application Service layer — handler acessa IRepository diretamente. Auto-discovery via reflection: não registrar manualmente no Program.cs.
+
+Após cada slice completo, verificar build:
+```bash
+dotnet build
+```
+
+### Passo 2: Iniciar Primeira Task
+
+```bash
+npx morph-spec task next $ARGUMENTS
+```
+
+Para cada task (T001 → T00N):
+
+1. **Marcar como em progresso (native task):**
+   ```
+   TaskUpdate(taskId="<native id de T001>", status="in_progress")
+   ```
+2. **Iniciar via CLI:**
+   ```bash
+   npx morph-spec task start $ARGUMENTS T001
+   ```
+3. **Ler a task description** completa
+4. **Ler contracts.cs** para DTOs/interfaces relevantes
+5. **Implementar** usando Write (novo) ou Edit (existente)
+6. **Verificar** — build, lint, testes
+6b. **⚠️ OBRIGATÓRIO — Verificação antes de `task done`:**
+   Invoke `Skill(verification-before-completion)` ou execute manualmente:
+   ```bash
+   npx morph-spec validate-feature $ARGUMENTS --phase implement
+   ```
+   Só prossiga para o passo 7 se a verificação passar. Se falhar → corrija antes de marcar `task done`.
+7. **Marcar como done via CLI:**
+   ```bash
+   npx morph-spec task done $ARGUMENTS T001
+   ```
+8. **Se `task done` retornar sem erro, marcar native task como concluída:**
+   ```
+   TaskUpdate(taskId="<native id de T001>", status="completed")
+   ```
+   > **Nota:** `TaskUpdate(completed)` só ocorre se `task done` retornar sem erro (validação passou).
+
+### Passo 3: Checkpoint a Cada 3 Tasks
+
+**A cada 3 tasks completadas:**
+
+```bash
+# Save checkpoint
+npx morph-spec checkpoint-save $ARGUMENTS
+
+# Run validation
+npx morph-spec validate-feature $ARGUMENTS --phase implement
+```
+
+**Se validação falhar:**
+1. NÃO avançar para próxima task
+2. Corrigir issues reportados
+3. Re-rodar validação
+4. Só então prosseguir
+
+### Passo 4: Test-Driven Development (Recomendado)
+
+Para cada task de implementação:
+
+1. **Escrever teste primeiro** (unit test para service/domain)
+2. **Rodar teste** — deve falhar (RED)
+3. **Implementar** o mínimo para passar
+4. **Rodar teste** — deve passar (GREEN)
+5. **Refatorar** se necessário (REFACTOR)
+
+```bash
+# .NET
+dotnet test --filter "FullyQualifiedName~{TestClass}"
+
+# Node.js
+npm test -- test/path/to/test.js
+```
+
+### Passo 5: Smoke Test com Playwright (se UI)
+
+Após implementar componentes visuais:
+
+```javascript
+// Navegar para a página
+await mcp__playwright__browser_navigate({ url: 'http://localhost:5000/feature-page' });
+
+// Capturar estado da página
+await mcp__playwright__browser_snapshot();
+
+// Verificar erros de console
+await mcp__playwright__browser_console_messages({ level: 'error' });
+
+// Screenshot para recap
+await mcp__playwright__browser_take_screenshot({ type: 'png' });
+```
+
+### Passo 6: Gerar `recap.md`
+
+Após TODAS as tasks completadas:
+
+```bash
+npx morph-spec generate recap $ARGUMENTS
+```
+
+> Para o formato completo do recap, veja `references/recap-example.md`
+
+### Passo 7: Atualizar State
+
+```bash
+npx morph-spec state set $ARGUMENTS status done
+npx morph-spec state mark-output $ARGUMENTS recap
+```
+
+### Passo 8: Revisão Pós-Implementação (obrigatório antes do PR)
+
+```bash
+/post-implementation $ARGUMENTS
+```
+
+Execute o skill `post-implementation` antes de criar o PR. Ele orquestra:
+- Scans automáticos (CRITICAL findings bloqueiam PR)
+- Test suite completo
+- `validate-feature` final
+- Smoke test via Playwright (obrigatório se dev server ativo)
+- Checklist de code review (CRITICAL + HIGH)
+- **`morph-checklist`** — compliance (segurança, SEO, performance, acessibilidade, LGPD)
+- Checkpoint + recap final
+
+### Passo 9: Frontend Review (NEXTJS/FULLSTACK)
+
+Se stack for NEXTJS ou FULLSTACK:
+
+```bash
+/frontend-review $ARGUMENTS
+```
+
+Complementa o `post-implementation` com: scan de acessibilidade (static + axe-core runtime),
+screenshots responsivos (mobile/tablet/desktop), e verificação de SEO metadata.
+
+---
+
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `test-driven-development` | Para cada task de implementação | `Skill(superpowers:test-driven-development)` |
+| `systematic-debugging` | **OBRIGATÓRIO** quando testes falham ou comportamento inesperado — invoke ANTES de tentar qualquer fix | `Skill(superpowers:systematic-debugging)` |
+| `requesting-code-review` | Após implementação completa | `Skill(superpowers:requesting-code-review)` |
+| `verification-before-completion` | Antes de marcar feature como done | Use `verification-before-completion` (morph-spec version) |
+| `post-implementation` | Antes de criar o PR (scans + smoke test + review) | `/post-implementation {feature}` |
+
+---
+
+## Outputs Gerados
+
+- Código fonte implementado (vários arquivos)
+- Testes unitários e de integração
+- `.morph/features/$ARGUMENTS/4-implement/recap.md` — Resumo da implementação
+
+## Critérios de Conclusão
+
+- [x] Todas as tasks completadas
+- [x] Build compila sem erros
+- [x] Testes passando
+- [x] Validation pipeline passa
+- [x] `recap.md` gerado
+- [x] State atualizado para `status: done`
+- [x] Checkpoints salvos a cada 3 tasks
+- [x] `/post-implementation` executado sem BLOCKs (smoke test, scans, code review, `morph-checklist`)
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:implement -->
+| Output | Caminho |
+|--------|---------|
+| `recap` | `.morph/features/{feature}/4-implement/recap.md` |
+<!-- /morph:outputs -->
+
+---
+
+Feature completa! Considere criar um PR e rodar `morph-spec generate recap $ARGUMENTS`.