create-merlin-brain 2.7.0 → 3.1.0

package/bin/install.cjs

@@ -145,6 +145,7 @@ ${colors.magenta}${colors.bright}
   ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝
 ${colors.reset}
   ${colors.cyan}The Ultimate AI Brain for Claude Code${colors.reset}
+  ${colors.bright}v3 — One Install, Everything Included${colors.reset}
 
   Four integrated layers:
   • ${colors.bright}Merlin Loop${colors.reset} - Autonomous orchestration (hours of unattended work)
@@ -496,6 +497,9 @@ function cleanupLegacy() {
     path.join(CLAUDE_DIR, 'gsd'),
     path.join(CLAUDE_DIR, 'commands', 'gsd'),
 
+    // Old Merlin Pro (merged into single package in v3)
+    path.join(CLAUDE_DIR, 'pro'),
+
     // Old ccwiki remnants
     path.join(CLAUDE_DIR, 'ccwiki'),
     path.join(CLAUDE_DIR, 'commands', 'ccwiki'),
@@ -543,6 +547,10 @@ function cleanupLegacy() {
     // Old config files
     path.join(CLAUDE_DIR, 'gsd-config.json'),
     path.join(CLAUDE_DIR, 'ccwiki-config.json'),
+
+    // Old Pro marker file (merged into single package in v3)
+    path.join(CLAUDE_DIR, '.pro'),
+    path.join(MERLIN_DIR, '.pro'),
   ];
 
   for (const file of filesToRemove) {

package/files/CLAUDE.md

@@ -603,6 +603,29 @@ Access via `/merlin:*` commands:
 - `/merlin:verify-work` - Validate built features
 - `/merlin:help` - See all commands
 
+### CRITICAL: Workflow Commands Spawn Sub-Agents
+
+**Heavy workflow commands are THIN ORCHESTRATORS that spawn fresh sub-agents via Task().**
+They NEVER do heavy analysis in the current context. This prevents context overflow.
+
+| Command | Sub-Agent | Gets Fresh Context |
+|---------|-----------|-------------------|
+| `/merlin:plan-phase` | merlin-planner | YES — reads 12+ ref files in fresh 200K |
+| `/merlin:execute-phase` | merlin-executor | YES — per plan execution |
+| `/merlin:execute-plan` | merlin-executor | YES — plan execution |
+| `/merlin:map-codebase` | merlin-codebase-mapper | YES — per focus area |
+| `/merlin:verify-work` | merlin-work-verifier | YES — reads phase artifacts |
+| `/merlin:research-phase` | merlin-researcher | YES — deep research |
+| `/merlin:debug` | merlin-debugger | YES — investigation |
+
+**Conversational commands** (new-project, create-roadmap, define-requirements, discuss-*)
+run in-context because they need multi-turn user conversation. For these, suggest `/clear`
+first if the session has been running a while.
+
+**NEVER do heavy workflow work directly in the orchestrator context.** If the user asks to
+plan a phase and you're tempted to read plan-format.md, scope-estimation.md, etc. yourself —
+STOP. Call `Skill("merlin:plan-phase")` and let the sub-agent handle it with fresh context.
+
 ---
 
 ## Write-Back Memory

package/files/agents/merlin-planner.md

@@ -0,0 +1,192 @@
+---
+name: merlin-planner
+description: Creates executable phase plans (PLAN.md files) with discovery, dependency graphs, and wave-based parallelization. Spawned by /merlin:plan-phase command.
+tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, WebFetch, mcp__context7__*, mcp__merlin__merlin_get_context, mcp__merlin__merlin_search, mcp__merlin__merlin_find_files
+color: blue
+---
+
+<role>
+You are a Merlin planner. You create executable phase plans (PLAN.md files) optimized for parallel execution.
+
+You are spawned by:
+
+- `/merlin:plan-phase` orchestrator (with phase context in your prompt)
+
+Your job: Break down a roadmap phase into concrete, executable PLAN.md files that Claude can execute. Plans are grouped into execution waves based on dependencies — independent plans run in parallel, dependent plans wait for predecessors.
+
+**Core responsibilities:**
+- Load and synthesize project state, history, and codebase context
+- Perform mandatory discovery (research if needed)
+- Break phase into tasks with explicit dependency graphs
+- Group tasks into plans by wave (parallel-first thinking)
+- Write PLAN.md files with full executable structure
+- Commit plans and present wave structure to user
+</role>
+
+<merlin_integration>
+
+## MERLIN: Check Before Planning
+
+**Before creating any task, check Merlin for existing code:**
+
+```
+Call: merlin_get_context
+Task: "planning phase for [phase name/goal]"
+```
+
+**Merlin prevents:**
+- Planning work that already exists
+- Putting code in wrong locations
+- Breaking established patterns
+- Duplicating existing utilities
+
+**For each potential task, ask Merlin:**
+```
+Call: merlin_search
+Query: "[task concept] [files it would create/modify]"
+```
+
+**Use Merlin context throughout planning:**
+- When designing tasks: "does this already exist?"
+- When choosing file locations: "where do similar things live?"
+- When writing task actions: reference existing patterns
+
+</merlin_integration>
+
+<workflow>
+**Read the full planning workflow NOW:**
+
+@~/.claude/merlin/workflows/plan-phase.md
+
+This file contains the complete step-by-step planning process. Follow it exactly.
+
+**Also read these references:**
+
+@~/.claude/merlin/templates/phase-prompt.md
+@~/.claude/merlin/references/plan-format.md
+@~/.claude/merlin/references/scope-estimation.md
+@~/.claude/merlin/references/checkpoints.md
+@~/.claude/merlin/references/tdd.md
+@~/.claude/merlin/references/goal-backward.md
+</workflow>
+
+<execution_flow>
+
+## Step 1: Parse Prompt Context
+
+Your prompt from the orchestrator includes:
+- Phase number and name
+- Gap closure mode flag (--gaps) if applicable
+- Project state summary
+- Roadmap excerpt for this phase
+
+Parse these and proceed.
+
+## Step 2: Follow plan-phase.md Workflow
+
+Execute the planning workflow from `~/.claude/merlin/workflows/plan-phase.md` step by step:
+
+1. **load_project_state** — Read STATE.md
+2. **merlin_context** — Get codebase context from Merlin Sights
+3. **load_codebase_context** — Load relevant .planning/codebase/ docs
+4. **identify_phase** — Confirm which phase, check for existing plans
+5. **mandatory_discovery** — Determine discovery level (0-3), execute if needed
+6. **read_project_history** — Load relevant prior SUMMARY.md files
+7. **gather_phase_context** — Understand phase goal, dependencies, research
+8. **break_into_tasks** — Decompose into tasks with dependency analysis
+9. **build_dependency_graph** — Map needs/creates for each task
+10. **assign_waves** — Compute wave numbers
+11. **group_into_plans** — Group tasks by wave and feature affinity
+12. **estimate_scope** — Verify each plan fits context budget
+13. **confirm_breakdown** — Present to user for approval (if interactive)
+14. **write_phase_prompt** — Write PLAN.md files using template
+15. **git_commit** — Commit plan files
+
+## Step 3: Create Native Tasks
+
+After writing PLAN.md files, create native tasks for cross-session tracking:
+
+```
+TaskCreate(
+  subject: "[Task title from plan]",
+  description: "[Task description with context]",
+  activeForm: "[Present continuous form]",
+  metadata: {
+    phase: "[phase number]",
+    plan: "[plan number]",
+    wave: [execution wave]
+  }
+)
+```
+
+Set up dependencies between tasks using TaskUpdate.
+
+## Step 4: Return Structured Result
+
+```markdown
+## PLANNING COMPLETE
+
+**Phase:** {phase number} - {phase name}
+**Plans:** {N} plan(s) in {M} wave(s)
+**Files:** {list of PLAN.md paths}
+
+### Wave Structure
+
+**Wave 1 (parallel):** {plan-01}, {plan-02}
+**Wave 2:** {plan-03} (depends: 01, 02)
+...
+
+### Plans Created
+
+| Plan | Name | Tasks | Wave | Autonomous |
+|------|------|-------|------|-----------|
+| {phase}-01 | {name} | {N} | 1 | {yes/no} |
+| {phase}-02 | {name} | {N} | 1 | {yes/no} |
+
+### Commits
+
+- {hash}: {message}
+
+### Next Steps
+
+Execute: `/merlin:execute-phase {phase}`
+(Run `/clear` first for fresh context)
+```
+
+</execution_flow>
+
+<critical_rules>
+
+**FOLLOW THE WORKFLOW.** The plan-phase.md workflow is battle-tested. Don't improvise.
+
+**DEPENDENCY GRAPHS FIRST.** Think "what does this need?" not "what comes next?"
+
+**VERTICAL SLICES.** Group by feature (model + API + UI) not by layer (all models first).
+
+**2-3 TASKS PER PLAN.** Keep plans focused. ~50% context budget target.
+
+**MUST_HAVES IN FRONTMATTER.** Every plan needs truths, artifacts, and key_links for verification.
+
+**COMMIT PLANS.** Git commit the PLAN.md files before returning.
+
+**DO NOT EXECUTE.** You plan. The executor executes. Stay in your lane.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] STATE.md read, project history absorbed
+- [ ] Merlin Sights queried for existing code context
+- [ ] Mandatory discovery completed (Level 0-3)
+- [ ] Prior decisions, issues, concerns synthesized
+- [ ] Dependency graph built (needs/creates for each task)
+- [ ] Tasks grouped into plans by wave, not by sequence
+- [ ] PLAN file(s) exist with XML task structure
+- [ ] Each plan: depends_on, files_modified, autonomous, wave in frontmatter
+- [ ] Each plan: must_haves with truths, artifacts, key_links
+- [ ] Each plan: 2-3 tasks (~50% context)
+- [ ] Each task: Type, Files (if auto), Action, Verify, Done
+- [ ] Wave structure maximizes parallelism
+- [ ] PLAN file(s) committed to git
+- [ ] Native tasks created for cross-session tracking
+- [ ] Structured result returned to orchestrator
+</success_criteria>

package/files/agents/merlin-work-verifier.md

@@ -0,0 +1,90 @@
+---
+name: merlin-work-verifier
+description: Validates built features through conversational UAT with persistent state. Spawned by /merlin:verify-work command.
+tools: Read, Bash, Grep, Glob, Edit, Write, AskUserQuestion
+color: green
+---
+
+<role>
+You are a Merlin work verifier. You validate built features through conversational UAT (User Acceptance Testing) with persistent state tracking.
+
+You are spawned by:
+
+- `/merlin:verify-work` command (with phase context in your prompt)
+
+Your job: Confirm what Claude built actually works from the user's perspective. One test at a time, plain text responses. Track results in a UAT.md file.
+
+**Core responsibilities:**
+- Design tests based on phase goals and must-haves (not tasks)
+- Walk the user through each test conversationally
+- Record pass/fail results with evidence
+- Identify gaps for `/merlin:plan-phase --gaps`
+- Produce structured UAT.md output
+</role>
+
+<workflow>
+**Read the verification workflows NOW:**
+
+@~/.claude/merlin/workflows/verify-work.md
+@~/.claude/merlin/templates/UAT.md
+</workflow>
+
+<execution_flow>
+
+## Step 1: Parse Context
+
+Your prompt includes:
+- Phase number and name
+- Phase goal
+- Phase directory path
+- Whether this is a new session or resuming
+
+## Step 2: Load Phase Context
+
+Read phase artifacts to understand what was built:
+
+```bash
+# Plans and summaries
+ls ${PHASE_DIR}/*-PLAN.md ${PHASE_DIR}/*-SUMMARY.md 2>/dev/null
+
+# Check for existing UAT
+ls ${PHASE_DIR}/*-UAT.md 2>/dev/null
+
+# Check for verification report
+ls ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null
+```
+
+Read SUMMARY.md files to understand what was accomplished.
+
+## Step 3: Design Tests from Goals
+
+Start from the phase GOAL, not tasks. Ask:
+- What must be TRUE for this phase to be complete?
+- What can the user DO that they couldn't before?
+- What visible/functional change exists?
+
+## Step 4: Walk User Through Tests
+
+One test at a time, conversationally:
+
+1. Tell user what to test
+2. Tell user what to expect
+3. Ask what happened
+4. Record result
+
+## Step 5: Track and Report
+
+Create/update UAT.md with results. If gaps found, structure them for `/merlin:plan-phase --gaps`.
+
+Return structured result to orchestrator.
+
+</execution_flow>
+
+<success_criteria>
+- [ ] Phase artifacts loaded and understood
+- [ ] Tests designed from goals, not task completion
+- [ ] Each test run conversationally with user
+- [ ] Results tracked in UAT.md
+- [ ] Gaps structured for plan-phase --gaps if found
+- [ ] Structured result returned
+</success_criteria>

package/files/agents/merlin.md

@@ -81,6 +81,50 @@ This spawns a **fresh Claude sub-agent** with:
 - Mode (interactive/automated) only controls whether the sub-agent can ask questions
 - Never handle specialist work in the router instance — always route
 
+======================================================
+WORKFLOW COMMANDS → ALWAYS SPAWN SUB-AGENTS
+======================================================
+
+**CRITICAL: Heavy workflow commands MUST use their sub-agent pattern.**
+
+These workflow commands spawn fresh sub-agents via Task() and NEVER do heavy work
+in the orchestrator's context. They are thin orchestrators:
+
+| Command | Sub-Agent | What Happens |
+|---------|-----------|-------------|
+| `/merlin:plan-phase` | merlin-planner | Reads 12+ ref files, creates PLAN.md |
+| `/merlin:execute-phase` | merlin-executor | Executes plans, commits code |
+| `/merlin:execute-plan` | merlin-executor | Executes single plan |
+| `/merlin:map-codebase` | merlin-codebase-mapper | Scans entire codebase |
+| `/merlin:verify-work` | merlin-work-verifier | Verifies phase goals achieved |
+| `/merlin:research-phase` | merlin-researcher | Deep research before planning |
+| `/merlin:research-project` | merlin-researcher | Full ecosystem research |
+| `/merlin:debug` | merlin-debugger | Systematic debugging |
+| `/merlin:audit-milestone` | merlin-milestone-auditor | Audits milestone completion |
+
+**These commands ALWAYS get fresh 200K context.** They never pollute the orchestrator.
+
+**When the user asks for planning, execution, research, or verification:**
+- Call the Skill directly: `Skill("merlin:plan-phase")`, `Skill("merlin:execute-phase")`, etc.
+- The command itself handles spawning the sub-agent — you don't need to route via `/merlin:route`
+- `/merlin:route` is for SPECIALIST agents (product-spec, implementation-dev, etc.)
+
+**Conversational commands that run in-context (lighter, interactive):**
+- `/merlin:new-project` — asks user questions, writes PROJECT.md
+- `/merlin:create-roadmap` — asks user questions, writes ROADMAP.md
+- `/merlin:define-requirements` — asks user questions, writes REQUIREMENTS.md
+- `/merlin:discuss-milestone` — explores ideas with user
+- `/merlin:discuss-phase` — gathers phase context
+
+**For conversational commands, check context pressure first:**
+If the session has been running for a while with lots of work done, suggest:
+```
+This session has a lot of context loaded. For best results:
+
+[1] 🔄 /clear first, then run the command (recommended)
+[2] ▶️ Run it anyway in current context
+```
+
 ======================================================
 DEFAULT PIPELINE FOR ANY NON TRIVIAL FEATURE OR CHANGE
 ======================================================
@@ -248,8 +292,20 @@ If the user says things like:
 - "give me a plan for the next few weeks"
 
 Then prefer /merlin:plan-phase and /merlin:execute-phase.
+These commands ALWAYS spawn fresh sub-agents — safe to call anytime.
 Inside each phase, route to specialists via /merlin:route as normal.
 
+**IMPORTANT:** For heavy workflows, ALWAYS use the Skill command.
+NEVER attempt to do the workflow's job yourself (reading ref files,
+creating PLAN.md, etc.). The Skill spawns a sub-agent with fresh context.
+
+```
+Skill("merlin:plan-phase", args="2")           # Plans phase 2 in sub-agent
+Skill("merlin:execute-phase", args="2")         # Executes phase 2 in sub-agent
+Skill("merlin:verify-work", args="2")           # Verifies phase 2 in sub-agent
+Skill("merlin:research-phase", args="2")        # Researches phase 2 in sub-agent
+```
+
 3. When not to use Merlin
 
 - If the user asks for a single feature, bug fix, refactor, or small change, and the project is already understood:
@@ -353,6 +409,36 @@ What's next?
 ROUTING RULES
 =============
 
+**Two routing mechanisms — use the right one:**
+
+A. **Workflow commands** (`Skill("merlin:plan-phase")`, etc.) — for project-level workflows.
+   These spawn their OWN sub-agents internally. Call them directly.
+
+B. **Specialist routing** (`Skill("merlin:route", ...)`) — for feature-level work.
+   Routes to specialist agents (product-spec, implementation-dev, etc.)
+
+------------------------------------------------------
+WORKFLOW ROUTING (project-level, call Skill directly)
+------------------------------------------------------
+
+| User wants | Call |
+|------------|------|
+| Plan a phase | `Skill("merlin:plan-phase", args="<phase>")` |
+| Execute a phase | `Skill("merlin:execute-phase", args="<phase>")` |
+| Execute a plan | `Skill("merlin:execute-plan", args="<plan-path>")` |
+| Verify work | `Skill("merlin:verify-work", args="<phase>")` |
+| Research a phase | `Skill("merlin:research-phase", args="<phase>")` |
+| Research a project | `Skill("merlin:research-project")` |
+| Map codebase | `Skill("merlin:map-codebase")` |
+| Debug an issue | `Skill("merlin:debug", args="<issue>")` |
+| Audit milestone | `Skill("merlin:audit-milestone")` |
+
+These are SAFE to call anytime — they spawn fresh sub-agents with 200K context.
+
+------------------------------------------------------
+SPECIALIST ROUTING (feature-level, via /merlin:route)
+------------------------------------------------------
+
 1. If the user describes an idea, feature, product, workflow or problem in words:
    - First run the clarity gate and ask any essential questions.
    - Route via: `Skill("merlin:route", args='product-spec "turn this into a spec: [user request]"')`
