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
#!/usr/bin/env python3
"""The single owner of the multi-llm mode table.

Every surface that enumerates modes is *rendered* from ``MODES`` rather than
hand-maintained: ``multi_llm.py --help``, ``SKILL.md``'s ``argument-hint`` line,
``check_workflow_prerequisites.py``'s ``--mode``/``--phase`` vocabulary and (with
a later change) each host shim's flag list. Adding a mode is a row here, never an
edit in twelve places, and ``tests/test_instruction_portability.py`` fails if the
dispatcher and ``argument-hint`` disagree.

Three vocabularies meet in this table and are deliberately kept distinct:

* **mode word** — what ``multi_llm.py`` takes as ``argv[1]`` (``review-code``).
* **user flag** — what a user types at the skill (``--review-code``). The mapping
  is mechanical: strip the leading ``--``, verify membership. No shim invents it.
* **phase** — the ``state.json`` / phase-dir name (``code-review``). It differs
  from the mode word for exactly one mode, which is why ``code-review`` is also a
  dispatcher alias.

Nothing here imports an orchestrator: ``target_module`` is a dotted path the
dispatcher resolves lazily, so ``import modes`` never drags in the ~9k lines of
orchestrator code just to list mode names.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Dict, Optional, Tuple

# Positional kinds a mode can declare, in the order they must appear.
POS_PLAN = "<plan>"
POS_QUESTION = "<question>"
POS_HOST = "<host>"
#: The commit modes' range. Spelled in square
#: brackets because, unlike the three kinds above, it is optional: no words
#: means ``HEAD``. It is also the only kind that spans several bare words, so
#: ``--review-commits last 2 commits`` needs no quotes: the dispatcher joins
#: every leading bare word into the one value (a ``-N`` word included) and
#: hands it on as ``--revs``, or as ``--plan-file`` when it is one commit
#: brief's path (``multi_llm._normalize_positionals``). ``--help`` and the
#: package surfaces render the spelling as it is written here.
POS_REVS = "[<range>]"


@dataclass(frozen=True)
class Mode:
    """One row of the dispatch table.

    Attributes:
        name: The mode word (``argv[1]``).
        positionals: Positional kinds, in order. Normalized by the dispatcher
            into the flags the target's own argparse parser already accepts.
            :data:`POS_REVS` is the one kind that is optional and joins every
            leading bare word into its one value.
        summary: One-line ``--help`` text.
        target_module: Dotted module path, imported lazily. ``None`` for modes
            whose implementation has not landed yet.
        target_attr: Callable attribute on that module, called as
            ``main(argv) -> int``.
        phase: ``state.json`` / phase-dir name, or ``None`` for modes that own no
            phase (``status``, ``init``, the install modes). A composite's
            (``full``) names its run dir only, for ``--detach``'s lock, log and
            ``run`` record; it records no phase of its own.
        instruction_file: Core instruction file under ``instructions/``, served
            token-free by ``multi_llm.py util instructions <mode>``.
        user_facing: True for the modes that appear in ``SKILL.md``'s
            ``argument-hint`` as ``--<name>``.
        is_workflow_phase: True for the eight phases
            ``check_workflow_prerequisites.py`` gates on.
        supports_detach: True for the modes ``--detach`` covers: the fan-out modes
            plus, since the write executor landed, every executor-backed mode
            (``implement``, the three apply phases, ``generate-tasks``, ``full``) —
            a write phase that schedules N batches through real agent CLIs outlives
            a host's shell cap exactly as a fan-out does. A mode with ``False``
            **rejects** ``--detach`` with exit 3 rather than accepting a flag that
            silently does nothing. ``generate-tasks`` and ``full`` carried the
            column before their orchestrators existed, so the gate a shim saw was
            already the final one; now that both are Python, the detach path they
            registered for is the one that actually runs.
        injected_flags: Flags the dispatcher prepends before the user's, because
            the mode is a thin view over a more general script.
        requires_uv: Whether the dispatcher runs D6c's layer-3 ``uv`` backstop
            before dispatching. True for every mode that *does* work, because a
            missing ``uv`` means nothing can run. False for exactly the two
            install modes: ``install-host --check`` **is** layer 1 of the same
            bootstrap and reports a missing ``uv`` as one of its five assertions,
            so failing at the backstop would replace a five-row prerequisite
            report with a one-line refusal — and ``uninstall-host`` has to work on
            a machine whose ``uv`` is already gone.
        unavailable: When set, the mode is dispatchable but exits 3 with this
            reason instead of running. Keeps the boundary a shim sees stable
            while the implementation is still a markdown sequence.
        runs_workflow: True for the mode that runs the whole workflow
            (``full``). Narrower than :attr:`is_composite`: a composite that
            runs two phases runs other modes but not the workflow. Read only
            where "the whole workflow" is the point, the next step a finished
            ``full`` falls back to (``suggested_next``), since it has no single
            next phase of its own. A reader that means "a mode that runs other
            modes" reads :attr:`is_composite`.
        sequence: The mode words a composite runs, in order, each through its
            own ``main(argv)``; empty on every other row. Mode words, and no
            reader uses them raw: :attr:`sequence_phases` gives the
            ``state.json`` phase words (``review-code`` → ``code-review``),
            :attr:`last_phase` the one it ends on, and ``utils/detach.py`` maps
            each phase through ``output_handler.PHASE_DIRECTORIES`` for the
            on-disk dir (``apply-code-fixes`` → ``apply-fixes``), which stays out
            of this module because ``output_handler`` imports it. Data rather
            than a name check, so a package's generated surface derives a
            composite's ``writes_worktree`` from the phases it runs, and a
            stopped composite retires the maps of exactly the phases it drove,
            without a list in a host layer or a mode word in ``detach``.
        optional_why: The generic reason an *optional* phase is offered before
            the next required one, shown beside its command in a finished
            phase's next-step block (``user_next_step.optional_before[].why``).
            Set on exactly the rows whose phase is in
            ``check_workflow_prerequisites.OPTIONAL_PHASES`` and ``None`` on
            every other row; ``utils/next_phase.py`` holds no prose of its own.
            A sentence that reads after the host's own "Optional, before
            that:" label, saying what the step does and what skipping it
            means, never one that starts "optional" itself (a
            host printed "Optional, before that: optional: have the models
            review…").
        commit_view_of: The phase mode a commit front door fronts
            ``review-code`` on
            ``review-commits``, ``apply-code-fixes`` on ``apply-commit-fixes``.
            Such a front door resolves its range to a commit brief, then
            re-records the invocation as that mode and calls its ``main``, so
            every run record, resume line and next step of the review names
            the fronted mode. This column is the one owner of the mapping
            back: wherever a command is rendered for a brief whose
            ``state.json`` holds ``commit_range``, the fronted word is spelled
            as the row that names it here. ``None`` on every other row,
            ``improve-commits`` included: that composite is recorded as
            itself (its own run dir, ``--mode improve-commits``) and never as
            ``improve-code``, so nothing maps back for it, and its steps come
            from its own ``sequence``.
    """

    name: str
    positionals: Tuple[str, ...]
    summary: str
    target_module: Optional[str] = None
    target_attr: str = "main"
    phase: Optional[str] = None
    instruction_file: Optional[str] = None
    user_facing: bool = True
    is_workflow_phase: bool = False
    supports_detach: bool = False
    injected_flags: Tuple[str, ...] = ()
    requires_uv: bool = True
    unavailable: Optional[str] = None
    runs_workflow: bool = False
    sequence: Tuple[str, ...] = ()
    optional_why: Optional[str] = None
    commit_view_of: Optional[str] = None

    @property
    def is_composite(self) -> bool:
        """True for a mode that runs other modes (``sequence`` is set)."""
        return bool(self.sequence)

    @property
    def sequence_phases(self) -> Tuple[str, ...]:
        """``sequence`` as ``state.json`` phase words, in order.

        Resolved at call time, never stored: a row is a frozen dataclass built
        inside ``MODES``, so it cannot read the table it sits in. A word that
        resolves to no phase is a table bug, and raises rather than hand a
        reader ``None`` to use as a phase or a directory name.
        """
        phases = []
        for word in self.sequence:
            phase = phase_for(word)
            if phase is None:
                raise ValueError(
                    f"modes.py row {self.name!r}: sequence word {word!r} "
                    "resolves to no phase"
                )
            phases.append(phase)
        return tuple(phases)

    @property
    def last_phase(self) -> Optional[str]:
        """The phase a composite ends on; ``None`` for a mode that runs no other."""
        phases = self.sequence_phases
        return phases[-1] if phases else None


# Reason strings for the modes that are dispatchable but not yet implemented.
# Kept as constants so the dispatcher's exit-3 text and the tests agree.
#
# Why they are in the table at all: **every mode word is invocable through
# multi_llm.py on every host from day one**, even where the implementation behind
# it is still a markdown sequence. "Instruction-only" describes an
# implementation, never the dispatcher boundary a shim sees — otherwise every
# non-Claude shim has to special-case the remainder and re-derive a
# Claude-authored instruction sequence, which is the coupling the dispatcher
# exists to delete. The dispatcher makes the "not yet here" call, so no shim
# carries a host-specific fallback.
#
# `generate-tasks` and `full` used to sit here: both are now Python
# (`generate_tasks_orchestrator.py`, `full_workflow_orchestrator.py`), so the two
# instruction-only rows are gone and their markdown is narrative only. So did
# `install-host`/`uninstall-host`, until `utils/host_install.py` landed the D7
# install contract; **no mode is unavailable today**, and the constant survives as
# the documented shape of an honest gap rather than as a live reason string.
NOT_YET_AVAILABLE = "not yet available"


# Order is the workflow order, and it is also the order rendered into
# SKILL.md's `argument-hint` line — keep them in sync by rendering, never by
# copying (see render_argument_hint).
MODES: Tuple[Mode, ...] = (
    Mode(
        name="review-plan",
        positionals=(POS_PLAN,),
        summary="Review a plan with every configured model, then group + validate.",
        target_module="review_plan_orchestrator",
        phase="review-plan",
        instruction_file="review-plan.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="apply-suggestions",
        positionals=(POS_PLAN,),
        summary="Prepare the validated plan-review suggestions for application.",
        target_module="apply_suggestions_orchestrator",
        phase="apply-suggestions",
        instruction_file="apply-suggestions.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="improve-plan",
        positionals=(POS_PLAN,),
        summary="Review the plan with every model, then apply the validated "
                "suggestions to it (unattended).",
        target_module="improve_plan_orchestrator",
        phase="improve-plan",          # run dir only, as `full`
        instruction_file="improve-plan.md",
        supports_detach=True,
        sequence=("review-plan", "apply-suggestions"),
    ),
    Mode(
        name="generate-tasks",
        positionals=(POS_PLAN,),
        summary="Decompose the plan into an implementable task list.",
        target_module="generate_tasks_orchestrator",
        phase="generate-tasks",
        instruction_file="generate-tasks.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="review-tasks",
        positionals=(POS_PLAN,),
        summary="Review the generated task list with every configured model.",
        target_module="review_tasks_orchestrator",
        phase="review-tasks",
        instruction_file="review-tasks.md",
        is_workflow_phase=True,
        supports_detach=True,
        optional_why=(
            "Have the models review the task list before implementing it; "
            "skipping this implements the tasks as they were generated."
        ),
    ),
    Mode(
        name="apply-task-suggestions",
        positionals=(POS_PLAN,),
        summary="Prepare the validated task-review suggestions for application.",
        target_module="apply_task_suggestions_orchestrator",
        phase="apply-task-suggestions",
        instruction_file="apply-task-suggestions.md",
        is_workflow_phase=True,
        supports_detach=True,
        optional_why=(
            "Apply the task-review suggestions to the task list before "
            "implementing it; skipping this implements the task list as it stands."
        ),
    ),
    Mode(
        name="implement",
        positionals=(POS_PLAN,),
        summary="Batch the tasks for implementation and track progress.",
        target_module="implement_orchestrator",
        phase="implement",
        instruction_file="implement.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="review-code",
        positionals=(POS_PLAN,),
        summary="Review the working diff against the plan with every model.",
        target_module="code_review_orchestrator",
        phase="code-review",
        instruction_file="review-code.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="apply-code-fixes",
        positionals=(POS_PLAN,),
        summary="Prepare the validated code-review fixes for application.",
        target_module="apply_code_fixes_orchestrator",
        phase="apply-code-fixes",
        instruction_file="apply-code-fixes.md",
        is_workflow_phase=True,
        supports_detach=True,
    ),
    Mode(
        name="improve-code",
        positionals=(POS_PLAN,),
        summary="Review the code changes with every model, then apply the "
                "validated fixes (unattended).",
        target_module="improve_code_orchestrator",
        phase="improve-code",
        instruction_file="improve-code.md",
        supports_detach=True,
        sequence=("review-code", "apply-code-fixes"),
    ),
    # The three commit modes: front doors that
    # resolve a commit range to a commit brief and run the code phases on it.
    # None is a workflow phase, so `full` never runs them and `full.sequence`
    # stays the workflow rows. Each core runs its front door (or, natively on
    # improve-commits, `util commit-brief`) and then loads the code phase cores
    # it fronts with `util instructions <phase>`, so validation, reaggregate and
    # the report stay single-sourced.
    Mode(
        name="review-commits",
        positionals=(POS_REVS,),
        summary="Review a commit range (HEAD by default) with every model, "
                "then group + validate.",
        target_module="review_commits_orchestrator",
        # The fronted phase: the run is review-code's on the commit brief.
        phase="code-review",
        instruction_file="review-commits.md",
        supports_detach=True,
        commit_view_of="review-code",
    ),
    Mode(
        name="apply-commit-fixes",
        positionals=(POS_REVS,),
        summary="Apply a commit review's validated fixes as uncommitted edits.",
        target_module="apply_commit_fixes_orchestrator",
        phase="apply-code-fixes",
        instruction_file="apply-commit-fixes.md",
        supports_detach=True,
        commit_view_of="apply-code-fixes",
    ),
    Mode(
        name="improve-commits",
        positionals=(POS_REVS,),
        summary="Review a commit range with every model, then apply the "
                "validated fixes (unattended).",
        target_module="improve_commits_orchestrator",
        phase="improve-commits",       # run dir only, as `improve-code`
        instruction_file="improve-commits.md",
        supports_detach=True,
        # The code words: every sequence word is a workflow-phase row.
        sequence=("review-code", "apply-code-fixes"),
    ),
    Mode(
        name="full",
        positionals=(POS_PLAN,),
        summary="Run the whole plan-to-code workflow as one resumable sequence.",
        target_module="full_workflow_orchestrator",
        # `full` owns no *workflow* phase (every phase it runs records its own
        # completion), but it does own a run dir: `--detach` needs somewhere for
        # `.status.json`, the log and the lock, and `status --phase full` has to
        # resolve through this same table rather than through a second vocabulary.
        phase="full",
        instruction_file="full-workflow.md",
        supports_detach=True,
        runs_workflow=True,
        # The eight workflow mode words, in `PREREQUISITE_PHASES` order, as a
        # literal: the row cannot derive them from the table it sits in.
        # `tests/test_mode_sequence.py` holds it to the `is_workflow_phase`
        # rows and to `FullWorkflow.steps()`.
        sequence=(
            "review-plan", "apply-suggestions", "generate-tasks", "review-tasks",
            "apply-task-suggestions", "implement", "review-code",
            "apply-code-fixes",
        ),
    ),
    Mode(
        name="ask",
        positionals=(POS_PLAN, POS_QUESTION),
        summary="Ask every configured model one free-text question about a plan.",
        target_module="ask_orchestrator",
        phase="ask",
        instruction_file="ask.md",
        supports_detach=True,
    ),
    Mode(
        name="status",
        positionals=(POS_PLAN,),
        summary="Report workflow phases (state.json) and detached runs "
                "({phase}/.status.json).",
        # Two views over two files behind one command word. The predecessor was
        # an instruction-only mode word whose markdown wrapper shelled out to
        # `check_workflow_prerequisites.py --status`; that function survives as
        # the workflow view's implementation (still directly callable, still
        # byte-identical under `--view workflow --json`), but the mode itself is
        # Python now, because a detached run with no command to poll it is
        # unusable.
        target_module="utils.run_status",
        instruction_file=None,
    ),
    Mode(
        name="doctor",
        positionals=(),
        summary="Check every configured provider CLI on this machine: present, "
                "version, auth, sandbox. No model calls; exit 0 or 3.",
        # D6 step 5. The one mode allowed to spawn provider CLIs outside a
        # phase — and only their model-free probes (`--version`, the declared
        # `auth_check`, the sandbox self-test). No lock, no phase dir, no
        # instruction file: like `status`, its flags are the whole interface.
        # Not user-facing: it is what the Claude Code plugin's SessionStart
        # hook runs (`hooks/hooks.json`, `--warn-only`) and what a user runs
        # by hand after a refusal names it — not a workflow flag.
        target_module="utils.doctor",
        instruction_file=None,
        user_facing=False,
    ),
    Mode(
        name="init",
        positionals=(),
        summary="Scaffold a per-project .multi-llm/providers.yaml override.",
        target_module="init_config",
        instruction_file="init-config.md",
    ),
    # Not user-facing: neither is part of the skill's own argument surface, so
    # neither gets a `--flag` in `argument-hint`.
    Mode(
        name="install-host",
        positionals=(POS_HOST,),
        summary="Install this skill's entry shim into another coding harness.",
        target_module="utils.host_install",
        target_attr="main",
        user_facing=False,
        requires_uv=False,
    ),
    Mode(
        name="uninstall-host",
        positionals=(POS_HOST,),
        summary="Remove a previously installed host shim.",
        target_module="utils.host_install",
        target_attr="uninstall_main",
        user_facing=False,
        requires_uv=False,
    ),
)


# A closed alias table, shown in `--help`. No prefix or fuzzy matching: an
# unrecognized word is an error, not a guess.
ALIASES: Dict[str, str] = {
    "review": "review-plan",
    "code-review": "review-code",
    "tasks": "generate-tasks",
    # Stopping a detached run has to be discoverable, so the verb is an alias
    # like any other — the only one that expands to a mode word *plus a flag*
    # (see ALIAS_FLAGS). Aliases are a human convenience: generated shims always
    # emit the `status … --abort` spelling so their text stays on one surface.
    "abort": "status",
    "cancel": "status",
    "stop": "status",
}


# The flags an alias contributes on top of its target mode, prepended before the
# user's own. Carried here so `--help` renders the expansion and nothing else
# re-derives it.
ALIAS_FLAGS: Dict[str, Tuple[str, ...]] = {
    "abort": ("--abort",),
    "cancel": ("--abort",),
    "stop": ("--abort",),
}


def alias_flags(word: str) -> Tuple[str, ...]:
    """Flags the dispatcher must inject for *word*, if it is a flag-bearing alias."""
    return ALIAS_FLAGS.get(word, ())


def alias_expansion(word: str) -> str:
    """How `--help` spells an alias: ``abort -> status --abort``."""
    target = ALIASES[word]
    extra = " ".join(ALIAS_FLAGS.get(word, ()))
    return f"{target} {extra}".rstrip()


#: The mode a bare argument text resolves to when it carries no mode flag.
#: **The single owner of "no mode flag means review-plan".** That sentence used
#: to be prose in two hand-written places (``SKILL.md`` and
#: ``hosts/opencode/shim.md.tmpl``) with no constant behind either, held together
#: only by ``tests/test_shim_correctness.py``. The npm plugin route would have
#: made a third copy inside a tool description, so the rule became a constant and
#: every surface now renders from it: ``dist/cli-surface.json`` (what the
#: model-facing tool definition is assembled from), and both places every shim
#: template states it — its step-2 prose and its worked example — through
#: ``cli_common.DEFAULT_MODE_PLACEHOLDER``.
#:
#: One surface cannot render, and is pinned instead: Claude Code's ``SKILL.md`` is
#: ``installable: false`` and is read by the host verbatim (it expands
#: ``${CLAUDE_SKILL_DIR}`` itself at load time), so nothing substitutes a token
#: there. Its two sentences are literals held to this constant by
#: ``test_default_mode_has_one_owner``, which asserts all three surfaces together
#: — the guard is what makes the claim above a property rather than an intention.
DEFAULT_MODE = "review-plan"


#: The model-callable tool's registration name on every package route — the
#: OpenCode plugin's ``tool`` hook key and the codex MCP server's ``tools/list``
#: entry. One owner, because it is also what every re-attach and abort
#: ``{tool, args}`` object the plugin hands back names, and two hosts spelling
#: it twice is two chances for a continuation to point at a tool that does not
#: exist. Emitted as the surface's ``tool_name``.
TOOL_NAME = "multi_llm"

#: The two literal values the tool description's worked examples fill in. The
#: examples themselves are *selected by shape* from the table (rule f) — the
#: default mode, a mode with no positional, a mode taking a question, an alias
#: carrying a flag — so these are the only written words in them.
EXAMPLE_PLAN_PATH = "plans/x.md"
EXAMPLE_QUESTION = "Why is the ceiling 120 s?"

#: The one authored sentence in the OpenCode plugin's model-facing tool
#: definition. It lives here rather than in JavaScript for the same reason the uv
#: preflight message lives in ``hosts/uv-missing.txt``: the plugin holds no prose
#: of its own, so everything it shows a model is generated from this tree
#: (D7.2). Everything *else* in that definition — the mode lines, the argument
#: descriptions, the reserved-flag rules — is derived from the table above, so
#: this is the only string a human writes.
#:
#: It carries the one thing no generated line can: that the tool is the *only*
#: way to run multi-llm on that host, and that its dispatcher must not be reached
#: through ``bash``.
TOOL_DESCRIPTION_LEDE = (
    "Run a multi-LLM workflow over a plan file. This tool is the only supported "
    "way to run multi-llm on this host: never invoke multi_llm.py, uv run or any "
    "dispatcher command through bash, because the flags this host requires are "
    "appended here and a shell invocation reaches none of them."
)

#: The lede's sibling: one line that names the four exit codes and the decision
#: exit 3 carries. A sibling rather than a clause folded into the lede, so the
#: two strings with two jobs stay separately assertable (the lede is pinned by
#: identity and by ``startswith``; this one by ``contains``). It is rendered
#: into the tool description after the mode block, so a model meets it in the
#: same glance as the modes. The four numbers are ``cli_common.EXIT_*``, held
#: to this line by a test rather than by an import: this module imports nothing
#: by design. "report" is the
#: result's ``error`` line whole — the stop's what, reported and not-run text
#: and whether anything ran the tests — beside the commands the result names.
TOOL_OUTCOMES_LINE = (
    "Exit codes: 0 done · 1 error · 2 nothing to do · 3 needs a human: stop, "
    "report its `error` line whole, do not do the phase's work."
)

#: How a host prints a ready section (``user_next_step.markdown``, a stop's
#: ``resume_markdown``, Claude Code's ``[NEXT_STEP_MARKDOWN]`` section), said
#: once here and word for word on every route. The relay surfaces carry it as a
#: literal, held to this constant by ``tests/test_relay_says_it_once.py``.
READY_SECTION_RULE = (
    "Copy it word for word, never wrapped in a fenced block of your own (its "
    "commands are fenced already), and say none of it twice: its whys, notes, "
    "manual tasks and \"Workflow complete.\" appear only in it, never above it."
)

#: The outcomes line's second sibling: what
#: ``user_next_step`` in a result is, said in the tool description a model reads
#: before any result. Lifting that key to a tool result's top level puts it next
#: to ``next``, which the same model is taught to treat as a call — so the
#: description says, once, that this one is the user's to type and never a call.
#: Rendered after :data:`TOOL_OUTCOMES_LINE` on both package hosts; neither
#: server authors the string. "Only then" / "never otherwise": on OpenCode racing run 4,
#: phase 06, the host ended an implement result
#: whose `command` named review-code, and whose notice listed the manual tasks
#: left, with "Workflow complete. Manual tasks left …". A command answer carries
#: `manual_tasks` and its note too,
#: and the line says to relay them on any result — the hosts named T009 from
#: the notice but never the command that records it done. It
#: said "which no phase will run" of every entry, while a task skipped with a
#: manual one (`waits_on`) runs on the resume the note names. The `command` first and
#: each optional entry after it with its
#: `why`, and the note as prose. The key carries the section already written, each command fenced
#: (`next_phase.render_next_step_markdown`), and the line says to copy it.
#: Its words and order, no caption, and the words never the host's own;
#: a stop's `resume_markdown` is copied the same way.
#: Codex 04/06/08 and OpenCode 03-08 wrote the
#: notice or the manual note above the copied section, OpenCode 08 opened a
#: fence of its own around it, the OpenCode decline run printed "Workflow
#: complete." twice (plain, then fenced), Codex 06 reworded the manual
#: note and OpenCode's stops added a recap and their own list of options
#: before `resume_markdown`: :data:`READY_SECTION_RULE`, and the stop's
#: section stands in place of any list of the host's own.
TOOL_USER_NEXT_STEP_LINE = (
    "`user_next_step` in a result is a command for the user to type, never a "
    "call to make: end your report with its `markdown`, copied as it is (its "
    "words and order, each command alone in its fenced block, each why and "
    "note plain text, the manual tasks it lists included, no caption of your "
    "own), then stop. " + READY_SECTION_RULE + " It says \"Workflow complete.\" only "
    "when it is `complete`: never write those words yourself, even when a "
    "notice lists manual tasks left for the user. Only `next` is a call. At a "
    "stop, `resume_markdown` is the same kind of thing: copy it the same way, "
    "in place of any list, recap or summary of the options or ways forward of "
    "your own, its commands (`resume_command` among them) the user's to type, "
    "never a call."
)

#: Where a finished run's notice goes.
#: The notice no longer carries what that section says (``run_status``); the
#: relay surfaces say so too, word for word.
NOTICE_PLACEMENT = (
    "Put it above the closing section, and repeat nothing that section says."
)

#: The finished run's relay: a completed
#: apply-code-fixes result carried, in `result.notice`, that nothing ran the
#: repository's tests and that two invalid fixes were not applied, and the host
#: relayed neither: no route's text named the key. The stop's own line is the
#: result's `error` (:data:`TOOL_OUTCOMES_LINE`); this is the other half.
#: Rendered after :data:`TOOL_NO_COMPOSED_COMMAND_LINE` on both package hosts.
TOOL_NOTICE_LINE = (
    "A finished run's `result` can carry a `notice`: what the run left out or "
    "could not check, such as items it did not apply or that nothing ran this "
    "repository's tests. Report what it says, every part of it, as plain text "
    "outside any fenced block. " + NOTICE_PLACEMENT
)

#: What a host does with a commit mode's blocks on a tool route. The CLI prints the commit block
#: (and ``[COMMIT_FIXES]`` on an apply) before any model runs, and the cores
#: relay them verbatim and once; both servers lift those lines out of the
#: output into one ``commit_blocks`` string, so the tool description has to say
#: the same thing the cores say.
TOOL_COMMIT_BLOCKS_LINE = (
    "A commit mode's result (review-commits, apply-commit-fixes, "
    "improve-commits) can carry `commit_blocks`: the commits the run acts on, "
    "and on an apply the fixes it will apply and skip. Relay it verbatim and "
    "once, as soon as you read it, before anything else from the result."
)

#: What every host does with the write policy at a stop. Round 18 told hosts
#: never to suggest loosening ``driver.write_paths`` after a Claude Code host
#: offered "remove the deny rule" on its own, while the plugin's own stop line
#: offered allowing the file, which hosts are told to relay whole. The plugin
#: keeps offering it, worded as the user's own call
#: (``write_safety.policy_allow_clause``), since it is theirs to decide and it
#: lets the run complete; a host relays it as given, adds no policy advice of
#: its own and never edits the setting itself. The change is
#: worded per rule (a deny hit names the deny rule to narrow, since the deny
#: list wins over ``allow``), so the rule names both kinds. Rendered into
#: :data:`NEEDS_HUMAN_RULE` (every file route, both plugin instructions and
#: Claude Code's ``SKILL.md``), :data:`TOOL_NO_COMPOSED_COMMAND_LINE` (both
#: tool descriptions) and :data:`NEEDS_HUMAN_MESSAGE` (the tool routes'
#: exit-3 message), and held word for word in implement's stop rule.
STOP_POLICY_RULE = (
    "Never edit `driver.write_paths`, or any other multi-llm setting in "
    "`.multi-llm/providers.yaml`, yourself. At a stop, offer only the ways "
    "forward the stop itself names, as it words them: when it names a change "
    "to `driver.write_paths` that lets a refused file be written (adding it to "
    "`allow`, or removing or narrowing a deny rule that covers it), that is "
    "one of them and the user's call; add no advice about the write policy of "
    "your own."
)

#: The user-next-step line's sibling (racing re-run 2026-10-04): after a failed
#: generate-tasks whose result carried no command at all, an OpenCode host model
#: printed a "next phase" it composed itself, in the tool-call spelling
#: (``multi_llm --mode review-tasks --plan …``) and for a phase a failed run
#: does not lead to. The line above says what the two command keys are; this
#: one says they are the only commands, and what a result carrying neither
#: means — every failed or needs-human result now says so explicitly, with
#: ``user_next_step: null`` and :data:`NO_COMMAND_REASON`. Rendered directly
#: after :data:`TOOL_USER_NEXT_STEP_LINE` on both package hosts. A host offered "remove the deny
#: rule" as a way past a task the write policy refused. It ends
#: with :data:`STOP_POLICY_RULE` instead of "never suggest loosening".
TOOL_NO_COMPOSED_COMMAND_LINE = (
    "Never compose a command for the user yourself, and never spell one from "
    "this tool's arguments: the only commands you may give them are the ones "
    "in `user_next_step`, `resume_command` and each `resume_answers` "
    "command, each copied verbatim. "
    "A result whose `user_next_step` is "
    "null and that carries no `resume_command` has no command to give "
    "(`no_command_reason` says why): name no command and no next phase. "
    + STOP_POLICY_RULE
)

#: The value of ``no_command_reason``, the key both package servers set beside
#: ``user_next_step: null`` on a failed or needs-human result that carries no
#: ``resume_command`` (the explicit "there is nothing to type" the line above
#: refers to). Read off the surface; a server whose surface lacks it still
#: sets ``user_next_step: null`` and simply omits the sentence.
NO_COMMAND_REASON = (
    "There is no command for the user to type: this phase did not finish, so no "
    "next phase follows it, and nothing names a re-run that would get past this "
    "stop as it stands. Report what happened and what its error names; do not "
    "compose a command."
)

#: The title the OpenCode package puts on its tool part when a call ends at a
#: stop (``tool.execute.after``). ``opencode run`` prints a
#: plugin tool's title on the tool's own line (the TUI's header reads it too,
#: not measured) as soon as the call returns and whether or not the session's model ever
#: writes its reply: OpenCode racing run 6's free model never did (28 min
#: idle), and the stop and its resume command were only in the tool output.
#: ``{line}`` is the run's own last error line (``result.error``, the line
#: the exit-3 ``message`` quotes) or ``no_line``; ``resume`` is appended,
#: ``{command}`` filled with ``resume_command``, when the result carries one.
#: ``{line}`` is shown without control characters and cut at
#: ``max_line`` characters, ending in ``cut``; the command is never cut.
#: By ``utils.text_clip.clip``'s rule (a word boundary, no
#: separator before ``cut``, a bracket the kept part opened closed after it).
STOP_TITLE = {
    "template": "stopped and needs you: {line}",
    "no_line": "the run did not finish; the tool output says why.",
    "resume": " Resume with: {command}",
    "max_line": 300,
    "cut": "…",
}

#: The route signal's one owner. The package routes' tool servers set ``ROUTE_ENV`` in every child
#: env they spawn (polls included) to their surface's
#: ``dispatcher.route_env.value``, which the surface generator picks from
#: ``TOOL_ROUTES`` — so neither server spells the name or the value. It picks
#: only the spelling a printed next-phase command uses, never which phases run
#: (D6b). ``utils.next_phase.resolve_route`` is the one reader, and it honours
#: a value only when it is a member of ``TOOL_ROUTES`` **and** the resolved host
#: carries a ``next_command`` cell for it. It is owned by the tool servers, not
#: a user setting. ``package`` is the route key ``hosts/capabilities.yaml``
#: already gives each host's distribution route, whatever the host calls it.
ROUTE_ENV = "MULTI_LLM_ROUTE"
TOOL_ROUTES: Tuple[str, ...] = ("package",)

#: The one sentence every needs-human surface shares, and the one the incident
#: turned on: an agent whose tool has just told it the run is blocked has no
#: sentence anywhere telling it not to do the work by hand. Composed into
#: :data:`NEEDS_HUMAN_RULE` (the file routes and the plugin's command body) and
#: into :data:`NEEDS_HUMAN_MESSAGE` (the plugin's exit-3 result), so the two
#: cannot say it differently.
NEEDS_HUMAN_WORK_SENTENCE = (
    "Do not perform the work this run was going to review, plan, or implement: "
    "doing it yourself is never a substitute for a failed run."
)

#: The decision rule for exit 3, authored once. Every instruction surface a
#: supported route loads renders it: both ``hosts/*/shim.md.tmpl``, the
#: opencode plugin's ``hosts/opencode/plugin-command.md.tmpl`` and the codex
#: plugin's ``hosts/codex/plugin-skill.md.tmpl`` through
#: ``cli_common.NEEDS_HUMAN_RULE_PLACEHOLDER``, and Claude Code's ``SKILL.md`` — read
#: verbatim by its host, so nothing substitutes a token there — as a literal
#: held to this constant by ``test_needs_human_rule_has_one_owner``, the same
#: shape :data:`DEFAULT_MODE` uses. It also owns the ``next`` clause, because
#: ``next`` and the plugin's ``options`` are one object under two names: on
#: ``0`` and ``2`` it runs verbatim, on ``3`` it is reported and waits for the
#: user. "Run verbatim" is the command-string wording the file routes and
#: Claude Code need; on the codex plugin route ``next`` is re-spelled as the
#: tool's arguments object (D3c) and is never a shell command, so that
#: template follows this token with its own line saying "run" means calling
#: the tool again with ``next`` as its arguments. The gloss lives in the
#: template, not here, so this constant — and the ``SKILL.md`` literal held
#: to it — keep one wording. Four hand-typed paraphrases of this rule are
#: exactly how two hosts come to contradict each other on the behaviour an
#: incident hinges on. It asked for "what was being run", which
#: on a file route is the dispatcher command with the flags the shim composed
#: (the needs-human message's `argv`, run-7 #13); it asks for the phase and
#: the plan. "which phase was running" came back as "Phase
#: running: implement" for a phase that had stopped.
#: "Or commit range" (commit modes' live run, 2026-10-26): a commit mode's
#: refusal before any phase (`[RANGE_DIVERGED]`) has a range and no plan, and
#: OpenCode reported "on which plan" all the same.
NEEDS_HUMAN_RULE = (
    "Run `next` verbatim when it is not `null` on `0` and `2`. On `3` stop: "
    "report to the user which phase stopped, on which plan or commit range, "
    "the last error line it printed, "
    "whole (on a stop it says what stopped, what it reported, what did not "
    "run and whether anything ran the repository's tests), "
    "and the options its output names (`next` included); do not run a "
    "different mode. " + NEEDS_HUMAN_WORK_SENTENCE + " Run an option only "
    "after the user has picked it. " + STOP_POLICY_RULE
)

#: The plugin's exit-3 ``message``, as a **template**: the JS selects a clause
#: for each token and substitutes, and authors no wording of its own — not even
#: a fallback. ``{phase}`` and ``{error}`` are literal tokens here (nothing in
#: Python ``%``- or ``.format``-expands them); the clause alternatives below are
#: what the plugin fills them with, chosen by what the child actually left:
#:
#: * ``phase_incomplete`` — the phase is named from the *launch* (the call's
#:   validated mode word, through the table above) and the result line's
#:   ``state`` is the needs-human state, so "did not complete" is true of it;
#: * ``phase_known`` — the phase is named but the result line does not say it
#:   failed to complete;
#: * ``review_completed`` — ``review-code --fail-on-high``: the review finished,
#:   found what it was told to stop on, and wants a decision. Never "did not
#:   complete";
#: * ``phase_unnamed`` — a result line is present but nothing names a phase;
#: * ``phase_unknown`` — no result line at all (a child that died before it
#:   emitted one, or a line that was not JSON), so nothing names the phase;
#: * ``error_known`` — the last error line, quoted: the result's own ``error``
#:   when it carries one, else the last non-blank line of the *redacted*
#:   output, else of the redacted stderr;
#: * ``error_unknown`` — the child left no line to quote; ``log`` is what to
#:   report.
#:
#: The ``options`` sentence is kept word for word from the message it replaces:
#: it is what tells the model where the redacted commands went.
#:
#: The message named `argv` as
#: what was being run, and the host told the user the tool's own
#: `--exec-subagents --detach`; it now says to report the phase and the plan,
#: and never to quote `argv` or its flags. The round's merge had
#: kept "what was being run (`argv`)" as the opening instruction beside the
#: later prohibition, telling the host both; the opening asks for the phase
#: and the plan, and a test fails any host-facing text that asks for `argv`.
NEEDS_HUMAN_MESSAGE = {
    "template": (
        "Stop here: this run is blocked and needs a human. {phase} {error} "
        "Report to the user which phase stopped, on which plan or commit range, "
        "that line whole, word for word (on a stop it says what stopped, what the "
        "task reported, what did not run and whether anything ran the "
        "repository's tests), and the "
        "`options`; an `options` entry is a tool call for you, never a command "
        "for the user to type, so do not print one as a command. The "
        "dispatcher's output is included as it was rendered, except that every "
        "runnable dispatcher command in it was re-spelled the way this host's "
        "user would type it (or replaced by a pointer where it could not be) "
        "and also comes back as a tool call in `options`, in the order it "
        "appeared, and its result line is in `result` instead; do not "
        "paraphrase the output, and do not lift a command out of it for the "
        "user: only `resume_command` (and each `resume_answers` command) is "
        "theirs to type. Do "
        "not run a different mode. Never quote `argv` or its flags to the user, "
        "which are this tool's own (`--host`, `--yes`, `--exec-subagents`, "
        "`--detach`) and nothing the user ran or types. "
        + NEEDS_HUMAN_WORK_SENTENCE + " " + STOP_POLICY_RULE + " Send back "
        "an `options` entry only after the user has picked one."
    ),
    "phase_incomplete": "The `{phase}` phase did not complete.",
    "phase_known": "The `{phase}` phase was running.",
    "review_completed": (
        "The `{phase}` review finished, found what it was told to stop on, and "
        "needs your decision."
    ),
    # Appended (never substituted) when the result carries `resume_command`: the
    # one command here that IS for the user to type. 2026-10-02: the run's
    # options were all the user was shown, as tool-call JSON on Codex and as
    # `call multi_llm with …` plus the agent-facing `human` sentence on OpenCode,
    # with "Pick an option and I'll run it" in a headless run.
    "resume": (
        "`resume_command` is what the user types to resume this phase once the "
        "cause above is fixed. Give it to the user verbatim in its own fenced "
        "block, as the way forward. It is never a tool call and never a shell "
        "command: do not run it, and do not offer to run it for them."
    ),
    # Appended instead of `resume` when the lookup says what the plain resume
    # does (`user_resume.why`, the result's `resume_why`). With no why the
    # hosts wrote one of their own — "re-runs the T002 check", false on
    # unchanged files, or "after addressing the write policy".
    # `{why}` is substituted as it comes.
    "resume_why": (
        "`resume_command` is what the user types to resume this phase; it "
        "{why}. Give it to the user verbatim in its own fenced block, with "
        "what it does as plain text above it. It is never a tool call and "
        "never a shell command: do not run it, and do not offer to run it for "
        "them."
    ),
    # Appended after `resume` when the stop offers answers as well. `{answers}` is the
    # dispatcher's `user_resume.answers_text` — each command in backticks and
    # what it does, one sentence apiece and ending its own (so a bracketed why never
    # reads "(T006))") — substituted as it comes; the
    # server authors none of it. Each is also in `resume_answers` and an `options` entry.
    # The host headed each
    # answer "Optional, before that:" and added a paraphrased "Ways forward"
    # list beside them; the clause says what they are and where the why goes.
    "answers": (
        "Instead of `resume_command` the user can type any of these, each "
        "with what it does (each is in `resume_answers` and is also an "
        "`options` entry, in the same order): {answers} After "
        "`resume_command`, give the user every one of them verbatim in its own "
        "fenced block, its why as plain text above it, and no list or summary "
        "of them of your own: they are the stop's ways forward. Like "
        "`resume_command`, none is a tool call or a shell command for you to run."
    ),
    # Appended instead of `resume`/`resume_why` and `answers` when the lookup
    # wrote the stop's ways forward as one section (`user_resume.markdown`,
    # the result's `resume_markdown`). Without it the hosts composed their own
    # blocks, reworded the whys, added "what ran" lists and printed `options`
    # entries as "Call multi_llm with …".
    # The host added a recap
    # and an "Options named in output (resume choices)" list before the
    # section, following the template's "report … the `options`": the
    # section IS that report.
    "resume_markdown": (
        "`resume_markdown` is the stop's ways forward, already written for "
        "the user: `resume_command` with what it does and, when the stop "
        "offers them, the answers they can type instead (each also in "
        "`resume_answers` and an `options` entry). It is the report of the "
        "`options` asked above: end your report with it, copied as it is, in "
        "place of any list of options or ways forward of your own, and write "
        "no list, recap or summary of the options or answers anywhere else. "
        + READY_SECTION_RULE + " Each command stays alone in its fenced "
        "block, each why stays plain text. None of its commands is a tool "
        "call or a shell command for you to run, and do not offer to run one."
    ),
    # Appended instead of `resume` when the result carries no
    # `resume_command` (racing re-run 2026-10-04: a result with neither command
    # key, and the host model composed a "next phase" of its own).
    "no_command": (
        "`user_next_step` is null and there is no `resume_command`: give the "
        "user no command to type and name no next phase; `no_command_reason` "
        "says why."
    ),
    "phase_unnamed": "Nothing in the result line names the phase that was running.",
    "phase_unknown": (
        "The dispatcher exited without a result line, so nothing here names the "
        "phase that was running; `log` says what ran."
    ),
    "error_known": "The last line it left is: {error}",
    "error_unknown": (
        "Its result line names no error, and what it printed is in `output` and "
        "`stderr`; `log` is what to report."
    ),
}

#: The one ``options`` entry that is not a retry: a legal exit. Appended by the
#: plugin after the scraped tool calls, as ``{human: <this sentence>}``, so an
#: agent reading the options finds "ask the user" beside "run this again".
NEEDS_HUMAN_OPTION = (
    "(a note to you, not a command and not for the user) stop here and report; "
    "send back one of the options above only after the user has picked one"
)

#: The one exit 3 that is not an unfinished run. ``review-code --fail-on-high``
#: completes the review and *then* exits 3 to hold a standalone gate for a
#: decision, and its result line carries the same needs-human state every other
#: exit 3 does. The plugin combines the launch flag with the result's positive
#: ``high_priority_groups.count`` before claiming completion: the flag alone
#: also appears on preflight failures where no review ever ran.
#: The flag is declared by ``code_review_orchestrator``'s parser; a test holds
#: the two spellings together.
REVIEW_GATE = {"mode": "review-code", "flag": "--fail-on-high"}


# ---------------------------------------------------------------------------
# The package routes' pre-spawn refusals — authored here, read off the surface
# ---------------------------------------------------------------------------
#
# Every message a package route's server returns *instead of* spawning the
# dispatcher is a template here, emitted into ``dist/cli-surface.json`` and
# returned by the server verbatim after token substitution — the same rule
# that keeps the exit-3 message in :data:`NEEDS_HUMAN_MESSAGE` and the uv
# preflight text in ``hosts/uv-missing.txt``. Tokens are literal ``{name}``
# spans replaced by plain string substitution (never ``str.format``), so a
# brace a user typed into a value can never be read as another token.

#: The environment name that lifts the codex tool's write-posture refusal, and
#: the one value that means "on" (the ``MULTI_LLM_ALLOW_DIRTY`` spelling:
#: ``=1`` and nothing else, so ``=0`` does not enable it). An environment name
#: and **not** a tool argument, because every tool argument is model-supplied
#: and a model must never be able to authorize its own escalation (D3b).
WRITE_POSTURE_LEVER_ENV = "MULTI_LLM_CODEX_UNSANDBOXED_WRITES"
WRITE_POSTURE_LEVER_VALUE = "1"

#: The refusal a write-capable mode gets under a read-only (or unreadable)
#: session posture. The codex server reads the posture per call from the
#: ``sandbox_mode`` in its turn metadata: ``read-only`` refuses,
#: ``workspace-write`` and ``danger-full-access`` allow. ``{mode}`` is the mode
#: word as sent; ``{posture}`` is the posture word the server read, or
#: :data:`WRITE_POSTURE_UNREADABLE` when it could not read one — absent, or a
#: word it does not know — and then the refusal fails closed.
WRITE_POSTURE_REFUSAL = (
    "Refused before anything ran: `{mode}` edits the working tree, and this "
    "session's sandbox posture is {posture}. This tool runs outside the "
    "session's exec sandbox, so it will not make edits the session was not "
    "granted. The single way to proceed is the user's, never yours: they set "
    + WRITE_POSTURE_LEVER_ENV + "=" + WRITE_POSTURE_LEVER_VALUE
    + " in the environment codex is launched from and restart it. Report this "
    "to the user. " + NEEDS_HUMAN_WORK_SENTENCE
)

#: What ``{posture}`` reads when the server could not observe the session's
#: sandbox posture at all.
WRITE_POSTURE_UNREADABLE = (
    "unreadable from this tool, so it is treated as read-only"
)

#: The refusal when no workspace-anchor candidate answered (D3f). ``{probed}``
#: is the list of candidates the server tried, in its own order. The process's
#: own working directory is never a fallback: on a plugin route it is the
#: install location, and a run anchored there scaffolds configuration into a
#: directory the next install deletes.
ANCHOR_UNRESOLVED = (
    "Refused before anything ran: this tool could not determine which "
    "workspace to run in. It probed {probed}, and none answered. It does not "
    "fall back to its own working directory, which is the plugin's install "
    "location, not your project. Report this to the user; do not retry with a "
    "different mode. " + NEEDS_HUMAN_WORK_SENTENCE
)

#: The refusal when the login shell the dispatcher is started through does not
#: resolve (D3a) — the Windows-without-Git-Bash case, and any ``PATH`` with no
#: POSIX shell on it. ``{shell}`` is the program searched for, ``{platform}``
#: the platform word, ``{path}`` the ``PATH`` that was searched. A shell-less
#: spawn is not offered: it would start the provider CLIs without the
#: credentials a login profile exports, and fail one layer down as an opaque
#: provider error.
SHELL_MISSING = (
    "Refused before anything ran: this tool starts the dispatcher through a "
    "login `{shell}`, and no `{shell}` was found on {platform} along this "
    "PATH: {path}. A POSIX bash on PATH is a prerequisite of this tool "
    "(on Windows, Git Bash). Install one, put it on PATH, and restart the "
    "host. Report this to the user; running without a login shell is not "
    "offered, because the provider CLIs would start without the credentials "
    "your profile sets."
)

#: The codex-only clause of the tool description (D3b: the tool says what it
#: is). ``{modes}`` is the comma-joined list of modes whose surface row carries
#: ``writes_worktree``. Emitted for the codex host alone; the OpenCode plugin
#: runs inside its host's own permission model and says nothing of the kind.
TOOL_WRITE_CAPABLE_NOTE = (
    "This tool runs outside the session's exec sandbox. {modes} edit the "
    "working tree through agent CLIs; under a read-only posture, or one this "
    "tool cannot read, they are refused unless the user has set "
    + WRITE_POSTURE_LEVER_ENV + "=" + WRITE_POSTURE_LEVER_VALUE + "."
)

#: The codex host's rule for waiting on a call. Under codex's code mode the model calls this tool from a JavaScript
#: ``exec`` cell that hands control back after ``yield_time_ms`` (30 s by
#: default) while the call is still running, and a model that then ends its
#: turn ends ``codex exec``, whose teardown aborts the run. Measured offline on
#: codex 0.160.1: a cell whose first line is the pragma below waited for a
#: 75 s call and returned only with its result. ``{BUDGET_MIN}`` and
#: ``{YIELD_MS}`` are filled from the plugin's ``tool_timeout_sec``
#: (``packaging/codex/mcp.json``) by ``packaging/common/surface.py``, so the
#: wait and the budget cannot drift. Rendered into the codex tool description
#: and the codex plugin's skill; no other host has the cell.
TOOL_LONG_CALL_RULE = (
    "A call can run for up to its {BUDGET_MIN}-minute budget. When you call this "
    "tool from an `exec` cell, start the cell with "
    '`// @exec: {"yield_time_ms": {YIELD_MS}}`, so the cell waits for the '
    'result. If a cell hands back "Script running" anyway, call `wait` until '
    "this call returns, and never end your turn while it is running."
)


# The `util` namespace is a mode word for routing purposes but is deliberately
# *not* a mode: it is excluded from `--help`'s mode list and from
# `argument-hint`, and is never rendered into a MULTI_LLM_RESULT.next value.
UTIL_NAMESPACE = "util"


# Legacy direct-invocation script name -> mode word. Used when a printed
# follow-up command has to be built from an orchestrator script name (the
# orchestrators pass their own filename around as `orchestrator_script`).
SCRIPT_TO_MODE: Dict[str, str] = {
    m.target_module + ".py": m.name
    for m in MODES
    if m.target_module and m.target_module.endswith("_orchestrator")
}


_BY_NAME: Dict[str, Mode] = {m.name: m for m in MODES}


def mode_names() -> Tuple[str, ...]:
    """Every mode word, in table order."""
    return tuple(m.name for m in MODES)


def user_facing_modes() -> Tuple[Mode, ...]:
    """The modes that have a ``--<name>`` user flag."""
    return tuple(m for m in MODES if m.user_facing)


def resolve(word: str) -> Optional[Mode]:
    """Resolve a mode word or alias to its :class:`Mode`, else ``None``."""
    return _BY_NAME.get(ALIASES.get(word, word))


def phase_for(word: str) -> Optional[str]:
    """The ``state.json`` phase name for a mode word or alias."""
    mode = resolve(word)
    return mode.phase if mode else None


def mode_for_script(script: str) -> Optional[str]:
    """The mode word that replaces a direct ``*_orchestrator.py`` invocation."""
    return SCRIPT_TO_MODE.get(script.rsplit("/", 1)[-1].rsplit("\\", 1)[-1])


def instruction_path(word: str) -> Optional[str]:
    """Repo-relative path of a mode's core instruction file, if it has one."""
    mode = resolve(word)
    if mode is None or mode.instruction_file is None:
        return None
    return "instructions/" + mode.instruction_file


#: The phase vocabulary ``check_workflow_prerequisites.py`` gates on, in
#: workflow order. Imported there so one table owns it.
PREREQUISITE_PHASES: Tuple[str, ...] = tuple(
    m.phase for m in MODES if m.is_workflow_phase and m.phase
)


#: The modes ``--detach`` covers, in table order. One owner: the dispatcher's
#: rejection, ``utils/detach.py``'s guard and every error message read this.
DETACH_MODES: Tuple[str, ...] = tuple(m.name for m in MODES if m.supports_detach)


def phase_names() -> Tuple[str, ...]:
    """Every phase name any mode owns, in table order (includes ``ask``)."""
    seen: Dict[str, None] = {}
    for mode in MODES:
        if mode.phase:
            seen.setdefault(mode.phase, None)
    return tuple(seen)


def phase_from_selector(word: str) -> Optional[str]:
    """Resolve a ``--phase``/``--mode`` value to a phase name, or ``None``.

    Accepts either vocabulary, because the two differ for exactly one mode
    (``review-code`` → phase ``code-review``) and a caller should not have to know
    which one a given flag wanted. The resolution lives here so ``status``'s
    ``--phase`` selector and ``check_workflow_prerequisites.py``'s ``--mode``
    choices cannot drift apart.
    """
    if word in phase_names():
        return word
    return phase_for(word)


# The non-mode part of `argument-hint` — everything after the mode alternation.
# A literal because it describes flags, not modes; the mode list itself is
# rendered so a new row cannot be forgotten here. The commit modes take an
# optional range where the others take a plan (`POS_REVS`), and add two flags
# of their own; the two plan-and-code composites take `--cascade`.
ARGUMENT_HINT_TRAILER = (
    f' <plan_path>|{POS_REVS} (<range>: --*-commits only) '
    '["<question>" (required for --ask)] '
    "[--models provider:model ...] [--interactive] [--quick] [--yes] [--force] "
    "[--scope-policy expand|preserve] "
    "[--cascade (--improve-plan/--improve-code only)] "
    '[--focus "<text>"|--context-plan PATH (--*-commits only)] '
    "[--dir PATH|--gitignore|--template-only (--init only)]"
)


def render_argument_hint() -> str:
    """Render SKILL.md's ``argument-hint`` value from the table."""
    flags = "|".join(f"--{m.name}" for m in user_facing_modes())
    return f"[{flags}]{ARGUMENT_HINT_TRAILER}"
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: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated 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: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall