@polymorphism-tech/morph-spec 4.5.0 → 4.6.0

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

@@ -1,7 +1,6 @@
 ---
 name: phase-design
-description: >
-  MORPH-SPEC Phase 2 (Design). Expands the approved proposal into spec.md, contracts.cs, decisions.md, and schema-analysis.md. Called by /morph-proposal after setup completes.
+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
@@ -21,8 +20,9 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **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 |
 |------|------------|-------------|
@@ -78,193 +78,21 @@ Parse o JSON para obter `activeAgents`, então use standards context (já carreg
 
 **⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts.cs`. Previne geração de DTOs com nomes de campos errados.
 
-#### 2.1. Detectar Se Análise É Necessária
+**Delegate para skill dedicada:**
 
-A análise de código é necessária se:
-- Feature interage com banco de dados existente
-- Feature usa APIs ou serviços existentes
-- Projeto tem código frontend/backend que será integrado
+> **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)
 
-**Pule este passo apenas se:**
+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
 
-#### 2.2. Tentar MCP Tools Primeiro (Preferencial)
-
-**Se MCP Supabase disponível:**
-
-```javascript
-// Verificar se MCP está disponível (procure por ferramentas mcp__supabase__*)
-// Se disponível, use para obter schema real:
-
-// 1. Listar todas as tabelas
-await mcp__supabase__list_tables();
-
-// 2. Para cada tabela relevante, obter schema completo
-await mcp__supabase__get_table_schema({ table: 'leads' });
-await mcp__supabase__get_table_schema({ table: 'users' });
-
-// 3. Obter relacionamentos
-await mcp__supabase__get_relationships({ table: 'leads' });
-
-// 4. Documentar findings em SCHEMA-ANALYSIS.md
-```
-
-**Se MCP Database/ORM disponível:**
-- Use ferramentas MCP equivalentes para PostgreSQL, MySQL, EF Core, etc.
-- Obtenha schema diretamente do banco
-
-#### 2.3. Fallback: Análise Manual de Código
-
-**Se MCP não disponível, use análise estática:**
-
-**Passo A: Encontrar Queries no Código**
-
-```bash
-# Use Grep tool para encontrar todas as queries:
-pattern: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|ef\.Database\."
-type: "ts,tsx,js,jsx,cs"
-output_mode: "files_with_matches"
-```
-
-**Passo B: Ler Arquivos de Query**
-
-Para cada arquivo encontrado, use Read tool para extrair:
-- **Nomes de tabelas:** `from('leads')`, `DbSet<Lead>`, `FROM leads`
-- **Nomes de colunas:** `.select('fullname, phonenumber')`, `l.FullName`, `SELECT full_name`
-- **Tipos de dados:** TypeScript interfaces, C# DTOs, column types
-- **Relacionamentos:** JOIN clauses, navigation properties, foreign keys
-
-**Passo C: Encontrar Type Definitions**
-
-```bash
-# TypeScript/JavaScript projects:
-Glob: "src/**/types/**/*.ts"
-Glob: "src/**/*.d.ts"
-Glob: "src/**/interfaces/*.ts"
-
-# .NET projects:
-Glob: "**/*Dto.cs"
-Glob: "**/Entities/**/*.cs"
-Glob: "**/Models/**/*.cs"
-```
-
-Leia cada arquivo e mapeie:
-- Interface/Type → Database Table
-- Property names → Column names
-- Data types → SQL types
-
-**Passo D: Inferir Schema Real**
-
-Com base nos arquivos lidos, criar um mapa:
-
-```markdown
-| Frontend/Code | Database | Type | Notes |
-|--------------|----------|------|-------|
-| user.name | users.fullname | string | MISMATCH! |
-| lead.phone | leads.phonenumber | string | MISMATCH! |
-| order.metadata | orders.metadata | JSONB | Complex type |
-| user.orders | users → orders (1:N) | relation | Foreign key: orders.user_id |
-```
-
-#### 2.4. Criar SCHEMA-ANALYSIS.md
-
-Documente os findings em `.morph/features/$ARGUMENTS/1-design/schema-analysis.md`:
-
-```markdown
-# Schema Analysis - {Feature Name}
-
-**Date:** {DATE}
-**Method:** {MCP Supabase / Manual Code Analysis}
-
-## Tables Analyzed
-
-### Table: leads
-
-**Source:**
-- MCP: supabase.list_tables()
-- Code: src/lib/database/queries.ts
-
-**Columns:**
-| Column Name | Type | Nullable | Default | Notes |
-|------------|------|----------|---------|-------|
-| id | uuid | NO | gen_random_uuid() | Primary key |
-| fullname | varchar(255) | NO | - | NOT 'name'! |
-| phonenumber | varchar(20) | YES | - | NOT 'phone'! |
-| metadata | jsonb | YES | {} | Complex object |
-| created_at | timestamptz | NO | now() | Auto-generated |
-| user_id | uuid | YES | - | FK to users table |
-
-**Relationships:**
-- leads.user_id → users.id (N:1)
-- leads.id ← roulette_spins.lead_id (1:N)
-
-**Indexes:**
-- PRIMARY KEY (id)
-- INDEX idx_leads_user_id ON (user_id)
-
-### Table: users
-{Repetir para cada tabela}
-
-## ⚠️ CRITICAL FINDINGS
-
-**Field Name Mismatches (MUST FIX):**
-- ❌ Use `fullname`, NOT `name` (column doesn't exist!)
-- ❌ Use `phonenumber`, NOT `phone` (column doesn't exist!)
-
-**Type Mismatches:**
-- ⚠️ `metadata` is JSONB, not `Record<string, string>` (use proper type)
-
-**Relationship Corrections:**
-- ✅ Lead → User is N:1 (NOT 1:1)
-- ✅ Lead → RouletteSpins is 1:N (NOT 1:1)
-
-## Recommendations for contracts.cs
-
-Based on real schema, DTOs should use:
-\`\`\`csharp
-public record LeadDto(
-    Guid Id,
-    string Fullname,        // NOT 'Name'!
-    string? Phonenumber,    // NOT 'Phone'! Nullable!
-    JsonObject? Metadata,   // NOT Record<string,string>!
-    Guid? UserId,           // Nullable FK
-    DateTime CreatedAt
-);
-\`\`\`
-```
-
-#### 2.5. CHECKPOINT OBRIGATÓRIO: Revisar Schema Analysis
-
-**⏸️ PAUSE - Validar findings antes de continuar:**
-
-Apresente ao usuário:
-- [ ] Analisei {N} arquivos de código
-- [ ] Identifiquei {N} tabelas: {lista}
-- [ ] Encontrei {N} field name mismatches
-- [ ] Encontrei {N} type mismatches
-- [ ] Mapeei {N} relacionamentos
-- [ ] Criei `schema-analysis.md` com todos os findings
-
-**Perguntas ao usuário:**
-1. "O schema analysis está correto?"
-2. "Encontrei field mismatches (fullname vs name). Confirma?"
-3. "Posso prosseguir para gerar contracts.cs com base nesse schema real?"
-
-**❌ Se usuário responder "Não" ou encontrar erros:**
-→ VOLTAR e revisar análise
-→ Corrigir schema-analysis.md
-→ Re-apresentar para aprovação
-
-**✅ Se usuário aprovar:**
-→ Prosseguir para Passo 3 (Gerar spec.md)
-
-#### 2.6. Atualizar State
-
-```bash
-npx morph-spec state mark-output $ARGUMENTS schema-analysis
-```
-
 ### Passo 3: Gerar `spec.md`
 
 Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:

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*

package/framework/skills/level-1-workflows/{phase-implement.md → phase-implement/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: phase-implement
-description: >
-  MORPH-SPEC Phase 5 (Implement). Executes tasks.md task-by-task with checkpoint validation every 3 tasks, producing code and recap.md. Called by /morph-apply.
+description: MORPH-SPEC Phase 5 (Implement). Executes feature tasks using TDD with checkpoint validation every 3 tasks, smoke tests via Playwright, and generates code + recap.md. Use after task list approval when starting feature implementation.
 argument-hint: "[feature-name]"
 disable-model-invocation: true
 context: fork
@@ -25,8 +24,9 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **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/recap-example.md` — filled-in recap.md showing expected output quality.
 
 | Ação | Ferramenta | Alternativa |
 |------|------------|-------------|

package/framework/skills/level-1-workflows/phase-implement/references/recap-example.md

@@ -0,0 +1,132 @@
+# Feature Recap: Photo Processing Pipeline
+
+> Example of a well-structured recap.md. Filled-in reference — not a template.
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | photo-processing |
+| **Completed** | 2025-01-22 |
+| **Total Tasks** | 11 / 11 |
+| **Time Spent** | ~9h |
+| **Agents Used** | dotnet-senior, azure-architect, blazor-builder |
+| **Stack** | blazor-azure |
+
+---
+
+## Tasks Completed
+
+| ID | Title | Category | Duration |
+|----|-------|----------|----------|
+| T001 | Define C# contracts and interfaces | Contract | 25min |
+| T002 | Create ProcessingJob entity and enum | Domain | 30min |
+| T003 | EF Core migration and DbContext setup | Infrastructure | 50min |
+| T004 | Azure Blob Storage service | Infrastructure | 45min |
+| T005 | Implement PhotoProcessingService | Service | 65min |
+| T006 | Implement Hangfire background job | Job | 70min |
+| T007 | Upload and status endpoints | API | 40min |
+| T008 | Blazor upload page component | UI | 60min |
+| T009 | Blazor status polling page | UI | 65min |
+| T010 | Unit tests for PhotoProcessingService | Test | 55min |
+| T011 | Integration tests for upload + status API | Test | 70min |
+
+---
+
+## What Was Delivered
+
+### Functionality
+- Photo upload via Blazor form (10MB limit, .jpg/.png only)
+- Azure Blob Storage integration with `uploads/{jobId}/original.jpg` path structure
+- Hangfire background job with 3-retry exponential backoff (5s/30s/120s)
+- Real-time status polling page (5s interval, stops on terminal state)
+- Download redirect for completed jobs
+
+### Backend (.NET)
+- Endpoints: `POST /api/upload`, `GET /api/status/{id}`, `GET /api/download/{id}`
+- Services: `PhotoProcessingService`, `PhotoProcessingJob`
+- Simulation: `FakeBlobStorageService`, `FakePhotoProcessingJob` for dev mode
+
+### Frontend (Blazor)
+- Pages: `Upload.razor`, `ProcessingStatus.razor`
+- Polling via `PeriodicTimer` — no SignalR dependency
+
+---
+
+## Files Created
+
+```
+src/Domain/Entities/ProcessingJob.cs
+src/Domain/Enums/ProcessingStatus.cs
+src/Application/PhotoProcessing/Interfaces/IPhotoProcessingService.cs
+src/Application/PhotoProcessing/Commands/UploadPhotoCommand.cs
+src/Application/PhotoProcessing/Queries/GetJobStatusQuery.cs
+src/Application/PhotoProcessing/DTOs/JobStatusDto.cs
+src/Application/PhotoProcessing/PhotoProcessingService.cs
+src/Application/PhotoProcessing/PhotoProcessingJob.cs
+src/Application/PhotoProcessing/FakePhotoProcessingJob.cs
+src/Infrastructure/Storage/IBlobStorageService.cs
+src/Infrastructure/Storage/AzureBlobStorageService.cs
+src/Infrastructure/Storage/FakeBlobStorageService.cs
+src/Infrastructure/Persistence/Configurations/ProcessingJobConfiguration.cs
+src/Web/Endpoints/PhotoProcessingEndpoints.cs
+src/Web/Pages/Upload.razor + .cs
+src/Web/Pages/ProcessingStatus.razor + .cs
+tests/Unit/Application/PhotoProcessing/PhotoProcessingServiceTests.cs
+tests/Integration/Api/PhotoProcessingEndpointTests.cs
+tests/Integration/Fixtures/PhotoProcessingApiFixture.cs
+```
+
+## Files Modified
+
+```
+src/Infrastructure/Persistence/AppDbContext.cs
+src/Infrastructure/DependencyInjection.cs
+src/Application/DependencyInjection.cs
+src/Web/Program.cs
+```
+
+---
+
+## Architecture Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| PeriodicTimer for polling (not SignalR) | Simpler, no hub overhead, sufficient at MVP scale |
+| FakeBlobStorageService as Singleton | Stores in-memory dict; Scoped would lose state between requests |
+| Hangfire RetryCount on entity (not Hangfire built-in) | Domain owns retry state; allows custom error messages per attempt |
+
+See full ADRs in `decisions.md`
+
+---
+
+## Test Coverage
+
+| Type | Files | Notes |
+|------|-------|-------|
+| Unit | `PhotoProcessingServiceTests.cs` | Happy path, invalid type, size limit, 404, all statuses |
+| Integration | `PhotoProcessingEndpointTests.cs` | POST /upload, GET /status, GET /download (completed + pending) |
+
+---
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|-----------|
+| `FakeBlobStorageService` registered as `Scoped` — lost uploads between requests | Changed to `Singleton` per simulation-checklist.md |
+| `PeriodicTimer` not stopping on component dispose | Added `CancellationTokenSource` + dispose pattern in `ProcessingStatus.razor.cs` |
+
+---
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tasks Completed | 11 / 11 |
+| Checkpoints Passed | 3 (after T003, T006, T009) |
+| Bugs Found | 2 |
+| Bugs Fixed | 2 |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/{phase-setup.md → phase-setup/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: phase-setup
-description: >
-  MORPH-SPEC Phase 1 (Setup). Reads project context, identifies the stack, activates relevant agents, and creates the feature folder structure. Called at the start of every feature.
+description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents via detect-agents, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
@@ -21,7 +20,7 @@ Inicialize o contexto e prepare o ambiente para uma feature aprovada.
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **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.
 
 | Ação | Ferramenta | Alternativa |

package/framework/skills/level-1-workflows/{phase-tasks.md → phase-tasks/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: phase-tasks
-description: >
-  MORPH-SPEC Phase 4 (Tasks). Breaks the approved design into ordered implementation tasks with dependencies and checkpoints, producing tasks.md. Called after clarifications resolve.
+description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ordered implementation tasks (T001...TXXX) with dependencies, checkpoints every 3 tasks, and effort estimates, producing tasks.md. Use after design and clarification phases to create a structured implementation plan before coding starts.
 argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
@@ -22,8 +21,10 @@ Quebre a especificação em tasks executáveis, defina ordem de execução e est
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **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/tasks-example.md` — filled-in tasks.md showing expected granularity and format.
+> **Script:** `scripts/validate-tasks.mjs` — validates tasks.md structure, T### IDs, and required fields.
 
 | Ação | Ferramenta | Alternativa |
 |------|------------|-------------|