git:20260827.debd979 to git:20260827.45d78ea

- This skill is automatically invoked by other skills — you don't always need to run it manually:

-

- - **`/cf-plan`** — runs `/cf-review` after all implementation tasks complete

- - **`/cf-fix`** — runs `/cf-review` after the fix is verified

- - **`/cf-optimize`** — runs `/cf-review` after the optimization is measured and verified

- Custom guide — auto-loaded below (if the raw command shows instead of its output, run it yourself):

-

- If output is not empty, integrate returned sections: `## Before` → before first step, `## Rules` → apply throughout, `## After` → after final step.

- - If `$ARGUMENTS` is empty, review all uncommitted changes (`git diff` + `git diff --staged`)

- - If `$ARGUMENTS` is a file path, review that file

- - If `$ARGUMENTS` is a commit range (e.g., `HEAD~3..HEAD`), review those commits

- - If `$ARGUMENTS` is a natural language description (e.g., "the auth logic changes"), review all uncommitted changes but **focus the review** on the described area — filter findings to only report issues relevant to that description

- - If `$ARGUMENTS` contains `--deep` or `--quick`, use that mode (override auto-detection)

- - If `$ARGUMENTS` contains `--with-codex` (or its alias `--codex`), set `codex=true` and strip the flag from `$ARGUMENTS` before any other parsing.

- - Otherwise, read `review.withCodex` from the config file (`CF_CONFIG_FILE`, default `.coding-friend/config.json`). If it is `true`, set `codex=true` (config-gated default; this is how auto-invokers like `/cf-plan`, `/cf-fix`, `/cf-optimize` opt in without passing the flag). If absent or `false`, `codex=false`.

- - When `codex=true`, the workflow runs Claude's own review (Steps 2–6) **and** a Codex review in parallel, then merges both (Steps 6.5–7). The Codex script (`run-codex-review.sh`) **auto-selects its scope** from git state so it covers committed work, not just the working tree: feature branch → `codex review --base <base>` (committed branch changes); on the base branch with unpushed commits → `--base <upstream>` (local commits not yet pushed); only uncommitted changes → `--uncommitted`; local-only repo → `--commit HEAD`. This lets Codex see a phase's changes even after they are committed — including on the base branch, where `gather-diff.sh` only reports uncommitted work (its committed-vs-base section is gated on being on a feature branch), so Codex covers committed-on-base work that Claude's own review would otherwise miss. Trade-off: a `--base`/`--commit` scope omits uncommitted/untracked files, and when Codex is unavailable that committed-on-base work degrades to a Claude-only review that may see nothing.

- - **Target compatibility:** the auto-scope above only matches the **default target** (empty `$ARGUMENTS`, or a natural-language description that still reviews the default change set). If `$ARGUMENTS` (after stripping flags) is a **file path** or a **commit range** (e.g. `HEAD~3..HEAD`), Claude reviews that specific target but Codex would review the unrelated default change set. In that case do NOT run Codex — print:

- Set `codex=false` and skip Steps 2.5/6.5.

- - After the codex block, parse `--claude`, `--gemini`, `--cursor`, `--grok` (and `--with-<agent>` aliases). Collect matched ones into an `agents=[…]` list; strip the flags from `$ARGUMENTS`.

- - **Host-match no-op:** read `HOST` from the session bootstrap context. Only skip a matching flag when there is **positive evidence** of the in-session host: a `HOST:` line exists **and** its value matches the flag. Concretely, if a `HOST:` line is present and equals `claude` and `--claude` was passed, drop `claude` from the list and print:

- If **no** `HOST:` line is present — e.g. running under a host that does not emit the coding-friend session bootstrap, such as Grok, Cursor, or Gemini — or its value is anything other than the requested flag, do **NOT** skip: run the requested reviewer. Never assume the in-session assistant is Claude just because a flag says `--claude`. When in doubt, run it: skipping wrongly loses a review the user explicitly asked for, whereas running an extra review is harmless.

- - When `agents` is non-empty, the workflow runs Claude's own review (Steps 2–6) **and** each requested agent review in parallel (Steps 2.5/6.5), then merges all surviving sources (Step 7). Each agent is invoked via `run-agent-review.sh`, which feeds `gather-diff.sh` output through `build-review-prompt.sh` and runs the headless CLI in read-only mode. The four agents review the **exact diff `gather-diff.sh` produces** — the same change set Claude's own review sees (deliberately different from Codex's auto-scope).

- - **Target compatibility:** same restriction as codex — only the **default target** (empty `$ARGUMENTS`, or a natural-language description). If `$ARGUMENTS` (after stripping flags) is a **file path** or **commit range**, print:

- Clear `agents=[]` and skip agent Steps 2.5/6.5.

- - If `$ARGUMENTS` contains `--out`, set `out=true` and strip the flag.

- - **Mutual exclusivity:** if `--out` is combined with any headless-agent flag (`--claude`/`--gemini`/`--cursor`/`--grok`/`--codex`), print:

- - `--out` implies the default target only (same restriction as codex); on a file-path/commit-range target, print the analogous warning and ignore `--out` (set `out=false`).

- - When `out=true`: run Claude's own review (Steps 2–6), then emit a `/cf-review-out`-style prompt file with Claude's findings embedded (see **Step 6.7**). Skip codex/agent Steps 2.5/6.5 and Step 7 merge. Display Claude's report to the user, then show the "📝 Review Prompt Ready" panel.

- Skip this step entirely when `codex=false`.

- Resolve the docs root and a label `YYYY-MM-DD-review`. Use `CF_DOCS_ROOT` (the absolute docs base dir from the session bootstrap context) so the result file lands in the project docs folder even when Claude is launched from a subdirectory — do NOT use the bare `docsDir` name with a cwd-relative path. Fallback: if `CF_DOCS_ROOT` is unset, use `$MAIN_REPO_ROOT/<docsDir>`. Spawn the Codex review as a **background Bash process** (`run_in_background: true`) so Claude's own review (Steps 3–6) runs concurrently:

- **Do NOT wait for or inspect the Codex result here.** Immediately proceed to Step 3 and run Claude's own review (Steps 3–6) while Codex runs in the background — that concurrency is the whole point. The harness automatically notifies Claude when the background process exits (do NOT poll, sleep, or check `/tasks` — per the Bash tool contract: "you'll be notified when it finishes"). The Codex exit status and result are checked later, in Step 6.5.

- For each agent in `agents`, spawn a background Bash process (`run_in_background: true`):

- Use the same `${CF_DOCS_ROOT}` and `<label>` as Codex. **Do NOT wait** — proceed immediately to Step 3.

- Determine review depth. Run the bundled script (one permission prompt instead of many):

-

- The script prints `KEY=value` lines: `FILES_CHANGED`, `LINES_CHANGED`, `SENSITIVE`, `CHANGED_FILES`, and `MODE`.

- Use the `MODE` value directly — no further calculation needed.

- | Mode | Condition | Behavior |

- | ------------ | -------------------------------------------------- | ----------------------------------------------------------------------- |

- | **QUICK** | ≤3 files AND ≤50 lines AND no sensitive paths | Layer 3: secrets + obvious injection only. Skip context research. |

- | **STANDARD** | 4–10 files OR 51–300 lines | Full 5-layer review. All security phases, concise. |

- | **DEEP** | >10 files OR >300 lines OR sensitive paths touched | Full 5-layer + extended security. Data flow tracing. Exploit scenarios. |

- If `SENSITIVE > 0`, always escalate to **DEEP** regardless of size.

- - **QUICK mode**: Skip this step entirely.

- - **STANDARD mode**: Search memory only (if `memory_search` tool is available). Call `memory_search` with: `{ "query": "<area being reviewed — e.g. auth, API, database>", "limit": 5 }`. Use results as context hints for the review.

- - **DEEP mode**: Launch the **cf-explorer agent** to understand callers, dependencies, and data flows around the changed files. Use the **Agent tool** with `subagent_type: "coding-friend:cf-explorer"`. Pass:

-

- > Explore the codebase context around these changed files: [list changed files]

- >

- > Questions to answer:

- >

- > 1. What calls these files/functions? (callers, entry points)

- > 2. What do these files depend on? (downstream effects)

- > 3. What conventions and patterns exist in the surrounding code?

- > 4. Are there related tests that should be checked?

-

- **Note:** cf-explorer already checks memory internally — do NOT call `memory_search` separately when using cf-explorer.

- Memory and explorer results are **hints** — always verify against actual code.

- Read changed files in full — do not review only the diff, understand the context.

- Use the **Agent tool** with `subagent_type: "coding-friend:cf-reviewer"`. Pass the full context:

- > [full content of each changed file from Step 5]

- > [memory search results or cf-explorer findings, if any]

- Wait for the agent to return its report.

- Skip this step entirely when `codex=false`.

- 1. **Wait for the Codex background process to finish.** By the time the cf-reviewer agent (Step 6) returns, the harness has likely already delivered the Codex completion notification. If it has not yet arrived, wait for it — do NOT poll or sleep. Only read the result file after the process has exited.

- 2. **Check the Codex exit status** (from the background process — its `CF_CODEX=...` stderr line and exit code):

- Set `codex=false` and skip the rest of this step (Step 7 will use the cf-reviewer report as-is).

- - `CF_CODEX=error` (non-zero exit) → Codex failed (e.g. not logged in). Print:

- Set `codex=false` and skip the rest of this step.

- - `CF_CODEX=empty` (exit 0, no result file) → nothing committed or uncommitted to review. Print:

- Set `codex=false` and skip the rest of this step.

- - `CF_CODEX=ok <file>` (exit 0) → the review was written to the result file; continue. (An optional `CF_CODEX_SCOPE=...` line on stderr records which scope was used.)

- 3. Normalize the raw Codex result into the standard 4-section format:

- (Use the same `${CF_DOCS_ROOT}`-based path the result was written to in Step 2.5.) This emits a `## 🔍 Codex Review` block with findings tagged `**[Codex]**` and severities mapped (`[P2]`→⚠️, `[P3]`→💡, anything else incl. `[P1]`/`[P0]`→🚨 so a top severity never fails silent). It never drops content — unparseable output is folded into the Summary section.

- Never block the workflow on Codex — any failure degrades gracefully to a Claude-only review.

- 1. **Wait for each agent's background process to finish** (same wait contract as Codex — harness notification, no polling).

- 2. **Check each agent's exit status** (`CF_AGENT=…` stderr line and exit code):

- - `CF_AGENT=unavailable` (exit 127) → print:

-

- > ⚠ \<Agent\> unavailable (not on PATH) — proceeding without it.

-

- Drop that agent.

-

- - `CF_AGENT=error` (non-zero exit) → print:

-

- > ⚠ \<Agent\> review failed (\<reason from stderr\>) — proceeding without it.

-

- Drop that agent.

-

- - `CF_AGENT=empty` (exit 0) → print:

-

- > ⚠ \<Agent\> found no changes to review — proceeding without it.

-

- Drop that agent.

-

- - `CF_AGENT=timeout` (exit 124) → print:

-

- > ⚠ \<Agent\> review timed out (\>Ns) — proceeding without it.

-

- Drop that agent. (N = `review.agentTimeout` from config, default 300.)

-

- - `CF_AGENT=ok <file>` (exit 0) → keep its result file. **No normalize step** — stdout is already CF-format.

- Never block the workflow on any external agent — failures degrade gracefully.

- After Step 6 returns Claude's report, emit a `/cf-review-out`-style prompt with Claude's findings embedded:

- 2. Build the prompt file:

- 3. Show the same "📝 Review Prompt Ready" panel, copy-paste external-agent instruction, and the `> When all external agents finish, run /cf-review-in <label> to collect all results.` reminder that `cf-review-out` Step 4 shows.

- 4. Display Claude's own report to the user **before** the panel so they see the findings that were embedded.

- 5. Skip Steps 7–10's normal completion banner — the review was exported, not completed in-session. Proceed to Step 8 (mark reviewed) if appropriate, then stop.

- **When no external sources survived** (`codex=false` and all agents dropped): the result of Step 6 is the final formatted report (🚨 Critical / ⚠️ Important / 💡 Suggestions / 📋 Summary). Do NOT reformat or restructure it — use it as-is in Step 10.

- **When any external source survived** (codex and/or one or more agents): merge all reviews through the reducer. Dispatch the **cf-reviewer-reducer** agent (Agent tool, `subagent_type: "coding-friend:cf-reviewer-reducer"`) with Claude's report as Source 1 and each surviving external review as an additional numbered source:

- > [the review content — normalized Codex block for Codex; raw result file for claude/gemini/cursor/grok agents]

- > Tag each external source's findings with `[\<Agent\>]` provenance (Codex → `[Codex]`, gemini → `[Gemini]`, etc.). Where multiple sources flag the same file:line for the same issue, merge into one finding (keep highest severity) and note agreement (raises confidence). Output the standard 🚨/⚠️/💡/📋 format.

- Use the reducer's merged output as the report in Step 10.

- If the review found **architectural insights** or **recurring patterns** worth preserving, call `memory_store` with:

-

- - type: "fact"

- - importance: 3

- - source: "auto-capture"

- - title/description/tags/content summarizing the insight

-

- Skip if the review was routine with no notable findings.

- Display the full report followed by the status banner in a **single message**.

-

- **IMPORTANT**: The structured report from step 8 and the banner below MUST appear together in the same final response. Do NOT split them across separate messages. This ensures the complete review is visible in the last message.

- Display the cf-reviewer's report first, then append the appropriate banner. When any external source contributed, add a `· Reviewed by: <in-session> + …` suffix listing the in-session reviewer plus each external agent/codex that actually contributed (e.g. `· Reviewed by: Claude + Codex + Gemini`). Label the in-session reviewer by the `HOST` value from the session bootstrap context, capitalized (`claude` → `Claude`, `codex` → `Codex`); if no `HOST:` line is present, use the neutral label `In-session AI` — do NOT hardcode `Claude`, since the assistant running this skill may be another host (Grok, Cursor, …). Omit the suffix when only the in-session reviewer ran.

- Skip this step's banner when `out=true` — Step 6.7 already showed the export panel.