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

utils/commit_paths.py

View on GitHub
"""Commit reviews' path layer: the commit brief that stands in for a plan, and its folder.

``--review-commits``, ``--apply-commit-fixes`` and ``--improve-commits`` do not
fork the review pipeline. Each is a front door that resolves a commit range
(``utils/commit_range.py``), writes a generated **commit brief** for it, and
runs review-code or apply-code-fixes on that brief as if it were a plan
(plans/review-commits.md §2.1). Everything a plan anchors (the output dir,
``state.json``, locks, ``status``, run records, the next-step lookup) then
works unchanged. This module owns what the brief is and where it lives; the
range grammar stays in ``commit_range``, which never imports this module, so
the dependency runs one way. The front doors themselves are
``utils/commit_front_door.py``.

**The path layer**:

- The folder is ``code_review.commit_reviews_dir``, read only through
  ``provider_registry.get_commit_reviews_dir`` and joined to the repository
  root. A folder the plugin creates ignores itself with a ``.gitignore``
  holding ``*``; an existing one is left as the user made it, and
  :func:`not_ignored_warning` says when git would show its briefs (§2.4,
  "The folder ignores itself").
- A brief is ``<folder>/<slug>.md`` with the slug ``<base12>-<head12>`` or
  ``root-<head12>``; its output dir is ``<folder>/<slug>/``, as for any plan.
  :func:`is_commit_brief` and :func:`brief_for_pinned` are how the dispatcher
  and ``status`` recognise a brief path or a pinned range without a git call
  beyond finding the root (§2.2).
- :func:`commit_review_artifact` names every brief and report folder by path
  string, so the review scope and ``tracked_files`` drop them as a class,
  whatever run is reviewing (§2.4, "Out of scope for every review").
- :func:`document_label` is the one test for whether a user-facing line calls
  the anchor a "commit brief" or a "plan" (§2.8), and
  :func:`read_commit_range` the read-only lookup of a brief's recorded range.
"""

from __future__ import annotations

import json
import os
import re
from pathlib import Path
from typing import Any, Dict, Mapping, Optional, Tuple, Union

from .cli_common import EXIT_ERROR as _EXIT_ERROR
from .git_utils import get_project_root_from_dir, git_path, ignored_paths
from .output_handler import output_dir_path
from .provider_registry import ConfigError, get_commit_reviews_dir

PathLike = Union[str, os.PathLike]

#: The brief's first line, exactly; the brief writer always puts it there. A
#: file that only quotes it further down (a plan about commit reviews) is not
#: a brief.
BRIEF_MARKER = "<!-- multi-llm:commit-brief v1 -->"

#: The line that closes the generated header. Everything below it (a host's
#: ``## Code Fixes Applied`` section) is kept when the header is rewritten.
BRIEF_END_MARKER = "<!-- /multi-llm:commit-brief -->"

#: §2.4's slug grammar: ``<base12>-<head12>``, or ``root-<head12>`` for a range
#: starting at the root commit. The same text as ``commit_range.SLUG_PATTERN``;
#: kept here as well so this module never imports the range grammar.
SLUG_PATTERN = r"(?:root|[0-9a-f]{12})-[0-9a-f]{12}"

#: §2.2's pinned spelling, ``<base12>..<head12>``, as records, resume lines and
#: next commands print it. The same text as ``commit_range.PINNED_PATTERN``.
PINNED_PATTERN = r"[0-9a-f]{12}\.\.[0-9a-f]{12}"

_SLUG_RE = re.compile(SLUG_PATTERN)
_PINNED_RE = re.compile(PINNED_PATTERN)
_BRIEF_NAME_RE = re.compile(SLUG_PATTERN + r"\.md")

#: The ``.gitignore`` a newly created commit-reviews folder gets.
FOLDER_GITIGNORE = "*\n"

#: How much of a file's first line :func:`is_commit_brief` reads. The marker
#: is 35 bytes; a longer first line is not the marker whatever follows.
_FIRST_LINE_BYTES = 256


class CommitReviewError(Exception):
    """A commit-review refusal: the message to print and the exit code.

    ``exit_code`` is :data:`utils.cli_common.EXIT_NEEDS_HUMAN` (3) unless the
    caller says otherwise; the message's first line starts with its marker
    tag when it has one.
    """

    def __init__(self, message: str, exit_code: int = 3):
        super().__init__(message)
        self.message = message
        self.exit_code = exit_code


def _start_dir(path_or_cwd: Optional[PathLike]) -> str:
    """The existing directory to ask git from: *path_or_cwd* or the cwd.

    A file, or a path that does not exist yet (a brief about to be written),
    is asked from its nearest existing ancestor.
    """
    current = os.path.abspath(os.fspath(path_or_cwd)) if path_or_cwd else os.getcwd()
    while not os.path.isdir(current):
        parent = os.path.dirname(current)
        if parent == current:
            break
        current = parent
    return current


def repo_root_of(path_or_cwd: Optional[PathLike] = None) -> Path:
    """The git root of *path_or_cwd* (a file, a directory, or the cwd when None).

    Raises :class:`CommitReviewError` outside a repository: a commit review
    always belongs to one.
    """
    start = _start_dir(path_or_cwd)
    root = get_project_root_from_dir(start)
    if not root:
        raise CommitReviewError(
            f"ERROR: {start} is not in a git repository; commit reviews review "
            f"a repository's commits"
        )
    return Path(root)


def _slug(base: Optional[str], head: str) -> str:
    """``<base12>-<head12>``, or ``root-<head12>`` when *base* is None."""
    head12 = str(head or "")[:12].lower()
    base12 = "root" if base is None else str(base)[:12].lower()
    slug = f"{base12}-{head12}"
    if not _SLUG_RE.fullmatch(slug):
        raise ValueError(
            f"not a commit range's endpoints: base={base!r}, head={head!r} "
            f"(expected full or 12-character hex SHAs, base None for a root range)"
        )
    return slug


def ensure_commit_reviews_dir(anchor: PathLike) -> Tuple[Path, bool]:
    """Create the configured commit-reviews folder if needed; ``(folder, created)``.

    *anchor* is the cwd's repository root, or a brief path. Only the
    configured folder gets a ``.gitignore``, never a parent created with it
    (a tracked or absent ``plans/``): a folder this call creates gets
    ``<folder>/.gitignore`` holding ``*`` with an exclusive create, as
    ``.multi-llm/tmp/`` and the review's ``diff/`` folder do, so plain
    ``git status --porcelain`` (and so ``pre_existing_changes``) never lists
    the briefs and report folders, and ``finalize_tracking``'s ignore filter
    leaves them out of ``tracked_files``.

    An existing folder is left exactly as it is: no ``.gitignore`` is written
    into a folder the plugin did not create, and one the user deleted is
    never restored, since deleting it is how a user chooses to commit reviews.
    Of two concurrent creators, the one whose ``mkdir`` succeeds writes it.

    Raises :class:`~utils.provider_registry.ConfigError` for a refused folder
    (outside the repository) and :class:`CommitReviewError` when the path is
    taken by something that is not a directory.
    """
    folder = get_commit_reviews_dir(anchor=anchor)
    if folder.is_dir():
        return folder, False
    if folder.exists() or folder.is_symlink():
        raise CommitReviewError(
            f"ERROR: code_review.commit_reviews_dir names {folder}, which exists "
            f"and is not a directory; move it or set the key to another folder"
        )
    folder.parent.mkdir(parents=True, exist_ok=True)
    try:
        folder.mkdir()
    except FileExistsError:
        if folder.is_dir():
            return folder, False
        raise
    try:
        with open(folder / ".gitignore", "x", encoding="utf-8", newline="\n") as handle:
            handle.write(FOLDER_GITIGNORE)
    except FileExistsError:
        pass
    return folder, True


def brief_path_for(base: Optional[str], head: str, *, anchor: PathLike) -> Path:
    """``<commit_reviews_dir>/<slug>.md`` for a range, whether it exists or not.

    *base* is None for a range starting at the root commit. Raises
    :class:`ValueError` for endpoints that are not hex SHAs, and the
    accessor's :class:`~utils.provider_registry.ConfigError`.
    """
    slug = _slug(base, head)
    return get_commit_reviews_dir(anchor=anchor) / f"{slug}.md"


def output_dir_for_brief(brief: PathLike) -> Path:
    """The brief's output dir, ``<folder>/<slug>/``: any plan's rule, computed only.

    Equal to ``output_handler.output_dir_path(brief)``; a slug survives
    ``sanitize_prefix`` unchanged, and it never equals its folder's name, so
    ``find_output_dir``'s double-nesting guard never applies (§2.4, "Slug").
    """
    return output_dir_path(Path(brief))


def _first_line_is_marker(path: str) -> bool:
    """Whether the file's first line is exactly :data:`BRIEF_MARKER`."""
    try:
        with open(path, "rb") as handle:
            head = handle.readline(_FIRST_LINE_BYTES)
    except OSError:
        return False
    line = head.decode("utf-8", errors="replace")
    if line.endswith("\n"):
        line = line[:-1]
    if line.endswith("\r"):
        line = line[:-1]
    return line == BRIEF_MARKER


def commit_reviews_folder_rel(root: PathLike) -> Optional[str]:
    """The commit-reviews folder, repository-relative in git's form, for *root*.

    ``get_commit_reviews_dir(root)`` through ``git_utils.git_path``. ``None``
    when the accessor raises (the outside-root refusal, a malformed base, no
    repository): a caller that only drops artifacts then drops nothing extra
    rather than failing, and the front door's own call raises the error.
    """
    try:
        folder = get_commit_reviews_dir(anchor=root)
    except (ConfigError, OSError):
        return None
    relative = git_path(folder, repo_root=root)
    if (not relative or os.path.isabs(relative) or relative.startswith("/")
            or relative == ".." or relative.startswith("../")):
        return None
    return relative.rstrip("/")


def _relative_to_root(path: PathLike, root: Path, cwd: Optional[PathLike]) -> str:
    """*path* (relative to *cwd*, else absolute) as git names it under *root*."""
    text = os.fspath(path)
    if not os.path.isabs(text):
        text = os.path.join(os.fspath(cwd) if cwd else os.getcwd(), text)
    return git_path(os.path.normpath(text), repo_root=root)


def matches_brief_path(path: PathLike, *, cwd: Optional[PathLike] = None) -> bool:
    """§2.2's folder rule on the path string alone: ``<commit_reviews_dir>/<slug>.md``.

    *path* is relative to *cwd* (the process's cwd when None) or absolute; the
    folder comes from ``get_commit_reviews_dir`` anchored on *cwd*'s
    repository root. No file is read, so a deleted brief's path still
    matches (what ``[COMMIT_REVIEW_NOT_FOUND]`` needs). ``False`` outside a
    repository or when the accessor raises.
    """
    try:
        root = repo_root_of(cwd)
    except CommitReviewError:
        return False
    folder = commit_reviews_folder_rel(root)
    if folder is None:
        return False
    relative = _relative_to_root(path, root, cwd)
    prefix = folder + "/"
    return relative.startswith(prefix) and bool(
        _BRIEF_NAME_RE.fullmatch(relative[len(prefix):])
    )


def is_commit_brief(path: PathLike, *, cwd: Optional[PathLike] = None) -> bool:
    """Whether the existing file *path* is a commit brief (§2.2).

    Either its first line is exactly :data:`BRIEF_MARKER`, or it sits at
    ``<commit_reviews_dir>/<slug>.md`` (:func:`matches_brief_path`), so a
    brief whose header the user cut away still qualifies. When the folder
    accessor raises, the marker alone decides. A plan, a README, or a file
    that quotes the marker below line 1 is not a brief, and neither is a path
    that is not a file. No git call beyond finding the root.
    """
    text = os.fspath(path)
    full = text if os.path.isabs(text) else os.path.join(
        os.fspath(cwd) if cwd else os.getcwd(), text
    )
    if not os.path.isfile(full):
        return False
    if _first_line_is_marker(full):
        return True
    return matches_brief_path(full, cwd=cwd)


def brief_for_pinned(text: str, *, cwd: Optional[PathLike] = None) -> Optional[Path]:
    """The brief a pinned ``<base12>..<head12>`` names, or None for other text.

    ``status`` maps its positional through this before its existence check
    (§2.2, "`status` takes the pinned spelling"): text that fully matches
    :data:`PINNED_PATTERN` names ``<commit_reviews_dir>/<base12>-<head12>.md``
    with the folder anchored on *cwd*'s repository root, whether or not the
    brief exists. Resolves nothing: no git call beyond finding the root.
    Raises :class:`CommitReviewError` outside a repository and the accessor's
    :class:`~utils.provider_registry.ConfigError` for a refused folder.
    """
    candidate = (text or "").strip()
    if not _PINNED_RE.fullmatch(candidate):
        return None
    base12, head12 = candidate.split("..")
    root = repo_root_of(cwd)
    return get_commit_reviews_dir(anchor=root) / f"{base12}-{head12}.md"


def commit_review_artifact(path: str, folder: str) -> bool:
    """Whether repo-relative *path* is a commit review's own file (§2.4).

    True for ``<folder>/<slug>.md`` (a brief) and for anything under
    ``<folder>/<slug>/`` (its ``state.json``, phase dirs, context-plan
    snapshot, restart archives), a ``<folder>/<slug>/`` entry itself
    included. Anything else in *folder* (a README, a script the user keeps
    there) is not. Reads the
    string only, never the disk, so a brief present only at a commit, or
    deleted since, still matches. *folder* is
    :func:`commit_reviews_folder_rel`'s answer; an empty one matches nothing.
    """
    folder = (folder or "").replace("\\", "/").strip("/")
    if not folder or not path:
        return False
    candidate = path.replace("\\", "/")
    while candidate.startswith("./"):
        candidate = candidate[2:]
    prefix = folder + "/"
    if not candidate.startswith(prefix):
        return False
    name, separator, _rest = candidate[len(prefix):].partition("/")
    if separator:
        return bool(_SLUG_RE.fullmatch(name))
    return bool(_BRIEF_NAME_RE.fullmatch(name))


def document_label(state: Optional[Mapping]) -> str:
    """``"commit brief"`` when *state* records a ``commit_range``, else ``"plan"``.

    The one owner of the word user-facing lines use for the anchor document
    (§2.8, "'Commit brief', never 'plan'"): each site calls this rather than
    testing ``commit_range`` itself. *state* is a ``state.json`` mapping or
    anything with a ``get`` (a ``StateManager``); None is a plan.
    """
    getter = getattr(state, "get", None)
    if getter is None:
        return "plan"
    return "commit brief" if isinstance(getter("commit_range"), Mapping) else "plan"


def not_ignored_warning(dir: PathLike, brief: PathLike) -> Optional[str]:
    """``[COMMIT_REVIEWS_NOT_IGNORED]`` when git would show the brief, else None.

    Only for a folder that already exists: one the plugin is about to create
    gets its own ``.gitignore`` (:func:`ensure_commit_reviews_dir`). The
    question is whether git ignores the brief's repository-relative path
    (``git_utils.ignored_paths``), so a tracked brief counts as not ignored.
    Read-only; the caller prints the line before writing anything, and the
    run continues.
    """
    folder = Path(dir)
    if not folder.is_dir():
        return None
    try:
        root = repo_root_of(folder)
    except CommitReviewError:
        return None
    brief_rel = _relative_to_root(brief, root, None)
    if brief_rel in ignored_paths([brief_rel], cwd=str(root)):
        return None
    shown = git_path(folder, repo_root=root).rstrip("/")
    return (
        f"[COMMIT_REVIEWS_NOT_IGNORED] {shown} is not ignored by git: its "
        f"briefs and reports show in git status and can be committed; add "
        f"{shown}/ to .gitignore unless committing them is intended"
    )


def read_commit_range(brief: PathLike) -> Optional[Dict[str, Any]]:
    """The ``commit_range`` the brief's ``state.json`` records, or None.

    A raw, read-only JSON read (no ``StateManager``: nothing is created,
    migrated or written back). None when there is no state, it does not
    parse, or it holds no ``commit_range`` mapping.
    """
    path = output_dir_for_brief(brief) / "state.json"
    try:
        with open(path, "r", encoding="utf-8") as handle:
            document = json.load(handle)
    except (OSError, ValueError):
        return None
    record = document.get("commit_range") if isinstance(document, dict) else None
    return dict(record) if isinstance(record, Mapping) else None


# ---------------------------------------------------------------------------
# A --detach launch's stage
# ---------------------------------------------------------------------------
#
# Under ``--detach`` a commit front door stages what it decided in a file in the
# phase dir and names it on the worker's argv (``--commit-stage``); the worker
# applies it once it owns the dir (``commit_front_door.apply_stage``, handed to
# ``detach`` by the worker's entry). Reading a stage is the path layer's, so the
# launcher's take-over decision (``detach``) reads it without the front door.

#: The stage file's format; ``commit_front_door._write_stage`` writes it.
_STAGE_VERSION = 1


def read_stage(stage: PathLike) -> Optional[Dict[str, Any]]:
    """A stage file's payload, or None when it is gone (already applied)."""
    try:
        with open(stage, "r", encoding="utf-8") as handle:
            data = json.load(handle)
    except FileNotFoundError:
        return None
    if not isinstance(data, dict) or data.get("version") != _STAGE_VERSION:
        raise CommitReviewError(f"ERROR: {stage} is not a commit-review stage this "
                                f"version can apply", exit_code=_EXIT_ERROR)
    return data


def stage_takes_over(stage: Optional[PathLike]) -> bool:
    """Whether a launch carrying *stage* may take a live run over with its
    ``--force``: only when the user typed ``--force``. A restart's
    synthesised ``--force`` restarts the round and never takes over a live
    run. True when there is no readable stage (the flag decides)."""
    if not stage:
        return True
    try:
        data = read_stage(stage)
    except (CommitReviewError, OSError, ValueError):
        return True
    if data is None:
        return True
    return bool(data.get("typed_force", True))
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