@polymorphism-tech/morph-spec 4.3.7 → 4.5.0

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

@@ -0,0 +1,244 @@
+# Claude Code Native Enrichment — Design Document
+
+> **Session:** 2026-02-22
+> **Approach:** Targeted native enrichment (Approach A)
+> **Output:** Design doc + implementation plan
+> **Docs reviewed:** permissions, sub-agents, hooks-guide, memory, settings
+
+---
+
+## Background
+
+This analysis was driven by the prompt at `.wiki/prompts/claude_code_docs_to_morph.md`:
+read the official Claude Code documentation, analyze morph-spec, compare philosophies,
+and produce concrete architectural improvements.
+
+The prior alignment work (plan `2026-02-22-claude-settings.md`) brought morph-spec into
+good native alignment. This document identifies the **next layer** of improvements
+that the docs reveal but morph-spec hasn't yet leveraged.
+
+---
+
+## What Is Already Well-Aligned
+
+| Native primitive | morph state |
+|---|---|
+| `permissions.deny` — file protection | ✓ protects `state.json` + `framework/**` |
+| `.claude/agents/` subagent discovery | ✓ tier-1 + tier-2 installed via agents-installer |
+| `.claude/skills/` flat install | ✓ level-0 + level-1 installed |
+| `.claude/rules/` path-scoped rules | ✓ 5 rules files (morph-workflow, csharp, frontend, testing, infra) |
+| `$schema`, `env`, `attribution`, `plansDirectory` | ✓ written by hooks-installer |
+| Global `statusLine` at `~/.claude/` | ✓ Python + shell scripts |
+| `.claude/CLAUDE.md` runtime instructions | ✓ `framework/CLAUDE_runtime.md` |
+| `SessionStart compact` hook for context re-injection | ✓ `inject-morph-context.js` |
+| `@.morph/context/README.md` import in CLAUDE.md | ✓ |
+
+---
+
+## Gaps Identified
+
+### G1: Agent frontmatter is bare minimum
+
+Current `morph-{id}.md` files in `.claude/agents/` have only `name` + `description`.
+
+The Claude Code subagent spec supports:
+- `model` — assign optimal model per tier (opus for orchestrators)
+- `tools` — restrict tool access per role
+- `maxTurns` — prevent runaway execution
+- `skills` — preload relevant framework skills into agent context
+- `memory` — persistent project memory across sessions
+- `hooks` — agent-scoped lifecycle hooks
+
+None are used. Tier-1 orchestrators could use `memory: project` to accumulate
+project patterns. All agents could have `skills: [morph-workflow]` preloaded.
+
+### G2: All hooks use `type: "command"` (Node.js scripts)
+
+The docs add two higher-level hook types:
+- `type: "prompt"` — single LLM call evaluates a condition
+- `type: "agent"` — spawns an agent with tools for multi-turn verification
+
+The `Stop` hook (`validate-completion.js`) reads `state.json` and checks JSON flags.
+A `type: "agent"` hook could read actual output files and verify they are non-empty
+and semantically valid — without Node.js and with Claude's reasoning.
+
+### G3: Skills levels 2–4 not installed as native skills
+
+`skills-installer.js` installs only `level-0-meta` and `level-1-workflows`.
+
+Users cannot invoke `/blazor`, `/ef-core`, `/authentication`, etc. natively.
+Levels 2–4 exist in `framework/skills/` and should be installed to `.claude/skills/`.
+
+### G4: SubagentStart/SubagentStop hooks unused
+
+The `SubagentStart` event fires when a morph native agent is activated.
+A lightweight log hook on matcher `morph-.*` would capture agent usage
+to `.morph/logs/agents.log` — useful for debugging and analytics.
+
+---
+
+## What Is NOT Changing (Justified Architecture)
+
+| Component | Reason to keep |
+|---|---|
+| `agents.json` as CLI source of truth | Needed for keyword matching, workflow detection, spawn-team |
+| `.morph/state.json` state machine | Claude Code has no native phase concept |
+| `.morph/memory/` | Stores structured morph outputs, distinct from Claude auto-memory |
+| 7-phase workflow system | Core framework differentiator |
+| All 12 existing hooks | Each serves a specific validated purpose |
+| `agents.json` dual-format (JSON + compiled .md) | JSON needed for CLI logic; .md for native discovery |
+
+---
+
+## Improvements
+
+### Improvement 1: Richer agent frontmatter
+
+**File:** `src/utils/agents-installer.js`
+**Change:** Expand `buildBody()` and the YAML header to emit `model`, `tools`,
+`maxTurns`, `skills`, and `memory` fields based on agent tier.
+
+**Tier mapping:**
+
+| Tier | model | tools | maxTurns | skills | memory |
+|------|-------|-------|----------|--------|--------|
+| 1 — Orchestrators | `inherit` | `Read, Grep, Glob, Bash, Task` | 30 | `morph-workflow` | `project` |
+| 2 — Domain Leaders | `inherit` | `Read, Grep, Glob, Bash` | 20 | `morph-workflow` | `local` |
+
+`morph-workflow` refers to the skill at `.claude/skills/morph-workflow.md`
+(copied from `framework/rules/morph-workflow.md` — note: skill vs. rules are
+separate directories; a `morph-workflow` skill should be added to `framework/skills/level-0-meta/`
+or the rules file referenced directly).
+
+**Expected output per agent:**
+```markdown
+---
+name: Chief Architect
+description: Team Lead (Delegate Mode). Coordinate Domain Leaders...
+model: inherit
+tools: Read, Grep, Glob, Bash, Task
+maxTurns: 30
+skills:
+  - morph-workflow
+memory: project
+---
+
+You are the Chief Architect and Team Lead...
+```
+
+**Tests:** Update `test/utils/agents-installer.test.js` to assert
+`model:`, `tools:`, `maxTurns:`, `memory:` appear in generated files.
+
+---
+
+### Improvement 2: Upgrade Stop hook to `type: "agent"`
+
+**File:** `src/utils/hooks-installer.js`
+**Change:** Replace the `Stop` hook entry from `type: "command"` (Node.js script)
+to `type: "agent"` with an inline prompt.
+
+```js
+{
+  event: 'Stop',
+  matcher: null,
+  hooks: [{
+    type: 'agent',
+    prompt: `Check if the active morph-spec feature phase is complete.
+1. Read .morph/state.json to find features with status "in_progress".
+2. For the active feature+phase, check that required output files exist and are non-empty.
+3. If all outputs exist, return {"ok": true}.
+4. If any required output is missing or empty, return {"ok": false, "reason": "Missing: <path>"}.
+Do NOT modify any files.`,
+    timeout: 60
+  }]
+}
+```
+
+**Migration:** Remove `framework/hooks/claude-code/stop/validate-completion.js`
+or keep it as fallback for environments where agent hooks aren't supported.
+Update hook pattern detection in `removeMorphHooks()` to handle `type: "agent"` entries.
+
+**Tests:** Update `test/hooks/hooks-installer.test.js` to assert the Stop hook
+uses `type: "agent"` and has the expected prompt fields.
+
+---
+
+### Improvement 3: Install all skill levels
+
+**File:** `src/utils/skills-installer.js`
+**Change:** Expand `SKILL_LEVELS_TO_INSTALL` to include all 5 levels.
+
+```js
+const SKILL_LEVELS_TO_INSTALL = [
+  'level-0-meta',
+  'level-1-workflows',
+  'level-2-domains',
+  'level-3-technologies',
+  'level-4-patterns'
+];
+```
+
+**Expected native invocations after change:**
+- `/blazor`, `/nextjs`, `/ef-core`, `/azure-devops` (level-3)
+- `/authentication`, `/caching`, `/validation` (level-4)
+- `/frontend`, `/backend`, `/devops` (level-2)
+
+**Tests:** Update `test/utils/skills-installer.test.js` to assert
+level-2, level-3, level-4 skill files are installed.
+
+---
+
+### Improvement 4: SubagentStart logging hook
+
+**New file:** `framework/hooks/claude-code/subagent/log-agent-start.js`
+**Change:** Add a new hook entry in `MORPH_HOOKS` for `SubagentStart`.
+
+Hook logic (log-agent-start.js):
+- Read JSON from stdin (contains `agent_type`)
+- Append `{timestamp, agentType}` to `.morph/logs/agents.log`
+- Exit 0 (always non-blocking)
+
+Hook definition:
+```js
+{
+  event: 'SubagentStart',
+  matcher: 'morph-.*',
+  hooks: [{
+    type: 'command',
+    command: 'node "$CLAUDE_PROJECT_DIR/framework/hooks/claude-code/subagent/log-agent-start.js"'
+  }]
+}
+```
+
+**Tests:** Add to `test/hooks/` for the new hook script.
+
+---
+
+## Success Criteria
+
+1. `morph-spec init` produces `.claude/agents/` files with `model`, `tools`,
+   `maxTurns`, `memory`, `skills` frontmatter fields
+2. `.claude/settings.local.json` Stop hook uses `type: "agent"` not `type: "command"`
+3. `.claude/skills/` contains files from all 5 skill levels (not just 0 + 1)
+4. `SubagentStart` hook entry present in settings with `morph-.*` matcher
+5. All existing tests pass (no regressions)
+6. New tests added for all 4 improvements
+
+---
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/utils/agents-installer.js` | Add tier-based `model`, `tools`, `maxTurns`, `skills`, `memory` to frontmatter |
+| `src/utils/skills-installer.js` | Add levels 2–4 to `SKILL_LEVELS_TO_INSTALL` |
+| `src/utils/hooks-installer.js` | Upgrade Stop hook to `type: "agent"`; add SubagentStart hook |
+| `framework/hooks/claude-code/subagent/log-agent-start.js` | **NEW** — agent activation logger |
+| `test/utils/agents-installer.test.js` | Assert new frontmatter fields |
+| `test/utils/skills-installer.test.js` | Assert levels 2–4 installed |
+| `test/hooks/hooks-installer.test.js` | Assert Stop hook type and SubagentStart entry |
+
+---
+
+*Design approved: 2026-02-22*
+*Next step: writing-plans skill to create step-by-step implementation plan*