9thlevelsoftware/legion/review-loop

Review Loop

Engine for /legion:review. Takes the output of a completed /legion:build phase and drives it through a structured dev-QA cycle: personality-injected review agents evaluate artifacts, findings are triaged by severity, fix agents resolve issues, and the cycle repeats up to the configured maximum (settings.review.max_cycles, default 3). A phase is never marked complete by exhaustion — only by reviewer approval.

Section 1: Review Principles

These rules govern all review decisions. Do not deviate from them.

MANDATORY: Follow the active CLI adapter's Execution Protocol.

Before spawning any review or fix agents, load the active adapter (see workflow-common CLI Detection Protocol).

The adapter defines how agents are spawned, coordinated, and cleaned up.

If adapter.parallel_execution is true AND adapter.structured_messaging is true (e.g., Claude Code):

Use the adapter's full coordination lifecycle for the review Team.

On Claude Code specifically: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS must be enabled.

If adapter.parallel_execution is false (e.g., Codex CLI, Aider):

Execute review and fix agents sequentially. Collect results via adapter.collect_results.

Always follow the adapter protocol. Do not hardcode CLI-specific tool calls.

Section 1.1: Adapter Resolution Protocol (precondition for all sections)

Before entering Section 2, review-loop MUST fully resolve the active adapter.

1. Run workflow-common CLI Detection Protocol to identify the active adapter.
2. Load the adapter completely (not just the keys named above).
3. Verify required adapter keys are present. Missing required keys → FAIL FAST with

error: "Adapter {adapter_name} is missing required key(s): {list}. Review cannot proceed." Do NOT silently default missing keys — that masks adapter drift.

Required keys (all must be present):

• parallel_execution (boolean)
• structured_messaging (boolean)
• spawn_agent_personality (method spec)
• collect_results (method spec)
• model_execution (string — model identifier)
• commit_signature (string)

Optional keys (defaults applied silently if absent):

• shutdown_agents — default: no-op (skip graceful termination)
• cleanup_coordination — default: no-op
• coordinate_parallel — default: no-op if parallel_execution == false; required if parallel_execution == true
• timeout_ms — default: 600000 (10 min)

1. Adapter conformance is also validated by the lint_commands declared in the adapter.

If available, run those as part of CI before review — catches drift pre-runtime.

1. Review the output, not the plan — review agents evaluate files created/modified during /legion:build, not the plan documents themselves. The plan is the specification; the output is what gets reviewed.
2. Full personality injection — each review agent receives the ENTIRE contents of its assigned .md file as system instructions. No summaries, no excerpts, no paraphrasing.
3. Structured feedback only — review agents must use the exact Finding format defined in Section 3. Vague assessments like "looks good" or letter grades are rejected.
4. Max cycle count comes from settings — use settings.review.max_cycles (default: 3). The loop is: review → collect findings → fix → re-review. If blockers remain after that many full cycles, escalate to the user (Section 8).
5. Adapter model for all agents — review agents and fix agents both use adapter.model_execution. This matches the Cost Profile Convention from workflow-common.md.
6. Approval required, not exhaustion — a phase is NOT marked complete when cycles run out. It is marked complete only when review agents give a PASS verdict with no remaining BLOCKERs or WARNINGs.
7. Skeptical by default — "no issues found" on a first review is a yellow flag. Review agents should expect to find at least something on an initial pass. If a reviewer returns PASS on cycle 1, their reasoning must explain what was checked and why confidence is warranted.
8. Confidence-gated reporting — every finding must include a confidence level: HIGH (80-100%), MEDIUM (50-79%), or LOW (<50%). Only HIGH-confidence findings appear in the default report. MEDIUM findings are collected but only surfaced if the user explicitly requests the full report. LOW findings are discarded — if you are not at least 50% confident, it is not a finding.
9. Do not auto-proceed after escalation — if the configured cycle budget is exhausted, stop and wait for user decision. Do NOT mark the phase complete or advance to the next phase without explicit user confirmation.

Section 1.2: Settings Input

Before starting cycle 1, resolve review limits from settings.json:

• Try Read settings.json
• If present, use review.max_cycles as {max_cycles}
• If missing or invalid, set {max_cycles} = 3
• Use {max_cycles} for every loop boundary, status message, and escalation check

Section 2: Review Agent Selection

How to choose the right review agents for a phase before spawning.

Step 1: Determine the phase type
  - Read the phase CONTEXT.md file at .planning/phases/{NN}-{slug}/{NN}-CONTEXT.md
  - Read all SUMMARY.md files in the phase directory to understand what artifacts were produced
  - Classify the phase into one or more types based on what was built:
    - "code"           — new code files, skills, commands, scripts, configuration
    - "api"            — API endpoints, integrations, external service connections
    - "design"         — UI components, design systems, visual assets, CSS
    - "marketing"      — content documents, campaign plans, copy, strategy docs
    - "infrastructure" — CI/CD, deployment configs, server setup, tooling
    - "workflow"       — process documents, methodology files, skill .md files
 
