@polymorphism-tech/morph-spec 4.7.2 → 4.8.4

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

@@ -1,244 +0,0 @@
-# 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*