@polymorphism-tech/morph-spec 4.13.0 → 4.14.0

package/framework/skills/level-1-workflows/morph-phase-tasks/references/task-planning-patterns.md

@@ -1,170 +1,143 @@
-# Task Planning Patterns — VSA e DDD
-
-> Padrões detalhados de task planning para VSA e DDD.
-> Referenciado pelos Passos 0.5 e 0.6 de `phase-tasks/SKILL.md`.
-
----
-
-## Padrão VSA (Vertical Slice Architecture)
-
-**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
-### Categorias de tasks VSA
-
-Uma task por slice — Handler + Validator + Endpoint juntos:
-
-| Categoria | Descrição | Arquivo(s) |
-|-----------|-----------|------------|
-| **entity** | Entity class + DbSet no ApplicationDbContext | `Entities/{Entity}.cs`, `Database/ApplicationDbContext.cs` |
-| **errors** | `{Entity}Errors` static class com factory methods | `Features/{Entity}Feature/{Entity}Errors.cs` |
-| **tags** | Constante em ApiTags (se tag nova) | `Constants/ApiTags.cs` |
-| **migration** | `dotnet ef migrations add` + `database update` | `Migrations/...` |
-| **slice** | Slice completo: Handler (+ Request + Response records) + Validator + Endpoint | `Features/{Entity}Feature/{Op}/{Op}Handler.cs`, `...Validator.cs`, `...Endpoint.cs` |
-| **tests** | Unit tests dos handlers | `Tests/Features/{Entity}Feature/...` |
-| **docs** | README, Swagger, comentários | — |
-
-### Ordem obrigatória (bottom-up VSA)
-
-```
-T001: Entity + DbContext DbSet
-   ↓
-T002: {Entity}Errors (factory methods)
-   ↓
-T003: ApiTags constant (se tag ainda não existe)
-   ↓
-T004: Migration (Add{Entity} + database update)
-   ↓
-T005: Slice Create{Entity}     ← Handler+Validator+Endpoint = 1 task
-T006: Slice GetAll{Entity}s    ← Handler+Endpoint = 1 task (sem Validator)
-T007: Slice Get{Entity}ById    ← Handler+Validator+Endpoint = 1 task
-T008: Slice Update{Entity}     ← Handler+Validator+Endpoint = 1 task
-T009: Slice Delete{Entity}     ← Handler+Validator+Endpoint = 1 task
-   ↓
-T010+: Slices customizados (operações extra do VSA Blueprint)
-   ↓
-T0NN: Tests
-```
-
-### Regras VSA para tasks
-
-- 1 task = 1 slice completo (Handler + Validator + Endpoint num único task)
-- `GetAll` NÃO tem Validator — mencionar explicitamente no task
-- Cada task de slice lista os 3 arquivos que devem ser criados no campo `files`
-- Entity task deve incluir a linha `DbSet<{Entity}>` no `ApplicationDbContext`
-- Migration task é separada da entity task (pode rodar em paralelo com errors + tags)
-
-### Exemplos de tasks VSA
-
-```json
-{ "id": "T001", "title": "Criar Entity Book + registrar DbSet no ApplicationDbContext",
-  "category": "entity", "dependencies": [],  "estimatedMinutes": 20,
-  "files": ["Entities/Book.cs", "Database/ApplicationDbContext.cs"] }
-
-{ "id": "T002", "title": "Criar BookErrors (NotFound + outros factory methods)",
-  "category": "errors", "dependencies": ["T001"], "estimatedMinutes": 10,
-  "files": ["Features/BookFeature/BookErrors.cs"] }
-
-{ "id": "T003", "title": "Adicionar ApiTags.Books em Constants/ApiTags.cs",
-  "category": "tags", "dependencies": [], "estimatedMinutes": 5,
-  "files": ["Constants/ApiTags.cs"] }
-
-{ "id": "T004", "title": "Criar migration AddBook + aplicar ao banco",
-  "category": "migration", "dependencies": ["T001"], "estimatedMinutes": 10,
-  "files": ["Migrations/...AddBook.cs"] }
-
-{ "id": "T005", "title": "Implementar slice CreateBook (Handler + Validator + Endpoint)",
-  "category": "slice", "dependencies": ["T001", "T002", "T003", "T004"],
-  "estimatedMinutes": 45,
-  "files": [
-    "Features/BookFeature/CreateBook/CreateBookHandler.cs",
-    "Features/BookFeature/CreateBook/CreateBookValidator.cs",
-    "Features/BookFeature/CreateBook/CreateBookEndpoint.cs"
-  ] }
-
-{ "id": "T006", "title": "Implementar slice GetAllBooks (Handler + Endpoint, sem Validator)",
-  "category": "slice", "dependencies": ["T001", "T004"], "estimatedMinutes": 25,
-  "files": [
-    "Features/BookFeature/GetAllBooks/GetAllBooksHandler.cs",
-    "Features/BookFeature/GetAllBooks/GetAllBooksEndpoint.cs"
-  ] }
-```
-
----
-
-## Padrão DDD — Mapeamento de Níveis para Categorias
-
-### Categorias por nível de complexidade
-
-| Nível | Categorias de Tasks |
-|-------|---------------------|
-| **1 — CRUD** | `domain` (Entity simples) → `infrastructure` (Repository, EF Config) → `application` (Service CRUD) → `presentation` (API/Page) → `tests` |
-| **2 — Business Logic** | `domain` (AggregateRoot, ValueObjects, DomainEvents) → `infrastructure` (Repository, EF Config) → `application` (Commands, Queries, Handlers) → `presentation` (API/Page) → `tests` |
-| **3 — Bounded Context** | `domain-bc` (BC setup, Aggregates, Events) → `infrastructure` (BC repositories, EF) → `application` (Commands, Queries, Integration handlers) → `presentation` → `tests` |
-
-**Nível 1:** Nenhuma task adicional obrigatória — apenas o padrão CRUD nas categorias listadas.
-
-### Tasks adicionais obrigatórias por nível
-
-**Nível 2 apenas:**
-- `T{N}: Implementar AggregateRoot {EntityName} com factory method e invariants` (domain)
-- `T{N}: Implementar ValueObjects: {lista do Aggregate Blueprint}` (domain)
-- `T{N}: Implementar DomainEvents: {lista do Aggregate Blueprint}` (domain)
-- `T{N}: Implementar Command Handlers com MediatR` (application)
-- `T{N}: Implementar Query Handlers com read models` (application)
-
-**Nível 3 apenas (além do Nível 2):**
-- `T{N}: Configurar namespace/pasta do Bounded Context {BoundedContext}` (infrastructure)
-- `T{N}: Implementar Integration Events para comunicação cross-BC` (domain-bc)
-- `T{N}: Implementar handlers de Integration Events` (application)
-
----
-
-## Estrutura de Task (formato JSON)
-
-```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"
-  ]
-}
-```
-
-## Categorias de Tasks (DDD)
-
-| 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 |
-
-## Ordem de Implementação Bottom-Up
-
-```
-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)
-```
+# Task Planning Patterns — VSA
+
+> Padrões detalhados de task planning para Vertical Slice Architecture.
+> Referenciado pelos Passos 0.5 e 0.6 de `phase-tasks/SKILL.md`.
+
+---
+
+## Padrão VSA (Vertical Slice Architecture)
+
+**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
+
+### Categorias de tasks VSA
+
+Uma task por slice — Handler + Validator + Endpoint juntos:
+
+| Categoria | Descrição | Arquivo(s) |
+|-----------|-----------|------------|
+| **entity** | Entity class + DbSet no ApplicationDbContext | `Entities/{Entity}.cs`, `Database/ApplicationDbContext.cs` |
+| **errors** | `{Entity}Errors` static class com factory methods | `Features/{Entity}Feature/{Entity}Errors.cs` |
+| **tags** | Constante em ApiTags (se tag nova) | `Constants/ApiTags.cs` |
+| **migration** | `dotnet ef migrations add` + `database update` | `Migrations/...` |
+| **slice** | Slice completo: Handler (+ Request + Response records) + Validator + Endpoint | `Features/{Entity}Feature/{Op}/{Op}Handler.cs`, `...Validator.cs`, `...Endpoint.cs` |
+| **tests** | Unit tests dos handlers | `Tests/Features/{Entity}Feature/...` |
+| **docs** | README, Swagger, comentários | — |
+
+### Ordem obrigatória (bottom-up VSA)
+
+```
+T001: Entity + DbContext DbSet
+   ↓
+T002: {Entity}Errors (factory methods)
+   ↓
+T003: ApiTags constant (se tag ainda não existe)
+   ↓
+T004: Migration (Add{Entity} + database update)
+   ↓
+T005: Slice Create{Entity}     ← Handler+Validator+Endpoint = 1 task
+T006: Slice GetAll{Entity}s    ← Handler+Endpoint = 1 task (sem Validator)
+T007: Slice Get{Entity}ById    ← Handler+Validator+Endpoint = 1 task
+T008: Slice Update{Entity}     ← Handler+Validator+Endpoint = 1 task
+T009: Slice Delete{Entity}     ← Handler+Validator+Endpoint = 1 task
+   ↓
+T010+: Slices customizados (operações extra do VSA Blueprint)
+   ↓
+T0NN: Tests
+```
+
+### Regras VSA para tasks
+
+- 1 task = 1 slice completo (Handler + Validator + Endpoint num único task)
+- `GetAll` NÃO tem Validator — mencionar explicitamente no task
+- Cada task de slice lista os 3 arquivos que devem ser criados no campo `files`
+- Entity task deve incluir a linha `DbSet<{Entity}>` no `ApplicationDbContext`
+- Migration task é separada da entity task (pode rodar em paralelo com errors + tags)
+
+### Exemplos de tasks VSA
+
+```json
+{ "id": "T001", "title": "Criar Entity Book + registrar DbSet no ApplicationDbContext",
+  "category": "entity", "dependencies": [],  "estimatedMinutes": 20,
+  "files": ["Entities/Book.cs", "Database/ApplicationDbContext.cs"] }
+
+{ "id": "T002", "title": "Criar BookErrors (NotFound + outros factory methods)",
+  "category": "errors", "dependencies": ["T001"], "estimatedMinutes": 10,
+  "files": ["Features/BookFeature/BookErrors.cs"] }
+
+{ "id": "T003", "title": "Adicionar ApiTags.Books em Constants/ApiTags.cs",
+  "category": "tags", "dependencies": [], "estimatedMinutes": 5,
+  "files": ["Constants/ApiTags.cs"] }
+
+{ "id": "T004", "title": "Criar migration AddBook + aplicar ao banco",
+  "category": "migration", "dependencies": ["T001"], "estimatedMinutes": 10,
+  "files": ["Migrations/...AddBook.cs"] }
+
+{ "id": "T005", "title": "Implementar slice CreateBook (Handler + Validator + Endpoint)",
+  "category": "slice", "dependencies": ["T001", "T002", "T003", "T004"],
+  "estimatedMinutes": 45,
+  "files": [
+    "Features/BookFeature/CreateBook/CreateBookHandler.cs",
+    "Features/BookFeature/CreateBook/CreateBookValidator.cs",
+    "Features/BookFeature/CreateBook/CreateBookEndpoint.cs"
+  ] }
+
+{ "id": "T006", "title": "Implementar slice GetAllBooks (Handler + Endpoint, sem Validator)",
+  "category": "slice", "dependencies": ["T001", "T004"], "estimatedMinutes": 25,
+  "files": [
+    "Features/BookFeature/GetAllBooks/GetAllBooksHandler.cs",
+    "Features/BookFeature/GetAllBooks/GetAllBooksEndpoint.cs"
+  ] }
+```
+
+---
+
+## Estrutura de Task (formato JSON)
+
+```json
+{
+  "id": "T001",
+  "title": "Criar Entity {Nome}",
+  "description": "Implementar entity {Nome} com propriedades X, Y, Z seguindo padrões EF Core",
+  "category": "entity",
+  "dependencies": [],
+  "estimatedMinutes": 30,
+  "status": "pending",
+  "specSections": ["## Domain Model", "## Business Rules"],
+  "contractInterfaces": ["I{Nome}Repository"],
+  "files": [
+    "Entities/{Nome}.cs",
+    "Database/ApplicationDbContext.cs"
+  ]
+}
+```
+
+## Categorias de Tasks (VSA)
+
+| Categoria | Descrição | Exemplos |
+|-----------|-----------|----------|
+| **entity** | Entities, Enums | Entity class, DbSet registration |
+| **errors** | Error factory classes | `{Entity}Errors.cs` |
+| **tags** | API endpoint tags | `ApiTags.cs` constants |
+| **migration** | DB migrations | EF migrations |
+| **slice** | Complete VSA slice | Handler + Validator + Endpoint |
+| **tests** | Unit tests, Integration tests | Handler tests, API tests |
+| **infra** | Docker, Migrations, Scripts | docker-compose, Supabase migrations |
+| **docs** | README, API docs | OpenAPI spec, README update |
+
+## Ordem de Implementação Bottom-Up (VSA)
+
+```
+1. Entity + DbContext registration
+   ↓
+2. Errors + ApiTags
+   ↓
+3. Migrations
+   ↓
+4. Slices (Handler + Validator + Endpoint per operation)
+   ↓
+5. Tests (Unit → Integration)
+   ↓
+6. Infra (Docker, Supabase migrations)
+   ↓
+7. Docs (README, Swagger)
+```

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (UI/UX). Creates design-system.md, mockups.md, c
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.13.0"
+cliVersion: "4.14.0"
 ---
 
 # MORPH UI/UX Design - Phase 2

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -4,7 +4,7 @@ description: Guided workflow for mid-implementation scope escalation — analyze
 user-invocable: true
 argument-hint: "[feature-name]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.13.0"
