plan-multi-agent-review

Files (7)

• SKILL.md
• review-prompt.md · references/
• reviewer-cli-matrix.md · references/
• build_prompt.sh · scripts/
• detect_reviewers.sh · scripts/
• gather_plan_context.sh · scripts/
• run_reviewer.sh · scripts/

SKILL.md (first lines)

# Plan Multi-Agent Review

Run several AI coding CLIs as an independent review panel over a **plan file** — judged against the
**code repository it targets** — then synthesize their reviews into one report. The value over a
single reviewer is *triangulation*: a flaw three tools independently flag is almost certainly real;
a concern only one raises is either a sharp catch or a false positive — and the report should make
that distinction visible so the user knows where to spend attention.

The two inputs are **a plan file** (an explicit path — required) and **the repo** the plan is
about. The **sole artifact produced is a review of the plan.** Nothing is posted anywhere; every
artifact is a local file in a temp directory.

**Requirements.** `git` and at least one reviewer CLI are mandatory. A `timeout`/`gtimeout` binary
is used if present; otherwise a built-in bash watchdog enforces the per-reviewer timeout. The
scripts avoid GNU-only flags (`readlink -f`, `mktemp --suffix`) so they run on stock macOS as well
as Linux.

**Trust boundary (read this).** Two distinct exposures, because the panel feeds the *plan* and
repo files into the reviewer CLIs and lets them explore a live working tree:

- **Prompt-injection → tool execution.** Two tools (`opencode`, `agy`) run without a hard
  read-only sandbox — `agy` with its auto-approving `--sandbox`. Because this skill points every
  reviewer at a **live repo as its working directory** so it can verify the plan, a malicious file
  in that repo (or a crafted instruction inside the plan) could attempt to drive those tools. Run
  this on repos and plans you trust, or isolate those tools (throwaway worktree, network off).
- **Data egress.** Every reviewer streams the plan and the repo content it reads to its model
  provider (Anthropic, OpenAI, GitHub, Google, …). This skill embeds the plan-referenced files
  **and** invites live exploration, so **more repo content can leave the machine than a single diff
  would** — don't review a plan whose repo holds secrets you can't share with the reviewers'
  backends.

Step 6 covers the specifics.

**The orchestrator (you) never reviews the plan yourself.** Your job is to gather context, dispatch
the panel, and collate. If you inject your own opinions as if they were a reviewer's, you destroy
the signal of how many *independent* tools agreed. You may reconcile and judge their findings during
collation, but the findings must originate from the panel.

---

## Workflow at a glance

1. **Resolve & validate** — locate the skill scripts; require an explicit plan-file path.
2. **Gather context** — copy the plan, resolve the repo, extract the files the plan references →
   temp context dir; `source` its `meta.env`.
3. **Safety baseline** — snapshot `git status` before the panel touches the repo.
4. **Pick the panel** — detect which reviewer CLIs are installed; apply any model overrides.
5. **Dispatch** — build the prompt once, then run every reviewer in parallel, read-only, with the
   repo as cwd, each writing its own review file.
6. **Collate** — synthesize all reviews (consensus-first) into `FINAL-REPORT.md`.
7. **Deliver & safety diff** — re-check `git status`; print the paths and a three-line summary.

Use a TodoList to track these — step 5 fans out into one task per reviewer and it's easy to lose one.

---

## Step 1: Resolve scripts and validate input

This skill reviews a specific plan file, so a path is **required** — there is no "current plan" to
auto-detect. If the user didn't give one, ask for it before doing anything else.

Resolve the skill directory portably (BSD `readlink` has no `-f`):

```bash
SKILL_LINK=~/.claude/skills/plan-multi-agent-review/SKILL.md
SKILL_TARGET="$(readlink "$SKILL_LINK" 2>/dev/null || echo "$SKILL_LINK")"
SKILL_DIR="$(cd "$(dirname "$SKILL_TARGET")" && pwd -P)"

PLAN_PATH="<the path the user gave>"   # e.g. ~/.claude/plans/foo.md or ./design.md
```

The gather helper (Step 2) hard-fails with a clear `❌` if `PLAN_PATH` is empty or unreadable, so
you don't need to re-validate here — just make sure you actually pass what the user intended.

## Step 2: Gather plan context

Create a temp workspace and populate it. One helper does all of it so every reviewer reads identical
inputs. Run it from inside the repo the plan targets (so it resolves the right `REPO_ROOT`), then
**`source` its `meta.env`** — that's how you get `REPO_ROOT` and `CURRENT_BRANCH` for the dispatch
cwd and the report header:

```bash
WORKDIR="$(mktemp -d)/plan-review" && mkdir -p "$WORKDIR"
"$SKILL_DIR/scripts/gather_plan_context.sh" "$PLAN_PATH" "$WORKDIR"
source "$WORKDIR/context/meta.env"   # sets PLAN_PATH, PLAN_NAME, REPO_ROOT, CURRENT_BRANCH
ls -1 "$WORKDIR/context"
```

After it runs, `$WORKDIR/context/` contains:

- `plan.md` — a copy of the plan under review (the primary artifact)
- `referenced-files/` — the repo files the plan cites, mirrored at their **real repo paths** so
  reviewers can cite findings at the correct `file:line`
- `referenced-files.txt` — the embedded relpaths, one per line
- `missing-references.txt` — path-shaped references that **don't exist** in the repo. For a plan
  this is expected for files it proposes to *create*, and a red flag when it claims to *modify*
  something absent — the panel judges which
- `repo-orientation.md` — repo root, branch, `git status`, recent commits, a bounded file list
- `meta.env` — `printf %q`-quoted `PLAN_PATH`, `PLAN_NAME`, `REPO_ROOT`, `CURRENT_BRANCH`

The grounding heuristic only ever marks a reference "missing" when it is **path-shaped** (contains
`/` or ends in a source extension) and absent from the repo — so bare code tokens like
`safe_fence()` or `set -euo pipefail` are never mis-flagged. A reference cited by basename resolves
to its real nested path via `git ls-files`. This is the skill's core grounding signal; trust it but
sanity-check `missing-references.txt` when collating.

## Step 3: Capture a safety baseline

Reviewers explore a **live repo** and three of them run with no hard sandbox (Step 6), so snapshot
the working tree before dispatch. After the panel finishes you diff against this to spot any stray
writes:

```bash
git -C "$REPO_ROOT" status --porcelain > "$WORKDIR/git-status.before"
```

## Step 4: Pick the review panel

Only run tools that are actually installed — invoking a missing binary wastes a turn and clutters

From surajssd/dotfiles, MIT.

More from surajssd/dotfiles