# MORPH-SPEC - Guia de Instalação

**M**ethodical **O**rchestration for **R**eliable **P**roduction-ready **SPEC**-driven development

---

## 📋 Pré-requisitos

- **Node.js** 18+ (para CLI)
- **Claude Code** (recomendado para melhor experiência)
- Projeto .NET, Next.js ou Shopify (opcional - funciona sem)

---

## 🚀 Instalação

### Método 1: npm Global (Recomendado)

```bash
# Instalar globalmente
npm install -g @polymorphism-tech/morph-spec

# Verificar instalação
morph-spec --version
morph-spec --help
```

### Método 2: npx (Sem instalação)

```bash
# Usar diretamente sem instalar
npx @polymorphism-tech/morph-spec init
```

---

## 🎯 Uso

### Cenário 1: Projeto Novo com MORPH

```bash
# 1. Criar projeto (exemplo .NET)
dotnet new blazor -n MeuProjeto
cd MeuProjeto

# 2. Inicializar MORPH
morph-spec init

# 3. Verificar estrutura criada
ls -la .morph/
```

**O que foi criado:**
```
.morph/
├── config.json                  # Config do projeto
└── project/
    ├── context/
    │   ├── README.md            # Overview do projeto
    │   ├── detection-log.md     # Log de detecção automática
    │   └── decisions-history.md # Histórico de decisões
    ├── standards/
    │   └── inferred.md          # Standards detectados
    └── outputs/                 # Features (vazio inicialmente)
```

---

### Cenário 2: Projeto Existente (Adotando MORPH)

```bash
# 1. Ir para projeto existente
cd meu-projeto-existente

# 2. Detectar estrutura primeiro (opcional mas recomendado)
morph-spec detect --verbose

# 3. Inicializar MORPH
morph-spec init

# 4. Revisar standards inferidos
cat .morph/project/standards/inferred.md
```

**Detecção automática identifica:**
- ✅ Stack (Blazor, Next.js, Shopify)
- ✅ Arquitetura (Clean Architecture, CQRS, MVC)
- ✅ UI Library (Fluent UI, MudBlazor)
- ✅ Patterns (Repository, DI, EF Core, etc)
- ✅ Tecnologias e versões

---

### Cenário 3: Usar SEM Instalar Framework (Degradado)

Claude Code ainda funciona sem MORPH instalado:

- ✅ Detecção automática de código
- ✅ Standards inferidos baseados no projeto
- ⚠️ Sem templates sofisticados
- ⚠️ Sem framework standards como referência

---

## 🔧 Comandos Principais

### `morph-spec init`

Inicializa MORPH no projeto atual.

```bash
morph-spec init

# Opções:
morph-spec init --force          # Sobrescrever instalação existente
morph-spec init --path ./outro   # Diretório customizado
```

---

### `morph-spec detect`

Detecta stack, arquitetura e padrões do projeto.

```bash
morph-spec detect

# Opções:
morph-spec detect --verbose       # Mostrar detalhes completos
morph-spec detect --no-save       # Não salvar resultados
morph-spec detect --path ./outro  # Diretório customizado
```

**Output:**
- `.morph/project/context/detection-log.md`
- `.morph/project/standards/inferred.md`

---

### `morph-spec sync`

Sincroniza standards a partir de decisões de features.

```bash
morph-spec sync

# Opções:
morph-spec sync --dry-run        # Ver o que seria sincronizado
morph-spec sync --path ./outro   # Diretório customizado
```

**O que faz:**
1. Varre `.morph/project/outputs/*/decisions.md`
2. Agrupa decisões por categoria
3. Promove para `.morph/project/standards/*.md`
4. Mantém histórico de evolução

---

### `morph-spec update`

Atualiza framework para versão mais recente.

```bash
morph-spec update

# Opções:
morph-spec update --templates     # Atualizar apenas templates
morph-spec update --standards     # Atualizar apenas standards
```

---

### `morph-spec doctor`

Diagnóstico de saúde da instalação.

```bash
morph-spec doctor
```

**Verifica:**
- ✅ Versão do framework
- ✅ Estrutura `.morph/` correta
- ✅ Arquivos obrigatórios presentes
- ✅ Links para framework funcionando

---

## 🤖 Integração com Claude Code

### 1. MORPH instalado globalmente

Ao abrir projeto com Claude Code:

```
FASE 0.5: CONTEXT (automática)
├─ Detectar framework MORPH ✓
├─ Carregar framework/standards/ ✓
├─ Carregar .morph/project/standards/ ✓
├─ Analisar código do projeto ✓
└─ Gerar/Atualizar inferred.md ✓

Pronto para FASE 0: PROPOSAL!
```

### 2. Sem MORPH instalado

Claude Code ainda funciona:

```
FASE 0.5: CONTEXT (modo degradado)
├─ Framework não detectado (modo inferred)
├─ Analisar código do projeto ✓
├─ Detectar stack e patterns ✓
└─ Gerar standards inferidos ✓

Funciona, mas sem templates do framework
```

---

## 📂 Estrutura Completa

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

```
meu-projeto/
├── .morph/
│   ├── config.json              # Config: link para framework + project
│   └── project/
│       ├── context/
│       │   ├── README.md
│       │   ├── detection-log.md
│       │   └── decisions-history.md
│       ├── standards/
│       │   ├── inferred.md       # Auto-gerado (não editar)
│       │   ├── coding.md         # (opcional) Overrides
│       │   ├── architecture.md   # (opcional) Overrides
│       │   └── integrations.md   # (opcional) Project-specific
│       └── outputs/              # Features em desenvolvimento
│           └── {feature-name}/
│               ├── proposal.md
│               ├── spec.md
│               ├── contracts.cs
│               ├── tasks.json
│               ├── decisions.md
│               └── recap.md
│
├── CLAUDE.md                     # Copiado do framework
├── (seu código aqui)
```

---

## 🔗 Framework (Instalado via npm)

Localização global (macOS/Linux):
```
~/.npm/_npx/*/node_modules/@polymorphism-tech/morph-spec/framework/
```

Localização global (Windows):
```
%APPDATA%\npm\node_modules\@polymorphism-tech\morph-spec\framework\
```

**Conteúdo:**
- `framework/standards/` - Padrões do MORPH (read-only)
- `framework/templates/` - Templates para features
- `framework/config/` - Configurações padrão
- `framework/claude/` - Comandos e skills

---

## ✅ Próximos Passos

Após instalação:

1. **Explorar standards detectados**
   ```bash
   cat .morph/project/standards/inferred.md
   ```

2. **Criar primeira feature com Claude Code**
   - Abra Claude Code
   - Digite: "Quero implementar autenticação com Clerk"
   - MORPH guiará pelas 8 fases

3. **Sincronizar aprendizados**
   ```bash
   morph-spec sync
   ```

4. **Manter framework atualizado**
   ```bash
   morph-spec update
   ```

---

## 🆘 Troubleshooting

### Problema: `morph-spec: command not found`

**Solução:**
```bash
# Reinstalar globalmente
npm install -g @polymorphism-tech/morph-spec

# Verificar PATH
echo $PATH  # macOS/Linux
echo %PATH% # Windows
```

---

### Problema: Claude Code não detecta framework

**Solução:**
```bash
# Verificar instalação
morph-spec doctor

# Forçar reinicialização
morph-spec init --force
```

---

### Problema: Standards não sendo gerados

**Solução:**
```bash
# Rodar detecção manualmente
morph-spec detect --verbose

# Verificar se há código no projeto
# (framework precisa de código para inferir standards)
```

---

## 📚 Documentação Adicional

- [Migration Guide](./migration-guide.md) - Migrar projetos existentes
- [Without Framework](./without-framework.md) - Usar sem npm package
- [Architecture](./architecture.md) - Como tudo funciona
- [CLAUDE.md](../CLAUDE.md) - Instruções completas para Claude Code

---

## 💬 Suporte

- **Issues**: https://github.com/lucasPolymorphism/morph-spec-framework/issues
- **Email**: support@polymorphism.com.br
- **Website**: https://polymorphism.com.br/morph-spec

---

*MORPH-SPEC by Polymorphism Tech*
