@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/skills/level-1-workflows/phase-clarify.md

@@ -0,0 +1,131 @@
+# MORPH Clarify - FASE 3
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Identifique ambiguidades na especificação e faça perguntas de clarificação para garantir que todos os edge cases estão cobertos.
+
+## Pré-requisitos
+
+- [ ] FASE 2 (Design) concluída
+- [ ] `spec.md` aprovado pelo usuário
+- [ ] `contracts.cs` definidos
+
+## Workflow
+
+### Passo 1: Analisar Spec
+
+Leia `.morph/project/outputs/{feature}/spec.md` em detalhes e identifique:
+
+#### 1.1. Ambiguidades
+- Requisitos vagos ou genéricos
+- Termos sem definição clara
+- Comportamentos não especificados
+
+#### 1.2. Edge Cases Não Documentados
+- O que acontece se...?
+- Como lidar com entradas inválidas?
+- Comportamento em caso de erro?
+- Estados intermediários (loading, empty)
+
+#### 1.3. Requisitos Conflitantes
+- Duas funcionalidades que parecem incompatíveis
+- Prioridades não claras (o que vem primeiro?)
+
+#### 1.4. Dados Faltantes
+- Validações de negócio não especificadas
+- Limites e constraints (tamanhos, quantidades)
+- Formatos de dados (datas, moedas, etc.)
+
+### Passo 2: Gerar Perguntas de Clarificação
+
+Com base na análise, gere **3-7 perguntas** focadas e específicas:
+
+**Formato de pergunta:**
+```markdown
+### Q{N}: {Categoria} - {Título}
+
+**Context:** {Por que esta pergunta é importante}
+
+**Question:** {Pergunta clara e objetiva}
+
+**Options (if applicable):**
+- A) {Opção 1}
+- B) {Opção 2}
+- C) {Deixar em aberto/usuário decidir}
+
+**Impact:** {Como a resposta afeta a implementação}
+```
+
+### Passo 3: Categorizar Perguntas
+
+Organize perguntas por categoria:
+
+| Categoria | Descrição | Exemplos |
+|-----------|-----------|----------|
+| **Validação** | Regras de negócio, constraints | Limites de tamanho, formatos aceitos |
+| **Comportamento** | O que acontece quando... | Error handling, estados vazios |
+| **Prioridade** | O que é must-have vs nice-to-have | MVP vs futuras iterações |
+| **Integração** | Como interage com sistemas externos | APIs, webhooks, formato de dados |
+| **Performance** | Requisitos de velocidade/volume | Quantos registros? Tempo de resposta? |
+| **UX** | Experiência do usuário | Feedback visual, mensagens de erro |
+
+### Passo 4: Apresentar Perguntas ao Usuário
+
+Liste todas as perguntas de forma clara e estruturada.
+
+**IMPORTANTE:** Não prossiga para próxima fase até ter respostas!
+
+### Passo 5: Atualizar `spec.md` com Respostas
+
+Após receber respostas do usuário, atualize o spec com:
+
+1. **Seção de Clarificações** no início do spec:
+```markdown
+## Clarifications (FASE 3)
+
+### Q1: {Título}
+**Answer:** {Resposta do usuário}
+**Date:** {YYYY-MM-DD}
+```
+
+2. **Atualizar seções relevantes** com detalhes adicionados
+
+### Passo 6: Validar Edge Cases
+
+Documente no spec como lidar com cada edge case identificado:
+
+```markdown
+## Edge Cases
+
+### EC001: {Nome do Edge Case}
+**Scenario:** {Quando acontece}
+**Expected Behavior:** {Como o sistema deve reagir}
+**Implementation Notes:** {Dicas para implementação}
+```
+
+### Passo 7: Atualizar State
+
+```bash
+npx morph-spec state set {feature-name} phase clarify
+```
+
+## Outputs Gerados/Atualizados
+
+- `.morph/project/outputs/{feature}/spec.md` - Atualizado com:
+  - Seção "Clarifications" com perguntas e respostas
+  - Edge cases documentados
+  - Requisitos mais específicos
+
+## Critérios de Avanço
+
+- [x] Perguntas de clarificação identificadas (3-7)
+- [x] Perguntas apresentadas ao usuário
+- [x] Respostas do usuário recebidas
+- [x] `spec.md` atualizado com clarificações
+- [x] Edge cases documentados
+- [x] State atualizado
+- [x] Nenhuma ambiguidade crítica remanescente
+
+---
+
+Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.

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

