<h1 align="center">MORPH-SPEC</h1>

<p align="center">
  <strong>Desenvolvimento orientado por especificações com agentes AI</strong><br>
  <em>by Polymorphism Tech</em>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@polymorphism-tech/morph-spec"><img src="https://img.shields.io/npm/v/@polymorphism-tech/morph-spec.svg" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@polymorphism-tech/morph-spec"><img src="https://img.shields.io/npm/dm/@polymorphism-tech/morph-spec.svg" alt="npm downloads"></a>
  <a href="#licença"><img src="https://img.shields.io/npm/l/@polymorphism-tech/morph-spec.svg" alt="license"></a>
</p>

<p align="center">
  <a href="#instalação">Instalação</a> •
  <a href="#começando">Começando</a> •
  <a href="#comandos">Comandos</a> •
  <a href="#agentes">Agentes</a> •
  <a href="docs/">Documentação</a>
</p>

<p align="center">
  <strong>📚 Guias de Uso:</strong>
  <a href="QUICKSTART.md">Quick Start</a> •
  <a href="CHEATSHEET.md">Cheat Sheet</a> •
  <a href="docs/README.md">API Docs</a>
</p>

---

## O que é MORPH-SPEC?

**M**ethodical **O**rchestration for **R**eliable **P**roduction-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](https://nodejs.org/) 18+
- [Claude Code](https://claude.ai/code) instalado

### Instalação Rápida (Recomendado)

```bash
# 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:

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

<details>
<summary><strong>⚠️ Windows + nvm-windows: Comando não reconhecido?</strong></summary>

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](https://github.com/coreybutler/nvm-windows/issues/391).

### Solução 1: Adicionar ao PATH manualmente

**PowerShell (executar como Administrador):**
```powershell
# 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:
```bash
npx @polymorphism-tech/morph-spec init
npx @polymorphism-tech/morph-spec doctor
```

### Verificar se funcionou

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

### Mais Ajuda

```bash
morph-spec doctor  # Detecta problemas de PATH automaticamente
```

Veja também: [Troubleshooting](#troubleshooting)

</details>

### 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

```bash
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

```bash
morph-spec doctor
```

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

### 2. Atualizar para a versão mais recente

**Instalação Global:**
```bash
# 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):**
```bash
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](content/.morph/examples/micro-saas/) | SaaS completo com Blazor + Asaas billing |
| [api-nextjs](content/.morph/examples/api-nextjs/) | .NET API + Next.js frontend |
| [multi-agent](content/.morph/examples/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:**
```bash
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):**
```bash
npx @polymorphism-tech/morph-spec init
```

**Solução 2 - Adicionar ao PATH:**

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

**Windows (PowerShell como Admin):**
```powershell
$npmPath = "$env:APPDATA\npm"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath", "User")
```

**Verificar correção:**
```bash
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:**
```bash
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):
```bash
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?

```bash
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: support@polymorphism.com.br
- 🐛 Issues: [GitHub](https://github.com/lucasPolymorphism/morph-spec-framework/issues)

---

## 📄 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](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: support@polymorphism.com.br
- 🌐 Website: https://polymorphism.com.br
- 📦 npm: [@polymorphism-tech/morph-spec](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)

---

## Links

- 📦 [npm Package](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
- 📚 [Documentação](docs/)
- 💡 [Exemplos](content/.morph/examples/)
- 🌐 [Polymorphism Tech](https://polymorphism.com.br)

---

*MORPH-SPEC by Polymorphism Tech*