Step 2: Select review agents based on phase type
  Map each detected phase type to a primary and secondary reviewer:
 
  | Phase Type     | Primary Reviewer              | Secondary Reviewer                    |
  |----------------|-------------------------------|---------------------------------------|
  | code           | testing-qa-verification-specialist       | testing-test-results-analyzer         |
  | api            | testing-api-tester            | testing-qa-verification-specialist               |
  | design         | design-brand-guardian         | testing-qa-verification-specialist               |
  | marketing      | testing-workflow-optimizer    | testing-qa-verification-specialist               |
  | infrastructure | testing-qa-verification-specialist       | testing-performance-benchmarker       |
  | workflow       | testing-workflow-optimizer    | testing-qa-verification-specialist               |
 
  **Note:** All agent IDs in this table are verified against the Legion 48-agent roster (see
  `agents/` and CLAUDE.md Division table). Agent IDs `testing-evidence-collector`,
  `engineering-devops-automator`, and `marketing-content-creator` do NOT exist in this roster
  and MUST NOT be referenced from this table.
 
  Rules:
  - Always include testing-qa-verification-specialist as either primary or secondary — they are the
    final quality gate for any phase type
  - For phases touching multiple types, include one reviewer per type (max 3 reviewers total)
  - If a phase spans 3+ types, use testing-qa-verification-specialist as universal secondary and pick
    the two most relevant primary reviewers
  - Present selected reviewers to the user for confirmation before spawning any agents
 
Step 3: Validate reviewer availability
  - Confirm each selected agent .md file exists at the expected path (using AGENTS_DIR
    resolved via workflow-common Agent Path Resolution Protocol):
    {AGENTS_DIR}/testing-qa-verification-specialist.md
    {AGENTS_DIR}/testing-test-results-analyzer.md
    {AGENTS_DIR}/testing-api-tester.md
    {AGENTS_DIR}/testing-workflow-optimizer.md
    {AGENTS_DIR}/testing-performance-benchmarker.md
    {AGENTS_DIR}/design-brand-guardian.md
  - MANDATORY: Use the Read tool to verify each personality file exists BEFORE claiming
    it is missing. Do NOT assume files are absent — the 48 agent files ship with Legion.
  - If Read genuinely returns file-not-found for a reviewer file: fall back to
    testing-qa-verification-specialist for that slot (not autonomous mode).
  - If testing-qa-verification-specialist.md is ALSO missing after a real Read attempt:
    STOP and error — do not run autonomous reviews. Agent personality injection is the
    core mechanism. Error: "Reviewer files not found. Run /legion:update to reinstall."
  - Log any fallback: "Warning: {agent-id}.md not found after Read attempt. Using
    testing-qa-verification-specialist for {phase-type} review slot."

Reviewer Confirmation Display

Before spawning review agents, show this to the user and wait for confirmation:

## Phase {N}: {phase_name} — Review Setup
 
**Phase Type(s)**: {detected types}
**Artifacts to Review**: {count files from all plan files_modified lists}
 
**Selected Reviewers**:
| Slot | Agent ID                    | Role                              | Rationale |
|------|-----------------------------|-----------------------------------|-----------|
| 1    | testing-qa-verification-specialist     | Final quality gate                | Always included |
| 2    | {secondary-agent-id}        | {domain-specific expertise}       | {why selected} |
 
Proceed with this reviewer team? (or name a replacement)

Section 3: Review Prompt Construction

How to build the prompt that each review agent receives.

Structured Review Request

When the review-loop is invoked after a build phase, it auto-constructs a structured review request from the phase's SUMMARY.md files. This gives reviewers complete context without manual assembly.

Auto-population sources:

• Scope: Git diff range from SUMMARY.md "Files Modified" sections
• Requirements: REQ-* references from the plan's YAML frontmatter
• Implementation summary: "Completed Tasks" sections from all SUMMARY.md files in the phase
• Known risks: "Open Questions" or escalation blocks from SUMMARY.md handoff context
• Verification results: Output of verification_commands from the plan (captured during build)

Injected into reviewer prompt as:

~~~

Review Context (auto-populated)

• Scope: {file list from SUMMARY.md Files Modified sections}
• Requirements addressed: {REQ-* list from plan frontmatter}
• What was built: {merged Completed Tasks from SUMMARY.md files}
• Known risks: {Open Questions and unresolved escalations}
• Verification: {verification command outputs, PASS/FAIL for each}

~~~

If SUMMARY.md files are not available (e.g., manual review without a prior build phase), skip auto-population and rely on the reviewer's own file discovery.

For each review agent:
 
Step 1: Gather phase artifacts
  - Read all {NN}-{PP}-PLAN.md files in the phase directory
  - Read all {NN}-{PP}-SUMMARY.md files in the phase directory
  - For each plan, extract the files_modified list from the YAML frontmatter
  - Build the complete list of files to review (deduplicated)
  - Read the phase CONTEXT.md for the phase goal and success criteria
  - Read .planning/ROADMAP.md to extract the phase success criteria
 
Step 2: Read the reviewer's personality file
  - Path: {AGENTS_DIR}/{agent-id}.md
    (AGENTS_DIR resolved via workflow-common Agent Path Resolution Protocol;
     cross-reference agent-registry.md Section 1 for the canonical agent ID)
  - Read the ENTIRE personality .md file — do not truncate or summarize
  - Capture this as: PERSONALITY_CONTENT