@@ -0,0 +1,213 @@
+# 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
+
+## Workflow
+
+### Passo 1: Carregar Contexto e Standards
+
+**Obtenha feature state e standards context:**
+
+```bash
+npx morph-spec state get {feature-name}
+```
+
+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/project/outputs/{feature}/proposal.md` - Proposta inicial
+2. `.morph/project/outputs/{feature}/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: Gerar `spec.md`
+
+Crie `.morph/project/outputs/{feature}/spec.md` com:
+
+#### 2.1. Overview
+- **Objetivo:** Resumo de 1-2 parágrafos
+- **Usuários afetados:** Quem vai usar?
+- **Problema resolvido:** Qual dor/necessidade?
+
+#### 2.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
+```
+
+#### 2.3. Non-Functional Requirements
+- Performance (tempos de resposta esperados)
+- Segurança (autenticação, autorização)
+- Escalabilidade (volume de dados/usuários)
+- Disponibilidade (uptime esperado)
+
+#### 2.4. Technical Architecture
+- **Camadas:** (Presentation, Application, Domain, Infrastructure)
+- **Patterns:** (Repository, CQRS, DI, etc.)
+- **Dependências:** Bibliotecas/serviços externos necessários
+
+#### 2.5. Data Model
+- Entities principais
+- Relacionamentos (1:1, 1:N, N:N)
+- Campos obrigatórios vs opcionais
+- Validações de negócio
+
+#### 2.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 3: Gerar `contracts.cs`
+
+Crie `.morph/project/outputs/{feature}/contracts.cs` com:
+
+```csharp
+// Interfaces, DTOs, Enums, Value Objects
+
+namespace {ProjectName}.Features.{FeatureName};
+
+// DTOs (Data Transfer Objects)
+public record {Feature}CreateDto(
+    string Name,
+    DateTime Date
+);
+
+public record {Feature}ResponseDto(
+    Guid Id,
+    string Name,
+    DateTime Date,
+    DateTime CreatedAt
+);
+
+// Interfaces
+public interface I{Feature}Service
+{
+    Task<{Feature}ResponseDto> CreateAsync({Feature}CreateDto dto, CancellationToken ct);
+    Task<{Feature}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct);
+}
+
+// Enums
+public enum {Feature}Status
+{
+    Pending,
+    Active,
+    Completed
+}
+```
+
+**Padrões obrigatórios:**
+- Records para DTOs (immutable)
+- Interfaces para serviços
+- CancellationToken em métodos async
+- Nullable reference types habilitados
+
+### Passo 4: Iniciar `decisions.md`
+
+Crie `.morph/project/outputs/{feature}/decisions.md` com ADRs relevantes:
+
+```markdown
+# Architectural Decision Records (ADRs)
+
+## ADR-001: {Decisão Arquitetural}
+
+**Status:** Proposed/Accepted/Deprecated
+
+**Context:**
+{Por que esta decisão foi necessária}
+
+**Decision:**
+{O que foi decidido}
+
+**Consequences:**
+**Pros:**
+- Pro 1
+
+**Cons:**
+- Con 1
+
+**Alternatives Considered:**
+- Alternativa 1: {Por que foi rejeitada}
+
+**Date:** {YYYY-MM-DD}
+```
+
+**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.)
+
+### Passo 5: 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 {feature-name} costs.estimated {X.XX}
+npx morph-spec state set {feature-name} costs.approved {true/false}
+```
+
+### Passo 6: Atualizar State
+
+```bash
+npx morph-spec state set {feature-name} phase design
+npx morph-spec state mark-output {feature-name} spec
+npx morph-spec state mark-output {feature-name} contracts
+npx morph-spec state mark-output {feature-name} decisions
+```
+
+## Outputs Gerados
+
+- `.morph/project/outputs/{feature}/spec.md` - Especificação técnica completa
+- `.morph/project/outputs/{feature}/contracts.cs` - Interfaces, DTOs, Enums
+- `.morph/project/outputs/{feature}/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
+
+---
+
+Continuar automaticamente para FASE 3 (Clarify) após aprovação.

package/framework/skills/level-1-workflows/phase-setup.md

@@ -0,0 +1,106 @@
+# MORPH Setup - FASE 1
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Inicialize o contexto e prepare o ambiente para uma feature aprovada.
+
+## Pré-requisitos
+
+- [ ] Feature tem `proposal.md` criado (FASE 0 concluída)
+- [ ] Proposal foi aprovado pelo usuário
+- [ ] Agentes foram detectados e registrados no state
+
+## Workflow
+
+### Passo 1: Verificar State
+
+Confirme que a feature existe no state:
+
+```bash
+npx morph-spec state get {feature-name}
+```
+
+Se não existir, volte para FASE 0 (proposal).
+
+### Passo 2: Carregar Contexto e Standards Automaticamente
+
+**Use detect-agents --json para obter standards context:**
+
+```bash
+npx morph-spec detect-agents --json "{feature description from proposal}"
+```
+
+O output JSON contém `standardsSummary` com todos os standards relevantes para cada agente ativo:
+
+```json
+{
+  "standardsSummary": {
+    "blazor-builder": {
+      "standards": ["blazor-lifecycle", "blazor-state", "coding", ...],
+      "fullContent": "# blazor-lifecycle\n\n...",  // Full standards text
+      "count": 10
+    }
+  }
+}
+```
+
+**Standards resolution order** (automático):
+1. `.morph/project/standards/*.md` (project overrides - highest priority)
+2. `.morph/standards/*.md` (AI Agent Framework, Azure)
+3. `framework/standards/*.md` (Blazor, CSS, .NET)
+4. `.morph/project/standards/inferred.md` (always loaded if exists)
+
+**Contexto geral** (leia manualmente):
+- `.morph/project/context/README.md` - Overview do projeto
+- `.morph/config.json` - Configurações
+
+### Passo 3: Confirmar Stack
+
+Baseado no proposal e contexto, confirme:
+- Stack tecnológica (Blazor Server, Next.js, etc.)
+- Padrões arquiteturais aplicáveis
+- Componentes reutilizáveis existentes
+
+### Passo 4: Listar Agentes Ativos
+
+Mostre os agentes detectados no proposal:
+
+```bash
+npx morph-spec state get {feature-name}
+```
+
+Parse o JSON e liste os `activeAgents` com seus emojis e responsabilidades (consulte `.morph/config/agents.json`).
+
+### Passo 5: Atualizar State
+
+Marque a feature como na fase SETUP:
+
+```bash
+npx morph-spec state set {feature-name} phase setup
+npx morph-spec state set {feature-name} status in_progress
+```
+
+## Outputs
+
+**Apresente ao usuário:**
+
+1. **Contexto carregado**:
+   - Nome do projeto
+   - Stack confirmado
+   - Standards aplicáveis
+
+2. **Agentes ativos**:
+   - Lista de agentes com emojis
+   - Responsabilidades de cada um
+
+## Critérios de Avanço
+
+- [x] Contexto do projeto carregado
+- [x] Standards identificados (framework + project)
+- [x] Stack confirmado
+- [x] Agentes listados
+- [x] State atualizado para phase: setup
+
+---
+
+Continuar automaticamente para próxima fase (UI/UX se detectado, ou Design).

package/framework/skills/level-1-workflows/phase-tasks.md

@@ -0,0 +1,164 @@
+# MORPH Tasks - FASE 4
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Quebre a especificação em tasks executáveis, defina ordem de execução e estabeleça checkpoints.
+
+## Pré-requisitos
+
+- [ ] FASE 3 (Clarify) concluída
+- [ ] `spec.md` atualizado com clarificações
+- [ ] Todos os edge cases documentados
+
+## Workflow
+
+### Passo 1: Analisar Spec
+
+Leia `.morph/project/outputs/{feature}/spec.md` e identifique:
+
+1. **Requisitos funcionais** (FR001, FR002, ...)
+2. **Componentes técnicos** (Entities, Services, Controllers, Pages)
+3. **Infraestrutura** (Bicep, migrations, configs)
+4. **Testes** (Unit tests, integration tests)
+
+### Passo 2: Quebrar em Tasks
+
+Crie tasks no formato **T{NNN}** seguindo ordem lógica de implementação.
+
+#### 2.1. Estrutura de Task
+
+```json
+{
+  "id": "T001",
+  "title": "Criar Entity {Nome}",
+  "description": "Implementar entity {Nome} com propriedades X, Y, Z seguindo padrões EF Core",
+  "category": "domain",
+  "dependencies": [],
+  "estimatedMinutes": 30,
+  "status": "pending",
+  "specSections": ["## Domain Model", "## Business Rules"],
+  "contractInterfaces": ["I{Nome}Repository"],
+  "files": [
+    "Domain/Entities/{Nome}.cs",
+    "Infrastructure/Data/Configurations/{Nome}Configuration.cs"
+  ]
+}
+```
+
+#### 2.2. Categorias de Tasks
+
+| Categoria | Descrição | Exemplos |
+|-----------|-----------|----------|
+| **domain** | Entities, Value Objects, Enums | Entity, DomainException |
+| **application** | Services, DTOs, Interfaces | Service, Validator, Mapper |
+| **infrastructure** | DbContext, Repositories, External APIs | EF Config, Repository impl |
+| **presentation** | Controllers, Pages, Components | API endpoint, Blazor page |
+| **tests** | Unit tests, Integration tests | Service tests, API tests |
+| **infra** | Bicep, Migrations, Scripts | Azure resources, DB migration |
+| **docs** | README, API docs, Swagger | OpenAPI spec, README update |
+
+#### 2.3. Ordem de Implementação
+
+**Bottom-up approach:**
+```
+1. Domain (Entities, Enums, Value Objects)
+   ↓
+2. Infrastructure (Repositories, DbContext configs)
+   ↓
+3. Application (Services, DTOs, Business logic)
+   ↓
+4. Presentation (Controllers, Pages, Components)
+   ↓
+5. Tests (Unit → Integration)
+   ↓
+6. Infra (Bicep, Migrations, Deploy scripts)
+   ↓
+7. Docs (README, Swagger, Comments)
+```
+
+### Passo 3: Definir Dependências
+
+Para cada task, especifique dependências:
+
+```json
+{
+  "id": "T005",
+  "title": "Criar {Nome}Service",
+  "dependencies": ["T001", "T002"],
+  "status": "pending"
+}
+```
+
+**Regra:** Task só pode ser executada quando todas as dependências estão `completed`.
+
+### Passo 4: Estabelecer Checkpoints
+
+Defina checkpoints a cada **3 tasks** ou **marcos significativos**:
+
+```json
+{
+  "id": "CHECKPOINT_001",
+  "title": "Domain Layer Completo",
+  "afterTasks": ["T001", "T002", "T003"],
+  "validations": [
+    "Todas as entities criadas",
+    "Migrations aplicadas",
+    "Testes de domain passando"
+  ]
+}
+```
+
+### Passo 5: Estimar Esforço
+
+Para cada task, estime tempo em minutos:
+
+| Complexidade | Tempo Estimado |
+|--------------|----------------|
+| Trivial (CRUD básico) | 15-30 min |
+| Simples (Service, Controller) | 30-60 min |
+| Média (Business logic, validações) | 60-120 min |
+| Complexa (Integrações, AI) | 120-240 min |
+
+### Passo 6: Gerar `tasks.json`
+
+Crie `.morph/project/outputs/{feature}/tasks.json` com a estrutura completa de tasks, checkpoints e estimativas.
+
+### Passo 7: Incluir Tasks de IaC (se necessário)
+
+Se houver recursos Azure, adicionar tasks de Bicep e migrations.
+
+### Passo 8: Atualizar State
+
+```bash
+npx morph-spec state set {feature-name} phase tasks
+npx morph-spec state set {feature-name} tasks.total {N}
+npx morph-spec state mark-output {feature-name} tasks
+```
+
+## Outputs Gerados
+
+- `.morph/project/outputs/{feature}/tasks.json` - Breakdown completo de tasks
+
+## PAUSA OBRIGATÓRIA
+
+Apresente ao usuário 3 ações sugeridas:
+
+1. **Aprovar breakdown e iniciar implementação**
+2. **Repriorizar tasks** - Mudar ordem de execução
+3. **Adicionar/remover tasks** - Ajustar escopo
+
+## Critérios de Avanço
+
+- [x] `tasks.json` criado com todas as tasks
+- [x] Tasks categorizadas corretamente
+- [x] Dependências mapeadas
+- [x] Checkpoints definidos (a cada 3 tasks)
+- [x] Esforço estimado por task
+- [x] Ordem de execução clara
+- [x] Tasks de IaC incluídas (se aplicável)
+- [x] State atualizado com total de tasks
+- [x] Usuário aprovou breakdown
+
+---
+
+Após aprovação: "Planejamento completo! Execute `/morph-apply {feature}` para iniciar implementação."