O que é MORPH-SPEC?

Methodical Orchestration for Reliable Production-ready SPEC-driven development

MORPH-SPEC é um framework de desenvolvimento orientado por especificações com 17 agentes AI especializados. Cada agente tem expertise em tecnologias específicas e segue workflows estruturados para entregar código production-ready.

Stacks suportadas: .NET/Blazor, .NET/Next.js, Shopify Infraestrutura: Azure Bicep (IaC) Ferramenta: Claude Code

Instalação

Pré-requisitos

• Node.js 18+
• Claude Code instalado

Instalação Rápida (Recomendado)

# Navegue até seu projeto
cd /caminho/do/seu/projeto

# Execute o instalador (não precisa instalar nada)
npx @polymorphism-tech/morph-spec init

Instalação Global (Opcional)

Se preferir ter o comando disponível globalmente:

npm install -g @polymorphism-tech/morph-spec
morph-spec init

Se você usa nvm-windows para gerenciar versões do Node.js, o npm não adiciona automaticamente os pacotes globais ao PATH. Este é um problema conhecido do nvm-windows.

Solução 1: Adicionar ao PATH manualmente

PowerShell (executar como Administrador):

# Verificar o caminho do npm global
npm config get prefix

# Adicionar ao PATH (substitua pelo caminho acima)
$npmPath = "$env:APPDATA\npm"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath", "User")

Depois, feche e reabra o terminal.

Solução 2: Use npx (Recomendado)

O npx funciona sem configurar PATH:

npx @polymorphism-tech/morph-spec init
npx @polymorphism-tech/morph-spec doctor

Verificar se funcionou

morph-spec --version
# Ou
npx @polymorphism-tech/morph-spec --version

Mais Ajuda

morph-spec doctor  # Detecta problemas de PATH automaticamente

Veja também: Troubleshooting

Comandos CLI

| Comando | Descrição | |---------|-----------| | morph-spec init | Inicializa MORPH no diretório atual | | morph-spec init --force | Sobrescreve instalação existente | | morph-spec update | Atualiza projeto para versão mais recente | | morph-spec update --templates | Atualiza apenas templates | | morph-spec update --standards | Atualiza apenas standards | | morph-spec doctor | Verifica saúde e versões da instalação |

Verificar Instalação

morph-spec doctor

O comando doctor verifica:

• ✓ Versão do CLI (se está atualizada)
• ✓ Versão do MORPH no projeto
• ✓ Estrutura de arquivos e configurações

Ou abra seu projeto no Claude Code e execute:

/morph-status

Mantendo Atualizado

1. Verificar se há atualizações

morph-spec doctor

Isso mostrará se há versões mais recentes disponíveis.

2. Atualizar para a versão mais recente

Instalação Global:

# Primeiro, atualize o CLI
npm install -g @polymorphism-tech/morph-spec@latest

# Depois, atualize seu projeto
cd /caminho/do/seu/projeto
morph-spec update

Usando npx (Recomendado - sempre pega a versão mais recente):

cd /caminho/do/seu/projeto
npx @polymorphism-tech/morph-spec@latest update

3. O que é atualizado?

O comando update sincroniza:

• ✅ Templates (.morph/templates/)
• ✅ Standards (.morph/standards/)
• ✅ Agentes (.morph/config/agents.json)
• ✅ Comandos Claude (.claude/commands/)
• ✅ Skills (.claude/skills/)
• ✅ Instruções (CLAUDE.md)

Importante: Seu config.json é preservado!

Começando

1. Criar uma Proposta

/morph-proposal minha-feature

Descreva o que quer implementar. O MORPH vai gerar a especificação completa.

2. Revisar a Spec

Arquivos gerados em .morph/features/minha-feature/:

• spec.md - Especificação técnica
• contracts.cs - Interfaces e DTOs
• decisions.md - Decisões arquiteturais

3. Aprovar o Design

Revise os arquivos gerados e aprove (ou peça ajustes).

4. Implementar

/morph-apply minha-feature

O MORPH implementa task por task, com testes a cada etapa.

