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.pyscript56.6 KB
apply_commit_fixes_orchestrator.pyscript2.3 KB
apply_suggestions_orchestrator.pyscript4.5 KB
apply_task_suggestions_orchestrator.pyscript19.1 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.pyscript74.5 KB
code_review_orchestrator.pyscript324.0 KB
display_decisions.pyscript9.8 KB
finalize_tracking.pyscript1.3 KB
full_workflow_orchestrator.pyscript58.8 KB
generate_tasks_orchestrator.pyscript44.2 KB
hosts/capabilities.yamlconfig49.9 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.0 KB
improve_code_orchestrator.pyscript1.6 KB
improve_commits_orchestrator.pyscript2.5 KB
improve_plan_orchestrator.pyscript1.6 KB
init_config.pyscript57.6 KB
instructions/apply-code-fixes.mdmarkdown52.0 KB
instructions/apply-commit-fixes.mdmarkdown10.3 KB
instructions/apply-suggestions.mdmarkdown48.2 KB
instructions/apply-task-suggestions.mdmarkdown53.9 KB
instructions/ask.mdmarkdown27.6 KB
instructions/full-workflow.mdmarkdown24.6 KB
instructions/generate-tasks.mdmarkdown18.1 KB
instructions/implement.mdmarkdown54.0 KB
instructions/improve-code.mdmarkdown25.0 KB
instructions/improve-commits.mdmarkdown24.8 KB
instructions/improve-plan.mdmarkdown26.2 KB
instructions/init-config.mdmarkdown6.6 KB
instructions/review-code.mdmarkdown43.5 KB
instructions/review-commits.mdmarkdown11.4 KB
instructions/review-plan.mdmarkdown38.4 KB
instructions/review-tasks.mdmarkdown37.8 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.yamlconfig19.6 KB
pyproject.tomlmanifest6.8 KB
references/apply-write-executor.mdmarkdown3.0 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.mdmarkdown4.9 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.pyexecutablescript22.3 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.jsonconfig21.5 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.2 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.pyscript220.6 KB
utils/apply_output_helpers.pyscript10.9 KB
utils/apply_path_helpers.pyscript683 B
utils/apply_report.pyscript51.2 KB
utils/apply_selection_helpers.pyscript6.8 KB
utils/apply_suggestion_phase.pyscript11.7 KB
utils/atomic_io.pyscript12.9 KB
utils/attempt_classifier.pyscript31.4 KB
utils/backup.pyscript2.0 KB
utils/batch_done.pyscript79.2 KB
utils/batch_ledger.pyscript27.4 KB
utils/batch_prompt.pyscript29.3 KB
utils/batch_prompt_builder.pyscript12.2 KB
utils/batch_reply.pyscript32.9 KB
utils/cascade_archive.pyscript50.6 KB
utils/cascade_ledger.pyscript39.3 KB
utils/cascade_provenance.pyscript22.0 KB
utils/check_records.pyscript59.3 KB
utils/check_reply.pyscript9.5 KB
utils/check_tree.pyscript1.2 KB
utils/cli_common.pyscript91.2 KB
utils/cli_version_cache.pyscript14.0 KB
utils/clock.pyscript3.5 KB
utils/code_fix_batcher.pyscript30.6 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.6 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.pyscript87.3 KB
utils/detach.pyscript186.8 KB
utils/dispatch_spawn.pyscript56.3 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/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.pyscript32.4 KB
utils/improve_workflow.pyscript114.4 KB
utils/interactive.pyscript31.6 KB
utils/json_extractor.pyscript61.5 KB
utils/judge_vocab.pyscript5.3 KB
utils/known_checks.pyscript37.5 KB
utils/landlock_dispatch.pyscript103.8 KB
utils/landlock_exec.pyscript21.4 KB
utils/launch_limiter.pyscript13.5 KB
utils/llm_client.pyscript126.9 KB
utils/manual_tasks.pyscript14.9 KB
utils/metrics.pyscript68.1 KB
utils/next_phase.pyscript96.1 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.pyscript37.6 KB
utils/process_control.pyscript228.7 KB
utils/process_state.pyscript6.6 KB
utils/progress_tracker.pyscript92.2 KB
utils/prompt_channels.pyscript34.1 KB
utils/prompt_files.pyscript24.5 KB

