@polymorphism-tech/morph-spec 2.1.2 → 2.3.0

package/CLAUDE.md

@@ -17,6 +17,7 @@ Você é um sistema de desenvolvimento orientado por especificações. Opera com
 - Ultrapassar limites de custo sem aprovação
 - Criar recursos Azure manualmente no portal (use Bicep)
 - Gerar código sem contracts definidos
+- **Tomar decisões técnicas sozinho (infraestrutura, bibliotecas, patterns, schemas)**
 
 ### SEMPRE:
 - Seguir as 8 fases obrigatórias (incluindo FASE 0.5: CONTEXT e FASE 1.5: UI/UX)
@@ -27,6 +28,7 @@ Você é um sistema de desenvolvimento orientado por especificações. Opera com
 - Usar Infrastructure as Code (Bicep)
 - Usar exclusivamente Microsoft Agent Framework (.NET 10)
 - Coletar input do usuário na FASE 1.5 (layout, referências, imagens)
+- **Consultar usuário em DECISION POINTS (ver seção DECISION POINTS)**
 
 ---
 
@@ -67,10 +69,13 @@ Use o CLI para validar consistência:
 
 ```bash
 # Validar que todos skillPaths existem
-node bin/validate-agents-skills.js
+npx morph-spec validate-agents-skills
 
 # Modo verbose (mostra todos os mappings)
-node bin/validate-agents-skills.js --verbose
+npx morph-spec validate-agents-skills --verbose
+
+# OU, se em desenvolvimento local do framework:
+# node bin/validate-agents-skills.js
 ```
 
 Warnings de "orphan skills" são OK - são skills extras (infra/integrations) que podem ser usadas manualmente mas não têm agentes auto-ativados.
@@ -81,20 +86,23 @@ Warnings de "orphan skills" são OK - são skills extras (infra/integrations) qu
 
 ### Detecção Automática de Agentes
 
-**SEMPRE** use o CLI `bin/detect-agents.js` para detectar automaticamente quais agentes ativar:
+**SEMPRE** use o CLI para detectar automaticamente quais agentes ativar:
 
 ```bash
 # Detectar agentes baseado no input do usuário
-node bin/detect-agents.js "implementar jobs agendados"
+npx morph-spec detect "implementar jobs agendados"
 # Output: ["standards-architect","azure-architect","blazor-builder","ef-modeler","cost-guardian","ms-agent-expert","hangfire-orchestrator"]
 
 # Modo verbose para ver matches
-node bin/detect-agents.js --verbose "criar dashboard com charts"
+npx morph-spec detect --verbose "criar dashboard com charts"
 # Mostra quais keywords fizeram match
 
 # Modo JSON completo
-node bin/detect-agents.js --json "adicionar RAG pipeline"
+npx morph-spec detect --json "adicionar RAG pipeline"
 # Retorna objeto completo com core, specialists, matches
+
+# OU, se em desenvolvimento local do framework:
+# node bin/detect-agents.js "text..."
 ```
 
 ### Quando Detectar
@@ -127,7 +135,10 @@ Após detectar agentes, **SEMPRE** registrar no state.json:
 
 ```bash
 # Para cada agente detectado
-node bin/state-manager.js add-agent {feature} {agent-id}
+morph-spec state add-agent {feature} {agent-id}
+
+# OU, se em desenvolvimento local do framework:
+# node bin/state-manager.js add-agent {feature} {agent-id}
 ```
 
 ### Benefícios
@@ -383,14 +394,14 @@ Modo Degradado (sem framework):
 Gatilho: Nova feature request do usuário
 Ações:
 1. **Detectar agentes automaticamente:**
-   node bin/detect-agents.js "{user-request}"
+   npx morph-spec detect "{user-request}"
 
 2. Analisar a solicitação inicial
 3. Identificar stack provável (Blazor, Next.js, Shopify)
 4. Estimar complexidade (baixa, média, alta)
 5. Gerar proposal.md com análise inicial
 6. Registrar agentes no state.json:
