Cf Plan Review

---
name: cf-plan-review
description: >
  Review a saved /cf-plan folder with a fresh reviewer before implementing; triggers "review the plan", "plan review", "second opinion on the plan", "check the plan before implementing", "cf-plan-review"; --fix/--inline applies Critical/Important findings without asking; does NOT review code (use /cf-review).
created: 2026-09-05
updated: 2026-09-22
---

# /cf-plan-review

Review the plan: **$ARGUMENTS**

## Purpose

Review a saved `/cf-plan` folder (not application code) with a fresh, clean-context subagent of the host that is running this skill. Optionally add external reviewers in parallel. Write `review.md` into the plan folder, then offer to apply Critical/Important findings — or apply them immediately with `--fix` (`--inline`).

- Unlike `/cf-review`: that skill reviews a code diff. This skill reviews the plan document before implementation.
- Unlike `cf-reviewer-plan`: that agent compares implemented code against the plan. This skill checks the plan itself before any code is written.

## Workflow

### Step 0: Custom Guide

```!
bash "<plugin-root>/lib/load-custom-guide.sh" cf-plan-review
```

If the block above printed anything, apply only the `## Before`, `## Rules`, and `## After` sections; if it shows the raw command instead of output, re-run that exact `load-custom-guide.sh` fence now.

### Step 1: Resolve the plan and flags

Read `docsDir` from `.coding-friend/config.json` (default: `docs`). Prefer `CF_DOCS_ROOT` from bootstrap (`$MAIN_REPO_ROOT/{docsDir}`).

**External reviewer flags:**

- Parse `--codex`, `--gemini`, `--claude`, `--cursor`, `--grok` (and `--with-<agent>` aliases) into `agents=[…]`; strip them from `$ARGUMENTS`.
- **Host-match no-op:** skip a matching flag only when a `HOST:` line exists **and** equals the flag (the flag matching the current host is skipped). Drop that agent and print:

  > ⚠ `--<host>` skipped: <Host> is already the in-session reviewer.

  No `HOST:` line or a different value → do **NOT** skip. When in doubt, run it.

**Apply flags:**

- Parse `--fix` (alias `--inline`); strip them from `$ARGUMENTS`. `--inline` here means apply findings — it is **not** `/cf-plan`'s no-file mode.
- If present, set apply=true and print:

  > 🔧 `--fix` — will apply Critical/Important findings after review (no confirmation).

What remains is `<plan>`.

If `<plan>` is empty: list folders in `{docsDir}/plans/` newest first (`ls -t`) and Ask the user which plan to review.

**Resolve the plan entry file** (same rules as `/cf-plan-resume`):

1. **Resolve the plan entry file**:
   - Full path to a folder → use `<folder>/README.md`. Full path to a file → use it directly. Validate the target is within the current working directory or `{docsDir}`; report error and stop if outside.
   - Name only (`<slug>`) → first, reject the argument outright if it contains `/`, `\`, or `..` (report: "Invalid plan name — slugs cannot contain path separators or `..`." and stop). This must happen BEFORE constructing any candidate path, since the candidates below are built by directly interpolating `<slug>` — a slug containing `../` would otherwise escape `{docsDir}/plans/`. Once the slug passes this check, resolve in this order, using the first that exists: `{docsDir}/plans/<slug>/README.md` (current layout) → `{docsDir}/plans/<slug>.md` (legacy single-file) → `{docsDir}/plans/<slug>` (append `.md` if it is a bare file).
   - If none found → report error and stop.

Read `README.md`, every `phase-N-*.md`, `brief.md` when present, and any other `*.md` the planner left in the folder (e.g. `baseline.md`, `review-request.md`; skip `review.md` / `overview.*`). If `brief.md` is missing, print:

> ℹ️ No brief.md — reviewing README.md and phase files only.

### Step 2: Build the review prompt

```bash
mkdir -p "${CF_DOCS_ROOT}/reviews" && \
  bash "<plugin-root>/skills/cf-plan-review/scripts/build-plan-review-prompt.sh" \
    <entry-file> <docsDir> \
  > "${CF_DOCS_ROOT}/reviews/<slug>-plan-prompt.md"
```

### Step 3: Spawn external reviewers (only when agents non-empty)

Skip when `agents=[]`.

For each agent, run one Bash command in the background (do not inspect at spawn); the harness reports when each finishes. The runner enforces `review.agentTimeout` (default 300s) on the CLI subprocess and its process group, so every job is bounded.

```
bash "<plugin-root>/skills/cf-review/scripts/run-agent-review.sh" <agent> "${CF_DOCS_ROOT}/reviews/<slug>-plan-result-<agent>.md" "${CF_DOCS_ROOT}/reviews/<slug>-plan-prompt.md"
```

Proceed immediately to Step 4.

### Step 4: In-session review

Dispatch a fresh general-purpose subagent (no Coding Friend agent name; not a fork of this context). It inherits this skill's model.

Prompt = the contents of `${CF_DOCS_ROOT}/reviews/<slug>-plan-prompt.md`, plus:

- Spot-check the repo read-only (Read / Glob / Grep). Do not run verify steps. Do not edit files.
- If the plan folder has a `review-request.md`, answer each of its questions explicitly.
- Return exactly the four sections: 🚨 Critical Issues / ⚠️ Important Issues / 💡 Suggestions / 📋 Summary.

Call this result **Source 1**.

### Step 5: Collect external results

Skip when `agents=[]` at spawn time.

Wait for each agent in bounded steps — the runner kills its own subprocess at the deadline, so the wait always ends. Read the `CF_AGENT=` line on stderr:

- `ok` → keep the result file.
- `unavailable` → print `> ⚠ <Agent> CLI not found — proceeding without it.` Drop it.
- `timeout` → print `> ⚠ <Agent> review timed out (>Ns) — proceeding without it.` Drop it. (N = `review.agentTimeout`, default 300.)
- `error` → print `> ⚠ <Agent> review failed — proceeding without it.` Drop it.
- `empty` → print `> ⚠ <Agent> returned empty output — proceeding without it.` Drop it (this also covers a CLI that exits 0 writing nothing).

Never block on an external reviewer — failures degrade gracefully.

### Step 6: Merge

**When no external source survived:** use Source 1 as-is. Do not reformat.

**When any external source survived:** merge via Dispatch `cf-reviewer-reducer`. Source 1 is the in-session report; each surviving external review is a numbered source:

> Merge these review reports into one unified, deduplicated, severity-ranked report.
>
> **Source 1 — in-session plan review:**
> [the full report from Step 4]
>
> **Source K — \<Agent\> review:** (for each surviving external source)
> [raw result file]
>
> Tag each external finding with `[\<Agent\>]` (codex → `[Codex]`, gemini → `[Gemini]`, etc.). Same file:line + same issue → one finding (highest severity) and note agreement. Output 🚨/⚠️/💡/📋.

End the merged report with a banner suffix when any external source contributed:

`· Reviewed by: <in-session label from HOST> + <Agents>`

Label from `HOST` (capitalized); if no `HOST:` line, use `In-session AI`. Omit the suffix when only the in-session reviewer ran.

### Step 7: Save review.md

Write (overwrite on re-run) `{plan-folder}/review.md` with frontmatter `slug`, `date`, `type: plan-review`, `reviewed_by`, then the 4-section report.

Legacy single-file plan → `{docsDir}/plans/<slug>-review.md`.

Delete `${CF_DOCS_ROOT}/reviews/<slug>-plan-prompt.md`. Keep `*-plan-result-*.md` and `.log` sidecars.

### Step 8: Apply findings

If any 🚨 or ⚠️ findings exist:

- **`--fix`:** do not Ask. Print `> 🔧 Applying Critical/Important findings to the plan.` and apply immediately.
- **Default:** Ask the user: "Apply Critical/Important findings to the plan?" Apply only if they agree.

When applying, edit `README.md` / `phase-N-*.md` yourself (do **not** dispatch cf-implementer). For a legacy single-file plan, edit `<slug>.md`.

**MUST guardrails:**

- Apply only 🚨 Critical and ⚠️ Important findings.
- Never touch `✅ DONE` rows.
- Never touch frontmatter (`slug` / `auto` / `status`).
- Never touch the `## AUTOPILOT` block.
- New tasks are added as `⬜ TODO` rows in Progress **and** numbered entries in Tasks.
- If a finding adds or changes files and `{docsDir}/context/<slug>.json` exists, update its `relevant_files`.

💡 Suggestions are listed only — do not apply them.

After applying (or if the user declines / nothing to apply), print a short summary and:

- Plan already has progress → `> Next: /cf-plan-resume <slug>`
- Plan not yet in execution → remind the user to return to `/cf-plan` Step 7.

## Completion Protocol

- **DONE** — Review saved to `review.md`. Show the 4-section report.
- **DONE_WITH_CONCERNS** — Review saved but 🚨 findings remain unapplied.
- **BLOCKED** — Could not resolve the plan (invalid slug, path outside cwd/`{docsDir}`, or no matching plan).

## Rules

- Do not edit application code. This skill reviews plans, not diffs.
- Do not run verify steps. Reviewers spot-check existence only (files / functions / commands named in tasks).
- Do not review a code diff — send the user to `/cf-review`.
- External reviewers always run sandboxed read-only.
- Never block because an external reviewer is unavailable, timed out, errored, or empty.
- Keep wording host-neutral: the flag matching the current host is skipped; the in-session label comes from `HOST:`.