instructions/improve-code.md

View on GitHub
# Improve Code Mode Instructions

Reviews the code changes with every model, then applies the validated fixes to the
code, in one unattended command. It runs two phases that exist on their own,
review-code and then apply-code-fixes, by loading each phase's own core; this file
says only which steps to run, with which flags, and how to report them.

## Usage

```bash
/multi-llm:multi-llm --improve-code <plan_path> [--quick | --models provider:model ...] [--files <path> (repeatable) | --files-from <file>] [--base-ref REF] [--scope-policy expand|preserve] [--cascade] [--force] [--resume]
```

`--files` takes one path per flag, as review-code's does: repeat it for each file
(`--files a.py --files b.py`), or list them one per line in a `--files-from` file.

## What it runs

| Step | Phase core | Flags it gets (`util improve-steps` prints them) |
| --- | --- | --- |
| 1 | `review-code` | `--yes`, plus `--models …` or `--quick` and the scope flags (`--files`, `--files-from`, `--base-ref`) when the user typed them; `--force --rerun-all` on a new round (`--force`), `--force` alone when the typed scope differs from the one the review on record used |
| 2 | `apply-code-fixes` | `--yes --agent-decide --no-confirm`, plus `--base-ref` (the one typed, else the one the review on record diffed against) and `--resume` when an interrupted apply continues |

Both steps also get `--scope-policy <value>` right after `--yes` when the user
typed one, or when a stopped run of this mode recorded one; with none, no step
gets it. `expand` (typed, or this mode's recorded choice) over a completed
apply that deferred items or stopped on a scope blocker runs step 2 again, to
offer them (`run (N scope deferral(s) to reconsider under --scope-policy
expand)`), instead of `[ALREADY_COMPLETE]`.

Python decides every flag. Never compose one, add one or drop one: pass the tokens
after each step's `[IMPROVE_STEP_FLAGS] <index>` exactly as printed, never the marker
or the index. The review's scope is review-code's own: the typed
`--files`/`--files-from`, else the files implement recorded, else the git diff it
announces with `[SCOPE_FALLBACK]`.

**`--cascade`** runs the two steps once per model, in the order of the review's model
list (`--models` as typed, else `--quick`, else the configured defaults; put the
cheapest first): each model alone reviews the code as the stages before it left
it, and its validated findings are applied before the next model reviews. Each stage's
review sees what earlier stages applied, rejected or held back. Section 1 then prints
no step block, and section 2C runs the stages.

## What a run writes, unattended

- **Source files, anywhere in the repository.** Each fix batch edits the files its
  fixes name, unasked. Nothing backs up the repository as a whole, so git is the way
  back: commit or stash first, so `git diff` shows exactly what the run changed and
  `git restore` undoes it. Nothing refuses a dirty tree. On a host that adds
  `--exec-subagents` each batch also keeps a pre-batch snapshot that
  `util restore-batch` restores.
- **The plan**, which gains apply-code-fixes' `## Code Fixes Applied` section.
- **The review's files** in `{plan}/code-review/` (reports, the scope manifest and
  diffs, `grouped.json`, `validation.json`, one result per model).
- **The apply's files** in `{plan}/apply-fixes/`: `summary.md`,
  `orchestrator_output.json`, `write_tasks.json`; the decision badges on
  `{plan}/code-review/report.html`; and the records in `{plan}/state.json`.
- **Under `--cascade`, one directory per cascade** in
  `{plan}/improve-code/cascades/`, which `{plan}/improve-code/cascade-current.json`
  names: `record.json`, `summary.md` (the per-round table), `ledger.md` (what each
  stage applied, rejected or held back), and one `stage-<k>/` per stage, holding the
  inputs frozen at its start and its review and apply files copied when it closed. The
  phase dirs above hold the last stage's round.
- **Nobody is asked.** A judge agent decides every `needs-human-decision` item, and
  `summary.md` names the judge and each decision it made.

## Unattended rows

The run is unattended whatever the user typed: every row it reaches resolves as below,
and no question is ever rendered.

| Row | Where | Resolution |
| --- | --- | --- |
| D6 row 1, uv missing | before step 1 | the prerequisite below: print `hosts/uv-missing.txt`, stop with exit 3 |
| D6 row 2, model selection | step 1 | `--yes` with the flags line's `--models` or `--quick`, else `defaults.models`; nothing asked, and exit 3 from the review when nothing resolves |
| D6 row 3, partial fan-out results | step 1 | the review core's `--yes` path: resume the missing models once, then `[PARTIAL_RESULTS: …]` and exit 0; zero results is exit 3. Under `--cascade` each stage's review has one model: a stage before the last with no result is recorded skipped (`[CASCADE_STAGE_SKIPPED]`, then `[AUTO_RESOLVED]`) and the next stage runs (section 2C, item 4); the last stage's is exit 3, and the re-run starts that stage over |
| D6 row 10, `needs-human-decision` items | step 2 | `--agent-decide`: the judge agent decides every item, nobody is asked |
| D6 row 11, no-selection confirmation | step 2 | `--no-confirm`: every valid fix is applied without asking |
| D6 row 14, a step fails | section 3 | stop, report the stop, give `[IMPROVE_RERUN]` as the way to continue (it carries `--cascade` while a cascade is unfinished); never ask whether to go on |
| D6 row 15, an empty or unrecognized decision flag (`--models ""`) | step 1 | `util improve-steps` exits 3 before any step runs |
| D6 row 16, scope policy | steps 1 and 2 | never asked: the flags lines carry the typed `--scope-policy` (or the one a stopped run of this mode recorded); with none, each step resolves its own (a new review `expand`, the apply its review's), and one nobody typed is recorded as `[AUTO_RESOLVED] scope-policy: …` |

`--interactive` (or `-i`) is no row: `util improve-steps` refuses it with exit 3 and
names the two phases to run instead. Code review has no consolidation pass, so this
mode never reaches row 4.

---

## Step-by-Step Execution

**Prerequisite — `uv` (D6 row 1).** Every command below runs through `uv run`.
If it is absent the resolution is fail-closed: print `hosts/uv-missing.txt`
verbatim and **stop with exit 3** — never install it, never ask, never fall back
to bare `python`.

*Step 1* and *step 2* below are the steps `util improve-steps` prints (the review and
the apply); this file's own sections are numbered 1 to 4. Keep going from step to step
in one turn: do not end your turn between steps, and do not announce the run as done
before section 4's report.

### 1. Plan the steps

```bash
uv run {UV_RUN_FLAGS} --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" util improve-steps "$PLAN_PATH" --mode improve-code --host <host-id> <the flags the user typed>
```

`<host-id>` is the host id your dispatcher command carries; it makes the printed
continuation your host's spelling. Then pass every flag the user typed, exactly as
typed, `--interactive` and `-i` included: the util refuses what it must, and this core
never checks or drops a flag itself. It prints one block per step, for example:

```text
  [IMPROVE_STEP] 1 review-code run (not reviewed yet)
  [IMPROVE_STEP_FLAGS] 1 --yes --quick --base-ref origin/main
  [IMPROVE_STEP] 2 apply-code-fixes run (review not applied yet)
  [IMPROVE_STEP_FLAGS] 2 --yes --agent-decide --no-confirm --base-ref origin/main
  [IMPROVE_RERUN] <the command that continues this run, in your host's spelling>
```

(indented here; the util prints each line at its start). A step it passes over reads
`skip (<why>)` instead of `run`. `[IMPROVE_STEP_FRESH] 1`
appears only for a review that must start over. Before the step blocks it can print
one notice: `[IMPROVE_SCOPE_CHANGED] …`, when the typed `--files`/`--files-from` differ
from the scope the review on record used (step 1 then reads `run (review scope
changed)`), or a `NOTE:` line, when `--files-from -` meets a completed review, which
stands. Keep the whole block: sections 2, 3 and 4 read it.

Read its exit code here; section 3's rule covers only the phase steps:

- `0`: go on to section 2, which runs the printed steps in order: 1, then 2. When
  it printed `[IMPROVE_CASCADE_NEXT] <command>` and no step (a cascade: `--cascade`
  typed, or a cascade on record that has not finished; or `--force` over such a
  cascade), go to section 2C instead.
- `2` with `[ALREADY_COMPLETE] …`: both steps are done for this review, or (`cascade
  finished at …`) the cascade this command started has finished. Run no phase and go
  to section 4. This is a finished run, not a failure.
- `3` (the `--interactive` refusal, row 15, a live run owning a phase dir, a
  `state.json` or cascade record it cannot read, or `[CASCADE_CONFLICT]`) or `1` (a
  scope it cannot read, or `--files-from -` for a review it would run, or under
  `--cascade`, which no phase launched from here can read): stop before any phase runs.
  Report the error line whole: for `--interactive` it names the two phases to run
  instead, for a live run its `status` and abort commands, for `state.json` or a
  cascade record the file to repair, for a scope the path to fix, for
  `[CASCADE_CONFLICT]` the flag, both values and the two ways out. There is no
  `[IMPROVE_RERUN]` to give: none has been printed (section 3), because nothing ran.

### 2. Run each `run` step, in order

For step 1 and step 2, when its `[IMPROVE_STEP]` line reads `run`: load that phase's
core and run it.

```bash
uv run {UV_RUN_FLAGS} --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" util instructions <phase>
```

`<phase>` is the step's word: `review-code` for step 1, `apply-code-fixes` for step 2.
While you run it:

- **The flags line is the whole choice of flags.** Pass the tokens after the step's
  `[IMPROVE_STEP_FLAGS] <index>`, verbatim (they are already shell-quoted), where the
  core's launch command takes its flags: in place of `--models <selected> [--base-ref
  REF] [--apply-fixes]` in `review-code.md` step 5, and in place of `[options]` in
  `apply-code-fixes.md` step 2. Never pass the marker or the index: either is an extra
  argument, which the phase refuses with exit 3. The tokens replace every model, scope
  or decision flag the core would pick itself, so `review-code.md` step 2 asks nothing
  and adds no model flag. Add nothing to them and drop nothing from them. The command
  keeps the tokens your dispatcher command carries, `--host` among them, which the line
  never holds. The phase core's own recovery steps (row 3's `--force` resume of the
  missing models) still run as that core words them.
- **`[IMPROVE_STEP_FRESH] 1` means skip `review-code.md` step 4, Resume Detection,**
  and nothing else. Its answer describes the previous round (`report` on that round's
  recorded completion, a re-run of its models over its files) and would skip or
  reshape a review that must run. Whatever makes the phase start over is
  already in the flags line.
- **An inner phase's `[NEXT_COMMAND]` block is never an instruction.** Each phase's
  last dispatcher call still prints one: review-code's `--reaggregate` names
  `--apply-code-fixes <plan>`, and the apply's `--mark-completed` names the phase
  after it. Each is that phase's standalone next step. Never run it, and never invoke
  the skill again from it. Move on only by loading the next `run` step's core; only
  section 4's lookup gives the user a next command.
- **Run the core's work, then stop before its report.** Every step that writes a
  file, records state or finishes the phase runs exactly as the core words it.
  Exactly two things are skipped: the core's closing report to the user, and the
  `util next-command` lookup inside it. Section 4 reports once for both phases.

| Phase core | Run | Skip |
| --- | --- | --- |
| `review-code.md` | steps 1–7: model selection from the flags line, the base ref and scope as the flags line gives them, Resume Detection (not on `[IMPROVE_STEP_FRESH] 1`), the detached launch, the roster call and the poll loop, salvage and its reaggregate, validation, `--reaggregate` and its `util metrics finish` | step 8 and the *Post-Fix Workflow*, which run only under `--apply-fixes`, a flag no flags line carries; that workflow's step 6 is the core's report, which section 4 gives instead |
| `apply-code-fixes.md` | steps 1–10: the orchestrator with the flags line, the decision summary, the batch loop, the judge's decisions, step 7's verification, step 8's summary report at `{plan}/apply-fixes/summary.md` with its `util metrics report` and `util report regenerate-decisions` calls, step 9's `## Code Fixes Applied` section in the plan, and step 10's `--mark-completed` once the loop reached its end | the *Then report to the user* paragraph after step 10 |

