Skip to content

hashgraph-online/awesome-codex-plugins / plugins/beastlabai/multi-llm-plugin/skills/multi-llm

multi-llm

Flagged

Orchestrate plan reviews, task generation, implementation and code reviews across several LLM CLIs in parallel, or ask every model one free-text question about a plan. Use when the user says: review my plan, multi-llm, run a code review, generate tasks from a plan, implement this plan, ask the models about my plan.

FileKindSize
SKILL.mdskill md4.0 KB
apply_code_fixes_orchestrator.pyscript57.0 KB
apply_commit_fixes_orchestrator.pyscript2.3 KB
apply_suggestions_orchestrator.pyscript4.6 KB
apply_task_suggestions_orchestrator.pyscript19.2 KB
ask_orchestrator.pyscript162.5 KB
assets/icons/Anthropic.svgother584 B
assets/icons/Codex.svgother1.3 KB
assets/icons/Copilot.svgother1.5 KB
assets/icons/Cursor.svgother793 B
assets/icons/GoogleGemini.svgother623 B
assets/icons/Goose.svgother3.2 KB
assets/icons/Kilocode.svgother531 B
assets/icons/MiniMax.pngbinary1.5 KB
assets/icons/Mistral.svgother717 B
assets/icons/MoonshotAI.svgother957 B
assets/icons/Nvidia.svgother2.4 KB
assets/icons/OhMyPi.svgother434 B
assets/icons/OpenAI.svgother1.7 KB
assets/icons/Opencode.svgother325 B
assets/icons/Pi.svgother440 B
assets/icons/Qwen.svgother1.7 KB
assets/icons/Zhipu.pngbinary442 B
assets/icons/xAI.svgother343 B
assets/omp/overlay.ymlconfig2.4 KB
check_workflow_prerequisites.pyscript77.8 KB
code_review_orchestrator.pyscript326.3 KB
display_decisions.pyscript9.8 KB
finalize_tracking.pyscript1.3 KB
full_workflow_orchestrator.pyscript69.7 KB
generate_tasks_orchestrator.pyscript44.2 KB
hosts/capabilities.yamlconfig50.2 KB
hosts/codex/plugin-skill.md.tmplother2.8 KB
hosts/codex/shim.md.tmplother7.3 KB
hosts/opencode/plugin-command.md.tmplother2.2 KB
hosts/opencode/shim.md.tmplother6.8 KB
hosts/render_capabilities.pyscript48.4 KB
hosts/snippets/poll-loop.mdmarkdown4.4 KB
hosts/snippets/uv-preflight.mdmarkdown2.2 KB
hosts/uv-missing.txtmarkdown1.5 KB
implement_orchestrator.pyscript156.4 KB
improve_code_orchestrator.pyscript1.6 KB
improve_commits_orchestrator.pyscript2.5 KB
improve_plan_orchestrator.pyscript1.6 KB
init_config.pyscript58.0 KB
instructions/apply-code-fixes.mdmarkdown56.2 KB
instructions/apply-commit-fixes.mdmarkdown10.3 KB
instructions/apply-suggestions.mdmarkdown48.9 KB
instructions/apply-task-suggestions.mdmarkdown54.5 KB
instructions/ask.mdmarkdown27.6 KB
instructions/full-workflow.mdmarkdown25.3 KB
instructions/generate-tasks.mdmarkdown18.1 KB
instructions/implement.mdmarkdown55.8 KB
instructions/improve-code.mdmarkdown25.7 KB
instructions/improve-commits.mdmarkdown25.5 KB
instructions/improve-plan.mdmarkdown26.7 KB
instructions/init-config.mdmarkdown6.6 KB
instructions/review-code.mdmarkdown44.0 KB
instructions/review-commits.mdmarkdown11.4 KB
instructions/review-plan.mdmarkdown38.8 KB
instructions/review-tasks.mdmarkdown38.2 KB
modes.pyscript58.8 KB
multi_llm.pyscript101.1 KB
prompts/ask.txtmarkdown948 B
prompts/code_review.txtmarkdown4.5 KB
prompts/commit_review.txtmarkdown6.2 KB
prompts/consolidate_suggestions.txtmarkdown3.1 KB
prompts/implementation_task.txtmarkdown1.4 KB
prompts/plan_review.txtmarkdown8.0 KB
prompts/task_review.txtmarkdown8.3 KB
providers.yamlconfig20.7 KB
pyproject.tomlmanifest7.0 KB
references/apply-write-executor.mdmarkdown3.5 KB
references/consolidation.mdmarkdown5.6 KB
references/host-capabilities.mdmarkdown13.5 KB
references/human-decision-batch.mdmarkdown17.2 KB
references/implement-prerequisites.mdmarkdown6.0 KB
references/implement-write-executor.mdmarkdown5.4 KB
references/interrupted-run-recovery.mdmarkdown3.1 KB
references/own-check.mdmarkdown4.3 KB
references/resume-detection.mdmarkdown8.5 KB
references/revalidation.mdmarkdown6.9 KB
references/review-code-apply-fixes.mdmarkdown4.3 KB
references/salvage-handling.mdmarkdown12.5 KB
references/summary-format.mdmarkdown10.0 KB
references/uv-check.mdmarkdown5.7 KB
references/wave-batching.mdmarkdown5.2 KB
review_commits_orchestrator.pyscript2.3 KB
review_plan_orchestrator.pyexecutablescript24.6 KB
review_tasks_orchestrator.pyscript10.7 KB
schemas/cascade_record.schema.jsonconfig6.6 KB
schemas/code_review_issues.schema.jsonconfig2.0 KB
schemas/consolidated.schema.jsonconfig6.8 KB
schemas/consolidation_batch.schema.jsonconfig3.7 KB
schemas/generated_tasks.schema.jsonconfig3.1 KB
schemas/host_capabilities.schema.jsonconfig38.3 KB
schemas/human_decision_verdicts.schema.jsonconfig2.6 KB
schemas/result_line.schema.jsonconfig10.1 KB
schemas/review_suggestions.schema.jsonconfig2.4 KB
schemas/state_file.schema.jsonconfig23.3 KB
schemas/status_file.schema.jsonconfig24.9 KB
schemas/status_json.schema.jsonconfig10.8 KB
schemas/subagent_tasks.schema.jsonconfig20.5 KB
schemas/task_decomposition.schema.jsonconfig1.2 KB
schemas/write_batch_result.schema.jsonconfig8.8 KB
templates/config/providers.override.yamlconfig17.8 KB
templates/consolidated_report_template.htmlother44.1 KB
templates/pr_report_template.htmlother181.2 KB
templates/report_template.htmlother67.5 KB
templates/shared/report_core.cssother4.1 KB
templates/shared/report_core.jsscript25.5 KB
update_plan_tasks.pyscript20.9 KB
utils/__init__.pyscript284 B
utils/advisory.pyscript4.8 KB
utils/apply_orchestrator_base.pyscript229.0 KB
utils/apply_output_helpers.pyscript10.9 KB
utils/apply_path_helpers.pyscript683 B
utils/apply_report.pyscript51.6 KB
utils/apply_selection_helpers.pyscript6.8 KB
utils/apply_suggestion_phase.pyscript11.7 KB
utils/atomic_io.pyscript12.9 KB
utils/attempt_classifier.pyscript33.2 KB
utils/backup.pyscript2.0 KB
utils/batch_done.pyscript81.3 KB
utils/batch_ledger.pyscript27.7 KB
utils/batch_prompt.pyscript30.1 KB
utils/batch_prompt_builder.pyscript13.2 KB
utils/batch_reply.pyscript32.9 KB
utils/batch_suppressions.pyscript15.5 KB
utils/cascade_archive.pyscript50.6 KB
utils/cascade_ledger.pyscript39.3 KB
utils/cascade_provenance.pyscript22.0 KB
utils/check_records.pyscript59.7 KB
utils/check_reply.pyscript9.5 KB
utils/check_tree.pyscript1.2 KB
utils/cli_common.pyscript94.3 KB
utils/cli_version_cache.pyscript14.0 KB
utils/clock.pyscript3.5 KB
utils/code_fix_batcher.pyscript31.4 KB
utils/codex_trust.pyscript12.9 KB
utils/commit_apply.pyscript73.3 KB
utils/commit_attribution.pyscript21.2 KB
utils/commit_brief.pyscript32.2 KB
utils/commit_front_door.pyscript81.9 KB
utils/commit_paths.pyscript18.0 KB
utils/commit_range.pyscript61.2 KB
utils/commit_report.pyscript19.9 KB
utils/commit_review.pyscript413 B
utils/commit_spelling.pyscript7.9 KB
utils/commit_write_guard.pyscript9.9 KB
utils/concurrency.pyscript11.6 KB
utils/consolidation.pyscript89.0 KB
utils/detach.pyscript187.9 KB
utils/dispatch_spawn.pyscript62.4 KB
utils/doctor.pyscript76.7 KB
utils/env_vars.pyscript20.5 KB
utils/failure_capture.pyscript10.1 KB
utils/file_discovery.pyscript11.0 KB
utils/filtering.pyscript19.9 KB
utils/fresh_reset.pyscript3.9 KB
utils/git_diff.pyscript23.6 KB
utils/git_utils.pyscript86.6 KB
utils/held_folder.pyscript21.3 KB
utils/host_capabilities.pyscript48.0 KB
utils/host_install.pyscript77.6 KB
utils/host_paths.pyscript12.0 KB
utils/host_routes/__init__.pyscript5.7 KB
utils/host_routes/codex.pyscript18.3 KB
utils/host_routes/npm.pyscript12.2 KB
utils/host_shim.pyscript14.7 KB
utils/html_report_generator.pyscript118.9 KB
utils/human_decisions.pyscript38.3 KB
utils/human_task_plan.pyscript30.2 KB
utils/importance.pyscript6.2 KB
utils/improve_cascade.pyscript63.7 KB
utils/improve_cascade_next.pyscript22.2 KB
utils/improve_steps.pyscript33.1 KB
utils/improve_workflow.pyscript120.9 KB
utils/interactive.pyscript31.6 KB
utils/json_extractor.pyscript83.1 KB
utils/judge_vocab.pyscript5.3 KB
utils/known_checks.pyscript41.6 KB
utils/landlock_dispatch.pyscript103.8 KB
utils/landlock_exec.pyscript21.4 KB
utils/launch_limiter.pyscript13.5 KB
utils/llm_client.pyscript142.7 KB
utils/manual_tasks.pyscript14.9 KB
utils/metrics.pyscript68.1 KB
utils/next_phase.pyscript96.7 KB
utils/next_phase_words.pyscript6.4 KB
utils/output_handler.pyscript23.2 KB
utils/phase_walk.pyscript6.4 KB
utils/plan_updater.pyscript17.9 KB
utils/positionals.pyscript5.8 KB
utils/prior_changes.pyscript28.7 KB
utils/probe_state.pyscript17.9 KB
utils/process_capture.pyscript44.1 KB
utils/process_control.pyscript228.7 KB
utils/process_state.pyscript6.6 KB
utils/progress_tracker.pyscript92.2 KB

