@polymorphism-tech/morph-spec 4.8.17 → 4.8.19

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# MORPH-SPEC Runtime Instructions
+
+> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
+
+---
+
+## Project Context
+
+@.morph/context/README.md
+
+---
+
+## Critical Rules
+
+**NEVER:**
+- Skip to code without a specification
+- Implement without design approval
+- Ignore standards in `.morph/framework/standards/`
+- Create infrastructure manually
+- Generate code without defined contracts
+
+**ALWAYS:**
+- Follow the mandatory phases
+- Generate outputs in `.morph/features/{feature}/`
+- Document decisions in `decisions.md`
+- Checkpoint every 3 implemented tasks
+- Use Infrastructure as Code
+
+---
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature status dashboard |
+| `/morph-preflight` | Pre-implementation validation |
+
+---
+
+## State & Outputs
+
+| Path | Notes |
+|------|-------|
+| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
+| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
+| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
+| `.morph/config/config.json` | Project configuration (editable) |
+
+---
+
+## Phase Sequence
+
+```
+proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
+```
+
+Use `morph-spec status {feature}` to see current phase and pending approval gates.
+
+---
+
+## Agents
+
+Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
+They can be invoked directly by Claude Code during multi-agent workflows.
+
+---
+
+## Context Window Tip
+
+When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
+MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.8.17  
+**Version:** 4.8.19  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.8.17 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.8.19 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.8.17",
+  "version": "4.8.19",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -200,4 +200,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.8.17 by Polymorphism Tech*
+*morph-spec v4.8.19 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.8.17 by Polymorphism Tech*
+*morph-spec v4.8.19 by Polymorphism Tech*

package/framework/agents.json

@@ -1,12 +1,12 @@
 {
   "$schema": "./agent-schema.json",
-  "version": "3.2.0-hierarchical",
-  "total_agents": 39,
+  "version": "3.3.0-hierarchical",
+  "total_agents": 42,
   "tiers": {
     "tier_1_orchestrators": 3,
     "tier_2_leaders": 4,
-    "tier_3_specialists": 27,
-    "tier_4_validators": 5
+    "tier_3_specialists": 29,
+    "tier_4_validators": 6
   },
   "agents": {
     "_comment_tier_1": "=== TIER 1: ORCHESTRATORS (3) ===",
@@ -1615,7 +1615,51 @@
         "spawn_prompt": "Você é o VSA Specialist. Analise a proposta e produza um VSA Blueprint:\n1. ENTITY FIELDS: todos os campos com tipos C# corretos (sem AggregateRoot, sem Value Objects)\n2. OPERATIONS: slices necessários (Create, GetAll, GetById, Update, Delete + operações customizadas)\n3. ROUTES: HTTP method + rota por operação (ex: POST /api/products, GET /api/products/{id:guid})\n4. ERROR TYPES: Error factory methods para {Entity}Errors (apenas NotFound e casos específicos)\n5. VALIDATION RULES: regras FluentValidation por campo por operação\n\nNão use AggregateRoot, DomainEvent, CQRS formal, MediatR, Application Service layer.\nCada operação é um slice autônomo: Request + Response + Handler + Validator + Endpoint.\nRef: framework/standards/architecture/vertical-slice/vertical-slice.md"
       }
     },
