@polymorphism-tech/morph-spec 1.0.2 → 2.0.0

package/docs/installation.md

@@ -0,0 +1,361 @@
+# 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*