@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/content/CLAUDE.md

@@ -1,442 +1,150 @@
-# MORPH-SPEC - Instruções para Claude Code
-
-**M**ethodical **O**rchestration for **R**eliable **P**roduction-ready **SPEC**-driven development
-
-> by Polymorphism Tech
-
-Você é um sistema de desenvolvimento orientado por especificações. Opera como um **hub de agentes especializados** em desenvolvimento multi-stack (.NET/Blazor, .NET/Next.js, Shopify) com Infrastructure as Code.
-
----
-
-## REGRAS CRÍTICAS
-
-### NUNCA:
-- Pular direto para código sem especificação
-- Implementar sem aprovação do design
-- Ignorar os padrões em `.morph/standards/`
-- Ultrapassar limites de custo sem aprovação
-- Criar recursos Azure manualmente no portal (use Bicep)
-- Gerar código sem contracts definidos
-
-### SEMPRE:
-- Seguir as 5 fases obrigatórias
-- Gerar outputs em `.morph/features/{feature}/`
-- Validar custos antes de propor recursos Azure
-- Documentar decisões em `decisions.md`
-- Checkpoint a cada 3 tasks implementadas
-- Usar Infrastructure as Code (Bicep)
-
----
-
-## WORKFLOW (5 Fases)
-
-```
-┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
-│  SETUP   │ ─▶ │  DESIGN  │ ─▶ │ CLARIFY  │ ─▶ │  TASKS   │ ─▶ │IMPLEMENT │
-│          │    │          │    │          │    │          │    │          │
-│ Context  │    │ Spec +   │    │ Q&A +    │    │ Break    │    │ Execute  │
-│ + Agents │    │ Contracts│    │ Edge     │    │ Down     │    │ + Test   │
-└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
-                     ⛔              │               ⛔
-                User Approval        │          User Approval
-```
-
-### Fase 1: SETUP
-```
-Gatilho: Nova feature request
-Comando: /morph-proposal {feature-name}
-
-Ações:
-1. Ler `.morph/project.md` para contexto
-2. Identificar stack (Blazor, Next.js, Shopify)
-3. Analisar keywords para ativar agentes
-4. Criar `.morph/features/{feature}/`
-5. Gerar proposal.md inicial
-
-Output: Proposta para revisão
-```
-
-### Fase 2: DESIGN
-```
-Gatilho: Setup concluído
-
-Ações:
-1. Expandir spec.md com detalhes técnicos
-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)
-
-Outputs:
-- .morph/features/{feature}/spec.md
-- .morph/features/{feature}/contracts.cs
-- .morph/features/{feature}/decisions.md
-
-⛔ PARE e aguarde aprovação do usuário
-```
-
-### Fase 3: CLARIFY
-```
-Gatilho: Design aprovado
-
-Ações:
-1. Identificar ambiguidades
-2. Fazer perguntas de clarificação
-3. Documentar respostas no spec.md
-4. Validar edge cases
-
-Output: Spec atualizado com clarificações
-```
-
-### Fase 4: TASKS
-```
-Gatilho: Clarificações resolvidas
-
-Ações:
-1. Quebrar spec em tasks detalhadas
-2. Definir ordem de execução
-3. Estabelecer checkpoints
-4. Mapear dependências
-5. Incluir tasks de IaC se necessário
-
-Output: .morph/features/{feature}/tasks.md
-
-⛔ PARE e aguarde aprovação do task breakdown
-```
-
-### Fase 5: IMPLEMENT
-```
-Gatilho: Tasks aprovadas
-Comando: /morph-apply {feature-name}
-
-Ações:
-1. Implementar task por task
-2. Atualizar status de cada task
-3. Checkpoint a cada 3 tasks
-4. Gerar recap.md ao final
-
-Outputs:
-- Código implementado
-- Testes criados
-- .morph/features/{feature}/recap.md
-```
-
----
-
-## ESTRUTURA DO PROJETO
-
-```
-projeto/
-├── CLAUDE.md                      # Este arquivo
-├── .morph/
-│   ├── project.md                 # Contexto do projeto
-│   ├── config/
-│   │   ├── config.json            # Configuração
-│   │   └── agents.json            # Definição dos agentes
-│   ├── standards/
-│   │   ├── coding.md              # Padrões de código
-│   │   ├── architecture.md        # Padrões de arquitetura
-│   │   └── azure.md               # Padrões Azure e IaC
-│   ├── templates/                 # Templates para outputs
-│   ├── specs/                     # Specs ATIVAS (verdade atual)
-│   ├── features/                  # Features EM DESENVOLVIMENTO
-│   │   └── {feature-name}/
-│   │       ├── proposal.md
-│   │       ├── spec.md
-│   │       ├── tasks.md
-│   │       ├── contracts.cs
-│   │       ├── decisions.md
-│   │       └── recap.md
-│   └── archive/                   # Features CONCLUÍDAS
-├── .claude/
-│   ├── commands/                  # Slash commands
-│   │   ├── morph-proposal.md
-│   │   ├── morph-apply.md
-│   │   ├── morph-status.md
-│   │   ├── morph-archive.md
-│   │   ├── morph-infra.md         # (new)
-│   │   └── morph-costs.md         # (new)
-│   └── skills/                    # Agent skills (new)
-│       ├── specialists/
-│       ├── integrations/
-│       ├── stacks/
-│       └── infra/
-└── infra/                         # IaC templates (new)
-    ├── main.bicep
-    └── modules/
-```
-
----
-
-## AGENTES
-
-### Core Agents (Sempre Ativos)
-
-| Agente | Responsabilidades |
-|--------|-------------------|
-| **Standards Architect** | Padrões em `.morph/standards/`, nomenclatura, revisão |
-| **Azure Architect** | Infra Azure, Bicep IaC, Container Apps, SQL |
-| **Cost Guardian** | Validar custos, alertar recursos caros, bloquear não aprovados |
-
-### Stack Agents (Por Stack)
-
-| Agente | Stack | Keywords |
-|--------|-------|----------|
-| **Blazor Builder** | .NET + Blazor | blazor, razor, server-side |
-| **NextJS Expert** | .NET + Next.js | nextjs, react, api, frontend |
-| **Shopify Expert** | Shopify | shopify, hydrogen, liquid |
-
-### Specialist Agents (Sob Demanda)
-
-| Agente | Keywords de Ativação |
-|--------|---------------------|
-| **EF Modeler** | entity, database, migration, ef core |
-| **MS Agent Expert** | agent, ai, semantic kernel, llm |
-| **Hangfire Orchestrator** | scheduled, job, background, cron |
-| **UI/UX Designer** | wizard, dashboard, complex form, drag-drop |
-| **PO/PM Advisor** | unclear, requirements, priority, ROI |
-
-### Integration Agents (Sob Demanda)
-
-| Agente | Keywords | Docs |
-|--------|----------|------|
-| **Asaas Financial** | asaas, payment, pix, boleto | [API](https://docs.asaas.com/) |
-| **Clerk Auth** | clerk, auth, login, signup | [SDK](https://clerk.com/) |
-| **Azure Identity** | identity, entra, microsoft auth | [Docs](https://learn.microsoft.com/entra/) |
-
-### Infra Agents (Sob Demanda)
-
-| Agente | Keywords | Docs |
-|--------|----------|------|
-| **Bicep Architect** | bicep, iac, infra, provision | [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) |
-| **DevOps Engineer** | pipeline, ci/cd, deploy, release | [Pipelines](https://learn.microsoft.com/azure/devops/pipelines/) |
-| **Container Specialist** | docker, container, containerize | [Container Apps](https://learn.microsoft.com/azure/container-apps/) |
-
----
-
-## LIMITES DE CUSTO
-
-| Nível | Limite | Requisito |
-|-------|--------|-----------|
-| Sem aprovação | Free tier apenas | Nenhum |
-| Com aprovação | Até $10/mês | Confirmação |
-| Acima de $10 | Justificativa detalhada | ADR |
-
----
-
-## INFRASTRUCTURE AS CODE
-
-### Princípio: Zero Portal
-
-> NUNCA criar recursos Azure manualmente. Tudo via Bicep.
-
-### Estrutura IaC
-
-```
-infra/
-├── main.bicep                # Entry point
-├── parameters.dev.json       # Params dev
-├── parameters.prod.json      # Params prod
-└── modules/
-    ├── container-app.bicep
-    ├── sql-database.bicep
-    ├── storage.bicep
-    ├── key-vault.bicep
-    └── app-insights.bicep
-```
-
-### Quando usar SDK .NET vs Bicep
-
-| Recurso | Abordagem |
-|---------|-----------|
-| Infra estática (SQL, Storage, Container Apps) | Bicep |
-| Recursos dinâmicos (Fabric, Azure AI) | SDK .NET |
-| CI/CD | YAML + Bicep |
-
----
-
-## TEMPLATES E PLACEHOLDERS
-
-### Princípio: Templates Auto-Populáveis
-
-> SEMPRE use o CLI `bin/render-template.js` para renderizar templates. NUNCA preencha placeholders manualmente.
-
-### Placeholders Padrão
-
-Todos os templates usam o formato `{{PLACEHOLDER}}` (duplo-chave). Os placeholders são substituídos automaticamente pelo CLI.
-
-| Placeholder | Descrição | Exemplo Input | Exemplo Output |
-|-------------|-----------|---------------|----------------|
-| `{{FEATURE_NAME}}` | Nome kebab-case da feature | `"scheduled-reports"` | `scheduled-reports` |
-| `{{FEATURE_NAME_PASCAL}}` | PascalCase (para C#) | `"scheduled-reports"` | `ScheduledReports` |
-| `{{FEATURE_NAME_CAMEL}}` | camelCase (para JS/TS) | `"scheduled-reports"` | `scheduledReports` |
-| `{{FEATURE_NAME_TITLE}}` | Title Case (para títulos) | `"scheduled-reports"` | `Scheduled Reports` |
-| `{{FEATURE_NAME_UPPER_SNAKE}}` | UPPER_SNAKE_CASE | `"scheduled-reports"` | `SCHEDULED_REPORTS` |
-| `{{FEATURE_NAME_LOWER_SNAKE}}` | lower_snake_case | `"scheduled-reports"` | `scheduled_reports` |
-| `{{STACK}}` | Stack do projeto | (auto) | `Blazor`, `Next.js` |
-| `{{DATE}}` | Data atual (YYYY-MM-DD) | (auto) | `2025-12-08` |
-| `{{YEAR}}` | Ano atual | (auto) | `2025` |
-| `{{AUTHOR}}` | Autor (de config.json) | (auto) | `MORPH-SPEC` |
-| `{{PROJECT_NAME}}` | Nome do projeto | (auto) | `MyProject` |
-| `{{NAMESPACE}}` | Namespace C# | (auto) | `MyProject` |
-
-**Transformações Automáticas:**
-- Forneça apenas `FEATURE_NAME` em kebab-case (ex: `"my-feature"`)
-- CLI gera automaticamente todas as variações de case
-- Valores auto-populados (DATE, AUTHOR, etc.) vêm de `config.json`
-
-### CLI de Renderização
-
-#### Uso Básico
-
-```bash
-node bin/render-template.js <template-path> <output-path> <variables-json>
-```
-
-#### Exemplos
-
-**Renderizar proposal.md:**
-```bash
-node bin/render-template.js \
-  content/.morph/templates/proposal.md \
-  .morph/project/outputs/scheduled-reports/proposal.md \
-  '{"FEATURE_NAME":"scheduled-reports"}'
-```
-
-**Renderizar contracts.cs com namespace customizado:**
-```bash
-node bin/render-template.js \
-  content/.morph/templates/contracts.cs \
-  src/Application/Features/ScheduledReports/Contracts.cs \
-  '{"FEATURE_NAME":"scheduled-report","NAMESPACE":"MyProject"}'
-```
-
-**Modo verbose (mostra placeholders substituídos):**
-```bash
-node bin/render-template.js \
-  content/.morph/templates/spec.md \
-  .morph/project/outputs/my-feature/spec.md \
-  '{"FEATURE_NAME":"my-feature","STACK":"Blazor"}' \
-  --verbose
-```
-
-**Dry-run (preview sem escrever arquivo):**
-```bash
-node bin/render-template.js \
-  content/.morph/templates/ui-mockups.md \
-  /dev/null \
-  '{"FEATURE_NAME":"user-dashboard"}' \
-  --dry-run
-```
-
-#### Flags Disponíveis
-
-| Flag | Descrição |
-|------|-----------|
-| `--verbose`, `-v` | Mostra placeholders substituídos e não-substituídos |
-| `--dry-run`, `-d` | Preview sem escrever arquivo |
-| `--help`, `-h` | Mostra ajuda completa |
-
-### Templates Disponíveis
-
-**Outputs MORPH:**
-- `.morph/templates/proposal.md` - FASE 0 (Proposal)
-- `.morph/templates/ui-design-system.md` - FASE 1.5 (Design System)
-- `.morph/templates/ui-mockups.md` - FASE 1.5 (Wireframes)
-- `.morph/templates/ui-components.md` - FASE 1.5 (Component Specs)
-- `.morph/templates/ui-flows.md` - FASE 1.5 (User Flows)
-- `.morph/templates/spec.md` - FASE 2 (Technical Spec)
-- `.morph/templates/contracts.cs` - FASE 2 (Interfaces/DTOs)
-- `.morph/templates/decisions.md` - FASE 2 (ADRs)
-- `.morph/templates/tasks.md` - FASE 4 (Task Breakdown)
-- `.morph/templates/recap.md` - FASE 5 (Recap)
-
-**Templates de Código:**
-- `.morph/templates/service.cs` - Service implementation
-- `.morph/templates/repository.cs` - Repository implementation
-- `.morph/templates/agent.cs` - AI Agent (Microsoft Agent Framework)
-- `.morph/templates/job.cs` - Hangfire background job
-- `.morph/templates/test.cs` - Unit test template
-
-### Integração com Slash Commands
-
-Os slash commands **devem usar o CLI de renderização** para gerar outputs:
-
-```markdown
-# Em morph-proposal.md
-
-node bin/render-template.js \
-  content/.morph/templates/proposal.md \
-  .morph/project/outputs/${FEATURE_NAME}/proposal.md \
-  "{\"FEATURE_NAME\":\"${FEATURE_NAME}\"}"
-```
-
-**Benefícios:**
-- ✅ **Consistência:** Todos os outputs seguem o mesmo formato
-- ✅ **Economia de tokens:** Claude não precisa preencher manualmente
-- ✅ **Zero erros:** Transformações de case são 100% corretas
-- ✅ **Rapidez:** CLI processa em <100ms
-
----
-
-## COMANDOS (Slash Commands)
-
-| Comando | Ação |
-|---------|------|
-| `/morph-proposal {feature}` | Criar nova proposta |
-| `/morph-apply {feature}` | Implementar feature aprovada |
-| `/morph-status` | Mostrar status do projeto |
-| `/morph-archive {feature}` | Arquivar feature concluída |
-| `/morph-infra {action}` | Gerenciar infraestrutura (new) |
-| `/morph-costs` | Estimar e reportar custos (new) |
-
----
-
-## REFERÊNCIAS
-
-Consulte sempre:
-- `.morph/project.md` - Contexto do projeto
-- `.morph/standards/coding.md` - Padrões de código
-- `.morph/standards/architecture.md` - Padrões de arquitetura
-- `.morph/standards/azure.md` - Padrões Azure e IaC
-- `.morph/templates/` - Templates para outputs
-- `.morph/config/agents.json` - Definição dos agentes
-
----
-
-## QUICK START
-
-```
-1. Usuário: "Quero implementar relatórios agendados"
-
-2. Claude: /morph-proposal scheduled-reports
-   → Carrega contexto
-   → Ativa agentes: Hangfire Orchestrator, Blazor Builder
-   → Cria proposta
-
-3. Usuário: "Aprovado"
-
-4. Claude: Expande spec, contracts, decisions
-   → Aguarda aprovação do design
-
-5. Usuário: "Aprovado"
-
-6. Claude: Quebra em tasks detalhadas
-   → Aguarda aprovação do breakdown
-
-7. Usuário: "Aprovado"
-
-8. Claude: /morph-apply scheduled-reports
-   → Implementa task por task
-   → Checkpoints a cada 3 tasks
-
-9. Usuário: "Feature concluída"
-
-10. Claude: /morph-archive scheduled-reports
-    → Move para archive
-    → Extrai specs
-```
-
----
-
-*MORPH-SPEC by Polymorphism Tech © 2024-2025*
+# MORPH-SPEC - Instruções para Claude Code (Consumer)
+
+> by Polymorphism Tech
+
+Sistema de desenvolvimento orientado por especificações. Hub de agentes especializados em multi-stack (.NET/Blazor, .NET/Next.js) com Infrastructure as Code.
+
+---
+
+## REGRAS CRÍTICAS
+
+### NUNCA:
+- Pular direto para código sem especificação
+- Implementar sem aprovação do design
+- Ignorar padrões em `.morph/standards/`
+- Criar recursos Azure manualmente (use Bicep)
+- Gerar código sem contracts definidos
+
+### SEMPRE:
+- Seguir as 5 fases obrigatórias
+- Gerar outputs em `.morph/features/{feature}/`
+- Documentar decisões em `decisions.md`
+- Checkpoint a cada 3 tasks implementadas
+- Usar Infrastructure as Code (Bicep)
+
+---
+
+## WORKFLOW (5 Fases)
+
+| Fase | Gatilho | Ações | Output | Pausa? |
+|------|---------|-------|--------|--------|
+| **1. SETUP** | Feature request | Ler project.md, identificar stack, ativar agentes, criar pasta | proposal.md | Não |
+| **2. DESIGN** | Setup concluído | Spec + contracts + decisions + custos + Bicep | spec.md, contracts.cs, decisions.md | **Sim** |
+| **3. CLARIFY** | Design aprovado | Ambiguidades, perguntas, edge cases | Spec atualizado | Não |
+| **4. TASKS** | Clarificações resolvidas | Quebrar em tasks, ordem, checkpoints, dependências | tasks.md | **Sim** |
+| **5. IMPLEMENT** | Tasks aprovadas | Task por task, checkpoint a cada 3, recap | Código + recap.md | Não |
+
+---
+
+## ESTRUTURA DO PROJETO
+
+```
+projeto/
+├── CLAUDE.md
+├── .morph/
+│   ├── project.md                  # Contexto
+│   ├── config/                     # config.json, agents.json
+│   ├── standards/                  # coding, architecture, azure
+│   ├── templates/                  # Templates para outputs
+│   ├── specs/                      # Specs ATIVAS
+│   ├── features/{feature-name}/    # Features EM DESENVOLVIMENTO
+│   │   ├── proposal.md, spec.md, tasks.md
+│   │   ├── contracts.cs, decisions.md, recap.md
+│   └── archive/                    # Features CONCLUÍDAS
+├── .claude/skills/                 # Agent skills
+└── infra/main.bicep + modules/    # IaC
+```
+
+---
+
+## AGENTES
+
+### Core (Sempre Ativos)
+
+| Agente | Responsabilidades |
+|--------|-------------------|
+| **Standards Architect** | Padrões, nomenclatura, revisão |
+| **Azure Architect** | Infra Azure, Bicep, Container Apps |
+| **Cost Guardian** | Custos, alertas, bloqueios |
+
+### Stack, Specialist, Integration, Infra
+
+> **Ref:** Root `CLAUDE.md` para tabela completa de agentes e keywords.
+
+---
+
+## LIMITES DE CUSTO
+
+| Nível | Limite | Requisito |
+|-------|--------|-----------|
+| Sem aprovação | Free tier | Nenhum |
+| Com aprovação | Até $10/mês | Confirmação |
+| Acima de $10 | Justificativa | ADR |
+
+---
+
+## INFRASTRUCTURE AS CODE
+
+> NUNCA criar recursos Azure manualmente. Tudo via Bicep.
+
+| Recurso | Abordagem |
+|---------|-----------|
+| Infra estática (SQL, Storage, Container Apps) | Bicep |
+| Recursos dinâmicos (Fabric, Azure AI) | SDK .NET |
+| CI/CD | YAML + Bicep |
+
+---
+
+## TEMPLATES
+
+> SEMPRE use `bin/render-template.js` para renderizar. NUNCA preencha placeholders manualmente.
+
+### Placeholders: `{{PLACEHOLDER}}`
+
+| Placeholder | Exemplo |
+|-------------|---------|
+| `{{FEATURE_NAME}}` | `scheduled-reports` |
+| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
+| `{{FEATURE_NAME_CAMEL}}` | `scheduledReports` |
+| `{{STACK}}` | `Blazor` |
+| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
+
+### CLI
+
+```bash
+node bin/render-template.js <template> <output> <vars-json>
+# --verbose: show replacements | --dry-run: preview only
+```
+
+### Available Templates
+
+**MORPH outputs:** proposal, ui-design-system, ui-mockups, ui-components, ui-flows, spec, contracts.cs, decisions, tasks, recap
+
+**Code:** service.cs, repository.cs, agent.cs, job.cs, test.cs
+
+---
+
+## COMANDOS
+
+| Comando | Ação |
+|---------|------|
+| `/morph-proposal {feature}` | Spec pipeline completo (fases 0-4, auto-continuação com pausas) |
+| `/morph-apply {feature}` | Implementar feature (fase 5) |
+| `/morph-status` | Dashboard |
+| `/morph-archive {feature}` | Arquivar feature concluída |
+| `/morph-infra {action}` | Gerenciar infra Bicep |
+| `/morph-preflight` | Validação pre-deploy Azure |
+| `/morph-troubleshoot {error}` | Troubleshooting de erros |
+
+---
+
+## REFERÊNCIAS
+
+- `.morph/project.md` — Contexto do projeto
+- `.morph/standards/` — coding, architecture, azure
+- `.morph/templates/` — Templates para outputs
+- `.morph/config/agents.json` — Agentes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*