review_plan_orchestrator.py

View on GitHub
#!/usr/bin/env python3
"""
Orchestrator for running plan reviews across multiple LLM models.

This script takes an implementation plan file and runs it through multiple
LLM models in parallel to gather review suggestions. Results are saved
per-model and aggregated into a consolidated markdown report.

Supports multiple providers (cursor-agent, gemini, opencode) via the provider
registry. Models can be specified as 'provider:model' or bare 'model' names
(which use the default provider from providers.yaml).

Usage:
    # Use YAML defaults (no prompting if defaults.models is set)
    uv run --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" review-plan plans/my-plan.md

    # Override defaults with specific models
    uv run --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" review-plan plans/my-plan.md --models cursor-agent:auto gemini:gemini-2.5-flash

    # Force interactive selection even if defaults exist
    uv run --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" review-plan plans/my-plan.md --interactive
"""

import argparse
import asyncio
import json
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Dict, List, Optional

# Add parent to path for imports
sys.path.insert(0, str(Path(__file__).parent))

from utils.stream_bootstrap import bootstrap_streams
from utils import cli_common
from utils.cli_common import build_parent_parser, dispatcher_prefix, add_scope_policy_argument
from utils.prompt_loader import load_prompt
from utils import scope_round as _scope_round
from utils.state_manager import load_groups_payload
from utils.provider_registry import (
    get_all_model_specs,
)
from utils.consolidation import (
    pre_group_by_section,
    prepare_consolidation_tasks,
    preview_consolidation_tasks,
    merge_consolidation_results,
    generate_consolidated_json,
    generate_consolidated_report,
    generate_consolidated_html,
    CONSOLIDATION_RECOMMENDED_THRESHOLD,
)
from utils.html_report_generator import (
    sort_consolidated_groups_by_priority,
    derive_aggregate_validation_status,
)
from utils.review_orchestrator_base import (
    run_review_orchestration,
    dispatch_subagent_tasks,
    recorded_served_models,
    recorded_usage,
    derive_prefix,
)
from utils import status_file as _status_file
from utils.git_utils import get_project_root
from utils.output_handler import _compute_file_hash
from utils.task_file_runner import dry_run_report

# Prompt template filename
REVIEW_PROMPT_FILE = "plan_review.txt"


def load_review_prompt_template() -> str:
    """Load the plan review prompt template.

    Returns:
        Prompt template string with placeholders for substitution
    """
    return load_prompt(REVIEW_PROMPT_FILE)


def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
    """Parse command line arguments."""
    # Get available models for help text - wrapped in try/except to allow --help
    # even if providers.yaml is missing or malformed
    try:
        available_models = get_all_model_specs()
    except FileNotFoundError:
        available_models = ["(providers.yaml not found - run with --models to specify)"]
    except Exception as e:
        available_models = [f"(config error: {type(e).__name__} - check providers.yaml)"]

    # `--help` goes to stdout, so its examples are *printed* commands and follow
    # the rule the follow-ups do (D1/D1c): fully resolved from `__file__`, never a
    # skill-dir placeholder — no shell but Claude Code's expands one, so on Codex or
    # OpenCode a copied example would die before Python started. Interpolating
    # `dispatcher_prefix()` also keeps the leading token `uv run`, which is what
    # keeps Claude Code's `Bash(uv:*)` glob matching, and names the single entry
    # point rather than this script.
    run = dispatcher_prefix()
    parser = argparse.ArgumentParser(
        description="Run plan reviews across multiple LLM models",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        parents=[build_parent_parser()],
        epilog=f"""
Available models (provider:model format):
  {', '.join(available_models[:10])}{'...' if len(available_models) > 10 else ''}

Model selection priority:
  1. --models flag       -> Use specified models
  2. --interactive flag  -> Force two-step interactive selection
  3. --quick flag        -> Use quick_models from providers.yaml (2 models)
  4. YAML defaults       -> Use configured defaults from providers.yaml
  5. Interactive         -> Two-step selection (fallback if no defaults)

Examples:
  # Use YAML defaults (no prompting)
  {run} review-plan plans/my-plan.md

  # Specify models explicitly
  {run} review-plan plans/my-plan.md --models cursor-agent:auto gemini:gemini-2.5-flash

  # Force interactive selection
  {run} review-plan plans/my-plan.md --interactive
        """
    )

    parser.add_argument(
        '--plan-file',
        required=True,
        help='Path to the implementation plan markdown file'
    )

    parser.add_argument(
        '--models',
        nargs='+',
        default=None,
        help='List of models in provider:model format (e.g., cursor-agent:auto gemini:gemini-2.5-flash). '
             'Bare model names use default provider from providers.yaml.'
    )

    parser.add_argument(
        '--quick', '-q',
        action='store_true',
        help='Use quick_models from providers.yaml for lightweight reviews (2 models)'
    )

    parser.add_argument(
        '--out-dir',
        default=None,
        help='Output directory (default: same as input plan file)'
    )

    parser.add_argument(
        '--timeout',
        type=int,
        default=None,
        help='Override timeout per model in seconds (default: use per-provider timeout from providers.yaml)'
    )

    parser.add_argument(
        '--max-parallel',
        type=int,
        default=5,
        help='Maximum number of parallel model invocations (default: 5)'
    )

    parser.add_argument(
        '--skip-validation',
        action='store_true',
        help='Skip the validation step (faster but no false-positive filtering)'
    )

    parser.add_argument(
        '--validation-model',
        type=str,
        default='auto',
        help='Model to use for validation (default: auto)'
    )

    parser.add_argument(
        '--reaggregate',
        action='store_true',
        help='Re-aggregate existing model results (use after salvage operations complete)'
    )

    cli_common.add_retired_flag(parser, '--internal-validation')

    parser.add_argument(
        '--consolidate',
        action='store_true',
        help='Run consolidation to cluster related suggestion groups by plan section'
    )

    parser.add_argument(
        '--reaggregate-consolidation',
        action='store_true',
        help='Re-aggregate consolidation batch results into final consolidated output'
    )

    parser.add_argument(
        '--consolidation-threshold',
        type=int,
        default=None,
        help='Override the minimum valid group count for consolidation recommendation '
             f'(default: {CONSOLIDATION_RECOMMENDED_THRESHOLD})'
    )

    parser.add_argument(
        '--consolidate-dry-run',
        action='store_true',
        help='Show consolidation batching stats without running subagents'
    )

    parser.add_argument(
        '--force',
        action='store_true',
        help='Bypass the completed-phase and partial-completion guards and resume '
             'the phase (already-completed per-model results are kept; only missing '
             'models re-run). For a full re-run that discards existing results, also '
             'pass --rerun-all.'
    )

    parser.add_argument(
        '--rerun-all',
        action='store_true',
        help='Re-run every model from scratch, discarding any existing per-model '
             'result files (default: resume — skip models that already have results).'
    )

    # A cascade stage's frozen inputs (`--improve-plan --cascade`): the
    # manifest this review verifies and records as its round's `cascade`
    # block (utils/cascade_provenance.py, utils/review_lane.open_round).
    # Hidden: only the composite writes it, and replay drops it.
    parser.add_argument('--cascade-stage-file', dest='cascade_stage_file', default=None,
                        help=argparse.SUPPRESS)

    parser.add_argument(
        '--report-style',
        choices=['pr', 'flat'],
        default='pr',
        help='HTML report template style: "pr" for PR-style contextual view, "flat" for classic card layout (default: pr)'
    )

    # plans/scope-policy-and-report-tags.md §4: declared once, in cli_common.
    add_scope_policy_argument(parser, role="review")

    return parser.parse_args(argv)