5. Arquivar

/morph-archive minha-feature

Move a feature concluída para o arquivo.

Como Funciona

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  SETUP   │ ─▶ │  DESIGN  │ ─▶ │ CLARIFY  │ ─▶ │  TASKS   │ ─▶ │IMPLEMENT │
│          │    │          │    │          │    │          │    │          │
│ Contexto │    │  Spec +  │    │  Q&A +   │    │  Quebra  │    │ Executa  │
│ + Agents │    │Contracts │    │  Edges   │    │  Tasks   │    │ + Testa  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
                     ⛔                              ⛔
                  Aprovação                       Aprovação

Pontos de aprovação: O MORPH para em 2 momentos para você revisar antes de continuar.

Comandos Claude Code

| Comando | Descrição | |---------|-----------| | /morph-proposal <nome> | Cria nova feature | | /morph-apply <nome> | Implementa feature aprovada | | /morph-status | Mostra status do projeto | | /morph-archive <nome> | Arquiva feature concluída | | /morph-infra <ação> | Gerencia infraestrutura (init, validate, deploy) | | /morph-costs | Estima custos Azure |

Agentes

Sempre Ativos

| Agente | Função | |--------|--------| | 📐 Standards Architect | Padrões de código e consistência | | ☁️ Azure Architect | Infraestrutura cloud e IaC | | 💰 Cost Guardian | Controle de custos |

Por Stack

| Agente | Keywords | |--------|----------| | 🔥 Blazor Builder | blazor, razor, component | | ⚛️ NextJS Expert | nextjs, react, frontend | | 🛒 Shopify Expert | shopify, hydrogen, liquid |

Especialistas

| Agente | Keywords | |--------|----------| | 🗄️ EF Modeler | database, entity, migration | | 🤖 MS Agent Expert | agent, ai, semantic kernel | | ⏰ Hangfire Orchestrator | scheduled, job, background | | 🎨 UI/UX Designer | wizard, dashboard, complex form | | 📋 PO/PM Advisor | unclear, requirements, ROI |

Integrações

| Agente | Keywords | |--------|----------| | 💳 Asaas Financial | asaas, pix, boleto, payment | | 🔐 Clerk Auth | clerk, auth, login | | 🆔 Azure Identity | identity, entra, microsoft auth |

Infraestrutura

| Agente | Keywords | |--------|----------| | 🏗️ Bicep Architect | bicep, iac, infra | | 🚀 DevOps Engineer | pipeline, ci/cd, deploy | | 📦 Container Specialist | docker, container |

Exemplos

| Exemplo | Descrição | |---------|-----------| | micro-saas | SaaS completo com Blazor + Asaas billing | | api-nextjs | .NET API + Next.js frontend | | multi-agent | Sistema multi-agente com Semantic Kernel |

Cada exemplo inclui: README.md, spec.md, contracts.cs, tasks.md, decisions.md

Estrutura do Projeto

Após a instalação, seu projeto terá:

seu-projeto/
├── CLAUDE.md                 # Instruções para o AI
├── .morph/
│   ├── config/               # Configurações
│   │   ├── config.json
│   │   └── agents.json
│   ├── standards/            # Padrões de código
│   │   ├── coding.md
│   │   ├── architecture.md
│   │   └── azure.md
│   ├── templates/            # Templates de código e IaC
│   │   ├── infra/
│   │   ├── integrations/
│   │   └── saas/
│   ├── examples/             # Exemplos completos
│   ├── features/             # Features em desenvolvimento
│   └── archive/              # Features concluídas
└── .claude/
    ├── commands/             # Slash commands
    └── skills/               # Skills dos agentes

Templates Incluídos

IaC (Bicep)

• main.bicep, container-app.bicep, sql-database.bicep, storage.bicep, key-vault.bicep, app-insights.bicep

Integrações

• asaas-client.cs, asaas-webhook.cs, clerk-config.cs, azure-identity-config.cs

SaaS

• subscription.cs, tenant.cs

Código

• service.cs, repository.cs, component.razor, agent.cs, job.cs, test.cs

Custos

O MORPH segue a filosofia "Free tier first":

| Nível | Limite | Requer | |-------|--------|--------| | Sem aprovação | Free tier | Nada | | Com aprovação | Até $10/mês | Confirmação | | Acima de $10 | Justificativa | ADR |

🔧 Troubleshooting

Comando morph-spec não encontrado

Sintoma: Após npm install -g, o comando não é reconhecido.

Diagnóstico:

npm config get prefix  # Ver onde npm instala globalmente
echo $PATH             # Linux/Mac: Verificar se está no PATH
$env:Path              # Windows: Verificar se está no PATH

Causa comum: Você está usando nvm ou nvm-windows, que não adiciona automaticamente npm global ao PATH.

Solução 1 - Usar npx (Recomendado):

npx @polymorphism-tech/morph-spec init

Solução 2 - Adicionar ao PATH:

Linux/Mac:

# Adicionar ao ~/.bashrc ou ~/.zshrc
export PATH="$HOME/.npm-global/bin:$PATH"

Windows (PowerShell como Admin):

$npmPath = "$env:APPDATA\npm"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath", "User")

Verificar correção:

morph-spec --version

morph-spec doctor reporta problemas

O que o doctor verifica:

• ✓ Versão do CLI (atualizada?)
• ✓ Versão do MORPH no projeto
• ✓ Comando morph-spec no PATH
• ✓ Estrutura de arquivos (.morph/, CLAUDE.md, etc.)

Se reportar "morph-spec not in PATH":

1. Use npx como alternativa (sempre funciona)
2. Ou siga as instruções acima para adicionar ao PATH

Se reportar arquivos faltando:

morph-spec init --force  # Reinstala estrutura completa

Erro ao instalar globalmente no Windows

Erro: EPERM: operation not permitted

Causa: Falta de permissões de administrador.

Solução:

1. Abra PowerShell ou CMD como Administrador
2. Execute: npm install -g @polymorphism-tech/morph-spec

Alternativa: Use npx (não requer admin):

npx @polymorphism-tech/morph-spec init

nvm-windows específico

Se você usa nvm-windows para gerenciar versões do Node.js:

Problema conhecido: npm global não vai para PATH automaticamente Issue oficial: https://github.com/coreybutler/nvm-windows/issues/391

Recomendações:

1. Melhor opção: Use npx para todos os comandos
2. Alternativa: Configure PATH manualmente (ver seção de instalação)
3. Verificar: Execute morph-spec doctor para diagnosticar

Precisa de mais ajuda?

morph-spec doctor          # Diagnóstico automático
morph-spec --help          # Ver todos os comandos
morph-spec <comando> --help  # Ajuda de comando específico

Suporte:

• 📧 Email: [email protected]
• 🐛 Issues: GitHub

📄 Licença e Distribuição

Repositório: Privado (código fonte protegido) Package npm: Público e gratuito via @polymorphism-tech/morph-spec

Licença Proprietária

O MORPH-SPEC framework é software proprietário da Polymorphism Tech. Veja LICENSE para detalhes.

Você PODE:

• ✅ Usar o CLI tool gratuitamente
• ✅ Gerar projetos para uso pessoal ou comercial
• ✅ Modificar código gerado pelos templates
• ✅ Distribuir seus projetos criados com MORPH-SPEC

Você NÃO PODE:

• ❌ Redistribuir ou vender o framework
• ❌ Criar produtos derivados competidores
• ❌ Modificar ou fazer engenharia reversa do framework
• ❌ Remover avisos de copyright

Código Gerado

Todo código gerado usando MORPH-SPEC é 100% seu para usar como quiser, incluindo uso comercial.

Suporte

• 📧 Email: [email protected]
• 🌐 Website: https://polymorphism.com.br
• 📦 npm: @polymorphism-tech/morph-spec

Links

• 📦 npm Package
• 📚 Documentação
• 💡 Exemplos
• 🌐 Polymorphism Tech

MORPH-SPEC by Polymorphism Tech