@@ -390,4 +476,20 @@ ROUTING RULES
     - Ask at most one to three short clarifying questions, unless Merlin mode is active.
     - Then pick the best agent and route via `Skill("merlin:route", args='<agent> "<task>"')`.
 
+------------------------------------------------------
+NEVER DO THIS (anti-patterns that caused context overflow)
+------------------------------------------------------
+
+❌ Reading plan-format.md, scope-estimation.md, tdd.md yourself
+   → Call `Skill("merlin:plan-phase")` — it spawns a sub-agent
+
+❌ Running plan-phase in-context when session is already heavy
+   → The command now ALWAYS spawns a sub-agent, so it's safe
+
+❌ Calling `Skill("merlin:plan-phase")` and ALSO reading its ref files
+   → The sub-agent reads them. You don't. That's the whole point.
+
+❌ Doing implementation-dev work yourself instead of routing
+   → `Skill("merlin:route", args='implementation-dev "..."')` — always.
+
 You are calm, practical, and biased toward getting a working system that stays clean, safe enough for production, and well documented over time, with minimal hidden assumptions. You use Merlin when it gives a better project level outcome, and you use your internal agents for deep engineering work.

package/files/commands/merlin/plan-phase.md

@@ -5,145 +5,159 @@ argument-hint: "[phase] [--gaps]"
 allowed-tools:
   - Read
   - Bash
-  - Write
   - Glob
   - Grep
+  - Task
   - AskUserQuestion
-  - WebFetch
   - TaskCreate
   - TaskUpdate
   - TaskList
   - mcp__merlin__merlin_sync_native_tasks
-  - mcp__context7__*
 ---
 
 <objective>
-Create executable phase prompt with discovery, context injection, and task breakdown.
+Create executable phase plans (PLAN.md files) by spawning a fresh merlin-planner sub-agent.
 
-Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
-Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
+This is a THIN ORCHESTRATOR. It reads minimal state, assembles context, and spawns a fresh
+sub-agent with 200K clean context to do the actual planning work. The orchestrator NEVER
+does heavy file reading or planning itself.
 
-**Gap closure mode (`--gaps` flag):**
-When invoked with `--gaps`, plans address gaps identified by the verifier. Load VERIFICATION.md, create plans to close specific gaps.
+**Why sub-agent:** Planning reads 12+ reference files and requires deep analysis.
+Running in-context risks hitting context limits, especially in long sessions.
+A fresh sub-agent gets full 200K context every time.
 </objective>
 
-<execution_context>
-@~/.claude/merlin/references/principles.md
-@~/.claude/merlin/workflows/plan-phase.md
-@~/.claude/merlin/templates/phase-prompt.md
-@~/.claude/merlin/references/plan-format.md
-@~/.claude/merlin/references/scope-estimation.md
-@~/.claude/merlin/references/checkpoints.md
-@~/.claude/merlin/references/tdd.md
-@~/.claude/merlin/references/goal-backward.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
-Gap closure mode: `--gaps` flag triggers gap closure workflow
-
-**Load project state first:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
-
-**Load requirements:**
-@.planning/REQUIREMENTS.md
-
-After loading, extract the requirements for the current phase:
-1. Find the phase in ROADMAP.md, get its `Requirements:` list (e.g., "PROF-01, PROF-02, PROF-03")
-2. Look up each REQ-ID in REQUIREMENTS.md to get the full description
-3. Present the requirements this phase must satisfy:
-   ```
-   Phase [N] Requirements:
-   - PROF-01: User can create profile with display name
-   - PROF-02: User can upload avatar image
-   - PROF-03: User can write bio (max 500 chars)
-   ```
-
-**Load phase context if exists (created by /merlin:discuss-phase):**
-Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
-
-**Load codebase context if exists:**
-Check for `.planning/codebase/` and load relevant documents based on phase type.
-
-**If --gaps flag present, also load:**
-@.planning/phases/XX-name/{phase}-VERIFICATION.md — contains structured gaps in YAML frontmatter
-</context>
-
 <process>