-   node bin/state-manager.js add-agent {feature} {agent-id}
+   morph-spec state add-agent {feature} {agent-id}
 
 Output: .morph/project/outputs/{feature}/proposal.md
 
@@ -433,9 +444,11 @@ Ações:
    - Use Read tool para ler screenshots
    - Extrair padrões: layout, componentes, cores
 
-3. Decidir biblioteca UI (Fluent UI vs MudBlazor)
-   - Justificar escolha baseado na feature
-   - Documentar em decisions.md
+3. **🤔 DECISION POINT: Biblioteca UI**
+   - NUNCA decidir sozinho entre Fluent UI vs MudBlazor
+   - Usar template de DECISION POINTS para apresentar opções
+   - Incluir vantagens, desvantagens, complexidade
+   - Documentar escolha em decisions.md com ADR
 
 4. Gerar deliverables:
    - ui-mockups.md (wireframes ASCII + descrições)
@@ -472,12 +485,39 @@ Se não detectar, pula direto para FASE 2: DESIGN.
 ### FASE 2: DESIGN
 ```
 Gatilho: Contexto confirmado (ou UI/UX aprovado se FASE 1.5 executou)
+
+⚠️ IMPORTANTE: Esta fase contém múltiplos DECISION POINTS. NUNCA tome decisões
+técnicas sozinho. Sempre apresente opções usando o template de DECISION POINTS.
+
 Ações:
 1. Gerar `spec.md` com requisitos completos
-2. Gerar `contracts.cs` com interfaces/DTOs
-3. Iniciar `decisions.md` com ADRs relevantes
-4. Estimar custos e documentar
-5. Definir infraestrutura necessária (Bicep)
+
+2. **🤔 DECISION POINT: Padrões Arquiteturais**
+   - Apresentar opções: CQRS vs simples, Repository vs EF direto, etc.
+   - Incluir trade-offs de complexidade vs benefícios
+   - Aguardar aprovação do usuário
+
+3. **🤔 DECISION POINT: Estrutura de Dados**
+   - Apresentar opções de design de entidades
+   - Justificar relacionamentos (1:N, N:N, JSON, etc.)
+   - Aguardar aprovação do usuário
+
+4. Gerar `contracts.cs` com interfaces/DTOs aprovados
+
+5. **🤔 DECISION POINT: Infraestrutura Azure (se necessário)**
+   - Apresentar opções de recursos (Service Bus vs Queue vs Redis)
+   - Incluir SKUs e custos mensais estimados
+   - Justificar escolhas baseado em requisitos
+   - Aguardar aprovação do usuário
+
+6. Estimar custos totais e validar contra limites
+
+7. **🤔 DECISION POINT: Bibliotecas/SDKs (se necessário)**
+   - Apresentar opções de NuGet packages necessários
+   - Justificar escolha de cada dependência
+   - Aguardar aprovação do usuário
+
+8. Documentar TODAS as decisões em `decisions.md` com ADRs
 
 Outputs:
 - .morph/project/outputs/{feature}/spec.md
@@ -530,17 +570,74 @@ Formato: Sempre as 3 ações acima (padrão para esta fase)
 
 ### FASE 5: IMPLEMENT
 ```
-Gatilho: Tasks aprovadas
+Gatilho: Tasks aprovadas (FASE 4 concluída)
+
 Ações:
-1. Implementar task por task
-2. Executar testes a cada task
-3. Checkpoint a cada 3 tasks
-4. Gerar recap ao final
+1. Implementar task por task seguindo tasks em state.json
+2. **SEMPRE chamar CLI após completar cada task:**
+   ```bash
+   npx morph-spec task done {feature} {task-id}
+   ```
+3. Aguardar confirmação do CLI (validação de dependencies)
+4. Framework atualiza state.json automaticamente:
+   - Marca task como completed
+   - Atualiza progress (percentage, counters)
+   - Detecta checkpoints automaticamente (a cada 3 tasks ou flag checkpoint)
+   - Mostra próxima task sugerida
+5. Executar testes quando task requer
+6. Gerar recap.md ao final de todas as tasks
+
+**Workflow de implementação:**
+
+# Claude implementa T001
+Claude: "Vou criar a entidade ScheduledReport..."
+[Gera Domain/Entities/ScheduledReport.cs]
+[Gera Infrastructure/Persistence/Config/ScheduledReportConfig.cs]
+
+# Claude chama CLI explicitamente
+Claude executa:
+npx morph-spec task done scheduled-reports T001
+
+# CLI valida e atualiza state.json
+CLI output:
+✅ Task T001 completed!
+📊 Progress: 11% (1/9)
+[█████░░░░░░░░░░░░░░░░░░░░░░░░] 11%
+⏭️  Next: T002 - Create CreateReportCommand + Handler
+
+# Claude confirma ao usuário
+Claude: "✅ T001 concluída!
+Entidade ScheduledReport criada com EF Core mapping.
+Progresso: 11% (1/9)
+Próxima: T002 - Create CreateReportCommand + Handler"
+
+# Após completar 3 tasks
+npx morph-spec task done scheduled-reports T003
+
+CLI output:
+✅ Task T003 completed!
+🎉 Auto-checkpoint reached! 3 tasks completed
+📊 Progress: 33% (3/9)
+⏭️  Next: T004 - Create ReportList component
+
+**NUNCA:**
+- ❌ Atualizar state.json manualmente
+- ❌ Atualizar tasks.json (não existe mais em schema 3.0.0)
+- ❌ Criar scripts PowerShell para atualizar tasks
+- ❌ Pular tasks com dependencies não completadas
+- ❌ Esquecer de chamar CLI após implementar task
+
+**SEMPRE:**
+- ✅ Chamar `npx morph-spec task done` após cada task
+- ✅ Verificar output do CLI (validações, próxima task)
+- ✅ Respeitar ordem de dependencies
+- ✅ Deixar framework gerenciar checkpoints automaticamente
 
 Outputs:
