@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

package/framework/skills/level-1-workflows/{phase-setup → morph-phase-setup}/SKILL.md

@@ -1,195 +1,238 @@
----
-name: morph:phase-setup
-description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.9.0"
----
-
-# MORPH Setup - FASE 1
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Inicialize o contexto e prepare o ambiente para uma feature aprovada.
-
-## Pré-requisitos
-
-- [ ] Feature tem `proposal.md` criado (FASE 0 concluída)
-- [ ] Proposal foi aprovado pelo usuário
-- [ ] Agentes foram detectados e registrados no state
-
-## 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.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Verificar state | **Bash** `npx morph-spec state get` | — |
-| Detectar agentes + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | — |
-| Ler contexto do projeto | **Read** `.morph/context/README.md` | — |
-| Ler config | **Read** `.morph/config/config.json` | — |
-| Detectar arquitetura VSA | **Read** `.morph/config/config.json` → verificar `config.architecture.style` | — |
-| Escanear estrutura do projeto | **Glob** `src/**/*.{ts,tsx,cs}` | — |
-| Metadata do repositório | **GitHub MCP** `get_repo()` | **Bash** `gh repo view --json` |
-| Atualizar state | **Bash** `npx morph-spec state set` | — |
-
-**MCPs desta fase:** GitHub (opcional — metadata do repo).
-
-**Anti-padrões:**
-- ❌ Chamar `detect-agents` CLI (não existe — leia `.morph/framework/agents.json` diretamente)
-- ❌ Task agent para o keyword matching inline de stack detection (rápido o suficiente direto)
-- ❌ WebSearch para info local do projeto (use Read/Glob)
-
----
-
-## Workflow
-
-### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
-
-**⏸️ Antes de prosseguir com setup:**
-
-- [ ] `proposal.md` existe em `.morph/features/$ARGUMENTS/`?
-- [ ] Proposal foi apresentado e aprovado pelo usuário?
-- [ ] Feature foi registrada no state?
-
-**❌ Se alguma checkbox NÃO estiver marcada:**
-→ Voltar para FASE 0 (Proposal)
-
----
-
-### Passo 1: Verificar State
-
-Confirme que a feature existe no state:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Se não existir, volte para FASE 0 (proposal).
-
-### Passo 2: Detectar Agentes e Carregar Standards
-
-#### Passo 2.0: Detectar Estilo de Arquitetura e Ativar Arquiteto
-
-**Leia `.morph/config/config.json` e verifique `config.architecture.style`:**
-
-| Valor | Ação |
-|-------|------|
-| `"vertical-slice"` | `npx morph-spec state add-agent $ARGUMENTS vsa-architect` |
-| ausente / qualquer outro | `npx morph-spec state add-agent $ARGUMENTS domain-architect` |
-
-**Prossiga com keyword detection normal para os demais agentes** (ef-modeler, api-designer, etc.).
-O arquiteto já foi adicionado acima — **ignore-o no keyword matching** para evitar duplicação.
-
-#### Passo 2.1: Keyword Detection
-
-**Leia agents.json diretamente e faça o match de keywords** (exceto `domain-architect` e `vsa-architect` que já foram tratados no Passo 2.0):
-
-1. Leia `.morph/framework/agents.json`
-2. Extraia título e descrição da feature de `0-proposal/proposal.md`
-3. Para cada agente no JSON (exceto arquitetos), verifique se alguma keyword do campo `keywords[]` aparece no texto da proposta
-4. Adicione os agentes correspondentes ao state:
-
-```bash
-npx morph-spec state add-agent $ARGUMENTS {agent-id}
-# Exemplo:
-npx morph-spec state add-agent $ARGUMENTS dotnet-senior
-npx morph-spec state add-agent $ARGUMENTS ef-modeler
-```
-
-**Para carregar standards dos agentes detectados:**
-- Para cada agente ativo, leia os standards referenciados pelo campo `standards[]` em `agents.json`
-- Os arquivos de standard ficam em `.morph/framework/standards/{path}`
-
-**Standards resolution order** (manual):
-1. `.morph/context/*.md` — project overrides (maior prioridade)
-2. `.morph/framework/standards/` — standards instalados pelo morph-spec
-3. `framework/standards/` — standards do pacote npm (fallback)
-
-**Contexto geral** (leia sempre):
-- `.morph/context/README.md` — Overview do projeto
-- `.morph/config/config.json` — Configurações
-
-### Passo 3: Confirmar Stack
-
-Baseado no proposal e contexto, confirme:
-- Stack tecnológica (Blazor Server, Next.js, etc.)
-- Padrões arquiteturais aplicáveis
-- Componentes reutilizáveis existentes
-
-### Passo 4: Listar Agentes Ativos e Preview de Dispatch
-
-Mostre os agentes detectados no proposal:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Parse o JSON e liste os `activeAgents` com seus emojis e responsabilidades (consulte `.morph/framework/agents.json`).
-
-**Se houver 2+ agentes especialistas ativos**, mostre o plano de dispatch para as próximas fases:
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS design
-```
-
-Isso informa quais agentes serão disparados em paralelo na fase de design e quais tasks eles executarão.
-
-> **Mapeamento importante:** `agents[].id` do dispatch config = `subagent_type` no `Agent` tool.
-> Exemplo: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
-> Cada `id` corresponde ao campo `name:` no frontmatter do arquivo em `.claude/agents/`.
-
-### Passo 5: Atualizar State
-
-Marque a feature como na fase SETUP:
-
-```bash
-npx morph-spec state set $ARGUMENTS status in_progress
-```
-
-## Outputs
-
-**Apresente ao usuário:**
-
-1. **Contexto carregado**:
-   - Nome do projeto
-   - Stack confirmado
-   - Standards aplicáveis
-
-2. **Agentes ativos**:
-   - Lista de agentes com emojis
-   - Responsabilidades de cada um
-
-## Critérios de Avanço
-
-- [x] Contexto do projeto carregado
-- [x] Standards identificados (framework + project)
-- [x] Stack confirmado
-- [x] Agentes listados
-- [x] State atualizado para phase: setup
-
----
-
-## Integração com Superpowers
-
-> Disponível quando o plugin `superpowers` está instalado.
-
-| Skill | Quando Usar | Invocação |
-|-------|-------------|-----------|
-| `using-git-worktrees` | Se feature requer isolamento do workspace | `Skill(superpowers:using-git-worktrees)` |
-
----
-
-## Outputs desta Fase
-
-<!-- morph:outputs:proposal -->
-| Output | Caminho |
-|--------|---------|
-| `proposal` | `.morph/features/{feature}/0-proposal/proposal.md` |
-<!-- /morph:outputs -->
-
----
-
+---
+name: morph:phase-setup
+description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.10.0"
+---
+
+# MORPH Setup - FASE 1
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Inicialize o contexto e prepare o ambiente para uma feature aprovada.
+
+## Pré-requisitos
+
+- [ ] Feature tem `proposal.md` criado (FASE 0 concluída)
+- [ ] Proposal foi aprovado pelo usuário
+- [ ] Agentes foram detectados e registrados no state
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Verificar state | **Bash** `npx morph-spec state get` | — |
+| Detectar agentes + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | — |
+| Ler contexto do projeto | **Read** `.morph/context/README.md` | — |
+| Ler config | **Read** `.morph/config/config.json` | — |
+| Detectar arquitetura VSA | **Read** `.morph/config/config.json` → verificar `config.architecture.style` | — |
+| Escanear estrutura do projeto | **Glob** `src/**/*.{ts,tsx,cs}` | — |
+| Metadata do repositório | **GitHub MCP** `get_repo()` | **Bash** `gh repo view --json` |
+| Atualizar state | **Bash** `npx morph-spec state set` | — |
+
+**MCPs desta fase:** GitHub (opcional — metadata do repo).
+
+**Anti-padrões:**
+- ❌ Chamar `detect-agents` CLI (não existe — leia `.morph/framework/agents.json` diretamente)
+- ❌ Task agent para o keyword matching inline de stack detection (rápido o suficiente direto)
+- ❌ WebSearch para info local do projeto (use Read/Glob)
+
+---
+
+## Workflow
+
+### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
+
+**⏸️ Antes de prosseguir com setup:**
+
+- [ ] `proposal.md` existe em `.morph/features/$ARGUMENTS/`?
+- [ ] Proposal foi apresentado e aprovado pelo usuário?
+- [ ] Feature foi registrada no state?
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar para FASE 0 (Proposal)
+
+---
+
+### Passo 1: Verificar State
+
+Confirme que a feature existe no state:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Se não existir, volte para FASE 0 (proposal).
+
+### Passo 2: Detectar Agentes e Carregar Standards
+
+#### Passo 2.0: Detectar Estilo de Arquitetura e Ativar Arquiteto
+
+**Leia `.morph/config/config.json` e verifique `config.architecture.style`:**
+
+| Valor | Ação |
+|-------|------|
+| `"vertical-slice"` | `npx morph-spec state add-agent $ARGUMENTS vsa-architect` |
+| ausente / qualquer outro | `npx morph-spec state add-agent $ARGUMENTS domain-architect` |
+
+**Prossiga com keyword detection normal para os demais agentes** (ef-modeler, api-designer, etc.).
+O arquiteto já foi adicionado acima — **ignore-o no keyword matching** para evitar duplicação.
+
+#### Passo 2.1: Keyword Detection
+
+**Leia agents.json diretamente e faça o match de keywords** (exceto `domain-architect` e `vsa-architect` que já foram tratados no Passo 2.0):
+
+1. Leia `.morph/framework/agents.json`
+2. Extraia título e descrição da feature de `0-proposal/proposal.md`
+3. Para cada agente no JSON (exceto arquitetos), verifique se alguma keyword do campo `keywords[]` aparece no texto da proposta
+4. Adicione os agentes correspondentes ao state:
+
+```bash
+npx morph-spec state add-agent $ARGUMENTS {agent-id}
+# Exemplo:
+npx morph-spec state add-agent $ARGUMENTS dotnet-senior
+npx morph-spec state add-agent $ARGUMENTS ef-modeler
+```
+
+**Para carregar standards dos agentes detectados:**
+- Para cada agente ativo, leia os standards referenciados pelo campo `standards[]` em `agents.json`
+- Os arquivos de standard ficam em `.morph/framework/standards/{path}`
+
+**Standards resolution order** (manual):
+1. `.morph/context/*.md` — project overrides (maior prioridade)
+2. `.morph/framework/standards/` — standards instalados pelo morph-spec
+3. `framework/standards/` — standards do pacote npm (fallback)
+
+**Contexto geral** (leia sempre):
+- `.morph/context/README.md` — Overview do projeto
+- `.morph/config/config.json` — Configurações
+
+### Passo 2.5: Validar Conexoes MCP
+
+Verifique se os MCPs configurados estao funcionando antes de prosseguir.
+
+**1. Coletar MCPs recomendados:**
+- Leia `framework/phases.json` → para cada fase no workflow da feature, colete os `recommendedMCPs[]`
+- Leia `framework/skills/level-0-meta/mcp-registry.json` → obtenha os `healthCheck` de cada MCP
+
+**2. Identificar MCPs configurados:**
+- Leia `.claude/settings.local.json` → identifique quais MCPs estao em `mcpServers`
+
+**3. Para cada MCP que esta CONFIGURADO E RECOMENDADO:**
+1. Procure nas suas ferramentas disponiveis por uma que contenha `healthCheck.toolPattern` no nome
+2. Se a ferramenta existir → execute o `healthCheck.testCall` com `healthCheck.testParams`
+3. Avalie o resultado:
+
+| Resultado | Acao |
+|-----------|------|
+| **Sucesso** | `✓ {MCP} — conexao verificada` |
+| **Ferramenta nao encontrada** | `○ {MCP} — precisa restart para ativar` |
+| **Erro** | → **AskUserQuestion** com 3 opcoes (abaixo) |
+
+**Em caso de erro — pergunte ao usuario:**
+
+Use `AskUserQuestion` com header `"{MCP}"` e opcoes:
+- **Continuar sem {MCP}** — Mostre o campo `fallback` do registry e prossiga
+- **Reconfigurar credenciais** — Colete novas credenciais e atualize `.claude/settings.local.json`
+- **Parar setup** — Aborte e reporte o que precisa ser corrigido
+
+**4. Para MCPs RECOMENDADOS mas NAO CONFIGURADOS:**
+- Print `△ {MCP} — nao configurado (fallback: {registry.fallback})`
+- Sugestao: `Tip: configure com /morph:init refresh ou npx morph-spec mcp setup`
+
+**Resumo:** Mostre uma tabela com status de cada MCP antes de prosseguir:
+```
+MCP Readiness:
+  ✓ context7 — conexao verificada
+  ○ playwright — precisa restart
+  △ supabase — nao configurado (fallback: Grep + Read para schema)
+```
+
+---
+
+### Passo 3: Confirmar Stack
+
+Baseado no proposal e contexto, confirme:
+- Stack tecnológica (Blazor Server, Next.js, etc.)
+- Padrões arquiteturais aplicáveis
+- Componentes reutilizáveis existentes
+
+### Passo 4: Listar Agentes Ativos e Preview de Dispatch
+
+Mostre os agentes detectados no proposal:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Parse o JSON e liste os `activeAgents` com seus emojis e responsabilidades (consulte `.morph/framework/agents.json`).
+
+**Se houver 2+ agentes especialistas ativos**, mostre o plano de dispatch para as próximas fases:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+Isso informa quais agentes serão disparados em paralelo na fase de design e quais tasks eles executarão.
+
+> **Mapeamento importante:** `agents[].id` do dispatch config = `subagent_type` no `Agent` tool.
+> Exemplo: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
+> Cada `id` corresponde ao campo `name:` no frontmatter do arquivo em `.claude/agents/`.
+
+### Passo 5: Atualizar State
+
+Marque a feature como na fase SETUP:
+
+```bash
+npx morph-spec state set $ARGUMENTS status in_progress
+```
+
+## Outputs
+
+**Apresente ao usuário:**
+
+1. **Contexto carregado**:
+   - Nome do projeto
+   - Stack confirmado
+   - Standards aplicáveis
+
+2. **Agentes ativos**:
+   - Lista de agentes com emojis
+   - Responsabilidades de cada um
+
+## Critérios de Avanço
+
+- [x] Contexto do projeto carregado
+- [x] Standards identificados (framework + project)
+- [x] Stack confirmado
+- [x] Agentes listados
+- [x] State atualizado para phase: setup
+
+---
+
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `using-git-worktrees` | Se feature requer isolamento do workspace | `Skill(superpowers:using-git-worktrees)` |
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:proposal -->
+| Output | Caminho |
+|--------|---------|
+| `proposal` | `.morph/features/{feature}/0-proposal/proposal.md` |
+<!-- /morph:outputs -->
+
+---
+
 Continuar automaticamente para próxima fase (UI/UX se detectado, ou Design).