@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/framework/commands/morph-proposal.md

@@ -1,122 +1,195 @@
+---
+description: MORPH Spec Pipeline — creates or resumes feature planning through phases 0-6 with mandatory approval pauses. Use whenever the user wants to plan, spec, or design a new feature, or when they say /morph-proposal. This is the primary entry point for all MORPH-SPEC feature work.
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
 # MORPH Spec Pipeline
 
-Crie ou retome o planejamento de uma feature, guiando automaticamente pelas fases 0→4 com pausas obrigatórias.
+Guide a feature through the full planning pipeline (proposal through tasks) with mandatory approval pauses at each gate.
 
 ---
 
 ## 1. Resume Logic
 
-Primeiro, verifique se a feature já existe:
+Check if the feature already has state:
 
 ```bash
 npx morph-spec state get {feature-name}
 ```
 
-- **Se existe:** Identifique a fase atual e retome de onde parou (pular fases já concluídas)
-- **Se não existe:** Iniciar do zero (FASE 0)
+- **Exists:** Read the current phase and resume from where it stopped (skip completed phases)
+- **Does not exist:** Start from scratch (PHASE 0)
 
 ---
 
-## 2. FASE 0: PROPOSAL
+## 2. PHASE 0: PROPOSAL
+
+### Step 1: Load project context
+
+Read these files to understand the project before writing anything:
+- `.morph/context/README.md` — project overview, tech stack, architecture
+- `.morph/config/config.json` — project configuration (language, workflow, architecture style)
+
+### Step 2: Detect agents
+
+Read `framework/agents.json` (or `.morph/framework/agents.json` in client projects). For each agent:
+1. Check if `always_active: true` — include automatically
+2. Compare agent `keywords[]` and `domains[]` against the feature description — include on match
+3. **Document false-positive exclusions**: for agents that match on keywords but are irrelevant to this feature, note why they were excluded (this helps audit agent selection later)
+
+Register each selected agent:
+```bash
+npx morph-spec state add-agent {feature-name} {agent-id}
+```
+
+### Step 3: Determine if UI/UX phase is needed
+
+If `ui-designer` is among the selected agents, the feature will trigger the UI/UX phase later. Note this decision — it affects the pipeline path.
+
+### Step 4: Create proposal
 
-### Workflow
+Read the proposal template at `framework/templates/docs/proposal.md` first, then create:
+
+```
+.morph/features/{feature-name}/
+  0-proposal/proposal.md
+```
 
-1. **Detecte agentes automaticamente:**
-   - Read `.morph/framework/agents.json`
-   - Para cada agente, compare `domains` e `keywords` com a feature solicitada
-   - Registre os agentes relevantes: `npx morph-spec state add-agent {feature-name} {agent-id}`
+Fill every section of the template. In particular:
+- **Metadata table**: date, author, status, priority, stack
+- **Problem Statement**: use the What/Who/Impact structure from the template
+- **Proposed Solution**: technical approach, key features, user journey
+- **Success Metrics**: quantified current vs target values
+- **Scope**: explicit In Scope, Out of Scope, and Future Considerations
+- **Risks**: table with likelihood, impact, mitigation
+- **Dependencies**: checklist of prerequisites
+- **Estimated Effort**: broken down by phase (in hours)
+- **Questions & Clarifications**: seed 3-6 questions for the clarify phase — these become input for phase 3
 
-2. **Invoque skills dos agentes detectados:**
-   - Para agentes com `skillPath` em agents.json, consulte o Skill correspondente
-   - Use conhecimento dos skills para enriquecer a proposta
+### Step 5: Register state
 
-3. **Analise a solicitação** e identifique: problema, usuários afetados, impacto
+```bash
+npx morph-spec state init {feature-name}
+npx morph-spec state set {feature-name} status draft
+npx morph-spec state mark-output {feature-name} proposal
+```
 
-4. **Crie a estrutura:**
-   ```
-   .morph/features/{feature-name}/
-   ├── 0-proposal/proposal.md
-   ├── 1-design/spec.md (iniciar)
-   └── 3-tasks/tasks.md (iniciar)
-   ```
+### MANDATORY PAUSE
 
-5. **Preencha `proposal.md`** baseado em `framework/templates/proposal.md`
+Use `AskUserQuestion` to present the approval gate with these elements:
 