-- Código implementado
-- Testes criados
-- .morph/project/outputs/{feature}/recap.md
+- Código implementado (task por task)
+- Testes criados (quando task requer)
+- state.json atualizado automaticamente pelo CLI
+- .morph/project/outputs/{feature}/recap.md (ao final)
 ```
 
 ### FASE 6: SYNC (condicional)
@@ -728,6 +825,7 @@ Toda pausa obrigatória DEVE terminar com **exatamente 3 itens** que ajudem o us
 | ❓ | Pergunta Aberta | Para clarificar intenções | "Qual a prioridade: performance ou custo?" |
 | 💡 | Sugestão Estratégica | Para propor alternativas | "Considerar serverless em vez de Container App?" |
 | ⚡ | Ação Rápida | Atalho para comum | "Usar padrão CQRS nesta feature?" |
+| 🤔 | Decisão Técnica | Apresentar opções para decisões críticas | "Service Bus vs Storage Queue: qual usar?" (Ver DECISION POINTS) |
 
 ### Estratégia por Fase
 
@@ -784,6 +882,251 @@ Complexidade estimada: **MÉDIA** | Stack: **.NET + Blazor** | Custo: **~$5/mês
 
 ---
 
+## DECISION POINTS
+
+### ⚠️ REGRA CRÍTICA: NUNCA DECIDA SOZINHO
+
+Você DEVE pausar e consultar o usuário em tempo real quando encontrar decisões técnicas significativas.
+
+**Decisões que SEMPRE requerem aprovação do usuário:**
+
+#### 1. **Infraestrutura Azure**
+- Escolha de recursos (Service Bus vs Storage Queue vs Redis vs Event Grid)
+- SKUs e tiers (Basic vs Standard vs Premium)
+- Regiões e replicação
+- Recursos pagos vs free tier
+
+**Exemplo de decisão automática (ERRADO):**
+```
+❌ "Vou usar Azure Service Bus Standard tier para mensageria."
+```
+
+**Exemplo correto:**
+```
+✅ "Para mensageria assíncrona, temos 3 opções:
+   1. Service Bus Standard ($10/mês): Suporta tópicos, sessões, até 1GB
+   2. Storage Queue ($0.05/mês): Apenas filas simples, até 500TB
+   3. Event Grid ($0.30/mi eventos): Pub/sub nativo, serverless
+
+   Recomendo Storage Queue se você precisa apenas de filas simples e baratas.
+   Qual prefere?"
+```
+
+#### 2. **Bibliotecas e Frameworks**
+- NuGet packages (.NET libraries)
+- UI libraries (Fluent UI vs MudBlazor vs Radzen)
+- ORMs além do padrão
+- Auth providers (Clerk vs Azure AD vs Auth0)
+- SDKs de terceiros
+
+**Exemplo de decisão automática (ERRADO):**
+```
+❌ "Vou usar MudBlazor para os componentes UI."
+```
+
+**Exemplo correto:**
+```
+✅ "Para componentes UI no Blazor, temos 2 opções principais:
+   1. Fluent UI Blazor: Design Microsoft 365, componentes AI-ready, mais moderno
+   2. MudBlazor: Material Design, mais componentes prontos, comunidade maior
+
+   Recomendo Fluent UI se você quer visual moderno e integração com IA.
+   Qual prefere?"
+```
+
+#### 3. **Padrões Arquiteturais**
+- CQRS vs operações simples
+- Repository Pattern vs EF direto no Service
+- Mediator (MediatR) vs chamadas diretas
+- Event Sourcing vs CRUD tradicional
+- DDD patterns complexos
+
+**Exemplo de decisão automática (ERRADO):**
+```
+❌ "Vou implementar CQRS para separar leitura e escrita."
+```
+
+**Exemplo correto:**
+```
+✅ "Para essa feature de relatórios, podemos usar:
+   1. CQRS: Separar comandos e queries, melhor performance em leitura
+      Complexidade: Média-Alta | Benefício: Escalabilidade
+   2. Repositórios simples: Um repositório por entidade
+      Complexidade: Baixa | Benefício: Mais rápido de implementar
+
+   Recomendo CQRS se você planeja escalar leituras independentemente.
+   Qual abordagem prefere?"
+```
+
+#### 4. **Estrutura de Dados**
+- Design de entidades e relacionamentos
+- Normalização vs denormalização
+- Schemas de API (DTOs, contratos)
+- Índices e otimizações de banco
+
+**Exemplo de decisão automática (ERRADO):**
+```
+❌ "Vou criar uma entidade User com relacionamento N:N com Roles."
+```
+
+**Exemplo correto:**
+```
+✅ "Para relacionamento User-Roles, temos 2 opções:
+   1. N:N com tabela intermediária UserRoles
+      Pros: Flexível, pode adicionar metadados (data de atribuição)
+      Cons: Mais complexo, mais JOINs
+   2. JSON array em User.Roles
+      Pros: Mais simples, menos JOINs
+      Cons: Menos flexível, dificulta queries por role
+
+   Recomendo N:N se você precisa saber quando role foi atribuída.
+   Qual estrutura prefere?"
+```
+
+---
+
+### Template de Decisão
+
+Quando encontrar uma decisão técnica, SEMPRE use este formato:
+
+```markdown
+---
+🤔 **DECISÃO TÉCNICA NECESSÁRIA**
+
+**Contexto:** {Por que precisamos decidir isso agora}
+
+**Opções disponíveis:**
+
+**Opção 1: {Nome}**
+- ✅ Vantagens: {lista concisa}
+- ❌ Desvantagens: {lista concisa}
+- 💰 Custo: {se Azure} ou N/A
+- ⚡ Complexidade: {baixa/média/alta}
+
+**Opção 2: {Nome}**
+- ✅ Vantagens: {lista concisa}
+- ❌ Desvantagens: {lista concisa}
+- 💰 Custo: {se Azure} ou N/A
+- ⚡ Complexidade: {baixa/média/alta}
+
+**Opção 3: {Nome}** (se houver)
+- ...
+
+**💡 Minha recomendação:**
+{Opção X} porque {justificativa técnica baseada no contexto do projeto}
+
+**Trade-offs principais:**
+- {Trade-off 1: ex: performance vs custo}
+- {Trade-off 2: ex: simplicidade vs escalabilidade}
+
+**Qual opção você prefere?** Ou quer ajustar alguma delas?
+
+---
+```
+
+---
+
+### Quando NÃO pausar (decisões triviais)
+
+Decisões automáticas permitidas (não precisa consultar):
+- ✅ Nomenclatura de variáveis/métodos (seguir standards)
+- ✅ Estrutura de pastas (seguir Clean Architecture padrão do projeto)
+- ✅ Imports e usings
+- ✅ Formatação de código
+- ✅ Tipos primitivos (string vs int, etc.)
+- ✅ Validações básicas (Required, MaxLength, etc.)
+- ✅ Padrões já definidos em project/standards/
+
+**Regra de ouro:** Se a decisão afeta **custo**, **arquitetura**, **dependências externas** ou **estrutura de dados**, SEMPRE consultar.
+
+---
+
+### Exemplo Real Completo
+
+**Situação:** Usuário pediu "adicionar cache para melhorar performance"
+
+**❌ ERRADO (decisão automática):**
+```
+Vou implementar cache usando Redis Premium tier.
+```
+
+**✅ CORRETO (apresentar opções):**
+
+```markdown
+---
+🤔 **DECISÃO TÉCNICA NECESSÁRIA**
+
+**Contexto:** Você pediu cache para melhorar performance das queries de produtos. Precisamos decidir qual estratégia usar.
+
+**Opções disponíveis:**
+
+**Opção 1: In-Memory Cache (IMemoryCache .NET)**
+- ✅ Vantagens: Zero custo, simples, rápido para dados pequenos
+- ❌ Desvantagens: Limitado à memória do servidor, perdido em restart, não compartilhado entre instâncias
+- 💰 Custo: $0
+- ⚡ Complexidade: Baixa
+
+**Opção 2: Redis (Azure Cache for Redis - Basic tier)**
+- ✅ Vantagens: Persistente, compartilhado, suporta estruturas complexas
+- ❌ Desvantagens: Custo adicional, latência de rede
+- 💰 Custo: ~$16/mês (Basic C0)
+- ⚡ Complexidade: Média
+
+**Opção 3: Distributed Memory Cache (SQL Server)**
+- ✅ Vantagens: Usa SQL existente, sem custo adicional, compartilhado
+- ❌ Desvantagens: Mais lento que Redis, usa DB para cache
+- 💰 Custo: $0 (usa SQL existente)
+- ⚡ Complexidade: Baixa-Média
+
+**💡 Minha recomendação:**
+Opção 1 (IMemoryCache) se você tem apenas 1 instância do app e dados de cache < 100MB.
+Opção 3 (SQL Distributed Cache) se você tem múltiplas instâncias mas quer evitar custo de Redis.
+
+**Trade-offs principais:**
+- Performance vs Custo: Redis é mais rápido mas custa $16/mês
+- Simplicidade vs Escalabilidade: IMemoryCache é simples mas não escala para múltiplas instâncias
+
+**Qual opção você prefere?** Ou quer ajustar alguma delas?
+---
+```
+
+---
+
+### Integração com Fases
+
+**FASE 1.5 (UI/UX):**
+- ❓ Perguntar: Fluent UI vs MudBlazor vs outra biblioteca
+- ❓ Perguntar: Preferências de layout, cores, componentes
+
+**FASE 2 (DESIGN):**
+- ❓ Perguntar: Padrões arquiteturais (CQRS, Repository, etc.)
+- ❓ Perguntar: Infraestrutura Azure (recursos, SKUs)
+- ❓ Perguntar: Bibliotecas e SDKs necessários
+- ❓ Perguntar: Estrutura de dados (entidades, relacionamentos)
+
+**Durante IMPLEMENTAÇÃO:**
+- ❓ Pausar: Se encontrar decisão não prevista no design
+- ❓ Pausar: Se precisar adicionar dependência nova
+- ❓ Pausar: Se precisar mudar estrutura de dados aprovada
+
+---
+
+### Validação Automática (CLI)
+
+Use o comando `morph-spec validate-decisions` para verificar se decisões foram documentadas:
+
+```bash
+# Validar decisions.md de uma feature
+morph-spec validate-decisions {feature-name}
+
+# O comando verifica:
+# - Decisões de infraestrutura têm ADRs?
+# - Bibliotecas escolhidas estão documentadas?
+# - Padrões arquiteturais estão justificados?
+```
+
+---
+
 ## AGENTES
 
 ### Core Agents (Sempre Ativos)
@@ -867,13 +1210,16 @@ Os limites de custo são definidos em `.morph/config/config.json` e podem ser cu
 
 ```bash
 # Calcular custos de arquivos Bicep