On a host that adds `--exec-subagents` the apply finishes in its one orchestrator
call, run detached as that core's step 2 says, writing `summary.md` and the decision
badges itself; do not run its native loop a second time. A core that stops early under its own rules
(a partial application, a batch that failed, a failed verification, an interrupted
run) stops there, and section 3 reports the stop.

Keep what the skipped reports would have carried; section 4 gives it: every reviewer
that produced nothing, with its reason; any `[RESULT_FILE_MISNAMED]` or
`[RESULT_SET_ASIDE]` line, as printed; and apply-code-fixes' `[TESTS_NOT_RUN]` line,
whose text after the tag `apply-code-fixes.md` step 7 asks for word for word.

### 2C. A cascade

Section 1 printed `[IMPROVE_CASCADE_NEXT] <command>`, then `[IMPROVE_RERUN] <command>`,
and no step. The command after `[IMPROVE_CASCADE_NEXT]` is the cascade's planner: each
call records where the cascade stands, closes the stage just run, and prints the next
stage's steps 1 and 2, for example:

```text
  [IMPROVE_CASCADE] stage 2 of 3: <the stage's model>
  [IMPROVE_STEP] 1 review-code run (new round, --force)
  [IMPROVE_STEP_FRESH] 1
  [IMPROVE_STEP_FLAGS] 1 --yes --models <the stage's model> --force --rerun-all --cascade-stage-file <path>
  [IMPROVE_STEP] 2 apply-code-fixes run (review not applied yet)
  [IMPROVE_STEP_FLAGS] 2 --yes --agent-decide --no-confirm
  [IMPROVE_CASCADE_CONTINUE] <the command that closes this stage and prints the next>
  [IMPROVE_RERUN] <the command that continues this run, in your host's spelling>
```