# ---------------------------------------------------------------------------
# Consolidation handlers (specific to review-plan)
# ---------------------------------------------------------------------------

def consolidate_mode(phase_dir: str, plan_path: str, args=None) -> None:
    """Run consolidation to cluster related suggestion groups.

    ``args`` is optional so a direct call still works; when it carries
    ``--exec-subagents`` the consolidation batch is dispatched and reaggregated in
    this same invocation (D3b) instead of printing a follow-up command for a host
    to drive.
    """
    grouped_path = os.path.join(phase_dir, "grouped.json")
    validation_path = os.path.join(phase_dir, "validation.json")

    if not os.path.exists(grouped_path):
        print(f"ERROR: grouped.json not found at {grouped_path}")
        sys.exit(1)
    if not os.path.exists(validation_path):
        print(f"ERROR: validation.json not found at {validation_path}")
        sys.exit(1)

    with open(grouped_path, 'r', encoding='utf-8') as f:
        groups = load_groups_payload(json.load(f))
    with open(validation_path, 'r', encoding='utf-8') as f:
        validation_data = json.load(f)
    if isinstance(validation_data, dict) and "groups" in validation_data:
        validation = validation_data["groups"]
    else:
        validation = validation_data

    section_groups = pre_group_by_section(groups, validation)

    if args is not None and getattr(args, "dry_run_subagents", False):
        consolidation_preview(groups, section_groups, phase_dir, plan_path)
        return

    tasks_metadata = prepare_consolidation_tasks(
        groups, section_groups, phase_dir, plan_path
    )

    total_batches = tasks_metadata["total_batches"]
    tasks_path = os.path.join(phase_dir, "consolidation_tasks.json")

    if total_batches == 0:
        print("No sections need consolidation (all singletons).")
        print("[CONSOLIDATION_SKIPPED] No batches to process.")
        return

    if total_batches == 1:
        print(f"\n[CONSOLIDATION_PENDING] {tasks_path}")
    else:
        print(f"\n[CONSOLIDATION_BATCHES_PENDING] {tasks_path}")
        print(f"Batches: {total_batches}")

    print("\nConsolidation prepared for Claude Code subagent.")
    if any(batch.get("prompt_path") for batch in tasks_metadata.get("batches", [])):
        # Live run 8: the host wrote these files itself, outside the
        # repository, when the batches named none.
        print(
            "Each batch's prompt is also in its own file "
            "(`prompt_path`, consolidation_batch_N.prompt.txt in the phase "
            "directory, the same bytes as its `prompt`)."
        )
    print(f"Sections with 2+ groups: {len([s for s in section_groups.values() if len(s) >= 2])}")
    print(f"Singleton sections: {len(tasks_metadata.get('singleton_sections', {}))}")

    # The stored value is the bare verb, never a command (D2 row 8): compose
    # the runnable string here, from this mode, the document's own plan_file,
    # that verb and the document's replay_flags — a live invocation of this
    # mode winning over the stored list.
    reaggregate_cmd = cli_common.retry_command(
        "review-plan",
        tasks_metadata.get("plan_file") or plan_path,
        tasks_metadata.get("reaggregate_command") or "--reaggregate-consolidation",
        flags=cli_common.current_replay_flags(
            tasks_metadata.get("replay_flags"), mode="review-plan"
        ),
    )

    # D3b: continue past the marker in-process when this run drives its own
    # subagents — consolidation's consumer is reaggregate_consolidation_mode, so
    # the phase closes here rather than owing a host a second turn.
    if args is not None and dispatch_subagent_tasks(
        args,
        task_file=tasks_path,
        phase_dir=phase_dir,
        phase="review-plan",
        document=tasks_metadata,
        plan_path=plan_path,
        label="consolidation",
        retry_command=reaggregate_cmd,
    ):
        prefix = derive_prefix(plan_path)
        reaggregate_consolidation_mode(phase_dir, plan_path, prefix)
        return

    # The plan as the user typed it (fix round 14).
    reaggregate_cmd = cli_common.retry_command(
        "review-plan",
        cli_common.typed_plan_for(tasks_metadata.get("plan_file") or plan_path),
        tasks_metadata.get("reaggregate_command") or "--reaggregate-consolidation",
        flags=cli_common.current_replay_flags(
            tasks_metadata.get("replay_flags"), mode="review-plan"
        ),
    )
    print("\nAfter consolidation completes, run:")
    print(f"  {reaggregate_cmd}")


def consolidation_preview(
    groups: List[Dict], section_groups: Dict[str, List[int]], phase_dir: str,
    plan_path: str,
) -> None:
    """``--consolidate --dry-run-subagents``: render each consolidation batch's
    command, start no child, and write nothing but the dry-run record.

    The batches are built as a real pass builds them
    (``consolidation.preview_consolidation_tasks``) and never written: no
    ``consolidation_tasks.json``, no prompt sidecars, no host index, so a
    composite whose previewed step is this pass records nothing, as its
    closing line says. ``task_file_runner.dry_run_report`` renders the
    commands and writes ``{phase}/subagent_dry_run.json``, the record every
    dry run leaves. No marker is printed: there is no task file for anyone
    to run (docs/development/workflows.md#a-dry-run-previews-one-step).
    """
    document = preview_consolidation_tasks(groups, section_groups, phase_dir, plan_path)
    total = document["total_batches"]
    print(f"Sections with 2+ groups: {len([s for s in section_groups.values() if len(s) >= 2])}")
    print(f"Singleton sections: {len(document.get('singleton_sections', {}))}")
    print(f"Batches: {total}")
    if total == 0:
        print("[dry-run-subagents] consolidation: no section needs it (all "
              "singletons), so a real pass dispatches nothing; nothing was written.")
        return
    report = dry_run_report(
        os.path.join(phase_dir, "consolidation_tasks.json"),
        phase_dir=phase_dir, phase="review-plan", document=document,
        anchor=plan_path, cwd=get_project_root(plan_path),
    )
    print(f"[dry-run-subagents] {report} — every consolidation command rendered, "
          f"no child started. Nothing else was written: a real pass writes "
          f"consolidation_tasks.json and its prompt files, then prints its marker.")
    cli_common.record_artifact(report)
    cli_common.record_next(None)


