@polymorphism-tech/morph-spec 4.6.0 → 4.7.1

package/README.md

@@ -1,700 +1,414 @@
-<h1 align="center">MORPH-SPEC</h1>
-
-<p align="center">
-  <strong>Framework de desenvolvimento spec-driven com 30 agentes AI especializados</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 **30 agentes AI especializados** organizados em 4 tiers hierárquicos. Cada agente tem expertise em tecnologias específicas e segue workflows estruturados para entregar código production-ready.
-
-**Stacks suportadas:** .NET 10/Blazor, .NET 10/Next.js, Node.js, Monorepos
-**Infraestrutura:** Azure Bicep (IaC) + Docker
-**Ferramenta:** Claude Code
-**Validação:** Pipeline automático de enforcement com gates por fase
-**Auto-Detecção:** ✨ LLM-powered context detection (v3.1+)
-
----
-
-## 🚀 Novidade v3.0: LLM Interaction Enhancements
-
-MORPH-SPEC v3.0 torna o framework **explícito e orientado** para Claude Code com 8 melhorias fundamentais:
-
-### 1. **Approval Gates** (Portões de Aprovação)
-- ✅ Rastreamento explícito de aprovações em `state.json`
-- 🚫 Bloqueio de transições de fase até aprovação explícita
-- 📝 Comandos: `approve`, `reject`, `approval-status`
-
-### 2. **Checkpoint Automation** (Validação Automática)
-- 🔍 Auto-validação a cada 3 tasks (T003, T006, T009...)
-- 🛡️ 4 validators: architecture, packages, security, design-system
-- 🚧 Bloqueia progresso se falhas detectadas
-
-### 3. **Stricter Phase Validation** (Validação Estrita)
-- 🎯 State machine com transições válidas
-- 📋 Validação de conteúdo (spec.md, tasks.json)
-- 5️⃣ Sistema de 5 gates de validação
-
-### 4. **Agent Team Spawning** (Spawning de Agentes)
-- 🤖 Detecção automática quando spawnar (5+ agents, 15+ files, multi-domain)
-- 🏗️ Comando `spawn-team` gera configs para Task tool
-- 📄 Templates prontos para agent context
-
-### 5. **Metadata Generation** (Geração de Metadados)
-- 📊 Auto-gera `metadata.json` após cada task
-- ⚡ Reduz uso de tokens em 60-80%
-- 🔗 Links rápidos para spec, tasks, decisões
-
-### 6. **Learning System** (Sistema de Aprendizado)
-- 📚 11 patterns pré-configurados (389 linhas)
-- 🔎 Busca: `search-patterns "{keyword}"`
-- 📝 Captura: `capture-pattern {feature} success "Description"`
-
-### 7. **MCP Template Enhancement** (Templates Dinâmicos)
-- 🌐 17 placeholders com dados do projeto
-- 📈 Injeta: files, coverage, compliance, commits
-- 🎨 Templates: `proposal-with-mcp.md`, `spec-with-mcp.md`
-
-### 8. **Interactive Decisions** (Decisões Estruturadas)
-- 💬 Templates para AskUserQuestion
-- 🎯 6 padrões documentados (scope, architecture, validation, etc.)
-- 📖 Guia completo em `.morph/framework/templates/decision-prompts.md`
-
-**Configuração:** `.morph/config/llm-interaction.json` com 3 presets (strict, lightweight, no-guardrails)
-
-**Documentação:** [docs/llm-interaction-config.md](docs/llm-interaction-config.md)
-
-**Migration:** `npx morph-spec upgrade --preset strict`
-
----
-
-## ✨ Novidade v3.1: Auto-Detecção Inteligente
-
-MORPH-SPEC agora **detecta automaticamente** o contexto do seu projeto usando Claude Code:
-
-- 🤖 **LLM Analysis**: Analisa package.json, .csproj, README, estrutura de pastas
-- 🎯 **90%+ Accuracy**: Few-shot learning com exemplos reais (Next.js, Blazor, Monorepo)
-- 🔒 **Privacy-First**: Processamento local, zero chamadas externas de API
-- 🛡️ **Secret Sanitization**: Redação automática de API keys, passwords, tokens
-- 🧙 **Wizard Fallback**: Wizard interativo de 7 perguntas se LLM falhar
-- ⚡ **Zero Manual Work**: Gera `.morph/project.md` e `config.json` em segundos
-
-**Saiba mais:** [docs/cli-auto-detection.md](docs/cli-auto-detection.md)
-
----
-
-## 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 e **detecta automaticamente** o contexto do projeto ✨ |
-| `morph-spec init --wizard` | Inicializa com wizard manual (sem auto-detecção LLM) |
-| `morph-spec init --skip-detection` | Inicializa sem detectar contexto (configuração manual) |
-| `morph-spec init --force` | Sobrescreve instalação existente |
-| `morph-spec update` | Atualiza projeto e **re-analisa contexto** automaticamente ✨ |
-| `morph-spec update --wizard` | Atualiza com wizard manual |
-| `morph-spec update --skip-detection` | Atualiza sem re-analisar contexto |
-| `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 |
-
-> ✨ **Novo em v3.1+:** Auto-detecção inteligente de stack, arquitetura e infraestrutura usando Claude Code!
-
-### 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/framework/templates/`)
-- Standards (`.morph/framework/standards/`)
-- Agentes (`.morph/framework/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 validação automática a cada etapa.
-
-### 5. Arquivar
-
-```
-/morph-archive minha-feature
-```
-
-Move a feature concluída para o arquivo.
-
----
-
-## Como Funciona
-
-```
-┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
-│ PROPOSAL │ -> │  DESIGN  │ -> │ CLARIFY  │ -> │  TASKS   │ -> │IMPLEMENT │
-│          │    │          │    │          │    │          │    │          │
-│ Contexto │    │  Spec +  │    │  Q&A +   │    │  Quebra  │    │ Executa  │
-│ + Agents │    │Contracts │    │  Edges   │    │  Tasks   │    │ + Valida │
-└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
-                     |                               |              |
-                 Spec Gate                    Design System     Validation
-                (C# checks)                     Gate          Pipeline
-```
-
-**Pontos de aprovação:** O MORPH para em 2 momentos para você revisar antes de continuar.
-
-**Gates de validação (v3):**
-- **Spec Gate** (Design -> Clarify): Valida contratos C# — CancellationToken, PascalCase, async suffix, sealed classes, records para DTOs
-- **Design System Gate** (Tasks -> Implement): Bloqueia se features de UI não tiverem design system definido
-- **Validation Pipeline** (cada task done): Roda validators baseados nos agentes ativos da feature
-
----
-
-## Novidades v3 — Validation Pipeline
-
-O v3 transforma MORPH de ferramentas isoladas em um **pipeline integrado de validação**:
-
-| Feature | O que faz | Comando |
-|---------|-----------|---------|
-| **Validation Pipeline** | Roda validators automaticamente ao completar tasks | `morph-spec task done` |
-| **Standards Injection** | Carrega standards relevantes por agente automaticamente | `morph-spec detect-agents --json` |
-| **Design System Gate** | Bloqueia FASE 5 se features UI não tiverem design system | `morph-spec phase advance` |
-| **Spec Validation** | Valida contratos C# na FASE 2, antes de implementar | `morph-spec phase advance` |
-| **Decision Constraints** | ADRs em decisions.md configuram validators automaticamente | Automático |
-| **Auto Recap** | Gera recap.md a partir de dados reais do projeto | `morph-spec generate recap` |
-| **Smart Phase Advance** | Avança fases com gates de validação obrigatórios | `morph-spec phase advance` |
-
-**Fluxo de dados:**
-```
-agents.json (30 agentes)
-    |-> detect-agents -> state.json (agentes ativos)
-    |-> standards-context-injector -> standards por agente
-    |-> validation-runner -> validators por agente
-decisions.md (ADRs)
-    |-> decision-constraint-loader -> constraints para validators
-```
-
----
-
-## Comandos
-
-### Claude Code (Slash Commands)
-
-| Comando | Descrição |
-|---------|-----------|
-| `/morph-proposal <nome>` | Cria nova feature (fases 0-4 com pausas) |
-| `/morph-apply <nome>` | Implementa feature aprovada (fase 5) |
-| `/morph-status` | Mostra status do projeto |
-| `/morph-archive <nome>` | Arquiva feature concluída |
-| `/morph-infra <ação>` | Gerencia infraestrutura (init, validate, deploy) |
-| `/morph-preflight` | Validação pre-deploy Azure |
-| `/morph-troubleshoot <erro>` | Busca soluções para erros |
-
-### CLI Completo
-
-| Comando | Descrição |
-|---------|-----------|
-| **Setup** | |
-| `morph-spec init` | Inicializa MORPH no diretório |
-| `morph-spec update` | Atualiza para versão mais recente |
-| `morph-spec doctor` | Verifica saúde da instalação |
-| `morph-spec detect` | Detecta stack, arquitetura, patterns |
-| `morph-spec detect-agents <input>` | Detecta agentes + complexidade + standards |
-| **Fases e Tasks** | |
-| `morph-spec phase advance <feature>` | Avança fase com gates de validação |
-| `morph-spec validate-phase <feature> <phase>` | Valida pré-requisitos de uma fase |
-| `morph-spec task done <feature> <ids>` | Completa tasks (roda validação antes) |
-| `morph-spec task start <feature> <id>` | Marca task como in_progress |
-| `morph-spec task next <feature>` | Mostra próxima task sugerida |
-| `morph-spec rollback <feature> <phase>` | Rollback para fase anterior |
-| **Geração** | |
-| `morph-spec generate design-system <md>` | Gera CSS + temas C# de ui-design-system.md |
-| `morph-spec generate recap <feature>` | Gera recap.md automático |
-| `morph-spec generate context [feature]` | Gera CONTEXT.md para Claude Code |
-| **Validação** | |
-| `morph-spec validate [validator]` | Validação de código (packages, architecture, contrast) |
-| `morph-spec validate-blazor [path]` | Valida patterns Fluent UI Blazor |
-| `morph-spec validate-blazor-state [path]` | Valida session state Blazor |
-| `morph-spec validate-css [path]` | Valida classes CSS em Razor files |
-| `morph-spec analyze-blazor-concurrency [path]` | Detecta concurrency issues em DbContext |
-| `morph-spec lint-fluent [path]` | Lint de patterns Fluent UI |
-| **State** | |
-| `morph-spec state list` | Lista todas as features |
-| `morph-spec state get <feature>` | Detalhes de uma feature |
-| `morph-spec state set <feature> <key> <value>` | Atualiza propriedade |
-| `morph-spec state checkpoint <feature> "nota"` | Cria checkpoint |
-| **Story-Driven** | |
-| `morph-spec story create <feature> <id>` | Cria story com Dev Notes |
-| `morph-spec story shard <feature>` | Divide spec em shards (90% token savings) |
-| `morph-spec story status <feature> <action>` | Gerencia sprint status |
-| **Learning** | |
-| `morph-spec learn analyze` | Aprende com histórico do projeto |
-| `morph-spec learn insights` | Mostra patterns aprendidos |
-| `morph-spec learn suggest [category]` | Sugestões por categoria |
-| **Outros** | |
-| `morph-spec troubleshoot <keywords>` | Busca soluções para erros |
-| `morph-spec session-summary <feature>` | Resumo da sessão atual |
-| `morph-spec sync` | Sincroniza standards de decisions |
-
----
-
-## Agentes
-
-MORPH-SPEC possui **30 agentes** organizados em 4 tiers hierárquicos com squads:
-
-### Tier 1 — Orchestrators (3)
-
-| Agente | Função | Ativação |
-|--------|--------|----------|
-| **Standards Architect** | Chief Architect, padrões e consistência | Sempre ativo |
-| **AI System Architect** | Arquitetura de sistemas multi-agente | Por keyword |
-| **PO/PM Advisor** | Requisitos, ROI, business value | Por keyword |
-
-### Tier 2 — Domain Leaders (3)
-
-| Agente | Squad | Ativação |
-|--------|-------|----------|
-| **Dotnet Senior** | Backend (10 specialists) | Sempre ativo |
-| **Azure Architect** | Infraestrutura (5 specialists) | Sempre ativo |
-| **UI/UX Designer** | Frontend (3 specialists) | Por keyword |
-
-### Tier 3 — Specialists (23)
-
-<details>
-<summary><strong>Backend Squad (10)</strong></summary>
-
-| Agente | Keywords |
-|--------|----------|
-| **EF Modeler** | database, entity, migration, ef core |
-| **Event Architect** | event, service bus, cqrs, real-time |
-| **API Designer** | rest, graphql, grpc, openapi |
-| **NoSQL/Cache Expert** | cosmos, redis, cache, blob storage |
-| **DDD Expert** | ddd, aggregate, bounded context |
-| **Hangfire Orchestrator** | scheduled, job, background, cron |
-| **MS Agent Expert** | agent, ai, microsoft agent framework, mcp, a2a |
-| **Asaas Financial** | asaas, pix, boleto, payment |
-| **Clerk Auth** | clerk, login, signup, oauth |
-| **Resend Email** | resend, email, transactional email |
-</details>
-
-<details>
-<summary><strong>Frontend Squad (3)</strong></summary>
-
-| Agente | Keywords |
-|--------|----------|
-| **Blazor Builder** | blazor, razor, component, fluent ui |
-| **NextJS Expert** | nextjs, react, shadcn, server actions |
-| **CSS Specialist** | css, design system, theme, design tokens |
-</details>
-
-<details>
-<summary><strong>Infrastructure Squad (5)</strong></summary>
-
-| Agente | Keywords |
-|--------|----------|
-| **Bicep Architect** | bicep, iac, infra, provision |
-| **DevOps Engineer** | pipeline, ci/cd, deploy, github actions |
-| **Container Specialist** | docker, container, container apps |
-| **Observability Expert** | monitoring, logging, tracing, app insights |
-| **Azure Identity** | identity, entra, passkeys, managed identity |
-</details>
-
-<details>
-<summary><strong>Quality Squad (5)</strong></summary>
-
-| Agente | Keywords |
-|--------|----------|
-| **Testing Specialist** | test, unit, integration, e2e, xunit, bunit |
-| **Code Analyzer** | analyze, review, refactor, clean code, solid |
-| **Troubleshooting Expert** | debug, troubleshoot, root cause, diagnose |
-| **Load Testing Expert** | load test, k6, stress test, scalability |
-| **Documentation Specialist** | readme, api docs, deployment guide |
-</details>
-
-### Tier 4 — Validators (1)
-
-| Agente | Função | Ativação |
-|--------|--------|----------|
-| **Security Expert** | SQL injection, XSS, secrets, CSRF | Sempre ativo (hooks) |
-
----
-
-## 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
-│   ├── framework/
-│   │   ├── agents.json       # 30 agentes em 4 tiers
-│   │   ├── standards/        # Padrões de código (26 arquivos)
-│   │   │   ├── coding.md
-│   │   │   ├── architecture.md
-│   │   │   ├── azure.md
-│   │   │   ├── blazor-*.md   # Lifecycle, state, pitfalls, EF Core
-│   │   │   ├── css-*.md      # Naming, animations
-│   │   │   ├── agent-framework-*.md  # Setup, workflows, production, blazor-ui
-│   │   │   └── ...
-│   │   └── templates/        # Templates de código e IaC
-│   │       ├── infra/
-│   │       ├── integrations/
-│   │       └── saas/
-│   ├── context/              # Contexto do projeto e overrides
-│   ├── features/             # Features em desenvolvimento
-│   └── archive/              # Features concluídas
-└── .claude/
-    ├── commands/             # Slash commands
-    └── skills/               # Skills dos agentes (31+ arquivos)
-```
-
----
-
-## 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/)
-- [Wiki (Base de Conhecimento)](.wiki/) - 33 artigos sobre .NET, Azure, IA, SaaS e Claude Code
-- [Polymorphism Tech](https://polymorphism.com.br)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# morph-spec
+
+> Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
+
+**Package:** `@polymorphism-tech/morph-spec`
+**Version:** 4.7.1  
+**Requires:** Node.js 18+, Claude Code
+
+---
+
+## What it does
+
+morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (proposal, design, tasks) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.
+
+It integrates natively with Claude Code: skills become slash commands, agents become native subagents, hooks inject state context automatically, and rules enforce standards based on file paths.
+
+---
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) (latest)
+- Node.js 18+
+- npm 9+ or pnpm
+
+---
+
+## Installation
+
+Install the CLI globally:
+
+```bash
+npm install -g @polymorphism-tech/morph-spec
+```
+
+Then initialize in your project:
+
+```bash
+morph-spec init
+```
+
+Or use the interactive wizard:
+
+```bash
+morph-spec init --wizard
+```
+
+### Init options
+
+
+| Flag               | Description                               |
+| ------------------ | ----------------------------------------- |
+| `--wizard`         | Interactive step-by-step setup            |
+| `--skip-detection` | Skip auto-detection of stack and patterns |
+| `--force`          | Overwrite existing installation           |
+| `--skip-mcp`       | Skip MCP configuration prompt             |
+
+
+After init, open the project in Claude Code. The framework activates automatically via `.claude/settings.local.json`.
+
+---
+
+## Project structure (after init)
+
+```
+your-project/
+├── CLAUDE.md                        # AI instructions for this project
+├── .morph/
+│   ├── config/
+│   │   └── config.json              # Project configuration
+│   ├── framework/
+│   │   ├── agents.json              # 37 agents in 4 tiers (READ-ONLY)
+│   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
+│   │   └── templates/               # Code and IaC templates (READ-ONLY)
+│   ├── context/                     # Project context (README.md, standards.md)
+│   ├── features/                    # Active features
+│   │   └── {feature}/
+│   │       ├── 0-proposal/          # User story + acceptance criteria
+│   │       ├── 1-design/            # Technical spec, contracts, decisions
+│   │       ├── 2-ui/                # UI/UX design (optional, UI-heavy features)
+│   │       ├── 3-tasks/             # Atomic task list
+│   │       └── 4-implement/         # Recap and implementation notes
+│   └── state.json                   # READ-ONLY — managed by CLI only
+└── .claude/
+    ├── commands/                    # Slash commands
+    ├── skills/                      # Framework skills (flat .md files)
+    ├── agents/                      # Native subagents (37 agents)
+    ├── rules/                       # Path-scoped standards rules
+    └── settings.local.json          # Hooks configuration (11 hooks)
+```
+
+---
+
+## Phase workflow
+
+Features move through structured phases. Some are optional depending on feature type.
+
+```
+proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
+```
+
+Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is a post-implementation reconciliation step.
+
+### Phase outputs
+
+
+| Phase     | Directory      | Key files                                                     |
+| --------- | -------------- | ------------------------------------------------------------- |
+| Proposal  | `0-proposal/`  | `proposal.md`                                                 |
+| Design    | `1-design/`    | `spec.md`, `contracts.cs`, `decisions.md`                     |
+| UI/UX     | `2-ui/`        | `design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Tasks     | `3-tasks/`     | `tasks.md`                                                    |
+| Implement | `4-implement/` | `recap.md`                                                    |
+
+
+### Approval gates
+
+- **Design gate** — Spec must be approved before moving to Tasks.
+- **Implementation gate** — Task list must be approved before implementation starts.
+
+Check gate status:
+
+```bash
+morph-spec state show {feature}
+```
+
+---
+
+## Slash commands
+
+These commands are available inside Claude Code after init.
+
+
+| Command                     | Description                                               |
+| --------------------------- | --------------------------------------------------------- |
+| `/morph-proposal {feature}` | Full spec pipeline (phases 0-4, pauses at approval gates) |
+| `/morph-apply {feature}`    | Implement approved feature (phase 5)                      |
+| `/morph-status`             | Feature status dashboard                                  |
+| `/morph-preflight`          | Pre-implementation validation                             |
+
+
+---
+
+## CLI reference
+
+### Project management
+
+```bash
+morph-spec init                        # Initialize MORPH in current project
+morph-spec init --wizard               # Interactive wizard setup
+morph-spec init --skip-detection       # Skip stack auto-detection
+morph-spec init --force                # Overwrite existing installation
+morph-spec update                      # Update framework files and re-analyze project
+morph-spec update --wizard             # Interactive update
+morph-spec update --skip-detection     # Skip detection during update
+morph-spec update --templates          # Update templates only
+morph-spec update --standards          # Update standards only
+morph-spec doctor                      # Check installation health
+morph-spec detect                      # Detect stack, architecture, patterns
+```
+
+### Feature workflow
+
+```bash
+morph-spec state list                  # List all features and their states
+morph-spec state get {feature}         # Get feature state
+morph-spec state set {feature} {key} {value}
+morph-spec state show {feature}        # Show phase + approval status
+morph-spec phase advance {feature}     # Advance to next phase
+morph-spec task done {feature}         # Mark current task complete
+morph-spec task start {feature}        # Start next task
+morph-spec task next {feature}         # Preview next task
+morph-spec status {feature}            # Feature status dashboard
+morph-spec diff {feature}              # Spec changes since last snapshot
+morph-spec rollback {feature}          # Rollback feature to previous phase
+```
+
+### Validation and standards
+
+```bash
+morph-spec validate                    # Run all validators
+morph-spec validate {validator}        # Run specific validator
+morph-spec standards --list            # List all 74 registered standards
+morph-spec standards --list --category {name}
+morph-spec standards --search {query}  # Search by name, tag, or ID
+morph-spec standards --show {id}       # Print standard content
+morph-spec standards --json            # Output as JSON
+```
+
+### Utilities
+
+```bash
+morph-spec cost {bicep-file}           # Estimate Azure resource costs
+morph-spec troubleshoot {keywords}     # Search known issues and solutions
+morph-spec state checkpoint {feature}  # Save state checkpoint
+```
+
+---
+
+## Agent hierarchy
+
+morph-spec includes 37 agents organized in 4 tiers. Tier 1-2 agents are installed as native Claude Code subagents in `.claude/agents/`. Tier 3 domain agents are installed as `.claude/agents/morph-domain-{name}.md`.
+
+### Tier 1 — Orchestrators (3)
+
+
+| Agent                 | Role                                                   | Active    |
+| --------------------- | ------------------------------------------------------ | --------- |
+| `standards-architect` | Chief Architect — enforces standards across all phases | Always    |
+| `ai-system-architect` | AI/Agent system design and orchestration               | On-demand |
+| `po-pm-advisor`       | Product and project advisory                           | On-demand |
+
+
+### Tier 2 — Domain Leaders (3)
+
+
+| Agent             | Squad                     | Active    |
+| ----------------- | ------------------------- | --------- |
+| `dotnet-senior`   | Backend squad lead        | Always    |
+| `azure-architect` | Infrastructure squad lead | Always    |
+| `ui-designer`     | UI/UX squad lead          | On-demand |
+
+
+### Tier 3 — Specialists (26)
+
+Organized into squads:
+
+**Backend (10):** C#/.NET specialists, EF Core, Dapper, SignalR, CQRS, Domain modeling, API design, Auth, Background services, Testing
+
+**Frontend (3):** Blazor components, Next.js/React, CSS/design system
+
+**Infrastructure (5):** Azure Bicep, CI/CD pipelines, Containerization, Monitoring, Cost optimization
+
+**Quality/Cross (8):** Security review, Performance, Accessibility, Documentation, Code review, Migration, Integration, Data modeling
+
+### Tier 4 — Validators (5)
+
+
+| Agent                          | Validates                               |
+| ------------------------------ | --------------------------------------- |
+| `security-expert`              | Security vulnerabilities and compliance |
+| `architecture-expert`          | Architectural decisions and constraints |
+| `packages-validator`           | Package versions and compatibility      |
+| `design-system-validator`      | Design system adherence                 |
+| `blazor-concurrency-validator` | Blazor thread safety and concurrency    |
+
+
+---
+
+## Hooks
+
+11 Claude Code hooks are installed into `.claude/settings.local.json` across 8 event types:
+
+
+| Event                | Hook                        | Purpose                                                  |
+| -------------------- | --------------------------- | -------------------------------------------------------- |
+| `SessionStart`       | `inject-morph-context.js`   | Injects active feature spec into context (3000 char max) |
+| `UserPromptSubmit`   | `protect-spec-files.js`     | Guards spec files at approval gates                      |
+| `PreToolUse`         | Bash guard (prompt type)    | Detects destructive patterns inline                      |
+| `PreToolUse`         | `validate-feature-phase.js` | Validates phase transitions                              |
+| `PostToolUse`        | `track-output-creation.js`  | Tracks feature output files as they are written          |
+| `PostToolUse`        | `checkpoint-trigger.js`     | Auto-checkpoints every 3 completed tasks                 |
+| `PostToolUseFailure` | `handle-tool-failure.js`    | Logs failures to `.morph/logs/tool-failures.log`         |
+| `Stop`               | `session-summary.js`        | Writes session summary on stop                           |
+| `PreCompact`         | `compact-context.js`        | Preserves critical context before compaction             |
+| `Notification`       | `morph-notify.js`           | Routes approval gate notifications                       |
+
+
+Protected files (via `permissions.deny`):
+
+- `.morph/state.json` — never edited directly, CLI only
+- `.morph/framework/`** — read-only framework content
+
+---
+
+## Rules
+
+Path-scoped rules are installed to `.claude/rules/` and activate automatically based on file patterns:
+
+
+| Rule file                     | Applies to                                               |
+| ----------------------------- | -------------------------------------------------------- |
+| `morph-workflow.md`           | Always active — spec-first mandate, phase commands       |
+| `csharp-standards.md`         | `**/*.cs`, `**/*.csproj`                                 |
+| `frontend-standards.md`       | `**/*.razor`, `**/*.tsx`, `**/*.ts`, `**/*.css`          |
+| `testing-standards.md`        | `tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/*Tests.cs` |
+| `infrastructure-standards.md` | `**/*.bicep`, `**/Dockerfile`, `**/pipelines/**`         |
+
+
+---
+
+## Stack support
+
+
+| Technology                                  | Support                                          |
+| ------------------------------------------- | ------------------------------------------------ |
+| .NET 10 / ASP.NET Core                      | Full — C# contracts, EF Core, CQRS, Minimal API  |
+| Blazor (WebAssembly / Server / MAUI Hybrid) | Full — components, concurrency, design system    |
+| Next.js / React / TypeScript                | Full — components, routing, state management     |
+| Azure (Bicep)                               | Full — IaC templates, cost estimation, pipelines |
+| GitHub Actions                              | Full — CI/CD workflow templates                  |
+| Supabase                                    | Supported via MCP integration                    |
+
+
+TypeScript strict mode is enforced by default. See `.morph/framework/standards/` for all coding standards.
+
+---
+
+## Update
+
+To update the framework files in an existing project:
+
+```bash
+morph-spec update
+```
+
+This re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md` with the installed package version. Your `.morph/config/config.json`, `.morph/context/`, and feature outputs are not touched.
+
+After updating, run `morph-spec doctor` to confirm the installation is healthy.
+
+---
+
+## Key rules
+
+**Never skip phases.** Every feature starts with a proposal. No code is written until the design is approved and a task list exists.
+
+**Never edit protected files directly:**
+
+- `.morph/state.json` — use `morph-spec state set`
+- `.morph/framework/`** — read-only, updated by `morph-spec update`
+
+**Always document decisions.** Each feature has a `1-design/decisions.md`. Architectural choices go there, not in commit messages.
+
+**Checkpoints every 3 tasks.** The framework auto-validates architecture compliance, package versions, and security after every third completed task.
+
+---
+
+## Troubleshooting
+
+### `morph-spec: command not found`
+
+If you are using nvm-windows or a Node version manager, the global bin path may not be on `PATH` in your shell. Use `npx` instead:
+
+```bash
+npx @polymorphism-tech/morph-spec init
+```
+
+Or add the npm global bin to your PATH:
+
+```bash
+npm config get prefix
+# Add {prefix}/bin to your PATH
+```
+
+### `morph-spec doctor` reports issues
+
+Run doctor to see all checks:
+
+```bash
+morph-spec doctor
+```
+
+Common fixes:
+
+- **Missing `.claude/agents/`** — run `morph-spec update` to reinstall agents
+- **Missing `.claude/rules/`** — run `morph-spec update` to reinstall rules
+- **State version mismatch** — state auto-migrates on next CLI command; if it fails, back up and re-init
+- **Hooks not firing** — confirm `.claude/settings.local.json` exists and contains the `hooks` key
+
+### EPERM on Windows global install
+
+Windows may block global npm installs without elevated permissions. Options:
+
+1. Run terminal as Administrator (not recommended long-term)
+2. Change npm global prefix to a user-writable directory:
+
+```bat
+mkdir %APPDATA%\npm-global
+npm config set prefix %APPDATA%\npm-global
+:: Add %APPDATA%\npm-global to your PATH
+npm install -g @polymorphism-tech/morph-spec
+```
+
+1. Use `npx` for all CLI invocations
+
+### Hook not triggering on SessionStart
+
+Ensure `.claude/settings.local.json` is not gitignored in your project. The file must be present for Claude Code to load hooks. If it is missing, re-run `morph-spec init --force`.
+
+---
+
+## Standards registry
+
+The framework ships 74 registered standards across 11 categories. Browse them:
+
+```bash
+morph-spec standards --list
+morph-spec standards --list --category csharp
+morph-spec standards --search "strict mode"
+morph-spec standards --show typescript-strict
+```
+
+Standards are stored in `.morph/framework/standards/STANDARDS.json` and sourced from `.morph/framework/standards/`.
+
+---
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE).
+
+Code generated by morph-spec (contracts, templates, implementation output) belongs to you.
+
+---
+
+*morph-spec v4.7.0 by [Polymorphism Tech](https://polymorphism.tech)*