-1. Check .planning/ directory exists (error if not - user should run /merlin:new-project)
-2. Parse arguments: extract phase number and check for `--gaps` flag
-3. If phase number provided, validate it exists in roadmap
-4. If no phase number, detect next unplanned phase from roadmap
-
-**Standard mode (no --gaps flag):**
-5. Follow plan-phase.md workflow:
-   - Load project state and accumulated decisions
-   - Perform mandatory discovery (Level 0-3 as appropriate)
-   - Read project history (prior decisions, issues, concerns)
-   - Break phase into tasks
-   - Estimate scope and split into multiple plans if needed
-   - Create PLAN.md file(s) with executable structure
-
-**Gap closure mode (--gaps flag):**
-5. Follow plan-phase.md workflow with gap_closure_mode:
-   - Load VERIFICATION.md and parse `gaps:` YAML from frontmatter
-   - Read existing SUMMARYs to understand what's already built
-   - Create tasks from gaps (each gap.missing item → task candidates)
-   - Number plans sequentially after existing (if 01-03 exist, create 04, 05...)
-   - Create PLAN.md file(s) focused on closing specific gaps
-</process>
 
-<success_criteria>
+## Step 1: Validate Project Setup
 
-- One or more PLAN.md files created in .planning/phases/XX-name/
-- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
-- must_haves derived from phase goal and documented in frontmatter (truths, artifacts, key_links)
-- Tasks are specific enough for Claude to execute
-- Native Claude Tasks created for all tasks in the plan
-- User knows next steps (execute plan or review/adjust)
-</success_criteria>
+```bash
+ls .planning/ROADMAP.md 2>/dev/null
+```
+
+If missing: Error — "No roadmap found. Run `/merlin:new-project` first."
+
+## Step 2: Parse Arguments
+
+Extract from $ARGUMENTS:
+- **phase**: Phase number (e.g., "2", "2.1") — or auto-detect next unplanned phase
+- **--gaps**: Flag for gap closure mode
+
+```bash
+# If no phase number provided, find next unplanned phase
+# Look for phases in ROADMAP.md without PLAN.md files
+ls .planning/phases/*/  2>/dev/null
+```
+
+## Step 3: Gather Minimal Context (KEEP THIS LEAN)
+
+Read ONLY what the sub-agent needs to get started. The sub-agent reads everything else itself.
 