def consolidate_dry_run_mode(phase_dir: str, plan_path: str) -> None:
    """Show consolidation stats without running subagents."""
    grouped_path = os.path.join(phase_dir, "grouped.json")
    validation_path = os.path.join(phase_dir, "validation.json")

    if not os.path.exists(grouped_path):
        print(f"ERROR: grouped.json not found at {grouped_path}")
        sys.exit(1)
    if not os.path.exists(validation_path):
        print(f"ERROR: validation.json not found at {validation_path}")
        sys.exit(1)

    with open(grouped_path, 'r', encoding='utf-8') as f:
        groups = load_groups_payload(json.load(f))
    with open(validation_path, 'r', encoding='utf-8') as f:
        validation_data = json.load(f)
    if isinstance(validation_data, dict) and "groups" in validation_data:
        validation = validation_data["groups"]
    else:
        validation = validation_data

    section_groups = pre_group_by_section(groups, validation)

    # Built, never written: a dry run leaves the phase dir as it found it.
    tasks_metadata = preview_consolidation_tasks(
        groups, section_groups, phase_dir, plan_path
    )

    total_batches = tasks_metadata["total_batches"]
    singleton_count = len(tasks_metadata.get("singleton_sections", {}))
    multi_sections = len([s for s in section_groups.values() if len(s) >= 2])
    total_groups = sum(len(indices) for indices in section_groups.values())

    print("\n=== CONSOLIDATION DRY RUN ===")
    print(f"Total valid groups: {total_groups}")
    print(f"Sections with 2+ groups: {multi_sections}")
    print(f"Singleton sections: {singleton_count}")
    print(f"Batches needed: {total_batches}")

    for batch in tasks_metadata.get("batches", []):
        print(f"  Batch {batch['batch_index']}: {batch['groups_count']} groups in '{batch['section_key']}'")

    print("\n[DRY_RUN_COMPLETE]")


