/mz:go

Execute the current phase plan by orchestrating executor agents. Supports two execution modes: subagent delegation (Task tool, fire-and-forget) and Agent Teams (TeamCreate, SendMessage, shared TaskList with real-time coordination). Auto-detects the optimal mode per wave based on plan complexity, with --teams/--no-teams overrides.

Reference @skills/init/design-system.md for visual output formatting. Reference @skills/shared/presentation-standards.md for content formatting rules. Reference @skills/shared/terminology.md for official term definitions. Reference @skills/go/executor.md for execution protocol and spawning patterns. Reference @skills/go/teams.md for Agent Teams execution protocol.

Step 1: Display Banner

Output the stage banner:

+===============================================+
|  MEGAZORD > EXECUTE                           |
+===============================================+

Step 2: Load Context and Validate

Read .planning/megazord.config.json. If missing, display error and stop:

## Error

Project not initialized — no megazord.config.json found.

`/mz:init`

If config exists, continue loading:

• Read .planning/STATE.md for current position.
• Read .planning/ROADMAP.md for phase details.

Determine review configuration from the config:

• If config.quality.review === "auto": review_enabled = true, review_mode = "auto"
• If config.quality.review === "manual": review_enabled = true, review_mode = "manual"
• If config.quality.review === "off": review_enabled = false

If review is disabled, display a one-time notice:

> Note: Code review is disabled (quality.review: "off"). Tasks will not be reviewed.

Determine TDD configuration:

• If config.quality.tdd === true: tdd_enabled = true
• Otherwise: tdd_enabled = false

Determine CORTEX configuration:

• If config.quality.cortex === true: cortex_enabled = true
• Otherwise: cortex_enabled = false

Display activation notices (same pattern as the review disabled notice):

• If TDD is enabled: > TDD mode active: RED-GREEN-REFACTOR enforced per task
• If CORTEX is enabled: > CORTEX classification active: tasks classified before execution

If CORTEX is enabled (cortex_enabled = true):

• Read {plugin_path}/skills/cortex/SKILL.md content using the Read tool.
• This content will be embedded in the executor prompt as a <cortex_protocol> block.

Parse the user's message (text after /mz:go) for arguments:

• --tasks N,M -- execute only specific plan numbers (e.g., --tasks 1,3)
• --from N -- start from plan N, skip earlier plans (e.g., --from 2)
• --dry-run -- show execution plan without running
• --teams -- force Agent Teams mode (requires experimental flag)
• --no-teams -- force subagent mode (skip Agent Teams detection)

Determine the plugin path for CLI commands:

1. Read plugin_path from the config JSON.
2. If plugin_path is not set in config, try ~/.claude/plugins/mz. Check if ~/.claude/plugins/mz/bin/megazord.mjs exists.
3. If neither exists, display error and stop:

## Error

Plugin path not configured.

`/mz:settings` to set plugin_path, or `/mz:init` to re-initialize.

Load the Agent Teams configuration from config:

• config.agent_teams.enabled: "auto" (default), "always", or "never"
• config.agent_teams.strict_ownership: true or false (default: false)

Use the resolved plugin path for all node {plugin_path}/bin/megazord.mjs commands below:

node {plugin_path}/bin/megazord.mjs tools plan list --phase-dir {dir}

Step 3: Find Plans

Determine the current phase from STATE.md position. Compute the phase directory path (e.g., .planning/phases/04-subagent-execution-and-atomic-commits).

List all plans:

node {plugin_path}/bin/megazord.mjs tools plan list --phase-dir {phase_dir}

If no plans returned, display error and stop:

## Error

No plans found for Phase {N}: {Name}.

`/mz:plan {N}`

Get incomplete plans:

node {plugin_path}/bin/megazord.mjs tools plan incomplete --phase-dir {phase_dir}

If all plans are complete (empty incomplete list), display info and stop:

> Phase Status
  Phase {N}: {Name} — {functional_sentence_from_goal}
  All plans complete. Run /mz:verify to validate.

Compute wave execution order:

node {plugin_path}/bin/megazord.mjs tools plan waves --phase-dir {phase_dir}

Check for file conflicts between plans:

node {plugin_path}/bin/megazord.mjs tools plan conflicts --phase-dir {phase_dir}

Display the execution plan:

> Execution Plan
  Phase {N}: {Name} — {functional_sentence_from_goal}
  Plans: {total} ({incomplete} remaining)
  Waves: {wave_count}

  Wave 1: {plan_list} — {functional_summary} (parallel)
  Wave 2: {plan_list} — {functional_summary} (sequential)

Extract the functional sentence from the phase Goal in ROADMAP.md. Wave functional summaries are derived from the plans' objectives — e.g., "foundation and shared references" not just plan numbers.

If conflicts are detected, note which plans will be serialized and why.

Step 4: Apply Execution Filters

If --tasks N,M was provided:

• Filter the incomplete plans to only include the specified plan numbers.
• Skip plans not in the list.

If --from N was provided:

• Filter to plans with number >= N.
• Verify plans before N have SUMMARY.md files (are completed). If not, warn but continue.

If --dry-run was provided:

• Display the execution plan from Step 3 and stop. Do not execute.

If neither flag was provided:

• Execute all incomplete plans (default behavior).

Step 5: Determine Execution Mode

For each wave, determine whether to use subagents or Agent Teams.

Detection logic (check in order):

1. If --teams flag provided: mode = "teams" (forced)
2. If --no-teams flag provided: mode = "subagents" (forced)
3. If config.agent_teams.enabled === "always": mode = "teams"
4. If config.agent_teams.enabled === "never": mode = "subagents"
5. If config.agent_teams.enabled === "auto": auto-detect per wave:
   • For each wave, examine the plans:
     • If review is enabled AND the wave has 2+ plans: mode = "teams" (review loops benefit from peer communication)
     • If the wave has plans with inter-plan dependencies (plans in the same wave that depend on each other -- unusual but possible via file overlap): mode = "teams"
     • Otherwise: mode = "subagents"

Display the chosen mode:

> Execution Mode: {Agent Teams | Subagents}
  {Reason: auto-detect / --teams flag / config}

If Agent Teams mode selected, verify availability:

Check if CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable is set:

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

If not set or empty: silently fall back to subagents. Display:

> Mode: Subagents (Agent Teams not available)

Step 6: Execute Waves

For each wave (waves execute sequentially):

Display:

> Wave {N}/{total_waves} — {wave_plan_count} tasks {parallel_note}

The execution path depends on the mode determined in Step 5.

---

Path A: Subagent Execution

This is the existing Task tool delegation path. Used when mode = "subagents".

Determine plan execution order within the wave:

• Parse the conflict analysis from Step 3.
• If no conflicts between plans in this wave: plans can run in parallel (spawn all Task calls).
• If conflicts exist: serialize conflicting plans, parallelize the rest.

For each plan in the wave:

Display (with progress bar showing plans completed so far within the wave):

  ████░░░░░░ Plan {NN}: {functional_objective}...

After each plan completes:

  ██████████ Plan {NN}: {functional_objective} ✓ ({duration})
  ████░░░░░░ Plan {MM}: {functional_objective}...

The progress bar (10 chars, █ filled / ░ empty) updates as plans complete within the wave. Use round(completed/total * 10) filled characters.

Resolve Models for Agents

Before spawning, determine models for this wave's agents:

1. Read model_profile and model_overrides from the loaded config.
2. Resolve executor model: check model_overrides.executor, fall back to profile mapping (quality->opus, balanced->sonnet, budget->haiku).
3. Update {plugin_path}/agents/mz-executor.md frontmatter model field to the resolved value.
4. If review is enabled, resolve reviewer model: check model_overrides.reviewer, fall back to profile mapping.
5. Update {plugin_path}/agents/mz-reviewer.md frontmatter model field to the resolved value.

Note: Model resolution is done ONCE per wave (before the first plan spawn), not per-plan.

Spawn Executor

1. Read the full PLAN.md content using the Read tool.
2. Read {plugin_path}/agents/mz-executor.md content using the Read tool.
3. Read .planning/megazord.config.json content using the Read tool.
4. If review_enabled is true: Read {plugin_path}/agents/mz-reviewer.md content using the Read tool.
5. Compose the Task prompt with all content inline, including the CORTEX protocol block if cortex_enabled is true (see @skills/go/executor.md for prompt structure):

<agent_role>
{content of agents/mz-executor.md}
</agent_role>

<plan>
{full content of PLAN.md}
</plan>

<config>
{content of megazord.config.json}
</config>

<reviewer_agent>
{content of agents/mz-reviewer.md -- only included if review_enabled is true}
</reviewer_agent>

<execution_rules>
- Phase: {phase_number}
- Plan: {plan_number}
- Phase directory: {phase_dir}
- Commit format: {type}({phase}-{plan}): {description}
- Do NOT add Co-Authored-By lines to commits
- Stage files individually (never git add . or git add -A)
- One commit per task, no exceptions
- Create SUMMARY.md at {phase_dir}/{padded}-{plan}-SUMMARY.md
- Do NOT update STATE.md or ROADMAP.md
- Use bun/bunx for all JS/TS operations (never npm/npx)
- Review enabled: {true|false}
- Review mode: {auto|manual} (only present if review_enabled is true)
- TDD enabled: {true|false}
- CORTEX enabled: {true|false}
</execution_rules>

<cortex_protocol>
{Content of skills/cortex/SKILL.md -- only included if cortex_enabled is true}
</cortex_protocol>

Note: The <reviewer_agent> section is only included when review_enabled is true. When review is disabled, omit this section entirely to save context budget. The <cortex_protocol> section is only included when cortex_enabled is true.

6. Spawn the executor via the Task tool:

   • subagent_type: "mz-executor"
   • description: "Execute Plan {phase}-{plan}: {brief objective}"
   • If spawning with subagent_type='mz-executor' fails, fall back to subagent_type='general-purpose' with the agent definition embedded inline in <agent_role> tags.

7. Wait for completion.

8. Parse the structured result. Look for ## PLAN COMPLETE in the response to extract:

   • Task count
   • Commit hashes and messages
   • SUMMARY.md path
   • Duration

9. Display result:

  > Plan {NN}: {functional_objective} — ✓ {duration}, {N} tasks, {commit_count} commits

After All Plans in Wave Complete (Subagent Path)

For each completed plan in this wave, update state via CLI tools:

Advance plan counter:

node {plugin_path}/bin/megazord.mjs tools state advance-plan

Record execution metric:

node {plugin_path}/bin/megazord.mjs tools state record-metric --phase {phase} --plan {plan} --duration {duration} --tasks {count} --files {count}

