@polymorphism-tech/morph-spec 4.10.0 → 4.10.1

package/framework/commands/morph-apply.md

@@ -1,231 +1,221 @@
 ---
-description: Implementa a feature especificada seguindo as tasks definidas na FASE 5 do workflow MORPH
+description: Implement the specified feature following the task breakdown from the MORPH-SPEC workflow. Orchestrates task execution with state tracking, checkpoints, agent dispatch, and verification.
 argument-hint: <feature-name>
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
 ---
 
-# Apply MORPH Feature Implementation - FASE 5
+# /morph-apply — Feature Implementation
 
-Implemente a feature especificada seguindo as tasks definidas.
+Implement the feature by executing its task breakdown, tracking progress through the morph-spec state machine, and producing a recap at the end.
 
-## Uso
+## Usage
 
 ```
 /morph-apply {feature-name}
 ```
 
-## Pré-requisitos
+## Recommended Tools
 
-### CRÍTICO: Validar Fases Anteriores
+> **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.
 
-**SEMPRE verifique que fases anteriores foram concluídas:**
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read spec, tasks, contracts | **Read** all outputs | — |
+| Detect architecture style | **Bash** `cat .morph/config/config.json \| grep architecture` | — |
+| Agent dispatch config | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | — |
+| Parallel task execution | **Agent** subagent per task group | Sequential fallback |
+| Look up implementation patterns | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Track progress | **Bash** `npx morph-spec state get $ARGUMENTS` | — |
+
+---
+
+## Pre-flight Validation
+
+Before writing any code, verify all prior phases are complete. This gate prevents implementation from starting with missing specs, unapproved designs, or incomplete task breakdowns.
+
+### 1. Check state and approvals
 
 ```bash
-# Obter estado da feature
-npx morph-spec state get {feature-name}
+npx morph-spec state get $ARGUMENTS
+npx morph-spec approval-status $ARGUMENTS
+npx morph-spec validate-feature $ARGUMENTS
 ```
 
-**Validações obrigatórias:**
+**All three must pass.** If any fails:
+
+```
+Feature is not ready for implementation.
+Run /morph-proposal $ARGUMENTS to complete planning phases.
+(Resumes automatically from the current phase.)
+```
 
-1. **FASE 0 (Proposal):**
-   - [ ] Output `proposal` criado
-   - [ ] Agentes detectados e registrados
+Do NOT proceed until all phases are complete and all gates approved.
 
-2. **FASE 1 (Setup):**
-   - [ ] Phase passou por "setup"
-   - [ ] Contexto carregado
+### 2. Load context in PARALLEL
 
-3. **FASE 1.5 (UI/UX) - SE APLICÁVEL:**
-   - [ ] Se `uiux-designer` está nos activeAgents → outputs ui-* devem existir
-   - [ ] Se NÃO tem uiux-designer → pode pular
+Read all prerequisite files in a single parallel call — every file listed here matters for implementation quality:
 
-4. **FASE 2 (Design):**
-   - [ ] Output `spec` criado
-   - [ ] Output `contracts` criado
-   - [ ] Output `decisions` criado
+```
+Read: .morph/features/$ARGUMENTS/1-design/spec.md              (→ functional requirements, API contracts)
+    + Read: .morph/features/$ARGUMENTS/1-design/contracts.cs    (or contracts.ts / contracts-vsa.cs → C# interfaces)
+    + Read: .morph/features/$ARGUMENTS/1-design/decisions.md    (→ ADRs, architectural choices)
+    + Read: .morph/features/$ARGUMENTS/3-plan/plan.md           (→ TDD structure, execution strategy)
+    + Read: .morph/features/$ARGUMENTS/4-tasks/tasks.md         (→ task breakdown with T### IDs)
+    + Read: .morph/config/config.json                           (→ architecture.style for VSA routing)
+```
 
-5. **FASE 3 (Clarify):**
-   - [ ] Phase passou por "clarify"
-   - [ ] Spec atualizado com clarificações
+**For VSA projects** (`architecture.style: "vertical-slice"`), also read:
+```
+Read: framework/standards/architecture/vertical-slice/vertical-slice.md
+```
+This contains the 9 VSA implementation rules (Handler+Validator+Endpoint per feature folder, no cross-feature imports, etc.).
 
-6. **FASE 4 (Plan):**
-   - [ ] Output `plan` criado
-   - [ ] Plano de implementação aprovado
+Also read relevant standards:
+- `framework/standards/` — coding standards for the detected stack
+- `.morph/context/` — project-specific patterns and conventions
 
