@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,147 +0,0 @@
----
-name: morph-scope-escalation
-description: Guided workflow for mid-implementation scope escalation — analyzes complexity discovery, recommends action, and executes phase regression or task expansion
-user-invocable: true
-argument-hint: "[feature-name]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
----
-
-# Scope Escalation Workflow
-
-Use this skill when a task during implementation reveals significantly more complexity than estimated.
-
-## Prerequisites
-
-- Feature must be in `implement` phase
-- You must have identified a specific task that triggered the discovery
-
-## Workflow
-
-### Step 1: COLLECT Evidence
-
-Use `AskUserQuestion` to gather the details:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Task ID",
-      "question": "Which task triggered the complexity discovery?",
-      "multiSelect": false,
-      "options": [
-        { "label": "T001", "description": "First task" },
-        { "label": "T002", "description": "Second task" },
-        { "label": "Other", "description": "Type the task ID" }
-      ]
-    },
-    {
-      "header": "Discovery",
-      "question": "What complexity did you discover?",
-      "multiSelect": true,
-      "options": [
-        { "label": "Hidden dependencies", "description": "More systems involved than spec assumed" },
-        { "label": "Wrong assumptions", "description": "Spec assumed simpler architecture" },
-        { "label": "Missing abstractions", "description": "Need new patterns/interfaces not in contracts" },
-        { "label": "Other", "description": "Describe the discovery" }
-      ]
-    }
-  ]
-}
-```
-
-> Populate the Task ID options dynamically from the feature's `tasks.md`. After receiving answers, **read the relevant code files** to verify the evidence before classifying.
-
-### Step 2: ANALYZE Impact
-
-Run dry-run analysis:
-
-```bash
-morph-spec scope escalate <feature> --task <id> --reason "<reason>" --dry-run
-```
-
-Read the recommendation output. Additionally:
-
-- Read `tasks.md` to understand which tasks are affected
-- Read `spec.md` to check if the spec assumed simpler architecture
-- Check completed tasks for potential impact
-
-### Step 3: CLASSIFY and PROPOSE
-
-Present the recommendation to the user:
-
-| Impact | Action | When |
-|--------|--------|------|
-| **Low** (1-3 tasks) | Task Expansion | The task is bigger than expected, but scope is contained |
-| **Medium** (4+ tasks, spec ok) | Regress to tasks | Multiple tasks need rewriting, but the spec is correct |
-| **High** (spec wrong) | Regress to design | The spec made incorrect assumptions about the codebase |
-
-Explain WHY you recommend this classification based on the evidence.
-
-### Step 4: APPROVE
-
-Pause and wait for user confirmation using `AskUserQuestion`:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Severity",
-      "question": "Impact classified as {LOW|MEDIUM|HIGH}. Do you agree?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Agree", "description": "Classification is correct" },
-        { "label": "Override", "description": "I think the impact is different" }
-      ]
-    },
-    {
-      "header": "Action",
-      "question": "Recommended action: {action}. Proceed?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Proceed", "description": "{action description}" },
-        { "label": "Different target", "description": "I want to regress to a different phase" },
-        { "label": "Cancel", "description": "Do not escalate — continue as-is" }
-      ]
-    }
-  ]
-}
-```
-
-**DO NOT proceed without explicit user approval.** If user chooses "Cancel", stop the workflow entirely.
-
-### Step 5: EXECUTE
-
-Based on approved action:
-
-**For expansion (low impact):**
-```bash
-morph-spec task expand <feature> <task-id> --into "T017a: <title>" "T017b: <title>" ...
-```
-
-**For regression (medium/high impact):**
-```bash
-morph-spec scope escalate <feature> --task <id> --reason "<reason>"
-```
-
-Or with target override:
-```bash
-morph-spec scope escalate <feature> --task <id> --reason "<reason>" --target design
-```
-
-### Step 6: GUIDE Next Steps
-
-After escalation:
-
-- **If regressed to tasks:** "Re-analyze the affected tasks. Rewrite tasks.md with accurate scope. Run `/morph-proposal <feature>` to continue from the tasks phase."
-- **If regressed to design:** "Re-analyze the spec. Update spec.md with the discovered architecture. Then regenerate tasks."
-- **If expanded:** "Continue implementing. Use `morph-spec task start <feature> <sub-task-id>` to start the first sub-task."
-
-Always remind: "Completed tasks flagged with `needsReview` should be checked for compatibility with the new scope."
-
-## Anti-Patterns
-
-- **DO NOT** skip the approval step
-- **DO NOT** escalate without evidence — read the actual code first
-- **DO NOT** regress to design when only tasks need rewriting
-- **DO NOT** expand when 4+ tasks are affected — regress instead

package/framework/squad-templates/backend-only.json