+cliVersion: "4.14.0"
 ---
 
 # Scope Escalation Workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/utils/agents-installer.js

@@ -103,23 +103,31 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 /**
  * Tier-based defaults for Claude Code subagent frontmatter fields.
  *
- * Tier 1 (Orchestrators): can spawn subagents via Task tool, 30 turns, project memory.
- * Tier 2 (Domain Leaders): coordinate specialists but do not spawn subagents, 20 turns, local memory.
+ * Tier 1 (Orchestrators): opus model, can spawn subagents via Agent tool, 30 turns, project memory, high effort.
+ * Tier 2 (Domain Leaders): sonnet model, coordinate specialists, 20 turns, local memory, medium effort.
+ * Tier 3 (Specialists): sonnet model, implementation focus, 15 turns, local memory, medium effort.
+ * Tier 4 (Validators): haiku model, read-only scanning, 10 turns, background execution, low effort.
  */
 const TIER_DEFAULTS = {
   1: {
-    model: 'inherit',
-    tools: 'Read, Grep, Glob, Bash, Task, Write, Edit',
+    model: 'opus',
+    tools: 'Read, Grep, Glob, Bash, Agent, Write, Edit',
     maxTurns: 30,
     skills: ['morph-checklist'],
     memory: 'project',
+    effort: 'high',
+    permissionMode: 'acceptEdits',
+    background: false,
   },
   2: {
-    model: 'inherit',
+    model: 'sonnet',
     tools: 'Read, Write, Edit, Bash, Glob, Grep',
     maxTurns: 20,
     skills: ['morph-checklist'],
     memory: 'local',
+    effort: 'medium',
+    permissionMode: 'acceptEdits',
+    background: false,
   },
   3: {
     model: 'sonnet',
@@ -127,6 +135,9 @@ const TIER_DEFAULTS = {
     maxTurns: 15,
     skills: [],
     memory: 'local',
+    effort: 'medium',
+    permissionMode: 'default',
+    background: false,
   },
   4: {
     model: 'haiku',
@@ -134,6 +145,9 @@ const TIER_DEFAULTS = {
     maxTurns: 10,
     skills: [],
     memory: 'project',
+    effort: 'low',
+    permissionMode: 'plan',
+    background: true,
   },
 };
 
@@ -149,10 +163,14 @@ function buildFrontmatter(agent, description) {
   const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
   const name = agent.title ?? agent.name;
 
-  // Allow per-agent tool overrides (e.g., morph-spec-validator needs Bash for npm test)
+  // Allow per-agent overrides from teammate config
   const tools = agent.teammate?.tools ?? defaults.tools;
-  // Allow per-agent maxTurns override
   const maxTurns = agent.teammate?.maxTurns ?? defaults.maxTurns;
+  const effort = agent.teammate?.effort ?? defaults.effort;
+  const permissionMode = agent.teammate?.permissionMode ?? defaults.permissionMode;
+  const background = agent.teammate?.background ?? defaults.background;
+  // color is a top-level field on the agent (not inside teammate)
+  const color = agent.color;
 
   const lines = [
     `name: ${name}`,
@@ -162,6 +180,11 @@ function buildFrontmatter(agent, description) {
     `maxTurns: ${maxTurns}`,
   ];
 
+  if (color) lines.push(`color: ${color}`);
+  if (effort) lines.push(`effort: ${effort}`);
+  if (permissionMode && permissionMode !== 'default') lines.push(`permissionMode: ${permissionMode}`);
+  if (background) lines.push(`background: true`);
+
   if (defaults.skills.length > 0) {
     const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
     lines.push(`skills:`, skillsList);
@@ -183,11 +206,18 @@ const GROUP_TO_CATEGORIES = {
 
 function buildDescription(agent) {
   const role = agent.teammate?.role ?? `Handles ${(agent.domains ?? []).join(', ')}`;
+  const triggers = agent.teammate?.triggers;
   const categories = GROUP_TO_CATEGORIES[agent.group];
-  const suffix = categories ? ` | Tasks: ${categories}` : '';
-  const full = `${role}${suffix}`;
+
+  let desc = role;
+  if (triggers) {
+    desc += `. Use proactively when: ${triggers}`;
+  } else if (categories) {
+    desc += ` | Tasks: ${categories}`;
+  }
+
   // Truncate to 200 chars for settings display
-  return full.length > 200 ? full.slice(0, 197) + '...' : full;
+  return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
 }
 
 /**