(indented here; lines such as `[IMPROVE_CASCADE] new cascade …`,
`[CASCADE_STAGE_SKIPPED] …`, `[AUTO_RESOLVED] …` or `NOTE: …` can come before the
stage line). Run the cascade like this:

1. Run the command after `[IMPROVE_CASCADE_NEXT]` once, exactly as printed. Exits `0`
   and `2` read as section 1's, plus `2` with `[CASCADE_COMPLETE] …`: every stage is
   done, go to item 5. Exit `3` or `1` is a refusal before any phase runs: report the
   error line whole as section 1 says, but section 1's hand-off has already printed an
   `[IMPROVE_RERUN]`, the latest one printed, so end the report with it (section 3).
   When what it printed has no `[IMPROVE_CASCADE_CONTINUE]` line (`--force` without
   `--cascade`: its `NOTE:` line says the cascade was left), the block is a plain one:
   run it as sections 2 and 3 say, as one round, then go to section 4.
2. On exit `0`, run the stage's steps exactly as section 2 says. Sections 2 and 3 apply
   unchanged: the flags lines verbatim (step 1's carries the stage's one model and
   `--cascade-stage-file <path>`, which ties the review round to the stage), inner
   `[NEXT_COMMAND]` blocks ignored, and the stop rules.
3. When the stage's last step is done (section 3), run the command after the latest
   `[IMPROVE_CASCADE_CONTINUE]`, never the `[IMPROVE_CASCADE_NEXT]` command again: that
   one carries the flags the user typed, and with `--force` it would start the cascade
   over. Each call closes the stage it follows and prints the next stage's block
   (item 2), never that stage's again, until one exits `2` with
   `[CASCADE_COMPLETE] <n> stages; table: <path>`. A call that exits `3` (the stage it
   follows did not finish, the last stage's review produced no result, a
   `[CASCADE_CONFLICT]`, an archive it cannot trust) or `1` is a stop: report it as
   section 3 says.
4. One exception to section 3's stop: when a stage's review step exits `3`, run the
   latest `[IMPROVE_CASCADE_CONTINUE]` command once before reporting a stop. If it
   prints `[CASCADE_STAGE_SKIPPED] …` (the stage's one model produced no result, and a
   stage before the last is skipped), go on with the block it printed (item 2).
   Otherwise it exits `3`: report the stop as section 3 says, the review's error line
   and then the call's. Never run that command a second time for the same stop.