-7. **FASE 5 (Tasks):**
-   - [ ] Output `tasks` criado
-   - [ ] `tasks.json` tem array de tasks
-   - [ ] `tasks.total` > 0 no state
+### 3. Detect architecture style
 
-**Se QUALQUER validação falhar:**
+```bash
+cat .morph/config/config.json | grep -A3 '"architecture"'
 ```
-❌ ERRO: Fase {X} não foi concluída!
 
-Para completar as fases de planejamento, execute:
-/morph-proposal {feature-name}
-(Resume automaticamente da fase atual: {current_phase})
+- **`"vertical-slice"`** → follow VSA implementation patterns from `framework/standards/architecture/vertical-slice/vertical-slice.md`. Each task is a complete slice (Handler + Validator + Endpoint in one folder).
+- **Otherwise** → follow DDD/Clean Architecture patterns. Tasks map to domain layers.
+
+### 4. Get agent dispatch config
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement --table
 ```
 
-**NÃO prossiga com implementação até todas as fases estarem completas!**
+This shows which agents are active for implementation and how tasks can be grouped. If agent teams are enabled and tasks have no dependencies between groups, consider dispatching parallel agents:
 
-### Arquivos Necessários
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
 
-- [ ] Feature existe em `.morph/features/{feature}/`
-- [ ] `spec.md` está aprovado
-- [ ] `tasks.json` tem tasks definidas
-- [ ] `contracts.cs` define as interfaces
+The JSON output includes `shouldDispatch`, `agents[]`, and `taskGroups` for multi-agent coordination.
+
+---
 
 ## Workflow
 
-1. **Carregue o contexto**:
-   - Leia `.morph/features/{feature}/1-design/spec.md`
-   - Leia `.morph/features/{feature}/3-plan/plan.md`
-   - Leia `.morph/features/{feature}/4-tasks/tasks.md`
-   - Leia `.morph/features/{feature}/1-design/contracts.cs`
-   - Leia framework/standards/ e .morph/context/ para padrões
-
-2. **Inicialize state tracking**:
-   ```bash
-   # Atualizar fase para implement
-   npx morph-spec state set {feature} phase implement
-   npx morph-spec state set {feature} status in_progress
-
-   # Definir total de tasks (baseado em tasks.json)
-   npx morph-spec state set {feature} tasks.total {N}
-   ```
-
-3. **Execute tasks em ordem**:
-   - Marque task como in progress: `npx morph-spec task start {feature} {task-id}`
-   - Implemente seguindo os padrões e contracts.cs
-   - Complete task: `npx morph-spec task done {feature} {task-id}`
-   - **Validators run automatically** on task-done. If validation fails:
-     - Read the error messages and fix violations
-     - Re-run `task done` — do NOT use `--skip-validation` unless user authorizes
-   - Framework auto-manages checkpoints (every 3 tasks, includes validation summary)
-
-4. **Phase advancement**:
-   ```bash
-   # Advance to next phase (validates → advances → shows next steps)
-   npx morph-spec phase advance {feature}
-   ```
-
-5. **Marcar outputs criados**:
-   Sempre que gerar um arquivo de output:
-   ```bash
-   npx morph-spec state mark-output {feature} spec
-   npx morph-spec state mark-output {feature} contracts
-   npx morph-spec state mark-output {feature} tasks
-   # etc.
-   ```
-
-6. **Ao finalizar**:
-   - Generate recap automatically: `npx morph-spec generate recap {feature}`
-   - Atualize state: `npx morph-spec state set {feature} status done`
-   - Marque recap: `npx morph-spec state mark-output {feature} recap`
-   - Liste arquivos criados/modificados
-   - Calcule custo real vs estimado
-
-## Padrões Obrigatórios
-
-Siga sempre (priorize context/ se houver):
-- `framework/standards/coding.md` - Padrões base do MORPH
-- `.morph/context/coding.md` - Padrões específicos do projeto
-- `.morph/context/architecture.md` - Estrutura de projeto
-- `.morph/context/azure.md` - Recursos e custos
+### Step 1: Advance to implement phase
 
----
+```bash
+npx morph-spec phase advance $ARGUMENTS
+```
 
-## Checklist Pré-Deploy Azure
+This validates phase eligibility and emits a SKILL DISPATCH block listing required skills for implementation (verification-before-completion, morph-checklist, etc.).
 
-**ANTES de fazer deploy para Azure, execute `/morph-preflight azure` ou verifique manualmente:**
+### Step 2: Initialize state tracking
 
-### Packages e Build
+```bash
+npx morph-spec state set $ARGUMENTS tasks.total {N}
+```
 
-- [ ] Packages sem conflitos de versão (`dotnet restore` sem warnings NU1605/NU1608)
-- [ ] `Azure.Identity` especificado explicitamente no `.csproj`
-- [ ] Build passa sem erros (`dotnet build`)
+Where `{N}` is the number of tasks in tasks.md (e.g., 6 for T001-T006).
 
-### EF Core Migrations
+### Step 3: Execute tasks in order
 
-- [ ] Sem pending model changes (`dotnet ef migrations has-pending-model-changes`)
-- [ ] Migration criada para todas as mudanças de schema
-- [ ] Migration script revisado (`dotnet ef migrations script --idempotent`)
+For each task in the breakdown, follow this cycle:
 
-### Blazor .NET 10 (se aplicável)
+```bash
+# 1. Start the task (activates task-tracking guard)
+npx morph-spec task start $ARGUMENTS {task-id}
 