def reaggregate_consolidation_mode(
    phase_dir: str, plan_path: str, prefix: str
) -> None:
    """Merge consolidation batch results and generate output files."""
    tasks_path = os.path.join(phase_dir, "consolidation_tasks.json")
    grouped_path = os.path.join(phase_dir, "grouped.json")

    if not os.path.exists(tasks_path):
        print(f"ERROR: consolidation_tasks.json not found at {tasks_path}")
        sys.exit(1)
    if not os.path.exists(grouped_path):
        print(f"ERROR: grouped.json not found at {grouped_path}")
        sys.exit(1)

    with open(tasks_path, 'r', encoding='utf-8') as f:
        tasks_metadata = json.load(f)
    with open(grouped_path, 'r', encoding='utf-8') as f:
        groups = load_groups_payload(json.load(f))

    consolidated_groups, partial_failures = merge_consolidation_results(
        phase_dir, tasks_metadata, groups
    )

    if partial_failures.get("count", 0) > 0:
        print(f"Warning: {partial_failures['count']} batch(es) had failures "
              f"(indices: {partial_failures['batches']})")

    plan_hash = _compute_file_hash(plan_path)
    grouped_hash = _compute_file_hash(grouped_path)

    total_original = sum(
        len(cg.get("underlying_group_indices", []))
        for cg in consolidated_groups
    )
    merged_count = sum(1 for cg in consolidated_groups if not cg.get("is_singleton", True))
    singleton_count = len(consolidated_groups) - merged_count

    metadata = {
        "schema_version": "1.0",
        "total_original_groups": total_original,
        "total_consolidated": len(consolidated_groups),
        "merged_count": merged_count,
        "singleton_count": singleton_count,
        "consolidation_ratio": round(
            len(consolidated_groups) / max(total_original, 1), 2
        ),
        "timestamp": datetime.now().isoformat(),
        "plan_hash": plan_hash,
        "grouped_hash": grouped_hash,
        "plan_hash_algorithm": "sha256",
        "skipped_report": False,
        "sections_processed": len(tasks_metadata.get("batches", [])) + len(tasks_metadata.get("singleton_sections", {})),
    }

    if partial_failures.get("count", 0) > 0:
        metadata["partial_failures"] = partial_failures

    json_path = generate_consolidated_json(consolidated_groups, metadata, phase_dir)
    print(f"Consolidated JSON: {json_path}")
    # Live run 8 (Claude Code racing 01): the checkpoint kept the
    # recommendation this pass answers, so `status` and its result line went
    # on saying "run --consolidate" after it ran.
    _status_file.remove_status_keys(phase_dir, ["consolidation_recommended"])

    if metadata.get("skipped_report"):
        print("Consolidation complete (report skipped -- minimal reduction).")
        return

    # --- Pre-generation coordination point ---
    # Load validation data for aggregate status derivation
    all_models = set()
    for group in groups:
        for m in group.get("models", []):
            all_models.add(m)

    validation_path = os.path.join(phase_dir, "validation.json")
    validation_for_html = None
    if os.path.exists(validation_path):
        with open(validation_path, 'r', encoding='utf-8') as f:
            validation_raw = json.load(f)
        if isinstance(validation_raw, dict) and "groups" in validation_raw:
            validation_for_html = validation_raw["groups"]
        else:
            validation_for_html = validation_raw
        # The underlying groups carry their validated scope verdicts (by stable
        # hash only) into the consolidated reports; consolidation itself is no
        # new scope authority (plan §3).
        _scope_round.attach_verdicts(groups, validation_for_html)
        scope_meta = (
            validation_raw.get("metadata") if isinstance(validation_raw, dict) else None
        ) or {}
        _scope_round.annotate_decisions(
            groups, scope_meta.get("scope_policy"),
            scope_meta.get("scope_round_baseline_id") or scope_meta.get("scope_baseline_id"),
        )

    # Derive aggregate validation status for each consolidated group
    if validation_for_html:
        validation_by_index = {}
        for entry in validation_for_html:
            g_idx = entry.get("group_index")
            if g_idx is not None:
                validation_by_index[g_idx] = entry.get("status", "")
        for cg in consolidated_groups:
            underlying_indices = cg.get("underlying_group_indices", [])
            statuses = [
                validation_by_index[idx]
                for idx in underlying_indices
                if idx in validation_by_index
            ]
            cg["validation_status"] = derive_aggregate_validation_status(statuses)

    # Sort once, reassign displayIndex, pass to both generators
    consolidated_groups = sort_consolidated_groups_by_priority(consolidated_groups)
    for i, cg in enumerate(consolidated_groups):
        cg["display_index"] = i + 1

    report_path = generate_consolidated_report(
        consolidated_groups, groups, phase_dir, prefix,
        validation=validation_for_html,
    )
    print(f"Consolidated report: {report_path}")

    # What the fan-out spent and which model and sandbox served each slot,
    # read back off the checkpoint the way the full report reads them:
    # consolidation runs in its own invocation, long after the slots exited,
    # and the per-model `{model}.json` files this mode re-reads are bare
    # suggestion lists. `None` for a default run, which leaves the report
    # exactly as it was.
    html_path = generate_consolidated_html(
        consolidated_groups, groups, phase_dir, plan_path, list(all_models),
        validation=validation_for_html,
        usage=recorded_usage(phase_dir),
        served_models=recorded_served_models(phase_dir),
    )
    print(f"Consolidated HTML: {html_path}")

    reduction_pct = round((1 - metadata["consolidation_ratio"]) * 100, 1)
    print("\nConsolidation complete!")
    print(f"  {total_original} groups -> {len(consolidated_groups)} consolidated ({reduction_pct}% reduction)")
    print(f"  Merged: {merged_count}, Singletons: {singleton_count}")