@@ -1,47 +0,0 @@
-{
-  "id": "backend-only",
-  "name": "Backend Squad",
-  "description": "Backend-focused squad: API + data + domain logic",
-  "parallel": true,
-  "coordination": "dotnet-senior",
-  "waitForAll": true,
-  "agents": [
-    {
-      "id": "dotnet-senior",
-      "role": "Backend Squad Leader",
-      "domain": "backend",
-      "standards": ["coding.md", "architecture.md", "dotnet10-compatibility.md"]
-    },
-    {
-      "id": "ef-modeler",
-      "role": "Database/EF Core Layer",
-      "domain": "backend",
-      "standards": ["coding.md", "ef-core.md"]
-    },
-    {
-      "id": "hangfire-orchestrator",
-      "role": "Background Jobs & Scheduling",
-      "domain": "backend",
-      "standards": ["coding.md"]
-    }
-  ],
-  "deliverables": {
-    "dotnet-senior": "Application services, business logic, command/query handlers, API endpoints, DTOs",
-    "ef-modeler": "Entity models, DbContext, migrations",
-    "hangfire-orchestrator": "Background jobs, recurring tasks, job scheduling"
-  },
-  "estimatedParallelGain": "2-3x throughput vs sequential",
-  "agent_team": {
-    "team_name_pattern": "{feature}-backend",
-    "lead": "standards-architect",
-    "teammates": [
-      {
-        "id": "dotnet-senior",
-        "spawn_context": "standards/coding.md, standards/architecture/, contracts.cs, spec.md",
-        "task_scope": "backend tasks (domain logic, application services, EF Core, API endpoints, DTOs, background jobs)"
-      }
-    ],
-    "coordination_notes": "Single-domain squad — Agent Teams not required. Use subagents for parallelization.",
-    "quality_gate": "Require plan approval before implementation. Only approve plans that match contracts.cs."
-  }
-}

package/framework/squad-templates/frontend-only.json

@@ -1,56 +0,0 @@
-{
-  "id": "frontend-only",
-  "name": "Frontend Squad",
-  "description": "Frontend-focused squad: UI components + CSS + UX",
-  "parallel": true,
-  "coordination": "ui-designer",
-  "waitForAll": true,
-  "agents": [
-    {
-      "id": "ui-designer",
-      "role": "UI Design Lead",
-      "domain": "frontend",
-      "standards": [
-        "css-architecture.md",
-        "css-design-system.md"
-      ]
-    },
-    {
-      "id": "nextjs-expert",
-      "role": "Frontend Developer",
-      "domain": "frontend",
-      "standards": [
-        "coding.md",
-        "nextjs-components.md"
-      ]
-    },
-    {
-      "id": "css-specialist",
-      "role": "CSS/Design System Specialist",
-      "domain": "frontend",
-      "standards": [
-        "css-architecture.md",
-        "css-design-system.md"
-      ]
-    }
-  ],
-  "deliverables": {
-    "ui-designer": "Design system tokens, component specs, mockup annotations",
-    "nextjs-expert": "React components, pages, state management",
-    "css-specialist": "CSS modules, design system implementation, responsive layout"
-  },
-  "estimatedParallelGain": "2x throughput vs sequential",
-  "agent_team": {
-    "team_name_pattern": "{feature}-frontend",
-    "lead": "standards-architect",
-    "teammates": [
-      {
-        "id": "ui-designer",
-        "spawn_context": "standards/css-architecture.md, standards/css-design-system.md, design-system.md, spec.md",
-        "task_scope": "frontend tasks (UI components, CSS, design system implementation, responsive layout)"
-      }
-    ],
-    "coordination_notes": "Single-domain squad — Agent Teams not required. Use subagents for parallelization.",
-    "quality_gate": "Require plan approval before implementation. Only approve plans that match spec.md and design-system.md."
-  }
-}

package/framework/squad-templates/full-stack.json

@@ -1,74 +0,0 @@
-{
-  "id": "full-stack",
-  "name": "Full Stack Squad",
-  "description": "Full-stack feature squad: backend API + frontend + infra",
-  "parallel": true,
-  "coordination": "standards-architect",
-  "waitForAll": true,
-  "agents": [
-    {
-      "id": "dotnet-senior",
-      "role": "Backend Squad Leader",
-      "domain": "backend",
-      "standards": [
-        "coding.md",
-        "architecture.md",
-        "dotnet10-compatibility.md"
-      ]
-    },
-    {
-      "id": "nextjs-expert",
-      "role": "Frontend Developer",
-      "domain": "frontend",
-      "standards": [
-        "coding.md",
-        "nextjs-components.md"
-      ]
-    },
-    {
-      "id": "infra-architect",
-      "role": "Infrastructure Engineer",
-      "domain": "infrastructure",
-      "standards": [
-        "infrastructure.md"
-      ]
-    },
-    {
-      "id": "css-specialist",
-      "role": "Design System & CSS",
-      "domain": "frontend",
-      "standards": [
-        "css-design-system.md"
-      ]
-    }
-  ],
-  "deliverables": {
-    "backend": "Services, controllers, DTOs, EF Core entities",
-    "frontend": "Next.js components, pages, CSS, design system",
-    "infrastructure": "IaC templates, deployment scripts"
-  },
-  "estimatedParallelGain": "3-5x throughput vs sequential",
-  "agent_team": {
-    "team_name_pattern": "{feature}-full-stack",
-    "lead": "standards-architect",
-    "teammates": [
-      {
-        "id": "dotnet-senior",
-        "spawn_context": "standards/coding.md, standards/architecture/, contracts.cs, spec.md",
-        "task_scope": "backend tasks (domain logic, EF Core, API endpoints, DTOs)"
-      },
-      {
-        "id": "nextjs-expert",
-        "spawn_context": "standards/coding.md, standards/nextjs-components.md, design-system.md, spec.md",
-        "task_scope": "frontend tasks (pages, components, CSS, state management)"
-      },
-      {
-        "id": "infra-architect",
-        "spawn_context": "standards/infrastructure.md, spec.md",
-        "task_scope": "infrastructure tasks (IaC templates, cloud resources, deployments)"
-      }
-    ],
-    "coordination_notes": "Backend deve sinalizar quando contracts.cs/DTOs estiverem estáveis antes do frontend prosseguir com chamadas de API. Infrastructure pode executar em paralelo com backend/frontend.",
-    "quality_gate": "Require plan approval before each teammate implements. Only approve plans that match contracts.cs and spec.md."
-  }
-}

package/src/commands/agents/agent-metrics.js

@@ -1,174 +0,0 @@
-/**
- * agent-metrics — Display agent performance metrics for a feature
- *
- * Reads dispatchLog from state.json, computes per-agent metrics
- * (dispatch count, task coverage, completion rate, avg duration),
- * and renders a table or JSON output.
- *
- * Usage:
- *   morph-spec agent-metrics <feature>
- *   morph-spec agent-metrics <feature> --json
- *   morph-spec agent-metrics --all
- */
-
-import { loadState, stateExists } from '../../core/state/state-manager.js';
-import { calculateMetrics, calculateAggregatedMetrics, formatDuration } from '../../lib/agents/metrics-calculator.js';
-import chalk from 'chalk';
-
-/**
- * CLI command: morph-spec agent-metrics [feature]
- *
- * @param {string} [featureName] - Feature name (required unless --all)
- * @param {Object} [options] - CLI options
- * @param {boolean} [options.json] - Output as JSON instead of table
- * @param {boolean} [options.all] - Aggregate metrics across all features
- */
-export async function agentMetricsCommand(featureName, options = {}) {
-  if (!options.all && !featureName) {
-    console.error(chalk.red('Usage: morph-spec agent-metrics <feature> [--json] [--all]'));
-    process.exit(1);
-  }
-
-  if (!stateExists()) {
-    console.error(chalk.red('No state.json found.'));
-    process.exit(1);
-  }
-
-  const state = loadState();
-
-  if (options.all) {
-    return renderAggregated(state.features || {}, options);
-  }
-
-  const feature = state.features?.[featureName];
-  if (!feature) {
-    console.error(chalk.red(`Feature '${featureName}' not found.`));
-    process.exit(1);
-  }
-
-  const log = feature.dispatchLog || [];
-  if (log.length === 0) {
-    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
-    return;
-  }
-
-  const result = calculateMetrics(log);
-  result.feature = featureName;
-
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  renderTable(featureName, result);
-}
-
-/**
- * Render per-feature metrics table.
- */
-function renderTable(featureName, result) {
-  const { agents, summary } = result;
-
-  console.log(chalk.bold(`\n  Agent Performance \u2014 ${featureName}`));
-  console.log('  ' + '\u2500'.repeat(70));
-
-  // Header
-  console.log(
-    '  ' +
-    pad('Agent', 28) +
-    pad('Dispatches', 12) +
-    pad('Tasks', 8) +
-    pad('Completed', 12) +
-    pad('Avg Duration', 14)
-  );
-  console.log('  ' + '\u2500'.repeat(70));
-
-  for (const agent of agents) {
-    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
-    const completed = agent.tasksAssigned > 0
-      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
-      : '\u2014';
-    const duration = formatDuration(agent.avgDurationMs);
-
-    console.log(
-      '  ' +
-      pad(agent.id, 28) +
-      pad(String(agent.dispatches), 12) +
-      pad(tasks, 8) +
-      pad(completed, 12) +
-      pad(duration, 14)
-    );
-  }
-
-  console.log();
-  const rate = summary.totalTasks > 0
-    ? `${Math.round(summary.completionRate * 100)}%`
-    : '0%';
-  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
-  console.log(`  Dispatches: ${summary.totalDispatches} total`);
-  console.log();
-}
-
-/**
- * Render aggregated metrics across all features.
- */
-function renderAggregated(features, options) {
-  const featureNames = Object.keys(features);
-  if (featureNames.length === 0) {
-    console.log(chalk.gray('\n  No features found.\n'));
-    return;
-  }
-
-  const result = calculateAggregatedMetrics(features);
-
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  console.log(chalk.bold(`\n  Agent Performance \u2014 All Features (${result.featureCount})`));
-  console.log('  ' + '\u2500'.repeat(70));
-
-  console.log(
-    '  ' +
-    pad('Agent', 28) +
-    pad('Dispatches', 12) +
-    pad('Tasks', 8) +
-    pad('Completed', 12) +
-    pad('Avg Duration', 14)
-  );
-  console.log('  ' + '\u2500'.repeat(70));
-
-  for (const agent of result.agents) {
-    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
-    const completed = agent.tasksAssigned > 0
-      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
-      : '\u2014';
-    const duration = formatDuration(agent.avgDurationMs);
-
-    console.log(
-      '  ' +
-      pad(agent.id, 28) +
-      pad(String(agent.dispatches), 12) +
-      pad(tasks, 8) +
-      pad(completed, 12) +
-      pad(duration, 14)
-    );
-  }
-
-  console.log();
-  const { summary } = result;
-  const rate = summary.totalTasks > 0
-    ? `${Math.round(summary.completionRate * 100)}%`
-    : '0%';
-  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
-  console.log(`  Dispatches: ${summary.totalDispatches} total across ${result.featureCount} features`);
-  console.log();
-}
-
-/**
- * Right-pad a string to a given width.
- */
-function pad(str, width) {
-  return str.length >= width ? str : str + ' '.repeat(width - str.length);
-}

package/src/commands/agents/audit-dispatch.js

@@ -1,82 +0,0 @@
-/**
- * audit-dispatch — Display dispatch audit log for a feature
- *
- * Reads dispatchLog from state.json and presents a summary:
- * - Total dispatches
- * - Per-dispatch: timestamp, phase, mode, agents with subagentTypes
- * - Agent coverage: which agents handled which tasks
- *
- * Usage:
- *   morph-spec audit-dispatch <feature>
- *   morph-spec audit-dispatch <feature> --json
- */
-
-import { loadState, stateExists } from '../../core/state/state-manager.js';
-import chalk from 'chalk';
-
-/**
- * CLI command: morph-spec audit-dispatch <feature>
- *
- * @param {string} featureName - Feature name
- * @param {Object} [options] - CLI options
- * @param {boolean} [options.json] - Output as JSON instead of table
- */
-export async function auditDispatchCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Usage: morph-spec audit-dispatch <feature>'));
-    process.exit(1);
-  }
-
-  if (!stateExists()) {
-    console.error(chalk.red('No state.json found.'));
-    process.exit(1);
-  }
-
-  const state = loadState();
-  const feature = state.features?.[featureName];
-  if (!feature) {
-    console.error(chalk.red(`Feature '${featureName}' not found.`));
-    process.exit(1);
-  }
-
-  const log = feature.dispatchLog || [];
-
-  if (options.json) {
-    console.log(JSON.stringify(log, null, 2));
-    return;
-  }
-
-  console.log(chalk.bold(`\n  Dispatch Audit — ${featureName}`));
-  console.log('  ' + '─'.repeat(50));
-  console.log(`  Total dispatches: ${log.length}`);
-
-  if (log.length === 0) {
-    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
-    return;
-  }
-
-  for (let i = 0; i < log.length; i++) {
-    const entry = log[i];
-    console.log(`\n  #${i + 1}: ${entry.timestamp} — ${entry.phase} (${entry.mode})`);
-    for (const agent of entry.agents || []) {
-      const taskCount = agent.tasks?.length || 0;
-      console.log(`      ${agent.id} → ${agent.subagentType} (${agent.group}) — ${taskCount} tasks`);
-    }
-  }
-
-  // Agent coverage summary
-  const coverage = {};
-  for (const entry of log) {
-    for (const agent of entry.agents || []) {
-      if (!coverage[agent.id]) coverage[agent.id] = { tasks: 0, dispatches: 0 };
-      coverage[agent.id].tasks += agent.tasks?.length || 0;
-      coverage[agent.id].dispatches += 1;
-    }
-  }
-
-  console.log(chalk.bold('\n  Agent Coverage:'));
-  for (const [id, data] of Object.entries(coverage)) {
-    console.log(`      ${id}: ${data.tasks} tasks across ${data.dispatches} dispatches`);
-  }
-  console.log();
-}