-- [ ] `.csproj` contém `<RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>`
-- [ ] Static assets funcionando localmente
+# 2. Implement the task
+#    - Follow spec.md and contracts
+#    - Follow coding standards from framework/standards/ and .morph/context/
+#    - For VSA: create all slice files in one folder (Handler + Validator + Endpoint)
+#    - For DDD: implement in the correct domain layer
 
-### Container/Docker (se Container Apps)
+# 3. Verify before completing — run validate-feature or check your work
+#    matches the spec and contracts before marking done
 
-- [ ] Dockerfile válido e testado localmente
-- [ ] `docker build` funciona sem erros
-- [ ] Container roda localmente (`docker run`)
+# 4. Complete the task (triggers Tier-4 validators automatically)
+npx morph-spec task done $ARGUMENTS {task-id}
+```
 
-### Infraestrutura Azure
+**If validation fails on `task done`:**
+- Read the error messages carefully
+- Fix the violations in your code
+- Re-run `task done` — do NOT use `--skip-validation` unless the user explicitly authorizes it
+- After 3 consecutive failures, escalate to the user
 
-- [ ] Bicep sem erros de sintaxe (`az bicep build`)
-- [ ] Key Vault URI configurado em `appsettings.Production.json`
-- [ ] Connection strings em Key Vault (não hardcoded)
-- [ ] Managed Identity habilitada nos recursos
+**Parallel execution (agent teams):**
+If `dispatch-agents` identified parallelizable task groups and agent teams are enabled, dispatch independent tasks to separate agents. Each agent still calls `task start` and `task done` for its assigned task.
 
-### Segurança
+### Step 4: Checkpoint every 3 tasks
 
-- [ ] Sem secrets em código ou `appsettings.json` (exceto Development)
-- [ ] HTTPS enforçado
-- [ ] CORS configurado corretamente
+After every 3 completed tasks, save a checkpoint:
 
-### Comandos de Verificação
+```bash
+npx morph-spec checkpoint-save $ARGUMENTS "after-T003"
+npx morph-spec state get $ARGUMENTS
+```
+
+Checkpoints validate architecture compliance, check package versions, scan for security issues, and save a restorable snapshot. The cadence is every 3 tasks — for 6 tasks: checkpoint after T003 and T006. For 10 tasks: after T003, T006, T009, and at completion.
+
+After each checkpoint, check progress:
 
 ```bash
-# 1. Package conflicts
-dotnet restore 2>&1 | grep -E "NU1605|NU1608"
+npx morph-spec state list
+```
+
+### Step 5: Finalize implementation
 
-# 2. Pending migrations
-dotnet ef migrations has-pending-model-changes \
-  --project src/Infrastructure \
-  --startup-project src/Web
+After all tasks are complete:
 
-# 3. Bicep validation
-az bicep build --file infra/main.bicep --stdout > /dev/null
+```bash
+# Final validation
+npx morph-spec validate-feature $ARGUMENTS
+
+# Generate recap (auto-marks 'recap' output in state)
+npx morph-spec generate recap $ARGUMENTS
 
-# 4. Docker build
-docker build -t myapp:test .
+# Verify final state
+npx morph-spec state get $ARGUMENTS
 
-# 5. Secret scan (basic)
-grep -rE "(Password=|Pwd=|Secret=)" appsettings*.json | grep -v Development
+# Advance to next phase
+npx morph-spec phase advance $ARGUMENTS
 ```
 
-### Se QUALQUER item falhar
+### Step 6: Post-implementation review
 
-```
-❌ BLOQUEADO: Não faça deploy até resolver!
+After implementation, present a summary to the user:
 