5. Then go to section 4. Never end your turn between stages, or between a stage's last
   step and its `[IMPROVE_CASCADE_CONTINUE]` call.

### 3. When a step is done, and when the run stops

A step is done when the last call of its phase's own mode exits `0` or `2`: the
review's `--reaggregate` (or, with no validation owed, the run its poll loop ended
on), and the apply's `--mark-completed` (or, under `--exec-subagents`, the `status` poll
that finds its detached orchestrator call finished), never a `util` call after it.

For steps 1 and 2, on exit `1` or `3`, or when the phase core stopped under its own
rules (row 14):

- report the phase, the plan, the last error line it printed, whole, and the options
  its output names, as you would for that phase run alone;
- when the stop's way forward is an answer to that phase (a `--human-task` answer, or
  a batch recorded with `--skipped`), give it as that phase's own command, exactly as
  the stop names it, alone in its own fenced code block, for example
  `--apply-code-fixes <plan> --resume --human-task apply-fix-batch-3=skip` in your
  host's spelling. `[IMPROVE_RERUN]` holds only the flags the user typed, never an
  answer, so it is the follow-up once that phase is recorded;
- end the report with the latest `[IMPROVE_RERUN]` command printed (by section 1's
  `util improve-steps`, or under a cascade by a `util improve-cascade next` call of
  section 2C, which prints one with each stage's block and with a stop at its stage;
  a call that printed none, a refusal, leaves the one before it the latest), as the
  way to continue once those are dealt with: everything after the marker, alone in
  its own fenced code block, copied character for character, as a `[NEXT_COMMAND]`
  command is.
  It is this run's one next step. The `[NEXT_COMMAND]` blocks the phases printed are
  not (section 2): never give review-code's `--apply-code-fixes <plan>` in its place,
  which is the review's standalone next step, not the way on from a stopped apply;
- never start the next step after a stop, and make no next-step lookup: a stopped
  run has no next phase.

### 4. Report

Report once, for the whole run, with the template below. No Python helper composes
this report on this path, so every number is read from the file the table names, never
recounted from your memory of the run; every host then prints the same numbers. A step
that read `skip` reads the same files, which the run on record left. Paths are under
`{plan}/`:

| Field | File | What to read |
| --- | --- | --- |
| models | `code-review/.status.json` | `models_completed`, and each `models_failed` entry with its reason, out of `models_requested` |
| findings | `code-review/grouped.json` | the number of entries in `groups` |
| valid, invalid, needs human decision, validation failed | `code-review/.status.json` | `validation_counts`. With no such key, a review whose `grouped.json` holds no group prints `0` for each |
| items applied | `apply-fixes/write_tasks.json`, `state.json` | the run's records (below) with status `applied` or `no-op` |
| declined by their batch, skipped at your request | `apply-fixes/write_tasks.json`, `state.json` | the run's records with status `declined` or `skipped`, each with its `details.reason` |
| decided by the judge | `state.json` | the `human_decisions_apply-fixes` entries whose `batch_context.decision_source` is `judge_auto_decide` (approved or skipped, by `decision`) or `judge_auto_decide_salvage` (salvaged); the older `claude_auto_decide` spellings read the same. The judge's raw replies (`apply-fixes/human_decision_batch_*.json`) are not counted |
| items skipped | `apply-fixes/orchestrator_output.json` | `skipped_count`, with `skipped_items` naming each |

The run is the whole apply run, every `--resume` of it included. A native `--resume`
rewrites `write_tasks.json` with only the batches still to run, and `state.json` keeps
the records of earlier runs, so neither the file's batches nor every record is the run:

- **The run's items** are `native_run.items` in `apply-fixes/write_tasks.json` (every
  item the run handed out, carried across its resumes) and the `expected_ids` of its
  `batches`. A file with no `native_run` (an `--exec-subagents` run, whose resume
  keeps every batch in the file) has its batches' `expected_ids` alone.
- **The run's records** are the `processed_apply-fixes` entries (one per item id)
  whose `details.grouped_sha256` equals the batches' `inputs.grouped_sha256`, or, when
  either has none, whose item is one of the run's items. When `native_run.started_at`
  is set, leave out every entry whose `timestamp` is earlier: it is an earlier run's.
