@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.8.12"
+cliVersion: "4.8.15"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -31,8 +31,9 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 
 | Ação | Ferramenta | Alternativa |
 |------|------------|-------------|
-| Verificar viabilidade de paralelização | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Grupos de tasks + prompts de subagents |
-| **Dispatch implementadores por domínio** (quando viável) | **Task** subagents — um por grupo | Backend + frontend + infra em paralelo |
+| 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 | — |
@@ -54,6 +55,9 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 - ❌ 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!)
@@ -65,9 +69,46 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 
 ---
 
+## ✅ 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 Paralelização
+### Passo 0.5: Planejar Modo de Execução
 
 **Execute antes de qualquer implementação:**
 
@@ -75,7 +116,17 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 npx morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
-**Se `shouldDispatch: true` no output:**
+**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:
@@ -91,12 +142,21 @@ Contexto completo:
 - 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. Execute: npx morph-spec task start $ARGUMENTS TXXX
-2. Leia a descrição completa da task
-3. Implemente os arquivos — use Write (novo) ou Edit (existente)
-4. Verifique build: [dotnet build / npm run build]
-5. Execute: npx morph-spec task done $ARGUMENTS TXXX
+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
@@ -112,11 +172,59 @@ Restrições OBRIGATÓRIAS:
 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 `shouldDispatch: false`** (feature pequena ou single-domain):
+**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:**
@@ -139,7 +247,7 @@ npx morph-spec approval-status $ARGUMENTS
 
 ### Passo 1: Carregar Contexto Completo
 
-Leia TODOS os outputs antes de implementar:
+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
@@ -159,71 +267,11 @@ Caso contrário → vá direto para o Passo 2.
 
 ### Passo 1.5: Guia de Implementação VSA (somente se `style: "vertical-slice"`)
 
-> **Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
-**Estrutura de arquivos obrigatória por slice:**
-
-```
-Features/
-└── {Entity}Feature/
-    ├── {Entity}Errors.cs                        ← 1 arquivo por feature (compartilhado)
-    ├── Create{Entity}/
-    │   ├── Create{Entity}Handler.cs             ← Request + Response records + Handler
-    │   ├── Create{Entity}Validator.cs           ← AbstractValidator<Request>
-    │   └── Create{Entity}Endpoint.cs           ← IApiEndpoint (internal sealed)
-    ├── GetAll{Entity}s/
-    │   ├── GetAll{Entity}sHandler.cs           ← sem Validator (sem parâmetros)
-    │   └── GetAll{Entity}sEndpoint.cs
-    ├── Get{Entity}ById/
-    │   ├── Get{Entity}ByIdHandler.cs
-    │   ├── Get{Entity}ByIdValidator.cs
-    │   └── Get{Entity}ByIdEndpoint.cs
-    ├── Update{Entity}/
-    │   ├── Update{Entity}Handler.cs
-    │   ├── Update{Entity}Validator.cs
-    │   └── Update{Entity}Endpoint.cs
-    └── Delete{Entity}/
-        ├── Delete{Entity}Handler.cs
-        ├── Delete{Entity}Validator.cs
-        └── Delete{Entity}Endpoint.cs
-```
-
-**Regras obrigatórias ao implementar cada slice:**
-1. `Request` e `Response` records ficam no **mesmo arquivo** que o `Handler`
-2. Tudo `sealed` — handlers, endpoints, validators, records
-3. `Guid.CreateVersion7()` para gerar IDs (não `Guid.NewGuid()`)
-4. Endpoints usam `result.Match(onSuccess, onFailure)` — nunca acesse `result.Value` sem checar `IsSuccess`
-5. Endpoints são `internal sealed` (não public)
-6. `{Entity}Errors` é static e compartilhado entre todos os slices da feature
-7. Handlers de escrita (Create/Update/Delete) injetam `IRepository<T>` + `IUnitOfWork`
-8. Handlers de leitura (GetAll/GetById) injetam apenas `IRepository<T>`
-9. GetAll não tem Validator
-
-**Registrar entidade no DbContext:**
-```csharp
-// Database/ApplicationDbContext.cs — adicionar:
-public DbSet<{Entity}> {Entities} { get; set; } = null!;
-```
-
-**Criar migration após DbContext atualizado:**
-```bash
-dotnet ef migrations add Add{Entity}
-dotnet ef database update
-```
-
-**Registrar tag em ApiTags (se necessário):**
-```csharp
-// Constants/ApiTags.cs — adicionar:
-public const string {Entities} = "{entities}";
-```
+> Para a estrutura completa de slices e regras VSA, veja `references/vsa-implementation-guide.md`
 
-**O que NÃO precisa fazer (auto-discovery via reflection):**
-- ❌ Registrar handler manualmente no Program.cs — `AddHandlersFromAssembly()` faz isso
-- ❌ Registrar endpoint manualmente — `RegisterApiEndpointsFromAssembly()` faz isso
-- ❌ Registrar validator manualmente — `AddValidatorsFromAssembly()` faz isso
-- ❌ Criar Application Service layer — handler acessa IRepository diretamente
+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.
 
-**Verificar build após cada slice completo:**
+Após cada slice completo, verificar build:
 ```bash
 dotnet build
 ```
@@ -232,19 +280,31 @@ dotnet build
 
 ```bash
 npx morph-spec task next $ARGUMENTS
-npx morph-spec task start $ARGUMENTS T001
 ```
 
-Para cada task:
-
-1. **Ler a task description** completa
-2. **Ler contracts.cs** para DTOs/interfaces relevantes
-3. **Implementar** usando Write (novo) ou Edit (existente)
-4. **Verificar** — build, lint, testes
-5. **Marcar como done:**
-```bash
-npx morph-spec task done $ARGUMENTS T001
-```
+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
 
@@ -308,45 +368,40 @@ Após TODAS as tasks completadas:
 npx morph-spec generate recap $ARGUMENTS
 ```
 
-Ou crie manualmente `.morph/features/$ARGUMENTS/4-implement/recap.md`:
-
-```markdown
-# Recap — {Feature Name}
-
-## Summary
-{1-2 parágrafos descrevendo o que foi implementado}
+> Para o formato completo do recap, veja `references/recap-example.md`
 
-## Tasks Completed
-- [x] T001: {título}
-- [x] T002: {título}
-- ...
+### Passo 7: Atualizar State
 
-## Key Decisions During Implementation
-- {Decisão 1}: {Razão}
-- {Decisão 2}: {Razão}
+```bash
+npx morph-spec state set $ARGUMENTS status done
+npx morph-spec state mark-output $ARGUMENTS recap
+```
 
-## Files Created/Modified
-{Lista de arquivos}
+### Passo 8: Revisão Pós-Implementação (obrigatório antes do PR)
 
-## Tests
-- Unit tests: X passing
-- Integration tests: Y passing
+```bash
+/post-implementation $ARGUMENTS
+```
 
-## Validation Results
-{Output do morph-spec validate-feature}
+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
 
-## Screenshots
-{Se UI, incluir screenshots}
-```
+### Passo 9: Frontend Review (NEXTJS/FULLSTACK)
 
-### Passo 7: Atualizar State
+Se stack for NEXTJS ou FULLSTACK:
 
 ```bash
-npx morph-spec state set $ARGUMENTS phase implement
-npx morph-spec state set $ARGUMENTS status done
-npx morph-spec state mark-output $ARGUMENTS recap
+/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
@@ -359,6 +414,7 @@ npx morph-spec state mark-output $ARGUMENTS recap
 | `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}` |
 
 ---
 
@@ -377,6 +433,7 @@ npx morph-spec state mark-output $ARGUMENTS recap
 - [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)
 
 ---
 

package/framework/skills/level-1-workflows/phase-implement/references/vsa-implementation-guide.md

@@ -0,0 +1,92 @@
+# VSA Implementation Guide
+
+> Guia completo de implementação para Vertical Slice Architecture.
+> Referenciado pelo Passo 1.5 de `phase-implement/SKILL.md`.
+> **Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
+
+---
+
+## Estrutura de Arquivos Obrigatória por Slice
+
+```
+Features/
+└── {Entity}Feature/
+    ├── {Entity}Errors.cs                        ← 1 arquivo por feature (compartilhado)
+    ├── Create{Entity}/
+    │   ├── Create{Entity}Handler.cs             ← Request + Response records + Handler
+    │   ├── Create{Entity}Validator.cs           ← AbstractValidator<Request>
+    │   └── Create{Entity}Endpoint.cs           ← IApiEndpoint (internal sealed)
+    ├── GetAll{Entity}s/
+    │   ├── GetAll{Entity}sHandler.cs           ← sem Validator (sem parâmetros)
+    │   └── GetAll{Entity}sEndpoint.cs
+    ├── Get{Entity}ById/
+    │   ├── Get{Entity}ByIdHandler.cs
+    │   ├── Get{Entity}ByIdValidator.cs
+    │   └── Get{Entity}ByIdEndpoint.cs
+    ├── Update{Entity}/
+    │   ├── Update{Entity}Handler.cs
+    │   ├── Update{Entity}Validator.cs
+    │   └── Update{Entity}Endpoint.cs
+    └── Delete{Entity}/
+        ├── Delete{Entity}Handler.cs
+        ├── Delete{Entity}Validator.cs
+        └── Delete{Entity}Endpoint.cs
+```
+
+---
+
+## 9 Regras Obrigatórias por Slice
+
+1. `Request` e `Response` records ficam no **mesmo arquivo** que o `Handler`
+2. Tudo `sealed` — handlers, endpoints, validators, records
+3. `Guid.CreateVersion7()` para gerar IDs (não `Guid.NewGuid()`)
+4. Endpoints usam `result.Match(onSuccess, onFailure)` — nunca acesse `result.Value` sem checar `IsSuccess`
+5. Endpoints são `internal sealed` (não public)
+6. `{Entity}Errors` é static e compartilhado entre todos os slices da feature
+7. Handlers de escrita (Create/Update/Delete) injetam `IRepository<T>` + `IUnitOfWork`
+8. Handlers de leitura (GetAll/GetById) injetam apenas `IRepository<T>`
+9. GetAll não tem Validator
+
+---
+
+## Registrar Entidade no DbContext
+
+```csharp
+// Database/ApplicationDbContext.cs — adicionar:
+public DbSet<{Entity}> {Entities} { get; set; } = null!;
+```
+
+---
+
+## Criar Migration Após DbContext Atualizado
+
+```bash
+dotnet ef migrations add Add{Entity}
+dotnet ef database update
+```
+
+---
+
+## Registrar Tag em ApiTags (se necessário)
+
+```csharp
+// Constants/ApiTags.cs — adicionar:
+public const string {Entities} = "{entities}";
+```
+
+---
+
+## O que NÃO Precisa Fazer (auto-discovery via reflection)
+
+- ❌ Registrar handler manualmente no Program.cs — `AddHandlersFromAssembly()` faz isso
+- ❌ Registrar endpoint manualmente — `RegisterApiEndpointsFromAssembly()` faz isso
+- ❌ Registrar validator manualmente — `AddValidatorsFromAssembly()` faz isso
+- ❌ Criar Application Service layer — handler acessa IRepository diretamente
+
+---
+
+## Verificar Build Após Cada Slice
+
+```bash
+dotnet build
+```

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech sta
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.15"
 ---
 
 # MORPH Setup - FASE 1
@@ -142,7 +142,6 @@ Isso informa quais agentes serão disparados em paralelo na fase de design e qua
 Marque a feature como na fase SETUP:
 
 ```bash
-npx morph-spec state set $ARGUMENTS phase setup
 npx morph-spec state set $ARGUMENTS status in_progress
 ```