Add decisions (extract key decisions from the plan's SUMMARY.md):

node {plugin_path}/bin/megazord.mjs tools state add-decision --phase {phase} --decision "{decision text}"

Update session continuity:

node {plugin_path}/bin/megazord.mjs tools state update-session --last-session {date} --stopped-at "Completed {phase}-{plan}" --resume-file "{next_plan_path or phase_dir}"

Failure Handling (Subagent Path)

If a plan FAILS in this wave (executor returns without ## PLAN COMPLETE):

1. Display failure:

  ✗ Plan {NN}: {functional_objective} — FAILED: {error description}
    Recovery: /mz:go to resume from this plan

2. Save the error output: Write the error output to {phase_dir}/{padded}-{plan}-ERROR.md using the Write tool.

3. Update session with error:

node {plugin_path}/bin/megazord.mjs tools state update-session --last-error "Plan {NN} failed: {brief error}"

4. Wait for other plans in the wave to finish (they may still succeed).

5. STOP after this wave. Do NOT start the next wave.

6. Display:

## Error

Execution stopped after Wave {N} — Plan {NN}: {functional_objective} failed.
{brief error description}

`/mz:go` to resume from the first incomplete plan.

---

Path B: Agent Teams Execution

This is the Agent Teams coordination path. Used when mode = "teams". Reference @skills/go/teams.md for the full protocol.

For each wave in Agent Teams mode:

1. Create Worktrees

For each plan in the wave, create an isolated worktree:

node {plugin_path}/bin/megazord.mjs tools worktree create --team {team_name} --agent exec-{plan_id}

Team name format: mz-{phase}-w{wave} (e.g., mz-06-w1).

2. Generate Ownership Manifest

Read each plan's files_modified frontmatter. Build the ownership manifest mapping each agent name to its declared files. Write to a temporary file that the hook can read:

{
  "exec-06-01": ["src/lib/worktree.ts", "src/cli/commands/worktree-tools.ts"],
  "exec-06-02": ["agents/mz-executor.md", "agents/mz-reviewer.md"]
}

3. Write Agent Context Files

For each worktree, write .mz-agent-context.json inside the worktree directory:

{
  "agent_name": "exec-{plan_id}",
  "team_name": "{team_name}",
  "team_lead": "mz-lead",
  "owned_files": ["file1.ts", "file2.ts"],
  "strict_ownership": false
}

The strict_ownership field reflects config.agent_teams.strict_ownership. This file is read by the ownership enforcement hook (since environment variables cannot be set for teammates).

4. Create Team

TeamCreate({ team_name: "{team_name}", description: "Phase {N} Wave {W}" })

5. Create Tasks

For each plan in the wave, create a task:

TaskCreate({
  subject: "Execute Plan {NN}: {objective}",
  description: "{full plan content with execution rules}",
  activeForm: "Executing Plan {NN}"
})

6. Resolve Models for Teammates

Before spawning, determine models for this wave's agents:

1. Resolve executor model and update {plugin_path}/agents/mz-executor.md frontmatter model field based on config profile/overrides.
2. If review is enabled, resolve reviewer model and update {plugin_path}/agents/mz-reviewer.md frontmatter model field.

7. Spawn Teammates

For each plan, spawn an executor teammate. If review is enabled, also spawn a reviewer teammate.

1. Read agent definitions ({plugin_path}/agents/mz-executor.md, {plugin_path}/agents/mz-reviewer.md) and embed inline.
2. Spawn executor teammate via Task tool with subagent_type="mz-executor" and team_name parameter. If named subagent spawning does not work for teammates, use "general-purpose" with inline embedding as fallback.

Task({
  description: "<agent_role>{mz-executor.md content}</agent_role>
<plan>{PLAN.md content}</plan>
<config>{megazord.config.json}</config>
<reviewer_agent>{mz-reviewer.md content -- if review enabled}</reviewer_agent>
<execution_rules>
- execution_mode: teammate
- Phase: {phase_number}
- Plan: {plan_number}
- Phase directory: {phase_dir}
- worktree_path: {worktree_path}
- owned_files: {file list from plan frontmatter}
- team_lead: mz-lead
- reviewer_name: reviewer-{plan_id} (if review enabled)
- task_id: {task_id from TaskCreate}
- Commit format: {type}({phase}-{plan}): {description}
- Do NOT add Co-Authored-By lines to commits
- Stage files individually (never git add . or git add -A)
- One commit per task, no exceptions
- Create SUMMARY.md at {phase_dir}/{padded}-{plan}-SUMMARY.md
- Do NOT update STATE.md or ROADMAP.md
- Use bun/bunx for all JS/TS operations (never npm/npx)
- Review enabled: {true|false}
- Review mode: {auto|manual}
- TDD enabled: {true|false}
- CORTEX enabled: {true|false}
</execution_rules>

<cortex_protocol>
{Content of skills/cortex/SKILL.md -- only included if cortex_enabled is true}
</cortex_protocol>",
  team_name: "{team_name}",
  name: "exec-{plan_id}"
})

3. If review is enabled, spawn reviewer teammate with subagent_type="mz-reviewer". If named subagent spawning does not work for teammates, use "general-purpose" with inline embedding as fallback:

Task({
  description: "<agent_role>{mz-reviewer.md content}</agent_role>
<review_rules>
- review_mode_type: teammate
- worktree_paths: {map of agent names to worktree paths}
- team_lead: mz-lead
- Phase: {phase_number}
- Plan scope: {plan numbers in this wave}
</review_rules>",
  team_name: "{team_name}",
  name: "reviewer-{plan_id}"
})

IMPORTANT: Spawn ALL teammates before entering coordination mode. Do NOT use API-level permissionMode: "delegate" -- this causes a known bug where teammates lose file system tools. Enforce delegate behavior through instructions only.

8. Coordinate (Delegate Mode)

After spawning, the lead enters coordination-only mode:

• You are the team LEAD. You NEVER implement directly.
• Your tools: TeamCreate, TaskCreate, TaskUpdate, TaskList, SendMessage, TeamDelete
• Do NOT use Edit, Write, or Bash for implementation work.
• Monitor via TaskList for task completion.
• Messages from teammates arrive automatically.
• If a reviewer escalates (max rounds reached), log the escalation.
• If an executor reports failure, save error output.
• Wait until all tasks in the wave are completed or failed.

9. Merge Worktrees

After all tasks complete, merge worktrees sequentially in plan order:

For each completed plan:

node {plugin_path}/bin/megazord.mjs tools worktree merge --team {team_name} --agent exec-{plan_id} --strategy merge

If merge fails (conflicts): stop the wave, leave worktree for inspection, log the conflict.

10. Shutdown Teammates

For each teammate:

SendMessage({ type: "shutdown_request", recipient: "{name}", content: "Wave complete" })

Wait for responses (timeout 60s, proceed anyway if no response).

11. Cleanup

node {plugin_path}/bin/megazord.mjs tools worktree prune --team {team_name}

Then TeamDelete() to remove team resources.

12. Update State

Same as subagent path: advance plan counter, record metrics, add decisions, update session for each completed plan in the wave.

13. Silent Fallback

If ANY of steps 1-7 fail (TeamCreate fails, worktree creation fails, API error), catch the error and fall back to subagent execution (Path A) for this wave:

[TEAMS FALLBACK] {reason}. Using subagent mode for wave {N}.

This is logged but does not prompt the user. Execution continues normally via the subagent path.

---

Step 7: Update Roadmap

After all waves complete (or after stopping due to failure):

• Read each completed plan's SUMMARY.md to verify it exists.
• In ROADMAP.md, update the plan checkboxes for completed plans:
  • Change - [ ] to - [x] for plans that now have SUMMARY.md files.
• Update the Progress table row for this phase with the current plan completion count.

Step 8: Check for Unresolved Review Findings

After all waves complete, check each completed plan's SUMMARY.md for "Unresolved Review Findings". If any plan mentions unresolved review findings, display a warning:

> Warning: Some tasks have unresolved review findings.
  Run /mz:review for manual review, or check the SUMMARY.md files for details.

Step 9: Post-Execution Summary

Display summary using heading-based layout (action boxes are reserved for important banners per presentation-standards.md — execution summaries use headings):

### Execution Complete

Phase {N}: {Name} — {functional_sentence}
Mode: {Subagents | Agent Teams | Mixed}
Plans: {completed}/{total}
Commits: {total_commits}
Duration: {total_time}

Wave 1 [Subagents]: Plan 01 — {functional_obj} ({time})
Wave 2 [Agent Teams]: Plan 02 — {functional_obj} ({time}), Plan 03 — {functional_obj} ({time})

Display the Next Up block. Determine verifier suggestion based on config:

• If all plans complete AND config.workflow.verifier is true:

## Next Up

**Verify Phase {N}: {Name}** — validate deliverables before advancing
`/mz:verify {N}`

<sub>`/clear` — start fresh context for the next step</sub>

• If all plans complete AND config.workflow.verifier is false:

## Next Up

**Phase {N}: {Name} — execution complete.** Verifier is disabled in config.
`/mz:plan {N+1}`

- Or verify manually: `/mz:verify {N}`

<sub>`/clear` — start fresh context for the next step</sub>

IMPORTANT: The /mz:verify skill itself is NEVER gated. It always works when manually invoked. Only the automated suggestion in /mz:go changes based on config.

• If some plans remain (failure case):

## Next Up

**Resume execution** — fix failure and continue
`/mz:go`

<sub>`/clear` — start fresh context for the next step</sub>

• If all phases complete:

## Next Up

**Project complete** — all phases delivered

Error Handling Summary

Error	Step	Action
Config missing	Step 2	Error box, suggest /mz:init. Stop.
No plans found	Step 3	Error box, suggest /mz:plan. Stop.
All plans complete	Step 3	Info message, suggest /mz:verify. Stop.
Plan execution fails	Step 6	Save error, stop after wave, suggest /mz:go.
State update fails	Step 6	Log warning, do not block (plans already committed).
Agent Teams unavailable	Step 5	Silent fallback to subagents.
TeamCreate fails	Step 6B	Silent fallback to subagents for this wave.
Worktree merge conflict	Step 6B	Stop wave, leave worktree for inspection.

Notes

• All file contents are read BEFORE spawning Task subagents/teammates and embedded as inline text. @file references do NOT work across Task boundaries.
• The executor agent ({plugin_path}/agents/mz-executor.md) enforces per-task atomic commits with conventional commit format.
• Wave computation and conflict detection are performed by CLI tools, not computed in this skill.
• The {plugin_path} for CLI commands and agent files is resolved from config.plugin_path, falling back to ~/.claude/plugins/mz.
• Only the orchestrator (this skill) updates STATE.md and ROADMAP.md. Executors never touch state files.
• ALWAYS use bun/bunx for JavaScript/TypeScript operations (never npm/npx).
• When CORTEX is enabled, the orchestrator reads {plugin_path}/skills/cortex/SKILL.md and embeds it as <cortex_protocol> in the executor prompt. This keeps the authoritative CORTEX content in one file while ensuring the executor receives it inline (required by the Task boundary constraint).

Usage Examples

/mz:go                Execute all incomplete plans (auto-detect mode)
/mz:go --dry-run      Preview execution plan without running
/mz:go --from 2       Start from plan 2, skip earlier plans
/mz:go --tasks 1,3    Execute only specific plans
/mz:go --teams        Force Agent Teams mode (requires experimental flag)
/mz:go --no-teams     Force subagent mode (skip Agent Teams)