-6. **Registre no state:**
-   ```bash
-   npx morph-spec state set {feature-name} status draft
-   npx morph-spec state set {feature-name} phase proposal
-   npx morph-spec state mark-output {feature-name} proposal
-   # Adicionar cada agente detectado:
-   npx morph-spec state add-agent {feature-name} {agent-id}
-   ```
+1. **Proposal summary** — 3-4 sentence overview of what was proposed
+2. **Agents activated** — table showing agent ID, tier, role, and why selected
+3. **Effort estimate** — total hours from the proposal
+4. **Key decisions pending** — 2-3 design decisions that will be resolved in the design phase
 
-### PAUSA OBRIGATORIA
+Options: Approve proposal / Request changes / Reject
 
-Apresente: resumo da proposta, agentes ativados, custo estimado, 3 itens de pausa.
+After approval:
+```bash
+npx morph-spec approve {feature-name} proposal
+npx morph-spec phase advance {feature-name}
+```
 
 ---
 
-## 3. Após Aprovação do Proposal → FASE 1: SETUP (auto, sem pausa)
+## 3. PHASE 1: SETUP (automatic, no pause)
 
-**Ler:** `.claude/skills/level-1-workflows/phase-setup.md` para instruções detalhadas.
+Invoke the `morph-phase-setup` skill.
 
-Resumo: carregar contexto do projeto, confirmar stack, listar agentes ativos, atualizar state.
+Summary: load project context, confirm stack, list active agents, update state.
 
-**Não pausa aqui.** Continuar automaticamente.
+**No pause here.** Continue automatically to the next phase.
 
 ---
 
-## 4. FASE 1.5: UI/UX (condicional)
+## 4. PHASE 1.5: UI/UX (conditional)
 
-Verificar se `uiux-designer` está nos `activeAgents`:
-- **Se SIM:** Ler `.claude/skills/level-1-workflows/phase-uiux.md` e executar. **PAUSA OBRIGATORIA** após gerar deliverables UI.
-- **Se NÃO:** Pular para FASE 2.
+Check if `ui-designer` is in `activeAgents`:
+- **Yes:** Invoke the `morph-phase-uiux` skill. **MANDATORY PAUSE** after generating UI deliverables.
+- **No:** Skip to PHASE 2.
+
+After approval:
+```bash
+npx morph-spec approve {feature-name} uiux
+npx morph-spec phase advance {feature-name}
+```
 
 ---
 
-## 5. FASE 2: DESIGN
+## 5. PHASE 2: DESIGN
 
-**Ler:** `.claude/skills/level-1-workflows/phase-design.md` para instruções detalhadas.
+Invoke the `morph-phase-design` skill.
 
-Resumo: gerar spec.md, contracts.cs, decisions.md com ADRs, estimar custos.
+Summary: generate spec.md, contracts.cs (or contracts-vsa.cs for VSA), decisions.md with ADRs.
 
-### PAUSA OBRIGATORIA
+### MANDATORY PAUSE
 
-Apresente: spec, contracts, decisions, custos. 3 itens de pausa (aprovar, ajustar escopo, modificar contracts).
+Present: spec, contracts, decisions, effort estimate. Use `AskUserQuestion` with options: Approve design / Adjust scope / Modify contracts.
+
+After approval:
+```bash
+npx morph-spec approve {feature-name} design
+npx morph-spec phase advance {feature-name}
+```
 
 ---
 
-## 6. Após Aprovação do Design → FASE 3: CLARIFY (interativo)
+## 6. PHASE 3: CLARIFY (interactive)
 
-**Ler:** `.claude/skills/level-1-workflows/phase-clarify.md` para instruções detalhadas.
+Invoke the `morph-phase-clarify` skill.
 
-Resumo: identificar ambiguidades, gerar 3-7 perguntas, aguardar respostas, atualizar spec com clarificações e edge cases.
+Summary: identify ambiguities in spec.md, generate 3-7 targeted questions (building on the questions seeded in the proposal), wait for user answers, update spec with clarifications and edge cases.
 
-**Aguardar respostas do usuário antes de continuar.**
+**Wait for user responses before continuing.**
 
 ---
 
-## 7. FASE 4: TASKS
+## 7. PHASE 4: PLAN
+
+Invoke the `morph-phase-plan` skill.
+
+Summary: generate a detailed implementation plan with exact file paths, TDD structure, and context-aware execution strategy.
 