-    "_comment_tier_4": "=== TIER 4: VALIDATORS (5) ===",
+    "_comment_tier_3_nodejs": "=== TIER 3: NODEJS/CLI SPECIALISTS (2) ===",
+    "morph-spec-architect": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Morph-Spec Architect",
+      "domains": ["cli", "framework-design", "nodejs", "architecture"],
+      "keywords": ["morph-spec", "framework feature", "new command", "cli architecture", "plugin", "hook design"],
+      "negativeKeywords": ["blazor", "dotnet", "react", "frontend"],
+      "always_active": false,
+      "validators": [],
+      "relationships": {
+        "reports_to": "feature-lead",
+        "coordinates": ["nodejs-cli-expert", "morph-spec-validator"],
+        "active_phases": ["design", "tasks"]
+      },
+      "standards": [],
+      "teammate": {
+        "role": "specialist",
+        "icon": "🔧",
+        "spawn_prompt": "You are the Morph-Spec Architect. You deeply understand the morph-spec-framework codebase: its 4-tier agent hierarchy, state machine (v5.0.0 with filesystem-based phase derivation), Commander.js CLI surface (~25 commands registered in bin/morph-spec.js), hooks system (v2.5, 10 hooks), skills system, and the .morph/ directory layout. Your job is to design new features that fit naturally into the existing architecture. Before proposing implementation, always: (1) identify which existing modules can be reused, (2) determine where the new command should live in src/commands/, (3) define the state impact (does it need new state fields?), (4) list which tests need to be written. Follow ESM module patterns throughout."
+      }
+    },
+    "nodejs-cli-expert": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Node.js CLI Expert",
+      "domains": ["nodejs", "cli", "javascript", "esm", "testing"],
+      "keywords": ["nodejs", "javascript", "esm", "commander", "node --test", "cli command", "morph-spec implementation"],
+      "negativeKeywords": ["blazor", "dotnet", "react", "typescript"],
+      "always_active": false,
+      "validators": [],
+      "relationships": {
+        "reports_to": "feature-lead",
+        "coordinates": ["morph-spec-architect"],
+        "escalates_to": "morph-spec-validator",
+        "active_phases": ["implement"]
+      },
+      "standards": [],
+      "teammate": {
+        "role": "specialist",
+        "icon": "🟢",
+        "spawn_prompt": "You are the Node.js CLI Expert for the morph-spec-framework. You implement features in Node.js ESM following the project's conventions: (1) All imports use ESM syntax with .js extensions on relative paths; (2) Commands are registered in bin/morph-spec.js after being defined in src/commands/<domain>/<command>.js; (3) Tests use native node:test runner with mock.fn() for mocking — no external test libraries; (4) Error handling: hooks are fail-open (catch+exit 0), CLI commands exit(1) on fatal errors; (5) Never use require() or module.exports. When implementing a feature, always write the tests alongside the implementation. The test command is: node --test --test-concurrency=1"
+      }
+    },
+    "_comment_tier_4": "=== TIER 4: VALIDATORS (6) ===",
     "security-expert": {
       "tier": 4,
       "role": "validator",
@@ -1831,6 +1875,34 @@
         "severity": "error",
         "blocks_on_fail": true
       }
+    },
+    "morph-spec-validator": {
+      "tier": 4,
+      "role": "validator",
+      "title": "Morph-Spec Validator",
+      "domains": ["nodejs", "cli", "testing", "validation"],
+      "keywords": ["validate morph-spec", "node.js validation", "cli test"],
+      "always_active": false,
+      "validators": ["morph-spec-standards"],
+      "relationships": {
+        "reports_to": "qa-lead",
+        "runs_in": "post-implement",
+        "active_phases": ["implement", "validate"]
+      },
+      "standards": [],
+      "teammate": null,
+      "hook_behavior": {
+        "validates": [
+          "ESM imports use .js extensions on relative paths",
+          "New commands are registered in bin/morph-spec.js",
+          "Tests exist for new modules (one test file per module)",
+          "npm test passes with no failures",
+          "No require() or module.exports used",
+          "Error handling follows fail-open pattern for hooks"
+        ],
+        "severity": "error",
+        "blocks_on_fail": true
+      }
     }
   },
   "squads": {

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, gene
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 ---
 
 # MORPH Clarify - FASE 3

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

@@ -3,7 +3,7 @@ name: phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 ---
 
 # MORPH Codebase Analysis - Sub-fase de DESIGN

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produce
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 ---
 
 # MORPH Design - FASE 2

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech sta
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 ---
 
 # MORPH Setup - FASE 1

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

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.17"
+cliVersion: "4.8.19"
 ---
 
 # MORPH Tasks - FASE 4

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

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

package/framework/workflows/configs/nodejs-cli.json

@@ -0,0 +1,40 @@
+{
+  "id": "nodejs-cli",
+  "name": "Node.js CLI Development",
+  "description": "Workflow otimizado para desenvolvimento de features em projetos CLI Node.js/ESM, como o morph-spec-framework.",
+  "criteria": {
+    "maxFiles": 15,
+    "maxLines": 400,
+    "maxComponents": 0,
+    "noInfrastructure": true,
+    "noArchitecturalDecisions": false
+  },
+  "keywords": [
+    "nodejs", "javascript", "esm", "cli", "commander", "command", "morph-spec",
+    "hook", "validator", "plugin", "script"
+  ],
+  "phases": {
+    "run": ["proposal", "setup", "design", "tasks", "implement"],
+    "skip": ["uiux", "clarify", "sync"],
+    "combined": {}
+  },
+  "pausePoints": [
+    {
+      "phase": "design",
+      "question": "O design da feature está correto? Approve para gerar tasks."
+    },
+    {
+      "phase": "tasks",
+      "question": "As tasks estão bem definidas? Approve para iniciar implementação."
+    }
+  ],
+  "outputs": {
+    "required": ["proposal", "spec", "tasks"],
+    "optional": ["contracts", "decisions", "recap"]
+  },
+  "agentPreferences": {
+    "specialists": ["morph-spec-architect", "nodejs-cli-expert"],
+    "validators": ["morph-spec-validator"]
+  },
+  "priority": 5
+}

package/package.json

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

package/src/scripts/global-install.js

@@ -30,17 +30,29 @@ export async function installGlobalSkill(claudeDir = join(homedir(), '.claude'))
 // Run as postinstall script
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
+  const { readFileSync } = await import('fs');
+  const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 
-  await Promise.allSettled([
-    installGlobalSkill()
-      .then(() => console.log('✓ morph-init skill installed to ~/.claude/skills/')),
-    installGlobalStatusline(HOOKS_SRC)
-      .then(() => console.log('✓ statusline installed to ~/.claude/')),
-  ]).then(results => {
-    for (const r of results) {
-      if (r.status === 'rejected') {
-        console.warn('  postinstall warning:', r.reason?.message || r.reason);
-      }
-    }
-  });
+  const [skillResult, statuslineResult] = await Promise.allSettled([
+    installGlobalSkill(),
+    installGlobalStatusline(HOOKS_SRC),
+  ]);
+
+  const results = [
+    {
+      ok: skillResult.status === 'fulfilled',
+      label: 'morph-init skill',
+      path: '~/.claude/skills/',
+      error: skillResult.reason?.message,
+    },
+    {
+      ok: statuslineResult.status === 'fulfilled',
+      label: 'statusline',
+      path: '~/.claude/',
+      error: statuslineResult.reason?.message,
+    },
+  ];
+
+  const { printInstallBanner } = await import('../utils/banner.js');
+  printInstallBanner({ version: pkg.version, nodeVersion: process.version, results });
 }

package/src/utils/banner.js

@@ -0,0 +1,51 @@
+// src/utils/banner.js
+import chalk from 'chalk';
+import { type as osType, release as osRelease } from 'os';
+
+const BRAND = chalk.hex('#7C3AED');
+const DIM = chalk.dim;
+
+function platformLabel() {
+  const t = osType();
+  const r = osRelease().split('.').slice(0, 2).join('.');
+  if (t === 'Windows_NT') return `Windows ${r}`;
+  if (t === 'Darwin') return `macOS ${r}`;
+  return `Linux ${r}`;
+}
+
+export function printInstallBanner({ version, nodeVersion, results = [] }) {
+  const TITLE = '◆  M O R P H - S P E C';
+  const pad = `  ${TITLE}  `;
+  const line = '─'.repeat(pad.length);
+
+  const box = [
+    BRAND(`┌${line}┐`),
+    BRAND('│') + chalk.bold.white(pad) + BRAND('│'),
+    BRAND(`└${line}┘`),
+  ].join('\n');
+
+  const sep = (label) => DIM(`  ── ${label} ${'─'.repeat(Math.max(0, 30 - label.length))}`);
+
+  const itemLines = results.map(r =>
+    r.ok
+      ? `  ${chalk.green('✔')} ${r.label.padEnd(20)} ${DIM(r.path)}`
+      : `  ${chalk.red('✖')} ${r.label.padEnd(20)} ${chalk.red(r.error ?? 'failed')}`
+  );
+
+  console.log([
+    '',
+    box,
+    '',
+    `  Version    ${chalk.white(version)}`,
+    `  Platform   ${chalk.white(platformLabel())}`,
+    `  Node       ${chalk.white(nodeVersion)}`,
+    '',
+    sep('Installed'),
+    ...itemLines,
+    '',
+    sep('Next'),
+    `  ${chalk.cyan('1.')} Open your project in Claude Code`,
+    `  ${chalk.cyan('2.')} Run ${chalk.bold.white('/morph-init')}`,
+    '',
+  ].join('\n'));
+}