Plan Skill Agents

Agent definitions used by the /mz:plan skill. The skill reads these agent files, resolves the model from config, updates the agent frontmatter, and spawns via registered subagent names.

Researcher Agent

• File: {plugin_path}/agents/mz-researcher.md (read this file and embed content in Task prompt; {plugin_path} is resolved from config.plugin_path, falling back to ~/.claude/plugins/mz)
• Purpose: Research the technical landscape for a phase before planning begins
• Model: Determined by resolveAgentModel(config, 'researcher') -- config profile mapping with optional override
• Spawning: Task tool with subagent_type="mz-researcher" (fallback: "general-purpose" with inline agent definition in <agent_role> tags)
• Output: {phase_dir}/{padded}-RESEARCH.md
• When to skip: --skip-research flag, or existing RESEARCH.md in phase directory, or workflow.research is false in config

Planner Agent

• File: {plugin_path}/agents/mz-planner.md (read this file and embed content in Task prompt; {plugin_path} is resolved from config.plugin_path, falling back to ~/.claude/plugins/mz)
• Purpose: Decompose a phase into executable PLAN.md files with tasks, dependencies, and waves
• Model: Determined by resolveAgentModel(config, 'planner') -- note: balanced profile uses opus for planner (differentiated)
• Spawning: Task tool with subagent_type="mz-planner" (fallback: "general-purpose" with inline agent definition in <agent_role> tags)
• Output: {phase_dir}/{padded}-{NN}-PLAN.md files (e.g., 03-01-PLAN.md, 03-02-PLAN.md)
• Input: Requires research findings, project state, roadmap, and context decisions

Critical: @file References Do NOT Work Across Task Boundaries

The Task tool spawns a fresh subagent session. @file references in the parent skill's prompt are NOT resolved in the subagent's context. The subagent cannot read files referenced with @ -- it only receives the literal text of the Task prompt.

The plan skill MUST follow this pattern:

1. Read all needed files into memory BEFORE spawning the Task:

   • Agent definition file (agents/mz-researcher.md or agents/mz-planner.md)
   • STATE.md content
   • ROADMAP.md content (or the relevant phase section)
   • CONTEXT.md content (if exists)
   • RESEARCH.md content (for the planner)
   • megazord.config.json content

2. Embed all file contents as inline text in the Task prompt string:

   Task(
     prompt="<agent_role>{agent_definition_content}</agent_role>
     <project_state>{state_content}</project_state>
     <roadmap>{roadmap_section}</roadmap>
     <context>{context_content}</context>
     <output_path>{phase_dir}</output_path>",
     subagent_type="general-purpose",
     description="Research Phase {N}: {Name}"
   )
   

3. Never use @file references inside the Task prompt -- they will be treated as literal text, not file references.

Model Selection

The /mz:plan skill resolves and applies the correct model before spawning each agent. This uses the resolveAgentModel() function from src/lib/config.ts.

Profile Mapping

(*) Planner is differentiated: promoted one tier for better reasoning quality in plan creation.

Override Precedence

1. Per-agent override (model_overrides.researcher / model_overrides.planner) wins if set and not "inherit"
2. Profile mapping applies otherwise (see table above)

Frontmatter Rewriting

Skills update the model field in the agent .md file's YAML frontmatter before spawning:

1. Read the agent file (e.g., {plugin_path}/agents/mz-researcher.md)
2. Resolve the model via config profile + overrides
3. Rewrite the model: {value} line in the frontmatter (e.g., model: inherit -> model: opus)
4. Spawn with subagent_type="mz-researcher" (Claude Code reads the updated frontmatter)

Session restart caveat: If Claude Code caches agent definitions, model changes may require a session restart to take effect.

Spawning Examples

Researcher Spawning (Model-Aware)

# 1. Read files
Read {plugin_path}/agents/mz-researcher.md -> researcher_instructions
Read .planning/STATE.md -> state_content
Read .planning/ROADMAP.md -> roadmap_content
Read {phase_dir}/{padded}-CONTEXT.md -> context_content (if exists)
Read .planning/megazord.config.json -> config

# 2. Resolve model and update agent frontmatter
resolved_model = resolveAgentModel(config, 'researcher')
  # Check model_overrides.researcher -> if set and not "inherit", use it
  # Otherwise: quality->opus, balanced->sonnet, budget->haiku
Rewrite model line in {plugin_path}/agents/mz-researcher.md:
  model: inherit  ->  model: {resolved_model}

# 3. Spawn with registered subagent name
Task(
  prompt="<objective>Research Phase {N}: {Name}</objective>

<project_state>{state_content}</project_state>

<roadmap_phase>{relevant_phase_section}</roadmap_phase>

<context_decisions>{context_content}</context_decisions>

<output>Write research to: {phase_dir}/{padded}-RESEARCH.md</output>",
  subagent_type="mz-researcher",
  description="Research Phase {N}: {Name}"
)

# 4. Fallback (if subagent_type="mz-researcher" fails)
Task(
  prompt="<agent_role>{researcher_instructions}</agent_role>
  ... (same context as above) ...",
  subagent_type="general-purpose",
  description="Research Phase {N}: {Name}"
)

Planner Spawning (Model-Aware)

# 1. Read files
Read {plugin_path}/agents/mz-planner.md -> planner_instructions
Read .planning/STATE.md -> state_content
Read .planning/ROADMAP.md -> roadmap_content
Read {phase_dir}/{padded}-RESEARCH.md -> research_content
Read {phase_dir}/{padded}-CONTEXT.md -> context_content (if exists)
Read .planning/megazord.config.json -> config_content

# 2. Resolve model and update agent frontmatter
resolved_model = resolveAgentModel(config, 'planner')
  # Check model_overrides.planner -> if set and not "inherit", use it
  # Otherwise: quality->opus, balanced->opus, budget->sonnet (differentiated!)
Rewrite model line in {plugin_path}/agents/mz-planner.md:
  model: inherit  ->  model: {resolved_model}

# 3. Spawn with registered subagent name
Task(
  prompt="<objective>Plan Phase {N}: {Name}</objective>

<project_state>{state_content}</project_state>

<roadmap_phase>{relevant_phase_section}</roadmap_phase>

<research>{research_content}</research>

<context_decisions>{context_content}</context_decisions>

<config>{config_content}</config>

<requirements>Cover these requirement IDs: {comma-separated IDs}</requirements>

<output>Write plans to: {phase_dir}/</output>",
  subagent_type="mz-planner",
  description="Plan Phase {N}: {Name}"
)

# 4. Fallback (if subagent_type="mz-planner" fails)
Task(
  prompt="<agent_role>{planner_instructions}</agent_role>
  ... (same context as above) ...",
  subagent_type="general-purpose",
  description="Plan Phase {N}: {Name}"
)