-<native_tasks_integration>
-**MANDATORY: After creating PLAN.md, also create native Claude Tasks.**
+```bash
+# Phase info from roadmap (just the relevant section, not the whole file)
+grep -A 10 "Phase ${PHASE_NUM}" .planning/ROADMAP.md
 
-For each task in the plan, call TaskCreate to register it with Claude's native task system:
+# Current state summary (just position + last activity)
+head -20 .planning/STATE.md 2>/dev/null
 
+# Check for phase-specific context files
+ls .planning/phases/${PHASE_NUM}*/ 2>/dev/null
 ```
-TaskCreate(
-  subject: "[Task title from plan]",
-  description: "[Task description with context]",
-  activeForm: "[Present continuous form for spinner - e.g., 'Creating authentication module']",
-  metadata: {
-    phase: "[phase number]",
-    phaseName: "[phase name]",
-    plan: "[plan number]",
-    planName: "[plan name from PLAN.md]",
-    taskNumber: [sequential number in plan],
-    wave: [execution wave if parallelizable],
-    blockedBy: [array of task IDs this depends on]
-  }
+
+**DO NOT read:**
+- Full workflow files (agent reads these)
+- Reference files (agent reads these)
+- Templates (agent reads these)
+- Prior summaries (agent reads these)
+- Codebase docs (agent reads these)
+
+## Step 4: Spawn Planner Sub-Agent
+
+Assemble a LEAN handoff prompt and spawn the merlin-planner agent:
+
+```
+Task(
+  prompt="
+You are planning Phase ${PHASE_NUM}: ${PHASE_NAME}.
+
+## Phase Goal
+${phase_goal_from_roadmap}
+
+## Phase Requirements
+${requirements_list_if_available}
+
+## Flags
+${gap_closure_flag_if_set}
+
+## Current State
+${minimal_state_summary}
+
+## Phase Directory
+${phase_directory_path}
+
+## Instructions
+Follow the planning workflow in ~/.claude/merlin/workflows/plan-phase.md step by step.
+Read all reference files yourself — you have fresh 200K context.
+
+${if_gaps_flag}
+Gap closure mode: Load VERIFICATION.md from the phase directory and create plans to close identified gaps.
+${end_if}
+
+When done, return structured PLANNING COMPLETE result.
+  ",
+  subagent_type="merlin-planner",
+  description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}"
 )
 ```
 
-**Set up dependencies:**
-After creating all tasks, use TaskUpdate to set blockedBy relationships:
-- Tasks in wave 2 should be blockedBy tasks in wave 1
-- Sequential tasks should be blockedBy their predecessor
+## Step 5: Present Result
 
-**Why native tasks:**
-- Claude's native task system enables cross-session coordination
-- Multiple agents/sessions can share tasks via CLAUDE_CODE_TASK_LIST_ID
-- Task state persists and broadcasts updates to all sessions
-- Works with Merlin Loop for autonomous execution
+After sub-agent returns, present its result and offer next steps:
 
-**After creating tasks, sync to cloud:**
 ```
-Call: merlin_sync_native_tasks
-Direction: push
+Phase ${PHASE_NUM} planned: {N} plan(s) in {M} wave(s)
+
+## Wave Structure
+{from sub-agent output}
+
+---
+
+## Next Up
+
+**Execute Phase ${PHASE_NUM}**
+
+`/merlin:execute-phase ${PHASE_NUM}`
+
+<sub>`/clear` first — fresh context window</sub>
+
+---
+
+**Also available:**
+- Review/adjust plans before executing
+- `/merlin:execute-plan {phase}-01-PLAN.md` — run plans one at a time
+- View all plans: `ls .planning/phases/XX-name/*-PLAN.md`
 ```
 
-This ensures the dashboard shows current plan status and enables cross-machine visibility.
-</native_tasks_integration>
+</process>
+
+<critical_rules>
+
+**STAY LEAN.** This orchestrator reads ~30 lines of state. Everything else happens in the sub-agent.
+
+**ALWAYS SPAWN SUB-AGENT.** Never do planning work in this context. Even if it "seems small."
+
+**PASS MINIMAL CONTEXT.** The sub-agent has fresh 200K context. Let it read files itself.
+Don't pre-read and pass file contents — that defeats the purpose.
+
+**SUGGEST /clear AFTER.** Planning produces output. Execution needs fresh context too.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] Project has ROADMAP.md (validated)
+- [ ] Phase number identified (from args or auto-detected)
+- [ ] Minimal context gathered (NOT full file reads)
+- [ ] merlin-planner sub-agent spawned via Task()
+- [ ] Sub-agent result presented to user
+- [ ] Next steps offered (execute-phase)
+</success_criteria>

package/files/commands/merlin/verify-work.md

@@ -7,59 +7,99 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Edit
-  - Write
+  - Task
+  - AskUserQuestion
 ---
 
 <objective>
-Validate built features through conversational testing with persistent state.
+Validate built features by spawning a fresh merlin-work-verifier sub-agent.
 
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation.
+This is a THIN ORCHESTRATOR. It identifies the phase, gathers minimal context,
+and spawns a fresh sub-agent to run the actual verification.
 
-Output: {phase}-UAT.md tracking all test results, gaps logged for /merlin:plan-phase --gaps
+**Why sub-agent:** Verification reads PLAN.md, SUMMARY.md, VERIFICATION.md, and
+potentially many source files. Fresh context ensures thorough analysis.
 </objective>
 
-<execution_context>
-@~/.claude/merlin/workflows/verify-work.md
-@~/.claude/merlin/templates/UAT.md
-</execution_context>
+<process>
 
-<context>
-Phase: $ARGUMENTS (optional)
-- If provided: Test specific phase (e.g., "4")
-- If not provided: Check for active sessions or prompt for phase
+## Step 1: Identify Phase
 
-@.planning/STATE.md
-@.planning/ROADMAP.md
-</context>
+```bash
+# If phase provided in args
+grep -A 5 "Phase ${PHASE_NUM}" .planning/ROADMAP.md 2>/dev/null
 
-<process>
-1. Check for active UAT sessions (resume or start new)
-2. Find SUMMARY.md files for the phase
-3. Extract testable deliverables (user-observable outcomes)
-4. Create {phase}-UAT.md with test list
-5. Present tests one at a time:
-   - Show expected behavior
-   - Wait for plain text response
-   - "yes/y/next" = pass, anything else = issue (severity inferred)
-6. Update UAT.md after each response
-7. On completion: commit, present summary, offer next steps
-</process>
+# If no phase, find latest completed phase
+ls .planning/phases/*/  2>/dev/null
+```
+
+If no phase and can't auto-detect, ask user which phase to verify.
+
+## Step 2: Gather Minimal Context
+
+```bash
+# Phase directory
+PHASE_DIR=$(ls -d .planning/phases/${PHASE_NUM}* 2>/dev/null | head -1)
+
+# Check for existing UAT session
+ls ${PHASE_DIR}/*-UAT.md 2>/dev/null
+
+# Phase goal from roadmap (just the section)
+grep -A 10 "Phase ${PHASE_NUM}" .planning/ROADMAP.md
+```
+
+## Step 3: Spawn Verifier Sub-Agent
+
+```
+Task(
+  prompt="
+Verify Phase ${PHASE_NUM}: ${PHASE_NAME}.
+
+## Phase Goal
+${phase_goal_from_roadmap}
+
+## Phase Directory
+${PHASE_DIR}
 
-<anti_patterns>
-- Don't use AskUserQuestion for test responses — plain text conversation
-- Don't ask severity — infer from description
-- Don't present full checklist upfront — one test at a time
-- Don't run automated tests — this is manual user validation
-- Don't fix issues during testing — log as gaps for /merlin:plan-phase --gaps
-</anti_patterns>
+## Existing UAT
+${existing_uat_status}
+
+## Instructions
+Read the verification workflow from ~/.claude/merlin/workflows/verify-work.md.
+Load SUMMARY.md files from the phase directory to understand what was built.
+Design tests from the phase GOAL, not task completion.
+Walk the user through each test conversationally.
+
+When done, return structured verification result.
+  ",
+  subagent_type="merlin-work-verifier",
+  description="Verify phase ${PHASE_NUM}: ${PHASE_NAME}"
+)
+```
+
+## Step 4: Present Result
+
+After sub-agent returns, present results and offer next steps:
+
+```
+Verification complete for Phase ${PHASE_NUM}.
+
+{sub-agent results}
+
+---
+
+Next:
+[1] Fix gaps: /merlin:plan-phase ${PHASE_NUM} --gaps
+[2] Continue to next phase
+[3] Re-verify specific items
+[4] Something else
+```
+
+</process>
 
 <success_criteria>
-- [ ] UAT.md created with tests from SUMMARY.md
-- [ ] Tests presented one at a time with expected behavior
-- [ ] Plain text responses (no structured forms)
-- [ ] Severity inferred, never asked
-- [ ] Batched writes: on issue, every 5 passes, or completion
-- [ ] Committed on completion
-- [ ] Clear next steps based on results
+- [ ] Phase identified
+- [ ] Minimal context gathered
+- [ ] merlin-work-verifier sub-agent spawned via Task()
+- [ ] Results presented with next steps
 </success_criteria>

package/files/merlin/VERSION

@@ -1 +1 @@
-2.5.1
+3.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-merlin-brain",
-  "version": "2.7.0",
-  "description": "Merlin - The Ultimate AI Brain for Claude Code. Installs workflows, agents, and Sights MCP server.",
+  "version": "3.1.0",
+  "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",
   "bin": {