@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/framework/skills/level-1-workflows/phase-design/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: phase-design
+description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts.cs, schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# MORPH Design - FASE 2
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Expanda a proposta em especificação técnica completa, contracts, decisões arquiteturais e estimativa de custos.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] FASE 1.5 (UI/UX) concluída OU pulada (se não houver front-end)
+- [ ] Proposta aprovada pelo usuário
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler proposal + UI specs | **Read** output files | — |
+| Obter schema do banco | **Supabase MCP** `list_tables()`, `get_table_schema()` | **Grep** queries + **Read** types |
+| Obter relacionamentos de FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK no código |
+| Obter políticas RLS | **Supabase MCP** `query()` com pg_policies | **Read** arquivos de políticas |
+| Encontrar arquivos de query (fallback) | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar definições de tipo (fallback) | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos de query/tipos (fallback) | **Read** cada arquivo encontrado | — |
+| Pesquisar biblioteca para ADR | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Buscar padrões no código | **GitHub MCP** `search_code()` | **Grep** padrões no projeto |
+| Renderizar template contracts.cs | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | — |
+| Renderizar template spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
+| Renderizar template decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
+| Criar schema-analysis.md | **Write** no diretório de outputs | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
+
+**MCPs desta fase:** Supabase (schema analysis — **PRIORITÁRIO**), Context7 (research), GitHub (code search).
+
+**Anti-padrões:**
+- ❌ Adivinhar nomes de campos sem verificar schema (use MCP ou Grep primeiro!)
+- ❌ Task agent para ler um único arquivo spec (use Read direto)
+- ❌ WebSearch para schema do banco (use Supabase MCP ou análise de código)
+- ❌ Escrever contracts.cs do zero (use template render)
+
+---
+
+## Workflow
+
+### Passo 1: Carregar Contexto e Standards
+
+**Obtenha feature state e standards context:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Parse o JSON para obter `activeAgents`, então use standards context (já carregado na FASE 1):
+- Standards relevantes estão em `standardsSummary` do detect-agents
+- Padrões já incluem project overrides + inferred learnings
+
+**Leia outputs existentes:**
+1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
+2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
+
+**Use standards context ao gerar spec.md:**
+- Architecture standards → guiam Technical Architecture section
+- Coding standards → definem contracts.cs patterns
+- Azure standards → determinam Infrastructure Requirements
+
+### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
+
+**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts.cs`. Previne geração de DTOs com nomes de campos errados.
+
+**Delegate para skill dedicada:**
+
+> **Ref:** `framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md` — workflow completo de análise de schema (MCP Supabase → fallback análise estática → SCHEMA-ANALYSIS.md → checkpoint de aprovação)
+
+Execute o workflow de `phase-codebase-analysis.md` para:
+1. Detectar se análise é necessária
+2. Tentar MCP Supabase (preferencial) ou análise estática (fallback)
+3. Mapear field name mismatches e type mismatches
+4. Gerar `schema-analysis.md` com findings reais
+5. Apresentar checkpoint ao usuário e aguardar aprovação
+
+**Pule se:**
+- Feature é 100% nova (sem dependências em código existente)
+- Não há banco de dados ou APIs envolvidas
+
+### Passo 3: Gerar `spec.md`
+
+Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:
+
+#### 3.1. Overview
+- **Objetivo:** Resumo de 1-2 parágrafos
+- **Usuários afetados:** Quem vai usar?
+- **Problema resolvido:** Qual dor/necessidade?
+
+#### 3.2. Functional Requirements
+Lista detalhada de requisitos funcionais:
+```markdown
+### FR001: {Requisito}
+**Description:** {O que deve fazer}
+**Acceptance Criteria:**
+- [ ] Critério 1
+- [ ] Critério 2
+**Priority:** High/Medium/Low
+```
+
+#### 3.3. Non-Functional Requirements
+- Performance (tempos de resposta esperados)
+- Segurança (autenticação, autorização)
+- Escalabilidade (volume de dados/usuários)
+- Disponibilidade (uptime esperado)
+
+#### 3.4. Technical Architecture
+- **Camadas:** (Presentation, Application, Domain, Infrastructure)
+- **Patterns:** (Repository, CQRS, DI, etc.)
+- **Dependências:** Bibliotecas/serviços externos necessários
+
+#### 3.5. Data Model
+- Entities principais
+- Relacionamentos (1:1, 1:N, N:N)
+- Campos obrigatórios vs opcionais
+- Validações de negócio
+
+#### 3.6. Infrastructure Requirements
+Se houver recursos Azure:
+- Banco de dados (Azure SQL, Cosmos DB)
+- Storage (Blob Storage)
+- Compute (Container Apps, App Service)
+- Monitoring (App Insights)
+
+**SEMPRE usar Bicep para infra!**
+
+### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
+
+**⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs corretos!
+
+**Renderizar template:**
+
+```bash
+# Use o template de contracts com dados do schema-analysis.md:
+npx morph-spec template render \
+  code/dotnet/contracts/contracts.cs \
+  .morph/features/$ARGUMENTS/1-design/contracts.cs \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "NAMESPACE": "{ProjectNamespace}",
+    "dtos": [...], # Extrair de schema-analysis.md
+    "interfaces": [...],
+    "enums": [...],
+    "valueObjects": [...]
+  }'
+```
+
+**OU use Read tool para ler template:**
+
+```bash
+# Leia o template base:
+Read: .morph/framework/templates/code/dotnet/contracts/contracts.cs.hbs
+
+# Preencha manualmente usando dados de schema-analysis.md
+# Template contém placeholders para:
+# - {{FEATURE_NAME_PASCAL}}
+# - {{NAMESPACE}}
+# - {{#each dtos}}...{{/each}}
+# - {{#each interfaces}}...{{/each}}
+# - {{#each enums}}...{{/each}}
+```
+
+**Padrões obrigatórios (já incluídos no template):**
+- Records para DTOs (immutable)
+- Interfaces para serviços
+- CancellationToken em métodos async
+- Nullable reference types habilitados
+- **USAR NOMES DE CAMPOS REAIS DO SCHEMA** (NÃO assumir!)
+- XML documentation comments
+- Value objects para complex types
+
+**⚠️ CHECKPOINT: Verificar contra schema-analysis.md**
+- [ ] Todos os field names correspondem ao schema real?
+- [ ] Tipos de dados corretos (JSONB → JsonObject, não string)?
+- [ ] Nullability correta (campo opcional no banco → nullable no DTO)?
+- [ ] Relacionamentos mapeados corretamente?
+- [ ] Template foi renderizado corretamente?
+
+### Passo 5: Iniciar `decisions.md`
+
+**Renderizar template:**
+
+```bash
+# Use o template de decisions:
+Read: .morph/framework/templates/feature/decisions.md
+
+# OU renderize via CLI:
+npx morph-spec template render \
+  feature/decisions \
+  .morph/features/$ARGUMENTS/1-design/decisions.md \
+  '{
+    "FEATURE_NAME": "$ARGUMENTS",
+    "DATE": "{{DATE}}",
+    "decisions": []
+  }'
+```
+
+**Template contém estrutura para ADRs (Architecture Decision Records):**
+- Status, Context, Decision, Consequences
+- Pros/Cons analysis
+- Alternatives Considered section
+- Date tracking
+
+**ADRs obrigatórios:**
+- Escolha de biblioteca UI (se FASE 1.5 executou)
+- Padrões arquiteturais (CQRS, Repository, etc.)
+- Recursos Azure (se houver infra)
+- Integrações externas (APIs, webhooks, etc.)
+- Análise de custos (se houver recursos pagos)
+
+### Passo 6: Estimar Custos
+
+Se houver recursos Azure na spec:
+
+**Limites configuráveis** (em config.json):
+- `costs.limits.freeTierOnly`: $0 (apenas free tier)
+- `costs.limits.withApproval`: $10 (requer confirmação do usuário)
+- `costs.limits.requiresADR`: $10 (requer ADR documentado)
+
+Documente custos em `decisions.md` e atualize state:
+
+```bash
+npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
+npx morph-spec state set $ARGUMENTS costs.approved {true/false}
+```
+
+### Passo 7: Atualizar State
+
+```bash
+npx morph-spec state set $ARGUMENTS phase design
+npx morph-spec state mark-output $ARGUMENTS schema-analysis
+npx morph-spec state mark-output $ARGUMENTS spec
+npx morph-spec state mark-output $ARGUMENTS contracts
+npx morph-spec state mark-output $ARGUMENTS decisions
+```
+
+## Outputs Gerados
+
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` - **NOVO!** Análise do schema real
+- `.morph/features/$ARGUMENTS/1-design/spec.md` - Especificação técnica completa
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs` - Interfaces, DTOs, Enums (baseados no schema real!)
+- `.morph/features/$ARGUMENTS/1-design/decisions.md` - ADRs (novo ou atualizado)
+- State atualizado com custos estimados
+
+## PAUSA OBRIGATÓRIA
+
+Apresente ao usuário 3 ações sugeridas:
+
+1. **Aprovar design e continuar para clarificação**
+2. **Ajustar escopo/complexidade** - Revisar spec.md
+3. **Modificar contracts** - Ajustar interfaces/DTOs
+
+## Critérios de Avanço
+
+- [x] `spec.md` completo com todos os requisitos
+- [x] `contracts.cs` com interfaces e DTOs
+- [x] `decisions.md` com ADRs relevantes
+- [x] Custos estimados e documentados (se houver infra)
+- [x] State atualizado
+- [x] Usuário aprovou design
+
+---
+
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `writing-plans` | Após spec aprovado, para estruturar abordagem de implementação | `Skill(superpowers:writing-plans)` |
+| `brainstorming` | Para explorar alternativas de arquitetura (use morph-spec version) | Use `brainstorming` (morph-spec version) |
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:design -->
+| Output | Caminho |
+|--------|---------|
+| `schemaAnalysis` | `.morph/features/{feature}/1-design/schema-analysis.md` |
+| `spec` | `.morph/features/{feature}/1-design/spec.md` |
+| `contracts` | `.morph/features/{feature}/1-design/contracts.cs` |
+| `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
+<!-- /morph:outputs -->
+
+---
+
+Continuar automaticamente para FASE 3 (Clarify) após aprovação.

package/framework/skills/level-1-workflows/phase-design/references/spec-example.md

@@ -0,0 +1,253 @@
+# Feature Specification: Photo Processing Pipeline
+
+> Example of a well-structured spec.md. This is a filled-in reference — not a template.
+
+| Field | Value |
+|-------|-------|
+| **ID** | photo-processing |
+| **Status** | Approved |
+| **Created** | 2025-01-15 |
+| **Stack** | blazor-azure |
+| **Complexity** | Medium |
+| **Estimated Cost** | ~$5.50/month |
+| **Agents** | Core: All / Specialists: azure-architect, dotnet-senior, blazor-builder |
+
+---
+
+## Overview
+
+**Problem:** Users cannot submit photos for AI transformation — the core product value proposition is blocked.
+
+**Solution:** End-to-end pipeline: upload → Blob Storage → Hangfire background job → AI processing → download link.
+
+**Success Criteria:**
+- [ ] Upload endpoint accepts .jpg/.png up to 10MB and stores in Azure Blob
+- [ ] Background job processes photo and updates status to Completed within 120s (p95)
+- [ ] Status polling page reflects real-time processing progress
+- [ ] Failed jobs retry up to 3 times with exponential backoff
+
+---
+
+## Requirements
+
+**Functional:**
+FR1: Upload photo (.jpg/.png, max 10MB) via Blazor form
+FR2: Store photo in Azure Blob Storage under `uploads/{jobId}`
+FR3: Enqueue Hangfire background job for AI processing
+FR4: Status polling endpoint returns `{ status, progress, createdAt }`
+FR5: Download endpoint redirects to Blob URL for completed jobs
+
+**Non-Functional:**
+NFR1: Processing time < 120s for p95 of requests
+NFR2: Upload endpoint < 2s response time
+NFR3: Retry 3x on AI API failure with 5s/30s/120s backoff
+
+---
+
+## User Stories
+
+### US001: Upload Photo
+**As** an authenticated user **I want** to upload a photo **so that** the AI can transform it.
+
+**Acceptance Criteria:**
+1. Accepts .jpg and .png files only — rejects other formats with clear error
+2. Rejects files larger than 10MB with a specific error message
+3. Returns a `jobId` and redirects to `/processing/{jobId}` on success
+
+**Edge Cases:**
+- Network timeout during upload: show retry button
+- Duplicate upload: create new job each time (idempotency not required)
+
+### US002: Track Progress
+**As** a user who uploaded a photo **I want** to see real-time status **so that** I know when my photo is ready.
+
+**Acceptance Criteria:**
+1. Page polls `/api/status/{jobId}` every 5 seconds
+2. Shows status label: Pending / Processing / Completed / Failed
+3. Shows "Download" button when status = Completed
+
+---
+
+## Technical Design
+
+### Stack
+
+| Component | Technology |
+|-----------|------------|
+| Frontend | Blazor Server |
+| Backend | .NET 10 / C# 14 Minimal API |
+| Background Jobs | Hangfire (self-hosted) |
+| Storage | Azure Blob Storage (LRS) |
+| Database | Azure SQL |
+
+### Data Model
+
+#### ProcessingJob
+
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK, default NEWID() |
+| OriginalPhotoUrl | nvarchar(500) | NOT NULL |
+| ProcessedPhotoUrl | nvarchar(500) | NULL (populated after processing) |
+| Status | int | NOT NULL, default 0 (Pending) |
+| ErrorMessage | nvarchar(1000) | NULL |
+| RetryCount | int | NOT NULL, default 0 |
+| CreatedAt | datetime2 | NOT NULL, default GETUTCDATE() |
+| UpdatedAt | datetime2 | NOT NULL |
+
+#### ProcessingStatus Enum
+
+```csharp
+public enum ProcessingStatus
+{
+    Pending = 0,
+    Processing = 1,
+    Completed = 2,
+    Failed = 100
+}
+```
+
+### Contracts
+
+```csharp
+// Commands
+public record UploadPhotoCommand(IFormFile Photo, string? Email);
+public record UploadPhotoResult(Guid JobId);
+
+// Queries
+public record GetJobStatusQuery(Guid JobId);
+public record JobStatusDto(Guid JobId, ProcessingStatus Status, string? ProcessedPhotoUrl, DateTime CreatedAt);
+
+// Service Interface
+public interface IPhotoProcessingService
+{
+    Task<UploadPhotoResult> UploadAsync(UploadPhotoCommand command, CancellationToken ct);
+    Task<JobStatusDto> GetStatusAsync(GetJobStatusQuery query, CancellationToken ct);
+}
+
+// Hangfire Job
+public interface IPhotoProcessingJob
+{
+    Task ProcessAsync(Guid jobId, CancellationToken ct);
+}
+```
+
+---
+
+## UI/UX Design
+
+### Upload Page (/upload)
+
+```
+┌─────────────────────────────────────┐
+│  Upload Photo                        │
+│  ─────────────────────────────────  │
+│  [📁 Select File] photo.jpg (2.3MB)  │
+│                                      │
+│  Allowed: JPG, PNG — Max: 10MB       │
+│                                      │
+│             [Upload →]               │
+│                                      │
+│  Error state:                        │
+│  ⚠ File too large. Max size is 10MB. │
+└─────────────────────────────────────┘
+```
+
+### Status Page (/processing/{jobId})
+
+```
+┌─────────────────────────────────────┐
+│  Processing your photo               │
+│  ─────────────────────────────────  │
+│  Status: ⏳ Processing               │
+│  ████████░░░░░░░  60%               │
+│                                      │
+│  Started: 2025-01-15 14:32:01        │
+│                                      │
+│  [Completed state]:                  │
+│  Status: ✅ Done!                    │
+│            [📥 Download]             │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Flows
+
+### Upload Flow
+**Trigger:** User submits photo form
+
+1. User selects file → client validates type/size before submit
+2. `POST /api/upload` — server validates, uploads to Blob at `uploads/{jobId}/original.jpg`
+3. Create `ProcessingJob` entity (status = Pending)
+4. Enqueue Hangfire job with `jobId`
+5. Return `{ jobId }` → client redirects to `/processing/{jobId}`
+
+**End State:** Job queued, user on status page
+
+### Processing Flow
+**Trigger:** Hangfire executes job
+
+1. Load `ProcessingJob` by Id, set status = Processing
+2. Download original from Blob Storage
+3. Call AI API (`POST /transform`, multipart/form-data)
+4. On success: upload result to `uploads/{jobId}/processed.jpg`, set status = Completed
+5. On failure: increment RetryCount, set status = Failed if RetryCount >= 3
+
+**End State:** Job = Completed (photo available) or Failed (user sees error)
+
+---
+
+## Cost Estimate
+
+| Resource | SKU | Monthly | Justification |
+|----------|-----|---------|---------------|
+| Blob Storage | LRS | $0.02 | ~500 photos/month × 2 files × avg 3MB |
+| Azure SQL | Basic | $4.99 | < 100k jobs/month |
+| Container App | Consumption | $0.49 | Scale to zero when idle |
+| Hangfire | Self-hosted | $0.00 | In-process with Container App |
+| **Total** | | **~$5.50** | |
+
+---
+
+## ADRs
+
+### ADR-001: Hangfire over Azure Functions for Background Processing
+**Status:** Accepted
+**Context:** Need async processing for AI photo transformation (30–120s duration).
+**Decision:** Hangfire (self-hosted in Container App)
+**Alternatives:**
+1. Azure Functions — serverless, auto-scaling, but cold start latency + $10/mo for 50k executions
+2. Quartz.NET — more features (CRON, clustering), steeper learning curve
+**Trade-offs:** Simplicity + zero cost vs scalability (Hangfire sufficient for MVP < 10k/month)
+
+### ADR-002: Polling over WebSockets for Status Updates
+**Status:** Accepted
+**Context:** Users need real-time feedback; SSE/WebSocket adds Blazor Hub complexity.
+**Decision:** 5-second HTTP polling from Blazor component
+**Trade-offs:** Slightly higher server load vs significantly simpler implementation; polling sufficient at MVP scale
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| Upload | Authenticated user |
+| View status | Owner of job (check UserId) |
+| Download | Owner of job (check UserId) |
+
+---
+
+## Definition of Done
+
+- [ ] Upload endpoint working, validated with unit + integration tests
+- [ ] Hangfire job processes photos end-to-end in dev environment
+- [ ] Status page shows correct states (Pending/Processing/Completed/Failed)
+- [ ] Code review approved
+- [ ] Deployed to staging environment
+- [ ] `recap.md` generated with implementation notes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*