- **When `apply-fixes/orchestrator_output.json` holds no batch**, the apply's last
  call handed nothing out, and `write_tasks.json` says why. A file whose
  `native_run.emitted_at` is later than `phases_completed["code-review"]` in
  `state.json` is this review's: that call was a `--resume` that found every batch
  already recorded (the host stopped before `--mark-completed`), so count the run
  from it as above. Otherwise (no `write_tasks.json`, no `native_run`, or one emitted
  before the review last completed, which an earlier review left) this review left
  nothing to apply: count nothing from that file, and an apply phase on record as
  completed prints `0` items applied and no declined or skipped line.

- A field whose file is missing or unreadable prints `not recorded (<path> missing)`,
  never `0` and never a number taken from another file, except as the no-batch rule
  above says.
- An output file that does not exist is listed with `(not written)` after it.

**Under a cascade** (section 2C ran) the report opens with a `### Cascade` section,
before Step 1: the table in the cascade's `summary.md`, copied as written. Never recount
it: each row was counted from that stage's archived files when the stage closed. The
cascade dir is `{plan}/improve-code/` joined with the `dir` that
`{plan}/improve-code/cascade-current.json` names, and `[CASCADE_COMPLETE]` names its
`summary.md`. A stopped cascade's table holds the stages closed so far; with none closed
yet there is no `summary.md`, so say that no stage has closed. The Step sections then
report the last stage that ran, read from the files above as for any run (the phase
dirs hold that stage's round), each heading naming the stage, for example `### Step 1:
Review Code (stage 3 of 3, <model>) — ran`. Output Files adds the cascade's
`summary.md` and `ledger.md` and its `stage-<k>/` dirs.

```markdown
## Improve Code Summary

**Plan**: <the plan path>

[ALREADY_COMPLETE] … (only when section 1 printed it: the line, whole)
[IMPROVE_SCOPE_CHANGED] … or NOTE: … (only when section 1 printed one: the line, whole)

### Cascade — <n> stages (only when section 2C ran)
<the table in summary.md, copied as written>
- Table: <the summary.md path> (`[CASCADE_COMPLETE]`'s, when printed)

### Step 1: Review Code — ran | skipped (<why>)
- Models: <completed> of <requested>; failed: <model> (<reason>), …
- Findings: N
- Valid: N · Invalid: N · Needs human decision: N · Validation failed: N
- [RESULT_FILE_MISNAMED] / [RESULT_SET_ASIDE] lines, as printed (only when any)

### Step 2: Apply Code Fixes — ran | skipped (<why>)
- Items applied: N
- Declined by their batch (not applied): N — <id> (<reason>), … (only when any)
- Skipped at your request (not applied): N — <id>, … (only when any)
- Decided by the judge: N (A approved, V salvaged, S skipped)
- Items skipped: N — <title> (<status>), …
- Tests: what apply-code-fixes.md step 7 says to report ([TESTS_NOT_RUN]'s text, word for word)

### Output Files
- {plan}/code-review/report.html
- {plan}/apply-fixes/summary.md
- each file `tracked_files` in {plan}/state.json names
- <the cascade dir>/summary.md, <the cascade dir>/ledger.md and its stage-1/ … stage-<n>/ dirs (only when section 2C ran)

### State
- State file: {plan}/state.json

### Next Steps
- (the section the lookup below prints)
```

Then get the next step, after every other command, on every host:

```bash
uv run {UV_RUN_FLAGS} --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" util next-command "$PLAN_PATH" --after improve-code --host <host-id>
```

`--after improve-code` is this mode's own word: the lookup walks on from the apply,
normally to "Workflow complete." with any manual tasks still owed. `<host-id>` is
section 1's; the lookup takes no other token of your dispatcher command (it refuses
`--yes` and `--exec-subagents`). This lookup is the run's one source of a next step:
the blocks the inner phases printed are not this run's. End the report with its
block, as the `### Next Steps` rule in `references/summary-format.md` says.
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: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated 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: 319kUpdated 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: 319kUpdated Claude CodeCodexVerifiedInstall