@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/docs/plans/2026-02-22-native-enrichment.md

@@ -0,0 +1,735 @@
+# Claude Code Native Enrichment Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Enrich morph-spec's use of Claude Code native primitives — richer agent frontmatter, Stop hook upgrade, level-2 skill installation, and SubagentStart telemetry.
+
+**Architecture:** Four independent improvements to `agents-installer.js`, `skills-installer.js`, `hooks-installer.js`, and a new `log-agent-start.js` hook. Each follows TDD with tests first. All are self-contained and can be committed independently.
+
+**Tech Stack:** Node.js ESM, node:test, fs/promises, Claude Code settings.json schema
+
+**Design doc:** `docs/plans/2026-02-22-native-enrichment-design.md`
+
+---
+
+## Task 1: Richer agent frontmatter
+
+**Context:** Currently generated `.claude/agents/morph-*.md` files have only `name` and `description` in YAML. Claude Code supports `model`, `tools`, `maxTurns`, `skills`, and `memory`. This task adds tier-based defaults to the installer.
+
+**Files:**
+- Modify: `src/utils/agents-installer.js`
+- Modify: `test/utils/agents-installer.test.js`
+
+**Tier defaults:**
+
+| Tier | model | tools | maxTurns | skills | memory |
+|------|-------|-------|----------|--------|--------|
+| 1 (Orchestrators) | `inherit` | `Read, Grep, Glob, Bash, Task` | `30` | `morph-checklist` | `project` |
+| 2 (Domain Leaders) | `inherit` | `Read, Grep, Glob, Bash` | `20` | `morph-checklist` | `local` |
+
+`morph-checklist` refers to `.claude/skills/morph-checklist.md` (installed from `framework/skills/level-0-meta/morph-checklist.md`).
+
+---
+
+### Step 1: Write failing tests
+
+Add to the bottom of `test/utils/agents-installer.test.js`:
+
+```js
+describe('installAgents — richer frontmatter', () => {
+  let tmpDir;
+
+  before(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'morph-agents-rich-'));
+    await installAgents(tmpDir, FRAMEWORK_DIR);
+  });
+
+  after(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('tier-1 agent has model field', async () => {
+    const files = await readdir(join(tmpDir, '.claude', 'agents'));
+    const tier1File = files.find(f => f.includes('standards-architect') || f.includes('ai-system'));
+    assert.ok(tier1File, 'should have a tier-1 agent file');
+    const content = await readFile(join(tmpDir, '.claude', 'agents', tier1File), 'utf-8');
+    assert.ok(content.includes('model:'), `${tier1File} should have model field`);
+  });
+
+  test('tier-1 agent has tools field including Task', async () => {
+    const files = await readdir(join(tmpDir, '.claude', 'agents'));
+    const tier1File = files.find(f => f.includes('standards-architect'));
+    assert.ok(tier1File);
+    const content = await readFile(join(tmpDir, '.claude', 'agents', tier1File), 'utf-8');
+    assert.ok(content.includes('tools:'), `${tier1File} should have tools field`);
+    assert.ok(content.includes('Task'), `${tier1File} tier-1 should have Task tool`);
+  });
+
+  test('tier-2 agent has tools field without Task', async () => {
+    const files = await readdir(join(tmpDir, '.claude', 'agents'));
+    // tier-2 agents don't have Task in their tools
+    const tier2File = files.find(f => f.includes('thread-orchestrator'));
+    if (tier2File) {
+      const content = await readFile(join(tmpDir, '.claude', 'agents', tier2File), 'utf-8');
+      assert.ok(content.includes('tools:'), `${tier2File} should have tools field`);
+    }
+    // At minimum, all files should have a tools: field
+    for (const file of files) {
+      const content = await readFile(join(tmpDir, '.claude', 'agents', file), 'utf-8');
+      assert.ok(content.includes('tools:'), `${file} should have tools field`);
+    }
+  });
+
+  test('all agents have maxTurns field', async () => {
+    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.includes('maxTurns:'), `${file} should have maxTurns field`);
+    }
+  });
+
+  test('all agents have memory field', async () => {
+    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.includes('memory:'), `${file} should have memory field`);
+    }
+  });
+
+  test('all agents have skills field with morph-checklist', async () => {
+    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.includes('skills:'), `${file} should have skills field`);
+      assert.ok(content.includes('morph-checklist'), `${file} should reference morph-checklist skill`);
+    }
+  });
+});
+```
+
+### Step 2: Run test to verify it fails
+
+```bash
+npm test -- test/utils/agents-installer.test.js
+```
+
+Expected: FAIL — `model:` / `tools:` / `maxTurns:` / `memory:` / `skills:` not found in generated files.
+
+### Step 3: Implement the changes in `agents-installer.js`
+
+In `buildDescription()` — no change.
+
+Replace the content generation line in `installAgents()`:
+
+```js
+// BEFORE (line 46):
+const content = `---\nname: ${agent.title ?? agent.name}\ndescription: ${description}\n---\n\n${body}\n`;
+
+// AFTER:
+const frontmatter = buildFrontmatter(agent, description);
+const content = `---\n${frontmatter}---\n\n${body}\n`;
+```
+
+Add `buildFrontmatter()` function after `buildDescription()`:
+
+```js
+function buildFrontmatter(agent, description) {
+  const isOrchestrator = agent.tier === 1;
+  const tools = isOrchestrator
+    ? 'Read, Grep, Glob, Bash, Task'
+    : 'Read, Grep, Glob, Bash';
+  const maxTurns = isOrchestrator ? 30 : 20;
+  const memory = isOrchestrator ? 'project' : 'local';
+  const name = agent.title ?? agent.name;
+
+  return [
+    `name: ${name}`,
+    `description: ${description}`,
+    `model: inherit`,
+    `tools: ${tools}`,
+    `maxTurns: ${maxTurns}`,
+    `skills:`,
+    `  - morph-checklist`,
+    `memory: ${memory}`,
+    ``
+  ].join('\n');
+}
+```
+
+### Step 4: Run tests to verify they pass
+
+```bash
+npm test -- test/utils/agents-installer.test.js
+```
+
+Expected: All 11 tests pass (5 original + 6 new).
+
+### Step 5: Run full suite to verify no regressions
+
+```bash
+npm test
+```
+
+Expected: All existing tests pass, 6 new tests pass.
+
+### Step 6: Commit
+
+```bash
+git add src/utils/agents-installer.js test/utils/agents-installer.test.js
+git commit -m "feat(agents): add tier-based model/tools/maxTurns/skills/memory to agent frontmatter"
+```
+
+---
+
+## Task 2: Upgrade Stop hook to `type: "agent"`
+
+**Context:** The current Stop hook runs `validate-completion.js`, a Node.js script that reads `state.json` and injects advisory context. The docs support `type: "agent"` — a subagent with tool access that makes a `{"ok": true/false}` decision. This replaces the Node.js script with an inline LLM-based check.
+
+**Key difference:** The current hook is *advisory* (injects context, always exits 0). The new hook is *blocking* (returns `ok: false` to continue Claude working). This changes behavior — Claude will be asked to continue if work is incomplete, rather than just warned.
+
+**Marker problem:** `removeMorphHooks()` identifies morph hooks by path pattern in `command`. Agent hooks have no `command`. We must add `_morph: true` to all morph hook entries so the cleanup logic can identify them regardless of type.
+
+**Files:**
+- Modify: `src/utils/hooks-installer.js`
+- Test: `test/hooks/hooks-installer.test.js`
+
+---
+
+### Step 1: Write failing tests
+
+Add to `test/hooks/hooks-installer.test.js` inside the `describe('installClaudeHooks', ...)` block:
+
+```js
+test('Stop hook uses type "agent" not type "command"', async () => {
+  await installClaudeHooks(tempDir);
+  const settings = readSettings();
+
+  const stopHooks = settings.hooks.Stop;
+  assert.ok(stopHooks, 'Stop event should exist');
+  assert.ok(stopHooks.length > 0);
+  const stopHook = stopHooks[0];
+  assert.ok(stopHook.hooks?.length > 0);
+  assert.strictEqual(stopHook.hooks[0].type, 'agent', 'Stop hook should use type: agent');
+});
+
+test('Stop hook has prompt and timeout fields', async () => {
+  await installClaudeHooks(tempDir);
+  const settings = readSettings();
+
+  const stopHook = settings.hooks.Stop[0].hooks[0];
+  assert.ok(typeof stopHook.prompt === 'string', 'agent hook should have prompt');
+  assert.ok(stopHook.prompt.includes('.morph/state.json'), 'prompt should reference state.json');
+  assert.ok(typeof stopHook.timeout === 'number', 'agent hook should have timeout');
+});
+
+test('SubagentStart hook is installed with morph-.* matcher', async () => {
+  await installClaudeHooks(tempDir);
+  const settings = readSettings();
+
+  assert.ok(settings.hooks.SubagentStart, 'SubagentStart event should exist');
+  const entry = settings.hooks.SubagentStart[0];
+  assert.strictEqual(entry.matcher, 'morph-.*');
+});
+
+test('morph hook entries have _morph marker for cleanup identification', async () => {
+  await installClaudeHooks(tempDir);
+  const settings = readSettings();
+
+  // Check a known morph hook event
+  const preToolUse = settings.hooks.PreToolUse;
+  const morphEntry = preToolUse.find(e => e._morph === true);
+  assert.ok(morphEntry, 'at least one PreToolUse entry should have _morph: true');
+});
+```
+
+### Step 2: Run tests to verify they fail
+
+```bash
+npm test -- test/hooks/hooks-installer.test.js
+```
+
+Expected: FAIL — Stop hook still uses `type: "command"`, no `SubagentStart`, no `_morph` marker.
+
+### Step 3: Update `MORPH_HOOKS` in `hooks-installer.js`
+
+**3a.** Add `_morph: true` to each hook entry in `MORPH_HOOKS`. Change every `hooks: [...]` array item wrapper to include the marker. Example — the SessionStart entry becomes:
+
+```js
+{
+  event: 'SessionStart',
+  matcher: 'startup|resume|compact',
+  _morph: true,
+  hooks: [{ type: 'command', command: 'node framework/hooks/claude-code/session-start/inject-morph-context.js' }]
+},
+```
+
+Do this for ALL entries in `MORPH_HOOKS` (9 existing entries).
+
+**3b.** Replace the Stop entry:
+
+```js
+// BEFORE:
+{
+  event: 'Stop',
+  matcher: null,
+  hooks: [{
+    type: 'command',
+    command: 'node framework/hooks/claude-code/stop/validate-completion.js'
+  }]
+},
+
+// AFTER:
+{
+  event: 'Stop',
+  matcher: null,
+  _morph: true,
+  hooks: [{
+    type: 'agent',
+    prompt: `Check if the active morph-spec feature phase outputs are complete.
+1. Read the file .morph/state.json to find features with status "in_progress".
+2. For each in_progress feature, check if required output files for the current phase exist and are non-empty.
+   - proposal phase: .morph/features/{feature}/0-proposal/proposal.md
+   - design phase: .morph/features/{feature}/1-design/spec.md
+   - tasks phase: .morph/features/{feature}/3-tasks/tasks.md
+   - implement phase: check tasks.completed vs tasks.total from state.json
+3. If all required outputs exist and tasks are complete, return {"ok": true}.
+4. If any required output is missing or empty, return {"ok": false, "reason": "Missing output: <path>"}.
+5. If state.json does not exist or no feature is in_progress, return {"ok": true}.
+Do NOT modify any files. Read only.`,
+    timeout: 60
+  }]
+},
+```
+
+**3c.** Add SubagentStart entry (after the Notification entry):
+
+```js
+// === SubagentStart ===
+{
+  event: 'SubagentStart',
+  matcher: 'morph-.*',
+  _morph: true,
+  hooks: [{
+    type: 'command',
+    command: 'node framework/hooks/claude-code/subagent/log-agent-start.js'
+  }]
+},
+```
+
+**3d.** Update `removeMorphHooks()` to detect `_morph: true` marker (not just command path):
+
+```js
+function removeMorphHooks(settings) {
+  const morphPathPattern = /framework\/hooks\/claude-code\//;
+
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+
+    settings.hooks[event] = entries.filter(entry => {
+      // Remove if marked with _morph flag
+      if (entry._morph === true) return false;
+
+      if (!Array.isArray(entry.hooks)) return true;
+      // Legacy detection: remove if all hooks are morph-managed command hooks
+      const nonMorphHooks = entry.hooks.filter(h =>
+        typeof h.command !== 'string' || !morphPathPattern.test(h.command)
+      );
+      return nonMorphHooks.length > 0;
+    });
+
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+}
+```
+
+**3e.** Update the install loop to propagate `_morph: true` to the installed entry:
+
+```js
+// In the for loop inside installClaudeHooks():
+const entry = { _morph: true };  // ← add this flag
+if (matcher) {
+  entry.matcher = matcher;
+}
+entry.hooks = hooks.map(h => {
+  // For agent/prompt type hooks, pass through as-is (no command path transform)
+  if (h.type === 'agent' || h.type === 'prompt') {
+    return { type: h.type, prompt: h.prompt, timeout: h.timeout };
+  }
+  return {
+    type: h.type,
+    command: `node "$CLAUDE_PROJECT_DIR/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
+    ...(h.timeout ? { timeout: h.timeout } : {})
+  };
+});
+```
+
+### Step 4: Run tests to verify they pass
+
+```bash
+npm test -- test/hooks/hooks-installer.test.js
+```
+
+Expected: All tests pass, including the 4 new ones.
+
+### Step 5: Run full suite
+
+```bash
+npm test
+```
+
+Expected: All existing tests pass. Note: the `installs all hook events` test checks `settings.hooks.Stop` — this still passes since Stop still exists, just uses type:agent now.
+
+### Step 6: Commit
+
+```bash
+git add src/utils/hooks-installer.js test/hooks/hooks-installer.test.js
+git commit -m "feat(hooks): upgrade Stop hook to type:agent; add SubagentStart hook; add _morph marker"
+```
+
+---
+
+## Task 3: Create `framework/hooks/claude-code/subagent/log-agent-start.js`
+
+**Context:** The SubagentStart hook added in Task 2 references this script. It needs to exist and be a simple, fail-open logger.
+
+**Files:**
+- Create: `framework/hooks/claude-code/subagent/log-agent-start.js`
+
+---
+
+### Step 1: Write the hook script
+
+```js
+#!/usr/bin/env node
+
+/**
+ * SubagentStart Hook: Log Morph Agent Activation
+ *
+ * Event: SubagentStart (matcher: morph-.*)
+ *
+ * Appends a JSON line to .morph/logs/agents.log whenever a morph
+ * native subagent is activated. Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'path';
+
+try {
+  const input = readFileSync('/dev/stdin', 'utf-8');
+  const data = JSON.parse(input);
+
+  const logDir = join(process.cwd(), '.morph', 'logs');
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+
+  const logPath = join(logDir, 'agents.log');
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    agentType: data.agent_type ?? data.agentType ?? 'unknown',
+    sessionId: data.session_id ?? null
+  }) + '\n';
+
+  writeFileSync(logPath, entry, { flag: 'a', encoding: 'utf-8' });
+} catch {
+  // Fail-open: never block agent activation
+}
+
+process.exit(0);
+```
+
+**Windows note:** `/dev/stdin` does not exist on Windows. Use `process.stdin` with a streaming approach. For cross-platform support, replace the stdin read with:
+
+```js
+import { readFileSync } from 'node:fs';
+
+function readStdin() {
+  try {
+    // Unix
+    return readFileSync('/dev/stdin', 'utf-8');
+  } catch {
+    // Windows fallback: read from fd 0
+    return readFileSync(0, 'utf-8');
+  }
+}
+```
+
+Actually, use the pattern already used by the other hooks. Check `framework/hooks/shared/stdin-reader.js` for the correct stdin reading utility.
+
+### Step 2: Check the existing stdin pattern
+
+```bash
+cat framework/hooks/shared/stdin-reader.js
+```
+
+Use whatever pattern it exports (likely `readStdin()` or similar). Import and use it.
+
+### Step 3: Run full test suite (no new unit tests for this hook — it's a simple I/O script)
+
+```bash
+npm test
+```
+
+Expected: All tests still pass. No regressions.
+
+### Step 4: Commit
+
+```bash
+git add framework/hooks/claude-code/subagent/log-agent-start.js
+git commit -m "feat(hooks): add SubagentStart log-agent-start.js hook script"
+```
+
+---
+
+## Task 4: Install level-2 skills in `skills-installer.js`
+
+**Context:** Level-2 domain skills (`level-2-domains/`) contain 17 `.md` files across 7 subdirectories. The skills-installer currently only handles flat directories (level-0 and level-1). Level-2 requires recursive walk. Level-3 and level-4 only have README.md — no content to install yet.
+
+**Duplicate file warning:** `hangfire-orchestrator.md` exists in both `backend/` and `integrations/` subdirectories. The flat install will overwrite with whichever comes last. This is acceptable — they likely have different content, but users get one version. Document this in comments.
+
+**Files:**
+- Modify: `src/utils/skills-installer.js`
+- Create: `test/utils/skills-installer.test.js`
+
+---
+
+### Step 1: Write failing tests
+
+Create `test/utils/skills-installer.test.js`:
+
+```js
+/**
+ * Tests for src/utils/skills-installer.js
+ */
+
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, readdir } from 'node:fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { installSkills } from '../../src/utils/skills-installer.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// skills-installer uses FRAMEWORK_SKILLS_DIR hardcoded from __dirname
+// So we can only test with the real framework directory
+
+describe('installSkills', () => {
+  let tmpDir;
+
+  before(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'morph-skills-'));
+  });
+
+  after(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('creates .claude/skills/ directory', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    assert.ok(files.length > 0, 'should have skill files installed');
+  });
+
+  test('installs level-0-meta skills', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    // morph-checklist comes from level-0-meta
+    assert.ok(files.some(f => f === 'morph-checklist.md'), 'morph-checklist.md should be installed');
+    assert.ok(files.some(f => f === 'code-review.md'), 'code-review.md should be installed');
+  });
+
+  test('installs level-1-workflows skills', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    assert.ok(files.some(f => f === 'phase-design.md'), 'phase-design.md should be installed');
+    assert.ok(files.some(f => f === 'phase-implement.md'), 'phase-implement.md should be installed');
+  });
+
+  test('installs level-2-domains skills from subdirectories', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    // These come from level-2-domains subdirectories
+    assert.ok(files.some(f => f === 'blazor-builder.md'), 'blazor-builder.md should be installed');
+    assert.ok(files.some(f => f === 'dotnet-senior.md'), 'dotnet-senior.md should be installed');
+    assert.ok(files.some(f => f === 'azure-architect.md'), 'azure-architect.md should be installed');
+    assert.ok(files.some(f => f === 'testing-specialist.md'), 'testing-specialist.md should be installed');
+  });
+
+  test('does not install README.md files', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    assert.ok(!files.includes('README.md'), 'README.md should not be installed');
+  });
+
+  test('installs more than 20 skills total (level-0 + level-1 + level-2)', async () => {
+    await installSkills(tmpDir);
+    const files = await readdir(join(tmpDir, '.claude', 'skills'));
+    // level-0: 6, level-1: 8, level-2: ~17 = ~31 total
+    assert.ok(files.length > 20, `should install more than 20 skills, got ${files.length}`);
+  });
+
+  test('is idempotent — running twice produces same result', async () => {
+    await installSkills(tmpDir);
+    const firstCount = (await readdir(join(tmpDir, '.claude', 'skills'))).length;
+    await installSkills(tmpDir);
+    const secondCount = (await readdir(join(tmpDir, '.claude', 'skills'))).length;
+    assert.strictEqual(firstCount, secondCount, 'file count should not change on second run');
+  });
+});
+```
+
+### Step 2: Run tests to verify they fail
+
+```bash
+npm test -- test/utils/skills-installer.test.js
+```
+
+Expected: FAIL — `blazor-builder.md`, `dotnet-senior.md`, `azure-architect.md`, `testing-specialist.md` not found (level-2 not installed). Also fails on `> 20 skills` count.
+
+### Step 3: Update `skills-installer.js`
+
+Replace the `SKILL_LEVELS_TO_INSTALL` constant and add a recursive walk helper:
+
+```js
+/**
+ * Skill levels to install as flat files in .claude/skills/.
+ * Level-0 (meta), Level-1 (workflows), Level-2 (domain specialists).
+ * Level-3 and Level-4 only contain README.md — no content to install.
+ * For Level-2, subdirectories are walked recursively and files are installed flat.
+ * Note: if two subdirs have a file with the same name, last-write wins.
+ */
+const SKILL_LEVELS_TO_INSTALL = ['level-0-meta', 'level-1-workflows', 'level-2-domains'];
+```
+
+Replace the install loop to handle subdirectories:
+
+```js
+export async function installSkills(projectDir) {
+  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
+  mkdirSync(claudeSkillsDir, { recursive: true });
+
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+
+    installSkillsFromDir(levelDir, claudeSkillsDir);
+  }
+}
+
+/**
+ * Recursively copy all .md skill files (excluding README.md) from srcDir
+ * to destDir as flat files.
+ * @param {string} srcDir
+ * @param {string} destDir
+ */
+function installSkillsFromDir(srcDir, destDir) {
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      // Recurse into subdirectory
+      installSkillsFromDir(srcPath, destDir);
+    } else if (entry.endsWith('.md') && entry !== 'README.md') {
+      const destPath = join(destDir, basename(entry));
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+```
+
+### Step 4: Run tests to verify they pass
+
+```bash
+npm test -- test/utils/skills-installer.test.js
+```
+
+Expected: All 7 tests pass.
+
+### Step 5: Run full suite
+
+```bash
+npm test
+```
+
+Expected: All existing tests pass, 7 new tests pass.
+
+### Step 6: Commit
+
+```bash
+git add src/utils/skills-installer.js test/utils/skills-installer.test.js
+git commit -m "feat(skills): install level-2 domain skills to .claude/skills/ with recursive walk"
+```
+
+---
+
+## Task 5: Final verification
+
+### Step 1: Confirm test counts
+
+```bash
+npm run test:coverage:summary
+```
+
+Expected: More tests than before Task 1 (was ~588). Verify no regressions.
+
+### Step 2: Smoke test with `morph-spec init`
+
+```bash
+node bin/morph-spec.js init --force --skip-mcp --skip-detection
+```
+
+Verify:
+```bash
+# Check agents have new frontmatter
+head -15 .claude/agents/morph-standards-architect.md
+# Expected: model:, tools:, maxTurns:, skills:, memory: all present
+
+# Check Stop hook type
+node -e "const s=JSON.parse(require('fs').readFileSync('.claude/settings.local.json')); console.log('Stop type:', s.hooks.Stop[0].hooks[0].type)"
+# Expected: Stop type: agent
+
+# Check SubagentStart hook exists
+node -e "const s=JSON.parse(require('fs').readFileSync('.claude/settings.local.json')); console.log('SubagentStart:', !!s.hooks.SubagentStart)"
+# Expected: SubagentStart: true
+
+# Check level-2 skills installed
+ls .claude/skills/ | grep -E "blazor|dotnet|azure" | head
+# Expected: blazor-builder.md, dotnet-senior.md, azure-architect.md etc.
+
+# Check total skill count
+ls .claude/skills/*.md | wc -l
+# Expected: > 20
+```
+
+### Step 3: Commit any final cleanup
+
+If any cleanup needed:
+```bash
+git add <changed files>
+git commit -m "chore: native enrichment cleanup after smoke test"
+```
+
+---
+
+## Summary of Files Changed
+
+| File | Change |
+|------|--------|
+| `src/utils/agents-installer.js` | Add `buildFrontmatter()` with tier-based model/tools/maxTurns/skills/memory |
+| `test/utils/agents-installer.test.js` | 6 new tests for richer frontmatter |
+| `src/utils/hooks-installer.js` | Stop→type:agent, SubagentStart hook, `_morph` marker, updated `removeMorphHooks()` |
+| `test/hooks/hooks-installer.test.js` | 4 new tests for Stop type, SubagentStart, `_morph` marker |
+| `framework/hooks/claude-code/subagent/log-agent-start.js` | **NEW** — fail-open agent activation logger |
+| `src/utils/skills-installer.js` | Add level-2 to install list, add recursive `installSkillsFromDir()` |
+| `test/utils/skills-installer.test.js` | **NEW** — 7 tests for skills installation |
+
+---
+
+*Plan saved: 2026-02-22*
+*Design doc: `docs/plans/2026-02-22-native-enrichment-design.md`*