-**Ler:** `.claude/skills/level-1-workflows/phase-tasks.md` para instruções detalhadas.
+### MANDATORY PAUSE
 
-Resumo: quebrar spec em tasks T001-TXXX, definir dependências, checkpoints, estimativas.
+Present: implementation plan with recommended strategy. Use `AskUserQuestion` with options: Approve plan / Adjust strategy / Modify plan.
 
-### PAUSA OBRIGATORIA
+After approval:
+```bash
+npx morph-spec approve {feature-name} plan
+npx morph-spec phase advance {feature-name}
+```
 
-Apresente: breakdown de tasks, ordem de execução, estimativa total. 3 itens de pausa (aprovar, repriorizar, adicionar/remover).
+---
+
+## 8. PHASE 5: TASKS
+
+Invoke the `morph-phase-tasks` skill.
+
+Summary: break spec into tasks T001-TXXX with dependencies, checkpoints, estimates.
+
+### MANDATORY PAUSE
+
+Present: task breakdown, execution order, total estimate. Use `AskUserQuestion` with options: Approve tasks / Reprioritize / Add or remove tasks.
+
+After approval:
+```bash
+npx morph-spec approve {feature-name} tasks
+npx morph-spec phase advance {feature-name}
+```
 
 ---
 
-## 8. Planejamento Completo
+## 9. Planning Complete
 
-Após aprovação das tasks:
+After task approval:
 
 ```
-Planejamento completo! Execute /morph-apply {feature-name} para iniciar implementação.
+Planning complete! Run /morph-apply {feature-name} to start implementation.
 ```
 
 ---
 
-**Feature solicitada:** $ARGUMENTS
+**Feature requested:** $ARGUMENTS

package/framework/commands/morph-status.md

@@ -1,51 +1,57 @@
+---
+description: Show current MORPH project status and all features in development with their phases and approvals
+argument-hint: [feature-name]
+allowed-tools: Read, Bash
+---
+
 # MORPH Project Status
 
-Mostre o status atual do projeto MORPH e features em desenvolvimento.
+Show the current MORPH project status and features in development.
 
-## Como Usar
+## Usage
 
-**SEMPRE** use o state-manager CLI para obter status:
+**ALWAYS** use the state-manager CLI to get status:
 
 ```bash
 npx morph-spec state list
 ```
 
-Este comando automaticamente mostra:
-- Todas as features ativas
-- Fase atual de cada feature
-- Progresso de tasks (X/Y)
-- Agentes ativos
-- Custos estimados
+This command automatically shows:
+- All active features
+- Current phase of each feature
+- Task progress (X/Y)
+- Active agents
+- Estimated costs
 
-## Verificações Adicionais
+## Additional Checks
 
-### 1. Configuração MORPH
-- [ ] `.morph/project.md` existe e está preenchido
-- [ ] `.morph/config/config.json` configurado
-- [ ] `.morph/framework/standards/` presentes
+### 1. MORPH Configuration
+- [ ] `.morph/project.md` exists and is filled in
+- [ ] `.morph/config/config.json` configured
+- [ ] `.morph/framework/standards/` present
 
-### 2. Detalhes de Feature Específica
+### 2. Specific Feature Details
 
-Para obter JSON detalhado de uma feature:
+To get detailed JSON for a feature:
 
 ```bash
 npx morph-spec state get {feature-name}
 ```
 
-### 3. Features Arquivadas
+### 3. Archived Features
 
-Verifique `.morph/archive/` manualmente se necessário:
-- Quantas features concluídas
-- Tempo total gasto
-- Custo acumulado
+Check `.morph/archive/` manually if needed:
+- How many features completed
+- Total time spent
+- Accumulated cost
 
-### 4. Specs Ativas
+### 4. Active Specs
 
-Verifique `.morph/specs/` para specs consolidadas.
+Check `.morph/specs/` for consolidated specs.
 
 ## Output
 
-O comando `npx morph-spec state list` automaticamente gera um dashboard formatado:
+The `npx morph-spec state list` command automatically generates a formatted dashboard:
 
 ```
 ╔════════════════════════════════════════════════════════════════╗
@@ -72,14 +78,14 @@ O comando `npx morph-spec state list` automaticamente gera um dashboard formatad
 ╚════════════════════════════════════════════════════════════════╝
 ```
 
