@polymorphism-tech/morph-spec 3.0.0 → 3.1.0

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">MORPH-SPEC</h1>
 
 <p align="center">
-  <strong>Desenvolvimento orientado por especificações com agentes AI</strong><br>
+  <strong>Framework de desenvolvimento spec-driven com 30 agentes AI especializados</strong><br>
   <em>by Polymorphism Tech</em>
 </p>
 
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <strong>📚 Guias de Uso:</strong>
+  <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>
@@ -32,11 +32,12 @@
 
 **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.
+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/Blazor, .NET/Next.js
+**Stacks suportadas:** .NET 10/Blazor, .NET 10/Next.js
 **Infraestrutura:** Azure Bicep (IaC)
 **Ferramenta:** Claude Code
+**Validação:** Pipeline automático de enforcement com gates por fase
 
 ---
 
@@ -67,7 +68,7 @@ morph-spec init
 ```
 
 <details>
-<summary><strong>⚠️ Windows + nvm-windows: Comando não reconhecido?</strong></summary>
+<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).
 
@@ -129,9 +130,9 @@ 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
+- 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:
 ```
@@ -171,12 +172,12 @@ 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)
+- 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!
 
@@ -209,7 +210,7 @@ Revise os arquivos gerados e aprove (ou peça ajustes).
 /morph-apply minha-feature
 ```
 
-O MORPH implementa task por task, com testes a cada etapa.
+O MORPH implementa task por task, com validação automática a cada etapa.
 
 ### 5. Arquivar
 
@@ -225,74 +226,191 @@ Move a feature concluída para o arquivo.
 
 ```
 ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
-│  SETUP   │ ─▶ │  DESIGN  │ ─▶ │ CLARIFY  │ ─▶ │  TASKS   │ ─▶ │IMPLEMENT │
+│ PROPOSAL │ -> │  DESIGN  │ -> │ CLARIFY  │ -> │  TASKS   │ -> │IMPLEMENT │
 │          │    │          │    │          │    │          │    │          │
 │ Contexto │    │  Spec +  │    │  Q&A +   │    │  Quebra  │    │ Executa  │
-│ + Agents │    │Contracts │    │  Edges   │    │  Tasks   │    │ + Testa  │
+│ + Agents │    │Contracts │    │  Edges   │    │  Tasks   │    │ + Valida │
 └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
-                     ⛔                              ⛔
-                  Aprovação                       Aprovação
+                     |                               |              |
+                 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
+
 ---
 
-## Comandos Claude Code
+## 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 |
-| `/morph-apply <nome>` | Implementa feature aprovada |
+| `/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-costs` | Estima custos Azure |
+| `/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
 
-### Sempre Ativos
+MORPH-SPEC possui **30 agentes** organizados em 4 tiers hierárquicos com squads:
+
+### Tier 1 — Orchestrators (3)
 
-| Agente | Função |
-|--------|--------|
-| 📐 **Standards Architect** | Padrões de código e consistência |
-| ☁️ **Azure Architect** | Infraestrutura cloud e IaC |
-| 💰 **Cost Guardian** | Controle de custos |
+| 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 |
 
-### Por Stack
+### 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 |
 |--------|----------|
-| 🔥 **Blazor Builder** | blazor, razor, component |
-| ⚛️ **NextJS Expert** | nextjs, react, frontend |
+| **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>
 
-### Especialistas
+<details>
+<summary><strong>Frontend Squad (3)</strong></summary>
 
 | 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 |
+| **Blazor Builder** | blazor, razor, component, fluent ui |
+| **NextJS Expert** | nextjs, react, shadcn, server actions |
+| **CSS Specialist** | css, design system, theme, design tokens |
+</details>
 
-### Integrações
+<details>
+<summary><strong>Infrastructure Squad (5)</strong></summary>
 
 | Agente | Keywords |
 |--------|----------|
-| 💳 **Asaas Financial** | asaas, pix, boleto, payment |
-| 🔐 **Clerk Auth** | clerk, auth, login |
-| 🆔 **Azure Identity** | identity, entra, microsoft auth |
+| **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>
 
-### Infraestrutura
+<details>
+<summary><strong>Quality Squad (5)</strong></summary>
 
 | Agente | Keywords |
 |--------|----------|
-| 🏗️ **Bicep Architect** | bicep, iac, infra |
-| 🚀 **DevOps Engineer** | pipeline, ci/cd, deploy |
-| 📦 **Container Specialist** | docker, container |
+| **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) |
 
 ---
 
@@ -300,9 +418,9 @@ Move a feature concluída para o arquivo.
 
 | 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 |
+| [micro-saas](stacks/blazor-azure/.morph/examples/micro-saas/) | SaaS completo com Blazor + Asaas billing |
+| [api-nextjs](stacks/blazor-azure/.morph/examples/api-nextjs/) | .NET API + Next.js frontend |
+| [multi-agent](stacks/blazor-azure/.morph/examples/multi-agent/) | Sistema multi-agente com Microsoft Agent Framework |
 
 Cada exemplo inclui: `README.md`, `spec.md`, `contracts.cs`, `tasks.md`, `decisions.md`
 
@@ -318,11 +436,15 @@ seu-projeto/
 ├── .morph/
 │   ├── config/               # Configurações
 │   │   ├── config.json
-│   │   └── agents.json
-│   ├── standards/            # Padrões de código
+│   │   └── agents.json       # 30 agentes em 4 tiers
+│   ├── standards/            # Padrões de código (26 arquivos)
 │   │   ├── coding.md
 │   │   ├── architecture.md
-│   │   └── azure.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/
@@ -332,7 +454,7 @@ seu-projeto/
 │   └── archive/              # Features concluídas
 └── .claude/
     ├── commands/             # Slash commands
-    └── skills/               # Skills dos agentes
+    └── skills/               # Skills dos agentes (31+ arquivos)
 ```
 
 ---
@@ -365,7 +487,7 @@ O MORPH segue a filosofia **"Free tier first"**:
 
 ---
 
-## 🔧 Troubleshooting
+## Troubleshooting
 
 ### Comando `morph-spec` não encontrado
 
@@ -409,10 +531,10 @@ 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.)
+- 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)
@@ -465,12 +587,12 @@ 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)
+- Email: support@polymorphism.com.br
+- Issues: [GitHub](https://github.com/lucasPolymorphism/morph-spec-framework/issues)
 
 ---
 
-## 📄 Licença e Distribuição
+## Licença e Distribuição
 
 **Repositório:** Privado (código fonte protegido)
 **Package npm:** Público e gratuito via `@polymorphism-tech/morph-spec`
@@ -480,16 +602,16 @@ morph-spec <comando> --help  # Ajuda de comando específico
 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
+- 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
+- Redistribuir ou vender o framework
+- Criar produtos derivados competidores
+- Modificar ou fazer engenharia reversa do framework
+- Remover avisos de copyright
 
 ### Código Gerado
 
@@ -497,18 +619,18 @@ Todo código gerado usando MORPH-SPEC é **100% seu** para usar como quiser, inc
 
 ### 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)
+- 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)
+- [npm Package](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
+- [Documentação](docs/)
+- [Exemplos](stacks/blazor-azure/.morph/examples/)
+- [Polymorphism Tech](https://polymorphism.com.br)
 
 ---