Developing Plan Reviewers

Developing Plan Reviewers

Create project-specific reviewer agents for the planning-project-features workflow. These agents review individual sub-plans for domain-specific correctness — catching issues that the generic global reviewers (architecture, risk) cannot.

For general agent development guidance (frontmatter fields, description examples, system prompt design), see the developing-agents skill.

How Plan Reviewers Fit In

The planning workflow (Phase 5) uses two types of reviewers:

1. Global reviewers (~/.claude/agents/) — plan-architect-reviewer and plan-risk-reviewer. Project-agnostic, already exist.
2. Local reviewers (.claude/agents/) — project-specific, domain-specialized. This is what you build.

The planner discovers local reviewers in Phase 4 by reading their descriptions, matches each sub-plan to the most appropriate reviewer, and launches them in Phase 5. No naming convention is assumed — the description is what matters.

Design Philosophy

A reviewer agent is a thin shell. It defines:

• What to review — the domain scope (via description and skills list)
• How to output — the standard review format (Verdict / Findings / Concerns / Observations)
• What tone to use — critical, not praising; specific, not vague

It does not define how to review. Domain knowledge comes from the preloaded skills, which encode conventions, patterns, and pitfalls. This separation prevents the reviewer from becoming a static checklist that rots as conventions evolve — the skills are maintained independently and stay in sync with the codebase.

Reviewer Agent Template

---
name: plan-<domain>-reviewer
description: "Use this agent to review sub-plans that involve <domain>. Evaluates <what it checks> against project conventions.\n\n<example>\nContext: A sub-plan covers <domain> implementation within a feature plan.\nuser: \"Review sub-plan 02-<task>.md for <domain> correctness.\"\nassistant: \"I'll review the sub-plan for <domain> issues using the plan-<domain>-reviewer agent.\"\n<commentary>\nSub-plan involves <domain> work. Launch the domain-specific reviewer.\n</commentary>\n</example>"
tools: Read, Glob, Grep
memory: project
skills:
  - <skill-1>
  - <skill-2>
---

You are a <domain> reviewer. Your job is to review implementation sub-plans
for <domain> correctness — ensuring the proposed approach follows established