@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

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

@@ -0,0 +1,515 @@
+# 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
+```