@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

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

@@ -1,517 +0,0 @@
-# Claude Code Settings & Native Subagents Alignment Plan
-
-**Status:** COMPLETE
-
-> **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
-```