@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/CLAUDE.md

@@ -1,993 +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 |
-
----
-
-## WORKFLOW DETECTION SYSTEM (Detecção Automática de Complexidade)
-
-O framework agora detecta **AUTOMATICAMENTE** o workflow apropriado baseado na análise do pedido do usuário.
-
-### 5 Tipos de Workflow
-
-| Workflow | Complexidade | Arquivos | Linhas | Keywords Exemplo |
-|----------|--------------|----------|--------|------------------|
-| **fast-track** | Trivial | ≤3 | ≤50 | bug, fix, corrigir, css, typo |
-| **standard** | Média | 3-10 | 50-500 | paginação, filtro, refactor, export |
-| **full-morph** | Alta | >10 | >500 | sistema, autenticação, integração, cqrs |
-| **design-impl** | N/A | N/A | N/A | prototype, figma, html para, replicar |
-| **ui-refresh** | N/A | N/A | N/A | redesign, modernizar, aesthetic, bonito |
-
-### Como Funciona
-
-**1. Quando Criar Feature:**
-
-```bash
-# Detecção automática
-npx morph-spec feature create user-pagination \
-  --request "add pagination to users table"
-
-# Output:
-🔍 Analyzing request...
-✓ Detected workflow: standard (85% confidence)
-  Matched keyword: "paginação"
-  Estimated: 5 files, ~200 lines
-
-📋 Created feature: user-pagination
-    Phase: proposal
-    Workflow: standard
-```
-
-**2. Análise Manual (Opcional):**
-
-```bash
-npx morph-spec detect-workflow "implement complete authentication system"
-
-# Output:
-Detected Workflow: full-morph (92% confidence)
-
-Criteria Match:
-  ✓ Keywords: "authentication", "complete", "system"
-  ✓ Estimated: 15 files, ~800 lines
-  ✓ Infrastructure: detected
-
-Phases to Run:
-  1. CONTEXT
-  2. PROPOSAL - ⏸️ Pause for approval
-  3. SETUP
-  4. UI/UX - ⏸️ Pause for approval
-  5. DESIGN - ⏸️ Pause for approval
-  6. CLARIFY
-  7. TASKS - ⏸️ Pause for approval
-  8. IMPLEMENT
-  9. SYNC - ⏸️ Pause for approval
-
-Phases Skipped: None (all mandatory for full-morph)
-
-Alternative Workflows:
-  - standard (15%): If scope reduced to basic login only
-```
-
-### Workflow Behaviors
-
-#### fast-track (Trivial)
-- **Objetivo:** Correções rápidas, ajustes CSS, edge cases
-- **Fases:** Quick Analysis (proposal+setup+design combinados) → Implement
-- **Fases Puladas:** UIUX, CLARIFY, TASKS, SYNC
-- **Outputs:** Apenas commit message (sem .md files)
-- **Exemplo:** "fix typo in login button"
-
-#### standard (Média Complexidade)
-- **Objetivo:** Features simples, refatorações, otimizações
-- **Fases:** PROPOSAL (simplificado) → DESIGN (conciso) → TASKS (se >5 tasks) → IMPLEMENT
-- **Fases Puladas:** SETUP (contexto já carregado), UIUX (sem frontend significativo), CLARIFY (spec claro), SYNC (decisões táticas)
-- **Outputs:** proposal.md, spec.md, recap.md (minimal)
-- **Exemplo:** "add pagination to users table"
-
-#### full-morph (Alta Complexidade)
-- **Objetivo:** Sistemas completos, arquitetura, integrações
-- **Fases:** TODAS (9 fases obrigatórias)
-- **Fases Puladas:** Nenhuma
-- **Outputs:** Completo (proposal, ui-*, spec, contracts, tasks, decisions, recap)
-- **Exemplo:** "implement complete authentication system with OAuth"
-
-#### design-impl (Prototipo → Código)
-- **Objetivo:** Converter HTML, Figma, mockups para código funcional
-- **Fases:** ANÁLISE DO PROTÓTIPO → TASKS (lista de telas) → IMPLEMENT (por tela)
-- **Fases Puladas:** PROPOSAL, DESIGN técnico, CLARIFY, SYNC
-- **Outputs:** recap.md, .razor code, CSS
-- **Exemplo:** "convert HTML prototype to Blazor components"
-
-#### ui-refresh (Redesign Visual)
-- **Objetivo:** Mudanças apenas visuais, sem lógica de negócio
-- **Fases:** ANÁLISE VISUAL → DESIGN SYSTEM (simplificado) → IMPLEMENT (por página)
-- **Fases Puladas:** SETUP completo, CONTRACTS, TASKS detalhadas, INFRA, CLARIFY, SYNC
-- **Outputs:** design-refresh-checklist.md, CSS, .razor pages, recap.md
-- **Exemplo:** "redesign dashboard to look more modern"
-
-### Algoritmo de Detecção
-
-O sistema usa 4 fatores ponderados:
-
-1. **Keywords (40%):** Matching de palavras-chave (PT + EN)
-2. **Complexity (30%):** Estimativa de arquivos/linhas/componentes
-3. **Priority (20%):** Workflows específicos > genéricos
-4. **Context (10%):** Condições especiais (has prototype? existing pages?)
-
-**Penalties:**
-- -50% para workflows sem keyword match (exceto full-morph)
-
-**Boosts:**
-- +20% para workflows com 3+ keywords matched
-
-### Override Manual
-
-```bash
-# Forçar workflow específico
-npx morph-spec state set user-auth workflow full-morph
-
-# Re-detectar após mudanças no pedido
-npx morph-spec state detect-workflow user-auth \
-  "implement basic login only (no OAuth)"
-
-# Output:
-🔄 Re-analyzing request...
-✓ New workflow: standard (78% confidence)
-  Previous: full-morph
-  Reason: Scope reduced - no OAuth, no registration
-```
-
-### Configurações de Workflow
-
-Workflows são definidos em `framework/workflows/configs/*.json`:
-
-```json
-{
-  "id": "standard",
-  "criteria": {
-    "minFiles": 3,
-    "maxFiles": 10,
-    "minLines": 50,
-    "maxLines": 500
-  },
-  "keywords": ["paginação", "pagination", "filtro", "filter"],
-  "phases": {
-    "run": ["proposal", "design", "tasks", "implement"],
-    "skip": ["setup", "uiux", "clarify", "sync"]
-  },
-  "priority": 2
-}
-```
-
-### Documentação Completa
-
-Veja `framework/workflows/` para:
-- **docs/STORY-DRIVEN-DEVELOPMENT.md:** Filosofia do sistema
-- **docs/{workflow}.md:** Detalhes de cada workflow (5 arquivos)
-- **configs/{workflow}.json:** Configurações executáveis (5 arquivos)
-- **README.md:** Guia completo do sistema de workflows
-
-**REGRA CRÍTICA:** Confie na detecção automática. Override manual apenas se houver contexto que o sistema não detectou (ex: "parece grande mas já temos 80% do código pronto").
-
----
-
-## 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`.
-
----
-
-## CLAUDE CODE HOOKS (Validação em Hooks)
-
-O framework integra com o sistema de hooks do Claude Code para validação automática em eventos Git e Agent Teams.
-
-### Arquitetura de Hooks
-
-**Universal (framework/hooks/):** Hooks compartilhados por todas as stacks
-- **pre-commit/**: `agents.sh`, `specs.sh`, `orchestrator.sh`
-- **commit-msg/**: `conventional-commits.sh` (Conventional Commits format)
-- **pre-push/**: `run-tests.sh` (executa test suite completo)
-- **agent-teams/**: `teammate-idle.js`, `task-completed.js`, `phase-advanced.js`
-
-**Stack-Specific (stacks/{stack}/.morph/hooks/):** Hooks específicos de cada stack
-- **pre-commit/**: `tests-csharp.sh` (blazor-azure), `tests-typescript.sh` (nextjs-supabase)
-
-### Instalação de Git Hooks
-
-```bash
-# No diretório .git/hooks do projeto
-cd .git/hooks
-
-# Pre-commit (valida agents.json, spec.md, executa testes)
-ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
-chmod +x pre-commit
-
-# Commit-msg (valida formato Conventional Commits)
-ln -sf ../../framework/hooks/commit-msg/conventional-commits.sh commit-msg
-chmod +x commit-msg
-
-# Pre-push (executa suite de testes antes de push)
-ln -sf ../../framework/hooks/pre-push/run-tests.sh pre-push
-chmod +x pre-push
-```
-
-### Configuração de Agent Teams Hooks
-
-Adicione em `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "TeammateIdle": "node framework/hooks/agent-teams/teammate-idle.js {feature}",
-    "TaskCompleted": "node framework/hooks/agent-teams/task-completed.js {feature} {taskId}",
-    "PhaseAdvanced": "node framework/hooks/agent-teams/phase-advanced.js {feature} {fromPhase} {toPhase}"
-  }
-}
-```
-
-### Validators com Hook Behavior
-
-5 validators tier-4 configurados em `agents.json` com `hook_behavior`:
-
-| Validator | Hook Triggers | Valida | Bloqueia? |
-|-----------|---------------|--------|-----------|
-| **security-expert** | TeammateIdle, TaskCompleted | SQL injection, XSS, Secrets | ✅ Sim |
-| **architecture-expert** | TeammateIdle, TaskCompleted | DbContext injection, async/await, DI order | ✅ Sim |
-| **packages-validator** | TaskCompleted | NuGet conflicts, .NET 10 compatibility | ✅ Sim |
-| **design-system-validator** | TeammateIdle | CSS palette, spacing, typography | ⚠️ Warning |
-| **blazor-concurrency-validator** | TaskCompleted | DbContext lifecycle, async void, JSInterop | ✅ Sim |
-
-### Como Funciona
-
-**Git Hooks:**
-```
-git commit → pre-commit hook → orchestrator.sh
-    ├─ Executa framework/hooks/pre-commit/*.sh (universal)
-    └─ Executa .morph/hooks/pre-commit/*.sh (stack-specific)
-    ↓
-commit-msg hook → valida formato Conventional Commits
-    ↓
-git push → pre-push hook → executa test suite
-```
-
-**Agent Teams Hooks:**
-```
-Teammate idle → TeammateIdle hook
-    ├─ Carrega agents.json
-    ├─ Filtra validators com hook_triggers: ["TeammateIdle"]
-    ├─ Executa validators via hook-executor.js
-    └─ Bloqueia se errors > 0 e blocks_on_fail: true
-```
-
-### Bypass (Não Recomendado)
-
-```bash
-# Pular hooks Git
-git commit --no-verify
-git push --no-verify
-
-# Pular validação de task
-npx morph-spec task done feature-name task-id --skip-validation
-```
-
-**IMPORTANTE:** Veja `framework/hooks/README.md` para documentação completa de hooks.
-
----
-
-## 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")
-# NOTA: Não há comando manual para gerar metadata - sempre auto-gerado
-```
-
-### 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
-
-> **Template System v2.0** - Organizado por tecnologia, reutilizável entre stacks, powered by Handlebars
-
-### Overview
-
-Templates estão em `framework/templates/` organizados por **tecnologia** (não por stack):
-- `code/dotnet/` - Templates .NET (service, repository, component, etc.)
-- `code/typescript/` - Templates TypeScript (contracts, etc.)
-- `code/sql/` - Templates SQL (Supabase migrations, RLS policies)
-- `infrastructure/azure/` - Bicep templates para Azure
-- `infrastructure/docker/` - Dockerfiles e Docker Compose
-- `integrations/` - Integrações (Asaas, Clerk, Azure Identity)
-- `ui/` - Design systems (CSS, Fluent/Mud themes)
-- `saas/` - Multi-tenant patterns
-
-**Por quê tecnologia?** Permite reutilizar templates entre stacks (ex: service.cs funciona para blazor-azure E nextjs-supabase).
-
-### CLI Commands
-
-```bash
-# Listar todos os templates
-morph-spec template list
-
-# Filtrar por categoria/tecnologia
-morph-spec template list --category code
-morph-spec template list --phase implement
-
-# Ver detalhes de um template
-morph-spec template show dotnet-backend-service --preview
-
-# Renderizar template (usando Handlebars)
-morph-spec template render dotnet-backend-service UserService.cs '{
-  "FEATURE_NAME": "user-auth",
-  "NAMESPACE": "MyApp.Services"
-}'
-
-# Customizar template (criar override stack-specific)
-morph-spec template customize dotnet-backend-service --stack blazor-azure
-```
-
-### Handlebars Helpers (v2.0)
-
-**✅ USE (novo):**
-
-| Helper | Input | Output | Uso |
-|--------|-------|--------|-----|
-| `{{pascalCase str}}` | `user-auth` | `UserAuth` | Classes |
-| `{{camelCase str}}` | `user-auth` | `userAuth` | Variables |
-| `{{snakeCase str}}` | `user-auth` | `user_auth` | SQL |
-| `{{titleCase str}}` | `user-auth` | `User Auth` | Titles |
-| `{{pluralize str}}` | `user` | `users` | Collections |
-
-**❌ DEPRECADO (v1.0):**
-
-| Placeholder | Status | Use Instead |
-|-------------|--------|-------------|
-| `{{FEATURE_NAME_PASCAL}}` | ❌ Deprecated | `{{pascalCase FEATURE_NAME}}` |
-| `{{FEATURE_NAME_CAMEL}}` | ❌ Deprecated | `{{camelCase FEATURE_NAME}}` |
-| `{{FEATURE_NAME_SNAKE}}` | ❌ Deprecated | `{{snakeCase FEATURE_NAME}}` |
-
-### Variáveis Padrão (auto-injetadas)
-
-| Placeholder | Exemplo |
-|-------------|---------|
-| `{{FEATURE_NAME}}` | `scheduled-reports` |
-| `{{STACK}}` | `Blazor` ou `NextjsSupabase` |
-| `{{DATE}}` | `2026-02-17` |
-| `{{YEAR}}` | `2026` |
-| `{{TIMESTAMP}}` | `2026-02-17T19:38:00Z` |
-| `{{NAMESPACE}}` | Auto from config.json |
-| `{{AUTHOR}}` | Auto from config.json |
-
-### Stack Overrides
-
-Templates são resolvidos com fallback automático:
-1. `stacks/{stack}/.morph/templates/` (override stack-specific)
-2. `.morph/templates/` (override project-local)
-3. `framework/templates/` (fallback padrão)
-
-Para customizar um template:
-```bash
-morph-spec template customize dotnet-backend-service --stack blazor-azure
-# Edite: stacks/blazor-azure/.morph/templates/code/dotnet/backend/service.cs
-```
-
-### Documentação Completa
-
-Veja `framework/templates/README.md` para:
-- Estrutura completa de diretórios
-- Todos os helpers Handlebars disponíveis
-- Como criar novos templates
-- Migração v1 → v2
-
----
-
-## 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*