-**Simplesmente execute o comando e mostre o resultado ao usuário.**
+**Simply run the command and show the result to the user.**
 
-## Ações Disponíveis
+## Available Actions
 
-Sugira próximas ações:
-- `/morph-proposal {feature}` - Criar nova feature
-- `/morph-apply {feature}` - Implementar feature
-- `/morph-archive {feature}` - Arquivar feature concluída
+Suggest next actions:
+- `/morph-proposal {feature}` - Create a new feature
+- `/morph-apply {feature}` - Implement a feature
+- `/morph-archive {feature}` - Archive a completed feature
 
 ---
 

package/framework/commands/morph-troubleshoot.md

@@ -1,121 +1,130 @@
-# Troubleshoot - Buscar Soluções para Erros
+---
+description: Find solutions for common .NET/Blazor/Azure development errors with root-cause analysis
+argument-hint: "[error-message]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# Troubleshoot - Find Solutions for Errors
 
-Busca soluções para erros e problemas comuns no desenvolvimento .NET/Blazor/Azure.
+Find solutions for common .NET/Blazor/Azure development errors and problems.
 
-## Uso
+## Usage
 
 ```
-/morph-troubleshoot <descrição do erro ou keywords>
+/morph-troubleshoot <error description or keywords>
 ```
 
-## Exemplos
+## Examples
 
 ```bash
 /morph-troubleshoot blazor.web.js 404
 /morph-troubleshoot DbContext second operation
 /morph-troubleshoot Azure.Identity NU1605
-/morph-troubleshoot Include retorna vazio
+/morph-troubleshoot Include returns empty
 /morph-troubleshoot PendingModelChanges
 ```
 
-## Workflow de 3 Níveis
+## 3-Level Workflow
 
-### Nível 1: Índice JSON (Primário)
+### Level 1: Search Standards (Primary)
 
-Primeiro, execute o comando CLI para buscar no índice de problemas conhecidos:
+Search the known problems and standards files for matching patterns:
 
 ```bash
-npx morph-spec troubleshoot {keywords}
-
-# Opções
---category <cat>     # Filtrar por categoria (blazor, efcore, azure)
---verbose            # Mostrar conteúdo completo da solução
---list-categories    # Listar categorias disponíveis
+# Search in framework standards
+Grep: "{keywords}" in framework/standards/ (glob: "*.md")
+Grep: "{keywords}" in .morph/framework/standards/ (glob: "*.md")
 ```
 
-### Nível 2: Grep nos Standards (Automático)
+Read matching files and extract the relevant solution sections.
+
+### Level 2: Search Codebase (Automatic)
+
+If standards don't cover the issue, search the codebase for the error pattern:
+
+```bash
+Grep: "{error pattern}" in src/ (glob: "*.cs,*.tsx,*.ts")
+```
 
-Se o índice retornar poucos resultados, o CLI automaticamente busca nos arquivos:
-- `framework/standards/*.md`
-- `.morph/framework/standards/*.md`
+Check if similar patterns exist elsewhere in the codebase that work correctly.
 
-### Nível 3: Web Search (Se necessário)
+### Level 3: Web Search (If needed)
 
-**IMPORTANTE:** Se os níveis 1 e 2 não encontrarem solução, use o tool **WebSearch** nativo do Claude Code para buscar nas seguintes fontes:
+**IMPORTANT:** If levels 1 and 2 don't find a solution, use Claude Code's native **WebSearch** tool to search the following sources:
 
-**Queries recomendadas:**
+**Recommended queries:**
 
 ```
 # GitHub Issues (.NET)
-site:github.com/dotnet/aspnetcore {erro}
-site:github.com/dotnet/efcore {erro}
+site:github.com/dotnet/aspnetcore {error}
+site:github.com/dotnet/efcore {error}
 
 # Stack Overflow
-site:stackoverflow.com [blazor] {erro}
-site:stackoverflow.com [entity-framework-core] {erro}
-site:stackoverflow.com [azure] {erro}
+site:stackoverflow.com [blazor] {error}
+site:stackoverflow.com [entity-framework-core] {error}
+site:stackoverflow.com [azure] {error}
 
-# Documentação Microsoft
-site:learn.microsoft.com {erro}
-site:learn.microsoft.com/azure {erro}
+# Microsoft Documentation
+site:learn.microsoft.com {error}
+site:learn.microsoft.com/azure {error}
 ```
 
-**Exemplo de uso do WebSearch:**
+**WebSearch usage example:**
 
-Se o usuário perguntar sobre um erro de SignalR:
-1. Primeiro: `npx morph-spec troubleshoot SignalR connection`
-2. Se não encontrar: WebSearch com `site:github.com/dotnet/aspnetcore SignalR connection closed`
-3. Retornar links relevantes formatados
+If the user asks about a SignalR error:
+1. First: `npx morph-spec troubleshoot SignalR connection`
+2. If not found: WebSearch with `site:github.com/dotnet/aspnetcore SignalR connection closed`
+3. Return formatted relevant links
 
-## Categorias Disponíveis
+## Available Categories
 
-| Categoria | Descrição |
+| Category | Description |
 |-----------|-----------|
-| `blazor` | Blazor Server/WASM, componentes, lifecycle, renderização |
+| `blazor` | Blazor Server/WASM, components, lifecycle, rendering |
 | `efcore` | Entity Framework Core, DbContext, migrations, queries |
 | `azure` | Azure services, deploy, identity, Key Vault |
 | `auth` | Authentication, authorization, tokens, claims |
 | `deploy` | Deployment, CI/CD, pipelines, containers |
 
-## Formato de Output
+## Output Format
 
-Ao encontrar uma solução, apresente no seguinte formato:
+When finding a solution, present in the following format:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-🔴 CRITICAL: {título do problema}
+🔴 CRITICAL: {problem title}
 
-📁 Arquivo: {caminho do arquivo com solução}
-📂 Seção: {seção específica}
+📁 File: {path to file with solution}
+📂 Section: {specific section}
 
-❌ Erro:
-   {padrão de erro que identifica o problema}
+❌ Error:
+   {error pattern that identifies the problem}
 
-💡 Causa:
-   {explicação da causa raiz}
+💡 Cause:
+   {root cause explanation}
 
-✅ Solução:
-   {código ou passos para resolver}
+✅ Solution:
+   {code or steps to resolve}
 
-📚 Ver completo: morph-spec read {arquivo}
+📚 See full: morph-spec read {file}
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-## Troubleshooting Rápido
+## Quick Troubleshooting
 
-### Problemas Mais Comuns
+### Most Common Problems
 
-| Erro | Solução Rápida |
+| Error | Quick Fix |
 |------|----------------|
 | `blazor.web.js 404` | `<RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>` |
-| `PendingModelChangesWarning` | `dotnet ef migrations add <Name>` antes de update |
-| `DbContext second operation` | Usar `IDbContextFactory` para background tasks |
-| `Include() vazio` | Usar `HasMany(x => x.Nav)` em vez de `HasMany<T>()` |
-| `Azure.Identity NU1605` | Especificar versão explícita no .csproj |
-| `Key Vault não carrega` | Não condicionar ao ambiente (IsDevelopment) |
-| `DefaultAzureCredential lento` | Desabilitar credenciais não usadas |
+| `PendingModelChangesWarning` | `dotnet ef migrations add <Name>` before update |
+| `DbContext second operation` | Use `IDbContextFactory` for background tasks |
+| `Include()` empty | Use `HasMany(x => x.Nav)` instead of `HasMany<T>()` |
+| `Azure.Identity NU1605` | Specify explicit version in .csproj |
+| `Key Vault won't load` | Don't condition on environment (IsDevelopment) |
+| `DefaultAzureCredential slow` | Disable unused credentials |
 
 ---
 

package/framework/hooks/claude-code/notification/approval-reminder.js

@@ -10,7 +10,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { stateExists, getActiveFeature, getPendingGates } from '../../shared/state-reader.js';
+import { stateExists, getActiveFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 
@@ -36,7 +36,8 @@ try {
     implement: ['design', 'tasks']
   };
 
-  const relevantGates = phaseGateRelevance[feature.phase] || [];
+  const currentPhase = feature.phase || derivePhaseForFeature(name);
+  const relevantGates = phaseGateRelevance[currentPhase] || [];
   const pendingRelevant = pending.filter(g => relevantGates.includes(g));
 
   if (pendingRelevant.length === 0) pass();