@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/CLAUDE.md

@@ -1,648 +0,0 @@
-# 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 com Infrastructure as Code.
-
----
-
-## STACKS DISPONÍVEIS
-
-| Stack | Backend | Frontend | Database | Deploy | CLAUDE.md |
-|-------|---------|----------|----------|--------|-----------|
-| **blazor-azure** | .NET 10 Blazor Server | Blazor (C#) | Azure SQL | Azure Container Apps (Bicep) | `stacks/blazor-azure/CLAUDE.md` |
-| **nextjs-supabase** | .NET 10 Minimal API | Next.js 15 | Supabase (PostgreSQL) | EasyPanel (Docker) | `stacks/nextjs-supabase/CLAUDE.md` |
-
-Para novos projetos, copie os arquivos da stack desejada:
-```bash
-cp -r stacks/{stack}/.morph/ seu-projeto/.morph/
-cp -r stacks/{stack}/.claude/ seu-projeto/.claude/
-cp stacks/{stack}/CLAUDE.md seu-projeto/CLAUDE.md
-```
-
----
-
-## 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 de infra manualmente (use IaC)
-- 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
-
----
-
-## 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 + IaC | spec.md, contracts, 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 |
-
----
-
-## APPROVAL GATES (Portões de Aprovação)
-
-O sistema agora rastreia aprovações explícitas para cada fase crítica em `state.json`.
-
-### Gates Obrigatórios
-
-| Gate | Quando | Bloqueio | Comando |
-|------|--------|----------|---------|
-| **design** | Após DESIGN concluído | Impede `design → clarify` | `npx morph-spec approve {feature} design` |
-| **tasks** | Após TASKS concluído | Impede `tasks → implement` | `npx morph-spec approve {feature} tasks` |
-
-### Workflow com Approval Gates
-
-```bash
-# 1. Completar fase DESIGN
-# Sistema gera: spec.md, contracts, decisions.md
-
-# 2. PAUSAR e apresentar ao usuário
-# Use AskUserQuestion: "Approve design to proceed to clarify phase?"
-
-# 3. Se aprovado pelo usuário:
-npx morph-spec approve {feature} design
-
-# 4. Avançar fase (agora permitido)
-npx morph-spec advance-phase {feature} clarify
-
-# 5. Mesmo processo para TASKS → IMPLEMENT
-```
-
-### Comandos de Approval
-
-```bash
-# Aprovar gate
-npx morph-spec approve {feature} {gate}
-
-# Rejeitar com motivo
-npx morph-spec reject {feature} {gate} "Reason here"
-
-# Ver status de todas as aprovações
-npx morph-spec approval-status {feature}
-```
-
-### Overrides (Usar com Cuidado)
-
-```bash
-# Pular verificação de aprovação (não recomendado)
-npx morph-spec advance-phase {feature} {next-phase} --skip-approval
-
-# Forçar transição inválida (emergências apenas)
-npx morph-spec advance-phase {feature} {next-phase} --force
-```
-
-**REGRA CRÍTICA:** SEMPRE apresente outputs ao usuário e obtenha aprovação explícita antes de avançar de DESIGN ou TASKS.
-
----
-
-## AUTOMATIC CHECKPOINTS (Validação Automática)
-
-A cada 3 tasks completadas, o sistema executa validação automática.
-
-### O Que é Validado
-
-| Validator | O Que Verifica | Falha Bloqueia? |
-|-----------|----------------|-----------------|
-| **architecture** | DI patterns, Blazor lifecycle, async/await | ✅ Sim |
-| **packages** | Conflitos NuGet, versões incompatíveis | ✅ Sim |
-| **design-system** | CSS compliance, color palette, spacing | ⚠️ Warning |
-| **security** | Secrets expostos, SQL injection, XSS | ✅ Sim |
-
-### Comportamento no Checkpoint
-
-```bash
-# Task 3, 6, 9, 12... completadas
-🔍 Running CHECKPOINT 1...
-✅ Architecture: 0 violations
-✅ Packages: 0 conflicts
-⚠️  Design System: 2 warnings (non-blocking)
-✅ Security: 0 issues
-
-✅ Checkpoint 1 passed
-
-# Se checkpoint FALHAR:
-❌ Checkpoint 2 failed!
-   - Architecture: DbContext injected directly in component
-   - Security: API key hardcoded in appsettings.json
-
-❌ Task NOT marked done. Fix violations before proceeding.
-```
-
-### Configuração
-
-Edite `.morph/config/llm-interaction.json`:
-
-```json
-{
-  "checkpoints": {
-    "frequency": 3,
-    "autoValidate": true,
-    "validators": {
-      "enabled": ["architecture", "packages", "security"]
-    },
-    "onFailure": {
-      "blockProgress": true,
-      "maxRetries": 3
-    }
-  }
-}
-```
-
-**IMPORTANTE:** Se checkpoint falha 3 vezes, use `AskUserQuestion` para decidir: simplificar implementação, pular validador (arriscado), ou escalar para troubleshooting-expert.
-
----
-
-## PHASE VALIDATION RULES (Validação Estrita)
-
-O sistema agora impede transições de fase inválidas com **state machine**.
-
-### Transições Válidas
-
-```
-proposal → setup
-setup → uiux | design
-uiux → design
-design → clarify
-clarify → tasks
-tasks → implement
-implement → sync | archived
-sync → archived
-```
-
-### 5 Gates de Validação
-
-Ao avançar fase, o sistema verifica (em ordem):
-
-1. **State Machine:** Transição é válida? (`proposal → implement` ❌)
-2. **Approval Gates:** Gate foi aprovado? (`design` ou `tasks` gates)
-3. **Output Requirements:** Arquivos obrigatórios existem? (spec.md, tasks.json)
-4. **Spec Content:** `spec.md` tem todas as seções? (Overview, Requirements, Technical Design, Data Model, API Contracts)
-5. **Tasks Content:** `tasks.json` tem estrutura válida? (IDs, descriptions, dependencies válidas, sem ciclos)
-
-### Exemplo de Bloqueio
-
-```bash
-npx morph-spec advance-phase user-auth implement
-
-❌ Invalid phase transition: design → implement
-   Valid next phases: clarify
-
-❌ Approval gate 'design' not approved
-   Run: npx morph-spec approve user-auth design
-
-❌ Spec validation failed:
-   - Missing section: ## Data Model
-   - Missing section: ## API Contracts
-
-Fix these issues before proceeding.
-```
-
-**REGRA:** Nunca pule fases. Se precisa pular (ex: feature simples sem UIUX), documente em `decisions.md` ADR e use `--force`.
-
----
-
-## AGENT INVOCATION PATTERNS (Spawning de Agentes)
-
-Use **Task tool** para spawnar subagentes quando apropriado.
-
-### Quando Spawnar Agentes
-
-Spawnar subagentes quando:
-
-- **5+ agentes ativos** (conforme state.activeAgents)
-- **Multi-domínio** (backend + frontend + infra)
-- **15+ arquivos** a modificar
-- **Complexidade: high ou critical**
-
-### Pattern 1: Squad Leader Spawning
-
-```typescript
-// Use Task tool
-{
-  subagent_type: "general-purpose",
-  description: "Implement backend API layer",
-  prompt: `You are the Backend Squad Leader (dotnet-senior)...
-
-Your Domain Leaders:
-- ef-modeler: Database/EF Core layer
-- api-designer: REST endpoints + DTOs
-- event-architect: Domain events + Hangfire jobs
-
-Your Mission: Implement user authentication API
-
-Feature Spec: [Include spec.md summary]
-
-Standards:
-- .morph/standards/coding.md
-- .morph/standards/architecture.md
-- .morph/standards/dotnet10-compatibility.md
-
-Your Tasks (from tasks.json):
-- T001: Create User entity + DbContext
-- T002: Implement UserService with password hashing
-- T003: Create AuthController with login/register endpoints
-
-Deliverables:
-- Entities/User.cs
-- Data/AppDbContext.cs
-- Services/UserService.cs
-- Controllers/AuthController.cs
-- DTOs (LoginRequest, RegisterRequest, AuthResponse)
-- Migrations
-
-Constraints:
-- Use IDbContextFactory (not direct DbContext injection)
-- BCrypt for password hashing
-- JWT tokens (not sessions)
-
-Report back when complete with file list + any blockers.`
-}
-```
-
-### Pattern 2: Get Team Hierarchy Helper
-
-```bash
-# Gera configurações prontas para Task tool
-npx morph-spec spawn-team {feature}
-
-# Output: JSON configs para cada squadmate
-{
-  "teammates": [
-    {
-      "agent": "dotnet-senior",
-      "role": "Backend Squad Leader",
-      "taskConfig": { ... }
-    },
-    {
-      "agent": "ef-modeler",
-      "role": "Database Layer",
-      "taskConfig": { ... }
-    }
-  ]
-}
-```
-
-### Pattern 3: Sequential Handoff
-
-```typescript
-// 1. Backend squad gera API contracts
-Task tool → dotnet-senior → generates contracts.cs
-
-// 2. AGUARDAR conclusão (não spawnar frontend ainda)
-
-// 3. Frontend squad usa contracts no contexto
-Task tool → nextjs-senior → uses contracts.cs for type generation
-```
-
-### Agent Context Template
-
-Use `.morph/templates/agent-context.md` para gerar contexto consistente:
-
-```bash
-node bin/render-template.js agent-context \
-  --feature=user-auth \
-  --agent=dotnet-senior \
-  --output=.morph/temp/agent-context.txt
-```
-
-**REGRA:** Sempre inclua spec.md summary, standards relevantes, e tasks específicas no prompt do agente.
-
----
-
-## METADATA & QUICK ACCESS (Acesso Rápido)
-
-Para features grandes, use `metadata.json` para acesso rápido (reduz uso de tokens em 60-80%).
-
-### Quando Usar metadata.json
-
-**USE metadata.json para:**
-- Quick status (fase atual, progresso %)
-- Lista de agentes ativos
-- Resumo de decisões (ADRs com links)
-- Histórico de checkpoints
-
-**USE arquivos .md completos para:**
-- Spec técnico detalhado
-- User stories completas
-- Diagramas e arquitetura
-
-### Estrutura do metadata.json
-
-```json
-{
-  "version": "1.0.0",
-  "feature": "user-authentication",
-  "status": "active",
-  "phase": "implement",
-
-  "spec": {
-    "id": "user-auth",
-    "status": "Approved",
-    "complexity": "Medium",
-    "summary": {
-      "problem": "Users need secure login/register...",
-      "solution": "JWT-based auth with BCrypt...",
-      "tags": ["security", "authentication", "jwt"]
-    },
-    "requirements": ["REQ1: JWT tokens", "REQ2: BCrypt hashing"],
-    "dataModel": ["User entity", "RefreshToken entity"]
-  },
-
-  "decisions": {
-    "decisions": [
-      {
-        "id": "ADR-001",
-        "title": "JWT vs Sessions",
-        "summary": "Chose JWT for stateless auth...",
-        "fullPath": ".morph/features/user-auth/decisions.md#adr-001"
-      }
-    ]
-  },
-
-  "tasks": {
-    "total": 12,
-    "completed": 8,
-    "progress": "67%"
-  },
-
-  "agents": ["dotnet-senior", "ef-modeler", "api-designer"],
-
-  "checkpoints": [
-    { "num": 1, "passed": true, "timestamp": "2026-02-14T10:30:00Z" },
-    { "num": 2, "passed": true, "timestamp": "2026-02-14T11:45:00Z" }
-  ],
-
-  "quickLinks": {
-    "spec": ".morph/features/user-auth/spec.md",
-    "tasks": ".morph/features/user-auth/tasks.json",
-    "decisions": ".morph/features/user-auth/decisions.md"
-  }
-}
-```
-
-### Workflow
-
-```bash
-# 1. Antes de trabalhar na feature, leia metadata.json
-cat .morph/project/outputs/user-auth/metadata.json
-
-# 2. Metadata auto-atualizado após cada task
-# (Configurado em llm-interaction.json: "updateFrequency": "on_task_done")
-
-# 3. Ou gere manualmente
-npx morph-spec generate metadata user-auth
-```
-
-### Configuração
-
-```json
-{
-  "metadata": {
-    "autoGenerate": true,
-    "updateFrequency": "on_task_done"
-  }
-}
-```
-
----
-
-## LEARNING SYSTEM (Biblioteca de Patterns)
-
-Capture e reutilize patterns bem-sucedidos em `.morph/memory/patterns-learned.md`.
-
-### Antes de Começar Nova Feature
-
-```bash
-# Buscar patterns relevantes
-npx morph-spec search-patterns "blazor state"
-npx morph-spec search-patterns "background job"
-npx morph-spec search-patterns "bicep naming"
-
-# Output:
-🔍 Found 3 pattern(s) for: "blazor state"
-
-1. Blazor DbContext Lifecycle
-   Category: Anti-Pattern to Avoid
-   Source: Framework standard
-
-   Problem: Directly injecting DbContext in Blazor components...
-
-   Correct Approach:
-   [Inject] IDbContextFactory<AppDbContext> DbFactory { get; set; }
-   ...
-```
-
-### Após Completar Feature
-
-```bash
-# Capturar pattern bem-sucedido
-npx morph-spec capture-pattern user-auth success "JWT refresh token rotation"
-
-# Capturar anti-pattern (o que evitar)
-npx morph-spec capture-pattern user-auth avoid "Storing tokens in localStorage"
-
-# Capturar otimização
-npx morph-spec capture-pattern user-auth optimization "EF Core query splitting for N+1"
-```
-
-### Categorias de Patterns
-
-| Categoria | Quando Usar |
-|-----------|-------------|
-| `success` | Abordagens comprovadas para replicar |
-| `avoid` | Anti-patterns e erros cometidos |
-| `optimization` | Melhorias de performance |
-| `security` | Best practices de segurança |
-| `convention` | Convenções do projeto (naming, estrutura) |
-| `best-practice` | Práticas gerais recomendadas |
-
-### Pattern Library Pré-Seeded
-
-O framework já vem com 11 patterns em `.morph/memory/patterns-learned.md`:
-
-- Blazor DbContext Lifecycle (anti-pattern)
-- Background Job Retry Strategy (best practice)
-- Azure Bicep Resource Naming (convention)
-- API Versioning Strategy (architecture)
-- EF Core Migration Naming (convention)
-- Blazor DI Registration Order (best practice)
-- Component Parameter Validation (best practice)
-- Async Method Naming (convention)
-- Error Handling Strategy (best practice)
-- Bicep Output Exports (convention)
-- Azure Key Vault Secrets (security)
-
-**REGRA:** Sempre busque patterns antes de começar. Capture patterns após completar. Biblioteca cresce com o tempo.
-
----
-
-## INTERACTIVE DECISIONS (Decisões Estruturadas)
-
-Use **AskUserQuestion** com templates estruturados em `.morph/templates/decision-prompts.md`.
-
-### Quando Usar AskUserQuestion
-
-**SEMPRE use para:**
-- Escolhas arquiteturais (múltiplas abordagens válidas)
-- Clarificação de escopo (requisitos ambíguos)
-- Override de validators (checkpoint failures)
-- Pular fases (features simples sem UIUX)
-- Breaking changes (API versioning, migrations)
-
-### Pattern 1: Arquitetura Choice
-
-```markdown
-I've designed two approaches for "user-authentication":
-
-**Option A: JWT with HttpOnly Cookies**
-- Pros: XSS protection, automatic CSRF with SameSite
-- Cons: Harder CORS, mobile app compatibility
-- Cost: +2 tasks (CSRF middleware)
-
-**Option B: JWT in Authorization Header**
-- Pros: Simpler CORS, better mobile support
-- Cons: Requires manual XSS protection
-- Cost: +1 task (XSS sanitization)
-
-Recommendation: Option A (more secure for web apps)
-
-Which approach do you prefer?
-```
-
-### Pattern 2: Scope Clarification
-
-```markdown
-Analyzing "scheduled-reports" feature. Need clarification:
-
-1. **Scope:** Include email delivery or just generation?
-2. **Users:** For admins only or all authenticated users?
-3. **Priority:** Critical (deploy this week) or enhancement (iterate)?
-4. **Format:** PDF only or PDF + Excel + CSV?
-
-Please clarify so I can generate accurate spec.
-```
-
-### Pattern 3: Validator Override
-
-```markdown
-Checkpoint failed 3 times:
-
-**Error:** Architecture validator - "DbContext injected directly in ReportsPage.razor"
-
-**Attempts:**
-1. Tried refactoring to service layer - still triggered (service was scoped)
-2. Tried IDbContextFactory - validator didn't detect pattern
-3. Re-read architecture.md - our implementation is correct per standard
-
-**Options:**
-1. Skip architecture validator for this checkpoint (risky)
-2. Simplify implementation (use in-memory data, no DB)
-3. Escalate to troubleshooting-expert agent
-4. Pause for your guidance
-
-What should I do?
-```
-
-### Pattern 4: Task Ordering
-
-```markdown
-Task dependency conflict detected in "user-auth":
-
-**Circular dependency:**
-- T003 (AuthController) depends on T005 (JWT service)
-- T005 (JWT service) depends on T003 (AuthController contracts)
-
-**Proposed resolution:**
-1. Split T003 into T003a (contracts/DTOs) and T003b (controller implementation)
-2. Order: T003a → T005 → T003b
-
-Approve this task breakdown?
-```
-
-### Templates Disponíveis
-
-Veja `.morph/templates/decision-prompts.md` para templates completos:
-- Scope Clarification
-- Architecture Choice
-- Task Ordering Conflict
-- Validation Failure Recovery
-- Breaking Change Approval
-- Phase Skip Justification
-
-**REGRA:** Sempre forneça contexto, 2-3 opções específicas, trade-offs, e sua recomendação. Usuário decide.
-
----
-
-## ESTRUTURA DO FRAMEWORK
-
-```
-morph-spec-framework/
-├── stacks/
-│   ├── blazor-azure/              # Stack Blazor + Azure
-│   │   ├── CLAUDE.md
-│   │   ├── .morph/{config, standards, templates, examples}
-│   │   └── .claude/{skills, commands}
-│   │
-│   └── nextjs-supabase/           # Stack Next.js + Supabase
-│       ├── CLAUDE.md
-│       ├── .morph/{config, standards, templates, examples}
-│       └── .claude/{skills}
-│
-├── framework/                     # Compartilhado entre stacks
-│   └── standards/{13 files}       # coding, architecture, blazor-*, css-*
-│
-└── src/                           # CLI (morph-spec)
-```
-
----
-
-## 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 ou Docker) |
-| `/morph-preflight` | Validação pre-deploy |
-| `/morph-troubleshoot {error}` | Troubleshooting de erros |
-
----
-
-## TEMPLATES
-
-> SEMPRE use `bin/render-template.js` para renderizar. NUNCA preencha placeholders manualmente.
-
-| Placeholder | Exemplo |
-|-------------|---------|
-| `{{FEATURE_NAME}}` | `scheduled-reports` |
-| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
-| `{{STACK}}` | `Blazor` ou `NextjsSupabase` |
-| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
-
----
-
-## REFERÊNCIAS
-
-- `stacks/{stack}/CLAUDE.md` — Instruções específicas da stack
-- `stacks/{stack}/.morph/standards/` — Standards da stack
-- `stacks/{stack}/.morph/config/agents.json` — Agentes da stack
-- `framework/standards/` — Standards compartilhados (coding, architecture)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*