-Use /morph-preflight azure para diagnóstico detalhado.
-```
+1. Total tasks completed (X/Y)
+2. Files created/modified
+3. Validation results
+4. Any deviations from spec
 
-## Validações
+For Azure projects, remind the user: "Run `/morph-preflight` before deploying to validate packages, migrations, Docker, and secrets."
 
-Antes de marcar task como completa:
-- [ ] Código compila
-- [ ] Segue padrões de nomenclatura
-- [ ] Testes unitários (se aplicável)
-- [ ] Sem hardcoded secrets
+---
 
-## Output
+## Task Output Format
 
-Ao final de cada task, mostre:
-1. Task completada
-2. Arquivos criados/modificados
-3. Próxima task
-4. Progresso geral (X/Y tasks) - usar `npx morph-spec state get {feature}`
+After each task completion, show:
 
-Ao final de cada checkpoint:
-```bash
-npx morph-spec state list
 ```
+Task {task-id} complete (X/Y tasks done)
+Files: [list of created/modified files]
+Next: {next-task-id} — {next-task-title}
+```
+
+---
+
+## Anti-patterns
 
-Isso mostra o progresso atualizado automaticamente.
+- Using `state set phase` instead of `phase advance` — phase advance validates eligibility first
+- Skipping `task start` before implementing — the task-tracking guard will warn
+- Using `--skip-validation` without user authorization
+- Implementing without reading spec.md and contracts first
+- Writing code before `phase advance` to implement — the hook will block writes
+- Skipping checkpoints — they catch integration issues early
 
 ---
 

package/framework/commands/morph-archive.md

@@ -1,51 +1,51 @@
 ---
-description: Arquiva uma feature concluída movendo de features/ para archive/ e atualizando o state
+description: Archive a completed feature by moving from features/ to archive/ and updating state
 argument-hint: <feature-name>
 allowed-tools: Read, Write, Edit, Bash
 ---
 
 # Archive MORPH Feature
 
-Arquive uma feature concluída, movendo-a de `features/` para `archive/`.
+Archive a completed feature, moving it from `features/` to `archive/`.
 
-## Pré-requisitos
+## Prerequisites
 
-Verifique antes de arquivar:
-- [ ] Feature existe em `.morph/features/{feature}/`
-- [ ] Todas as tasks estão completas
-- [ ] `recap.md` está preenchido
-- [ ] Código está em produção (ou staging)
+Verify before archiving:
+- [ ] Feature exists in `.morph/features/{feature}/`
+- [ ] All tasks are complete
+- [ ] `recap.md` is filled in
+- [ ] Code is in production (or staging)
 
 ## Workflow
 
-1. **Valide a conclusão**:
-   - Leia `.morph/features/{feature}/4-tasks/tasks.md`
-   - Verifique que todas tasks estão completadas
-   - Confirme com o usuário se pode arquivar
+1. **Validate completion**:
+   - Read `.morph/features/{feature}/4-tasks/tasks.md`
+   - Verify all tasks are completed
+   - Confirm with user before archiving
 
-2. **Complete o recap**:
-   - Atualize `.morph/features/{feature}/5-implement/recap.md`
-   - Preencha métricas finais
-   - Documente lições aprendidas
+2. **Complete the recap**:
+   - Update `.morph/features/{feature}/5-implement/recap.md`
+   - Fill in final metrics
+   - Document lessons learned
 
-3. **Extraia specs**:
-   - Se a feature define comportamento permanente
-   - Copie spec relevante para `.morph/specs/`
-   - Isso vira a "verdade atual" do sistema
+3. **Extract specs**:
+   - If the feature defines permanent behavior
+   - Copy relevant spec to `.morph/specs/`
+   - This becomes the "current truth" of the system
 
-4. **Mova para archive**:
+4. **Move to archive**:
    ```
    .morph/features/{feature}/  →  .morph/archive/{feature}/
    ```
 
-5. **Atualize métricas do projeto**:
-   - Incremente contador de features
-   - Atualize custo total
-   - Atualize tempo total
+5. **Update project metrics**:
+   - Increment feature counter
+   - Update total cost
+   - Update total time
 
 ## Output
 
-Apresente resumo do arquivamento:
+Present archival summary:
 
 ```
 ╔════════════════════════════════════════════╗
@@ -72,9 +72,9 @@ Apresente resumo do arquivamento:
 ╚════════════════════════════════════════════╝
 ```
 
-## Specs Extraídas
+## Extracted Specs
 
-Se houver specs extraídas:
+If specs were extracted:
 ```
 Specs extracted to .morph/specs/:
 - {domain}/spec.md - {description}