review

name	review
description	Two-stage code review (spec compliance + code quality)
disable-model-invocation	false

/mz:review

Perform on-demand two-stage code review (spec compliance + code quality) independently of the /mz:go pipeline. Users can trigger this manually at any time, regardless of the quality.review config setting. Spawns a reviewer subagent via the Task tool that checks changes against plan specs and code quality standards.

Reference @skills/init/design-system.md for visual output formatting. Reference @agents/mz-reviewer.md for the review agent definition.

Step 1: Display Banner

Output the stage banner:

+===============================================+
|  MEGAZORD > REVIEW                            |
+===============================================+

Step 2: Parse Arguments and Determine Scope

Parse the user's message (text after /mz:review) for the review target:

• /mz:review (no args) -- review the most recent commit's changes
• /mz:review --plan {phase}-{plan} -- review all changes from a specific plan (diff from before plan started to after plan completed)
• /mz:review --files path/to/file.ts path/to/other.ts -- review specific files (diff of uncommitted changes, or latest commit affecting those files)
• /mz:review --last N -- review the last N commits

Determine the diff to review based on the scope:

No args (default):

git diff HEAD~1 HEAD

--plan {phase}-{plan}: Compute diff range from plan's first to last commit. Read the plan's SUMMARY.md for commit hashes:

1. Read SUMMARY.md in the phase directory for the specified plan.
2. Extract the first and last commit hashes from the Task Commits section.
3. Compute: git diff {first_commit}~1 {last_commit}

If SUMMARY.md not found, report error: plan has not been executed yet.

--files {file1} {file2} ...: Check for uncommitted changes first:

git diff HEAD -- {files}

If no uncommitted changes, find latest commit affecting those files:

git log -1 --format=%H -- {files}

Then diff: git diff {hash}~1 {hash} -- {files}

--last N:

git diff HEAD~{N} HEAD

Display the scope:

> Review Scope
  Target: {description of what will be reviewed}
  Files: {count} affected

Step 3: Load Context

• Read .planning/megazord.config.json (optional -- review works even without config).
• If a plan is specified (--plan), read the PLAN.md for task definitions and requirements context.
• Determine the plugin path:
  1. Read plugin_path from the config JSON (if config was loaded).
  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:

     Plugin path not configured. Run /mz:settings and set plugin_path, or re-run /mz:init.

• Read {plugin_path}/agents/mz-reviewer.md content using the Read tool.

Step 4: Prepare Review Context

1. Get the diff based on the scope determined in Step 2.
2. Identify affected files from the diff:

   git diff --name-only {diff_range}
   

3. Read each affected file's full content using the Read tool (skip if diff exceeds approximately 300 lines -- diff alone is sufficient for large changes).
4. If plan context available: extract task definitions and requirements from the PLAN.md frontmatter.
5. Determine the report output path:
   • If within a phase context (plan specified or active phase): {phase_dir}/{padded}-{plan}-REVIEW-manual.md
   • If no phase context: .planning/reviews/REVIEW-{timestamp}.md
   • Ensure the output directory exists before spawning the reviewer.

Step 5: Spawn Reviewer

Compose the Task prompt and spawn the reviewer subagent:

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

<task_definition>
{plan task definition if available, or "Manual review -- no plan context"}
</task_definition>

<diff>
{the computed diff}
</diff>

<affected_files>
{full content of affected files, if diff <= 300 lines}
</affected_files>

<plan_requirements>
{requirements from plan if available, or "Manual review -- no plan requirements"}
</plan_requirements>

<review_rules>
- Phase: {phase_number or "N/A"}
- Plan: {plan_number or "N/A"}
- Task: manual
- Phase directory: {phase_dir or ".planning/reviews"}
- Report path: {computed report path}
- Severity levels: critical (blocks), warning (recommended), info (informational)
- Two separate reports: spec compliance + code quality
- Spec findings MUST cite plan task or requirement (if plan context available)
- Architectural concerns are warning/info only, never critical
</review_rules>

Spawn via Task tool:

• subagent_type: "general-purpose"
• description: "Manual code review: {scope description}"

Wait for completion.

Note: All file contents are read BEFORE spawning the Task subagent and embedded as inline text. @file references do NOT work across Task boundaries.

Step 6: Display Results

Parse the structured result (look for ## REVIEW COMPLETE).

Display results in design system format:

+===============================================+
|  Review Complete                              |
+-----------------------------------------------+
|  Scope: {description of what was reviewed}    |
|  Status: {passed | issues_found}              |
|  Critical: {N}                                |
|  Warnings: {N}                                |
|  Info: {N}                                    |
+===============================================+

If findings exist, display them organized by severity:

Critical findings first (with specific fix suggestions):

> Critical Findings

1. [{file}:{line}] {title}
   Issue: {description}
   Fix: {suggestion}

Warning findings second:

> Warnings

1. [{file}:{line}] {title}
   Issue: {description}
   Suggestion: {recommendation}

Info findings last:

> Info

1. [{file}:{line}] {title}
   Note: {description}

Display Next Up block:

If passed:

===============================================
> Next Up
**Code review passed.** No issues found.
===============================================

If issues found:

===============================================
> Next Up
**Review the findings above.** Fix critical issues before proceeding.
===============================================

Error Handling

Error	Step	Action
No git history	Step 2	Error message, suggest making a commit first. Stop.
Plan SUMMARY.md not found	Step 2	Error: plan not executed. Suggest /mz:go. Stop.
Empty diff	Step 2	Info message: no changes to review. Stop.
Reviewer subagent fails	Step 5	Save error, display failure details. Stop.

Notes

• This skill works independently of config.quality.review. Even if review is set to "off" in config, /mz:review can still be invoked manually.
• The reviewer agent ({plugin_path}/agents/mz-reviewer.md) is the same agent used by the /mz:go execution pipeline. Reports use the same format and severity levels.
• For plan-scoped reviews, the SUMMARY.md commit hashes are used to compute the diff range covering all tasks in that plan.
• The {plugin_path} for CLI commands and agent files is resolved from config.plugin_path, falling back to ~/.claude/plugins/mz.
• ALWAYS use bun/bunx for JavaScript/TypeScript operations (never npm/npx).