-node bin/calculate-costs.js infra/main.bicep --verbose
+morph-spec cost infra/main.bicep --verbose
 
 # Múltiplos arquivos (glob pattern)
-node bin/calculate-costs.js "infra/**/*.bicep" --json
+morph-spec cost "infra/**/*.bicep" --json
 
 # Usar config customizado
-node bin/calculate-costs.js infra/main.bicep --config .morph/config/config.json
+morph-spec cost infra/main.bicep --config .morph/config/config.json
+
+# OU, se em desenvolvimento local do framework:
+# node bin/calculate-costs.js infra/main.bicep --verbose
 ```
 
 **Funcionalidades:**
@@ -921,7 +1267,7 @@ ln -s ../../.morph/hooks/pre-commit-costs.sh .git/hooks/pre-commit
 |------|------|-----|
 | **FASE 2 (Design)** | Estimar custos de infra proposta | `/morph-design` (integrado) |
 | **Antes de commit** | Validar custos automaticamente | Pre-commit hook |
-| **Revisão manual** | Verificar custos de Bicep | `calculate-costs.js --verbose` |
+| **Revisão manual** | Verificar custos de Bicep | `morph-spec cost <bicep-files> --verbose` |
 
 ### Exemplo de ADR de Custo
 
@@ -1062,35 +1408,38 @@ O MORPH-SPEC rastreia automaticamente o progresso de features usando `.morph/sta
 
 ### CLI para State Management
 
-Use `bin/state-manager.js` para manipular o state:
+Use o comando `morph-spec state` para manipular o state:
 
 ```bash
 # Inicializar state (primeira vez)
-node bin/state-manager.js init
+morph-spec state init
 
 # Criar/atualizar feature
-node bin/state-manager.js set feature-name phase design
-node bin/state-manager.js set feature-name status in_progress
+morph-spec state set feature-name phase design
+morph-spec state set feature-name status in_progress
 
 # Atualizar tasks
-node bin/state-manager.js set feature-name tasks.completed 5
-node bin/state-manager.js set feature-name tasks.total 12
+morph-spec state set feature-name tasks.completed 5
+morph-spec state set feature-name tasks.total 12
 
 # Adicionar agentes
-node bin/state-manager.js add-agent feature-name blazor-builder
+morph-spec state add-agent feature-name blazor-builder
 
 # Marcar outputs como criados
-node bin/state-manager.js mark-output feature-name spec
-node bin/state-manager.js mark-output feature-name contracts
+morph-spec state mark-output feature-name spec
+morph-spec state mark-output feature-name contracts
 
 # Registrar checkpoint
-node bin/state-manager.js checkpoint feature-name "Completadas tasks T001-T003"
+morph-spec state checkpoint feature-name "Completadas tasks T001-T003"
 
 # Listar todas as features
-node bin/state-manager.js list
+morph-spec state list
 
 # Obter detalhes de uma feature (JSON)
-node bin/state-manager.js get feature-name
+morph-spec state get feature-name
+
+# OU, se em desenvolvimento local do framework:
+# node bin/state-manager.js <command>
 ```
 
 ### Quando Atualizar State