npm - @polymorphism-tech/morph-spec - Versions diffs - 4.7.2 → 4.8.4 - Mend

@polymorphism-tech/morph-spec 4.7.2 → 4.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (342) hide show

package/docs/plans/2026-02-22-claude-settings.md DELETED Viewed

@@ -1,515 +0,0 @@
-# Claude Code Settings & Native Subagents Alignment Plan
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-**Goal:** Align morph-spec with the latest Claude Code native primitives — native subagents (`.claude/agents/`), additional settings keys, and proper CLAUDE.md scoping.
-**Architecture:** Add an `agentsInstaller.js` that converts morph's tier-1/tier-2 agents into native Claude Code subagent markdown files; expand `hooks-installer.js` to configure additional settings keys ($schema, env, attribution, plansDirectory, teammateMode); split CLAUDE.md into human-readable root vs. Claude-Code-runtime `.claude/CLAUDE.md`.
-**Tech Stack:** Node.js ESM, fs-extra, node:test, Claude Code settings.json schema
-**Plan file should be copied to:** `docs/plans/2026-02-22-claude-settings.md`
----
-## Context
-The Claude Code settings documentation reveals three native primitives morph-spec does not yet leverage:
-1. **Native Subagents** (`.claude/agents/`): Claude Code natively discovers `.md` files with YAML frontmatter in `.claude/agents/`. morph-spec has 37 agents in a custom JSON registry that are entirely invisible to this native mechanism.
-2. **Missing settings keys**: `$schema`, `env`, `attribution`, `plansDirectory`, `teammateMode`, `spinnerVerbs` — all recognized by Claude Code but not written by morph-spec's init.
-3. **CLAUDE.md scopes**: Claude Code explicitly supports `.claude/CLAUDE.md` (alongside settings). morph-spec installs only the root `CLAUDE.md`, mixing human documentation with Claude Code runtime instructions.
-**Already well-aligned — no changes needed:**
-- Skills flat-install to `.claude/skills/` ✓
-- Commands install to `.claude/commands/` ✓
-- Global statusline at `~/.claude/` ✓
-- Native `permissions.deny` for state.json + framework/ ✓
-- 12 lifecycle hooks with `_morph_managed` tracking ✓
----
-## Task 1: Create `src/utils/agents-installer.js`
-**Files:**
-- Create: `src/utils/agents-installer.js`
-- Test: `test/utils/agents-installer.test.js`
-### Step 1: Write failing test
-```js
-// test/utils/agents-installer.test.js
-import { test, describe, before, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtemp, rm, readdir, readFile, mkdir } from 'node:fs/promises';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { installAgents } from '../../src/utils/agents-installer.js';
-describe('installAgents', () => {
-  let tmpDir;
-  before(async () => { tmpDir = await mkdtemp(join(tmpdir(), 'morph-agents-')); });
-  after(async () => { await rm(tmpDir, { recursive: true, force: true }); });
-  test('creates .claude/agents/ with tier-1 and tier-2 agent files', async () => {
-    const frameworkDir = 'framework'; // uses real agents.json
-    await installAgents(tmpDir, frameworkDir);
-    const files = await readdir(join(tmpDir, '.claude', 'agents'));
-    assert.ok(files.length >= 6, 'should install at least 6 agents');
-    assert.ok(files.every(f => f.endsWith('.md')), 'all files should be .md');
-  });
-  test('each file has valid YAML frontmatter with name and description', async () => {
-    await installAgents(tmpDir, 'framework');
-    const files = await readdir(join(tmpDir, '.claude', 'agents'));
-    for (const file of files) {
-      const content = await readFile(join(tmpDir, '.claude', 'agents', file), 'utf-8');
-      assert.ok(content.startsWith('---\n'), `${file} should start with YAML frontmatter`);
-      assert.ok(content.includes('name:'), `${file} should have name`);
-      assert.ok(content.includes('description:'), `${file} should have description`);
-    }
-  });
-  test('is idempotent — running twice does not duplicate files', async () => {
-    await installAgents(tmpDir, 'framework');
-    await installAgents(tmpDir, 'framework');
-    const files = await readdir(join(tmpDir, '.claude', 'agents'));
-    const morphFiles = files.filter(f => f.startsWith('morph-'));
-    const unique = new Set(morphFiles);
-    assert.equal(morphFiles.length, unique.size);
-  });
-});
-```
-### Step 2: Run test to verify it fails
-```bash
-npm test -- test/utils/agents-installer.test.js
-```
-Expected: FAIL — `agents-installer.js` not found.
-### Step 3: Write the implementation
-```js
-// src/utils/agents-installer.js
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join } from 'path';
-/**
- * Installs tier-1 and tier-2 morph agents as native Claude Code subagents
- * in .claude/agents/ with YAML frontmatter.
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- */
-export async function installAgents(projectDir, frameworkDir = 'framework') {
-  const agentsJsonPath = join(frameworkDir, 'agents.json');
-  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
-  const agents = agentsJson.agents ?? agentsJson;
-  const targetDir = join(projectDir, '.claude', 'agents');
-  mkdirSync(targetDir, { recursive: true });
-  const eligible = agents.filter(a => a.tier === 1 || a.tier === 2);
-  for (const agent of eligible) {
-    const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
-    const filename = `morph-${slug}.md`;
-    const targetPath = join(targetDir, filename);
-    const description = buildDescription(agent);
-    const body = buildBody(agent);
-    const content = `---\nname: ${agent.title ?? agent.name}\ndescription: ${description}\n---\n\n${body}\n`;
-    writeFileSync(targetPath, content, 'utf-8');
-  }
-}
-function buildDescription(agent) {
-  const domains = (agent.domains ?? []).join(', ');
-  const base = agent.teammate?.role ?? `Handles ${domains}`;
-  // Truncate to 200 chars for settings display
-  return base.length > 200 ? base.slice(0, 197) + '...' : base;
-}
-function buildBody(agent) {
-  const lines = [];
-  if (agent.teammate?.spawn_prompt) {
-    lines.push(agent.teammate.spawn_prompt);
-  } else {
-    lines.push(`You are the ${agent.title} agent in the MORPH-SPEC framework.`);
-    if (agent.domains?.length) lines.push(`\n## Domains\n${agent.domains.map(d => `- ${d}`).join('\n')}`);
-  }
-  if (agent.standards?.length) {
-    lines.push(`\n## Standards to Reference\n${agent.standards.map(s => `- ${s}`).join('\n')}`);
-  }
-  return lines.join('\n');
-}
-```
-### Step 4: Run test to verify it passes
-```bash
-npm test -- test/utils/agents-installer.test.js
-```
-Expected: PASS (3 tests pass).
-### Step 5: Commit
-```bash
-git add src/utils/agents-installer.js test/utils/agents-installer.test.js
-git commit -m "feat(agents): add agents-installer for native .claude/agents/ subagent discovery"
-```
----
-## Task 2: Integrate `installAgents` into `init.js`
-**Files:**
-- Modify: `src/commands/project/init.js`
-- Modify: `src/utils/claude-settings-manager.js` (re-export)
-### Step 1: Add import and call in init.js
-In `src/commands/project/init.js`, after the skills install block:
-```js
-// After: await installSkills(targetPath);
-import { installAgents } from '../../utils/agents-installer.js';
-// ...
-await installAgents(targetPath, FRAMEWORK_DIR);
-logger.success('Native subagents installed to .claude/agents/');
-```
-Find `FRAMEWORK_DIR` in init.js (or equivalent constant pointing to `framework/`).
-### Step 2: Re-export from claude-settings-manager
-Add to `src/utils/claude-settings-manager.js`:
-```js
-export { installAgents } from './agents-installer.js';
-```
-### Step 3: Add agent files to existing integration test
-In `test/commands/init.test.js`, add assertion:
-```js
-const agentFiles = await readdir(join(projectDir, '.claude', 'agents'));
-assert.ok(agentFiles.some(f => f.startsWith('morph-')), 'agents should be installed');
-```
-### Step 4: Run all tests
-```bash
-npm test
-```
-Expected: All existing tests pass + new assertion passes.
-### Step 5: Commit
-```bash
-git add src/commands/project/init.js src/utils/claude-settings-manager.js
-git commit -m "feat(init): install native subagents to .claude/agents/ during init"
-```
----
-## Task 3: Settings Enhancements — `$schema`, `env`, `attribution`, `plansDirectory`
-**Files:**
-- Modify: `src/utils/hooks-installer.js`
-- Test: existing `test/hooks/hooks-installer.test.js`
-These settings go into `.claude/settings.local.json` (same file as hooks/permissions).
-### Step 1: Write failing test
-In `test/hooks/hooks-installer.test.js`, add:
-```js
-test('installClaudeHooks adds $schema to settings', async () => {
-  await installClaudeHooks(tmpDir);
-  const settings = JSON.parse(readFileSync(join(tmpDir, '.claude', 'settings.local.json'), 'utf-8'));
-  assert.ok(settings['$schema'], 'should include $schema key');
-  assert.equal(settings['$schema'], 'https://json.schemastore.org/claude-code-settings.json');
-});
-test('installClaudeHooks adds env section with MORPH vars', async () => {
-  await installClaudeHooks(tmpDir);
-  const settings = JSON.parse(readFileSync(join(tmpDir, '.claude', 'settings.local.json'), 'utf-8'));
-  assert.ok(settings.env?.MORPH_SPEC_ACTIVE, 'should set MORPH_SPEC_ACTIVE');
-});
-test('installClaudeHooks sets attribution', async () => {
-  await installClaudeHooks(tmpDir);
-  const settings = JSON.parse(readFileSync(join(tmpDir, '.claude', 'settings.local.json'), 'utf-8'));
-  assert.ok(settings.attribution, 'should set attribution');
-});
-```
-### Step 2: Run test to verify it fails
-```bash
-npm test -- test/hooks/hooks-installer.test.js
-```
-Expected: FAIL — schema/env/attribution not in settings.
-### Step 3: Implement in `hooks-installer.js`
-In `installClaudeHooks(targetPath)`, before writing settings, merge:
-```js
-// Add at top of installClaudeHooks, after loading existing settings:
-settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
-settings.env = {
-  ...settings.env,
-  MORPH_SPEC_ACTIVE: 'true',
-};
-if (!settings.attribution) {
-  settings.attribution = {
-    commit: '🤖 Co-authored by MORPH-SPEC',
-    pr: '',
-  };
-}
-if (!settings.plansDirectory) {
-  settings.plansDirectory = '.morph/plans';
-}
-```
-### Step 4: Run test to verify it passes
-```bash
-npm test -- test/hooks/hooks-installer.test.js
-```
-Expected: All hooks-installer tests pass including new ones.
-### Step 5: Commit
-```bash
-git add src/utils/hooks-installer.js test/hooks/hooks-installer.test.js
-git commit -m "feat(settings): add \$schema, env, attribution, plansDirectory to installed settings"
-```
----
-## Task 4: Create `.claude/CLAUDE.md` (Claude Code Runtime Instructions)
-The project-root `CLAUDE.md` is for humans + Claude Code. The `.claude/CLAUDE.md` file should hold Claude Code-specific runtime instructions that don't need to be in the project root.
-**Files:**
-- Create: `framework/CLAUDE_runtime.md` (source template → installs as `.claude/CLAUDE.md`)
-- Modify: `src/commands/project/init.js` (copy runtime CLAUDE.md)
-- Test: `test/commands/init.test.js`
-### Step 1: Create runtime CLAUDE.md template
-```markdown
-<!-- framework/CLAUDE_runtime.md -->
-# MORPH-SPEC Runtime Instructions
-This file is loaded by Claude Code at runtime. For project documentation, see `CLAUDE.md` in the project root.
-## Quick Reference
-- Feature status: `/morph-status`
-- Start new feature: `/morph-proposal {feature-name}`
-- Implement feature: `/morph-apply {feature-name}`
-- Preflight check: `/morph-preflight`
-## State & Outputs
-- State file: `.morph/state.json` (READ-ONLY — use `morph-spec` CLI to update)
-- Feature outputs: `.morph/features/{feature}/{phase}/`
-- Framework files: `.morph/framework/` (READ-ONLY)
-## Phase Sequence
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-Use `morph-spec state show {feature}` to see current phase and pending gates.
-```
-### Step 2: Write failing test
-```js
-test('init creates .claude/CLAUDE.md', async () => {
-  // run init with mocks
-  const content = readFileSync(join(projectDir, '.claude', 'CLAUDE.md'), 'utf-8');
-  assert.ok(content.includes('MORPH-SPEC Runtime'), 'should have runtime header');
-  assert.ok(content.includes('/morph-status'), 'should reference slash commands');
-});
-```
-### Step 3: Add copy in init.js
-After the skills install block, add:
-```js
-const runtimeClaudeMdSrc = join(FRAMEWORK_DIR, 'CLAUDE_runtime.md');
-const runtimeClaudeMdDest = join(targetPath, '.claude', 'CLAUDE.md');
-await copyFile(runtimeClaudeMdSrc, runtimeClaudeMdDest);
-logger.success('Runtime CLAUDE.md installed to .claude/CLAUDE.md');
-```
-### Step 4: Run test to verify it passes
-```bash
-npm test -- test/commands/init.test.js
-```
-### Step 5: Commit
-```bash
-git add framework/CLAUDE_runtime.md src/commands/project/init.js test/commands/init.test.js
-git commit -m "feat(init): install .claude/CLAUDE.md with Claude Code runtime quick reference"
-```
----
-## Task 5: Add `morph-spec update-agents` command
-Allow users to refresh `.claude/agents/` when framework agents are updated (similar to how `morph-spec update` refreshes framework files).
-**Files:**
-- Create: `src/commands/project/update-agents.js`
-- Modify: `bin/morph-spec.js` (register command)
-- Test: `test/commands/update-agents.test.js`
-### Step 1: Write failing test
-```js
-// test/commands/update-agents.test.js
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { updateAgentsCommand } from '../../src/commands/project/update-agents.js';
-test('updateAgentsCommand re-installs agents from framework', async () => {
-  // Should call installAgents with projectDir and frameworkDir
-  // Should log success message
-  assert.ok(typeof updateAgentsCommand === 'function');
-});
-```
-### Step 2: Implement
-```js
-// src/commands/project/update-agents.js
-import { installAgents } from '../../utils/agents-installer.js';
-import { logger } from '../../utils/logger.js';
-import { join } from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const FRAMEWORK_DIR = join(__dirname, '..', '..', '..', 'framework');
-export async function updateAgentsCommand(args, options) {
-  const projectDir = process.cwd();
-  logger.info('Updating native subagents in .claude/agents/...');
-  await installAgents(projectDir, FRAMEWORK_DIR);
-  logger.success('Native subagents updated. Claude Code will discover them on next session start.');
-}
-```
-### Step 3: Register in `bin/morph-spec.js`
-Find the agents command group and add:
-```js
-program
-  .command('update-agents')
-  .description('Refresh .claude/agents/ with latest morph orchestrator and domain agents')
-  .action(updateAgentsCommand);
-```
-### Step 4: Run tests
-```bash
-npm test -- test/commands/update-agents.test.js
-npm test
-```
-### Step 5: Commit
-```bash
-git add src/commands/project/update-agents.js bin/morph-spec.js test/commands/update-agents.test.js
-git commit -m "feat(cli): add morph-spec update-agents command for refreshing native subagents"
-```
----
-## Task 6: Final integration test + docs update
-**Files:**
-- Test: `test/integration/init-full.test.js` (if it exists) or `test/commands/init.test.js`
-- Modify: `framework/CLAUDE.md` (note new .claude/CLAUDE.md)
-- Modify: `docs/plans/` (save plan here)
-### Step 1: Run full test suite
-```bash
-npm test
-```
-Expected: All 552+ tests pass (0 regressions, new tests added).
-### Step 2: Run coverage check
-```bash
-npm run test:coverage:summary
-```
-Verify new modules have reasonable coverage.
-### Step 3: Manual smoke test
-```bash
-node bin/morph-spec.js init --force --skip-mcp --skip-detection
-ls -la .claude/agents/
-ls -la .claude/CLAUDE.md
-cat .claude/settings.local.json | node -e "process.stdin.on('data',d=>{ const s=JSON.parse(d); console.log('schema:', s['\$schema']); console.log('env:', s.env); console.log('attribution:', s.attribution); })"
-```
-Expected: 6+ agent `.md` files, CLAUDE.md present, settings has `$schema` + `env` + `attribution`.
-### Step 4: Save plan to docs
-```bash
-cp "C:\Users\Lucas\.claude\plans\magical-moseying-sutton.md" "docs/plans/2026-02-22-claude-settings.md"
-git add docs/plans/2026-02-22-claude-settings.md
-git commit -m "docs: save claude-settings alignment plan"
-```
----
-## Critical Files to Modify
-| File | Change |
-|------|--------|
-| `src/utils/agents-installer.js` | **NEW** — converts agents.json tier-1/2 to `.claude/agents/` markdown |
-| `src/utils/claude-settings-manager.js` | Re-export `installAgents` |
-| `src/commands/project/init.js` | Call `installAgents` + copy `.claude/CLAUDE.md` |
-| `src/utils/hooks-installer.js` | Add `$schema`, `env`, `attribution`, `plansDirectory` to settings |
-| `src/commands/project/update-agents.js` | **NEW** — CLI command to refresh agents |
-| `bin/morph-spec.js` | Register `update-agents` command |
-| `framework/CLAUDE_runtime.md` | **NEW** — source for `.claude/CLAUDE.md` |
-## Verification
-```bash
-# Full suite
-npm test
-# Smoke test init
-node bin/morph-spec.js init --force --skip-mcp --skip-detection
-# Verify native agents
-ls .claude/agents/
-cat .claude/agents/morph-standards-architect.md  # Should have YAML frontmatter
-# Verify settings
-cat .claude/settings.local.json | grep -A2 "schema\|env\|attribution"
-# Verify .claude/CLAUDE.md
-cat .claude/CLAUDE.md
-```