async def main(argv: Optional[List[str]] = None) -> int:
    """Main entry point."""
    # Line buffering + UTF-8/replace stream encoding (Windows-safe output);
    # see utils/stream_bootstrap.py for the full rationale.
    bootstrap_streams()

    args = parse_args(argv)

    # Load the prompt template
    prompt_template = load_review_prompt_template()

    # Build prompt context factory
    plan_path_abs = os.path.abspath(args.plan_file)
    effective_prefix = derive_prefix(plan_path_abs)

    def prompt_context_factory(model_spec: str) -> Dict:
        return {
            "plan_path": plan_path_abs,
            "prefix": effective_prefix,
        }

    # Set up consolidation handlers
    consolidation_handlers = {
        'dry_run': consolidate_dry_run_mode,
        'consolidate': consolidate_mode,
        'reaggregate_consolidation': reaggregate_consolidation_mode,
    }

    await run_review_orchestration(
        args=args,
        phase_name='review-plan',
        invoke_phase='plan_review',
        salvage_phase_name='review_plan',
        prompt_template=prompt_template,
        prompt_context_factory=prompt_context_factory,
        orchestrator_script='review_plan_orchestrator.py',
        supports_consolidation=True,
        consolidation_handlers=consolidation_handlers,
        base_ref=None,
        tasks_path=None,
        template_style=args.report_style,
    )
    # Any non-zero outcome is raised as SystemExit by the orchestration itself;
    # reaching here means the phase completed.
    return 0


if __name__ == "__main__":
    from utils import process_control

    # A process entry of its own: provider children must stay this process's.
    process_control.restore_sigchld_default()
    sys.exit(asyncio.run(main(sys.argv[1:])))
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall