ccc-review

name	ccc-review
description	audit current branch, security posture, performance hotpaths, or run full project x-ray. Spawns the matching specialist agent in the background; findings land at…
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Workflow","Agent","AskUserQuestion","TodoWrite","mcp__ccd_session__spawn_task","mcp__ccd_session__mark_chapter"]
argument-hint	[audit type: diff | security | perf | xray]

/ccc-review — Audit your work

Click-first review flow. Four audit types, one specialist agent per pick, one scorecard artifact. User picks the lens, the agent works in the background, the markdown report lands in tasks/reviews/.

Broad reviews/audits run workflow-first — fan out by dimension, adversarially verify findings before acting. See commander/cowork-plugin/rules/workflow-first.md.

Session markers

• At the START of review (after user picks an audit type): call mcp__ccd_session__mark_chapter with title: "Code review: <branch>" and summary: "<audit-type> audit on <branch>".
• At COMPLETION (when the agent reports back or findings are surfaced): call mcp__ccd_session__mark_chapter with title: "Review complete" and summary: "<N> findings — <blocker-count> blocking".

Sidebar chips (spawn_task)

Refute before chips (Agent fallback only — the workflows already verify): when findings came from the Agent-based flow, dispatch ONE fresh refute agent before any chip fires: "Adversarially verify these findings — try to REFUTE each. Default verdict PLAUSIBLE unless you confirm it from the actual code (then CONFIRMED); drop anything you refute." Only CONFIRMED 🔴/🟠 findings become chips; PLAUSIBLE ones stay as markdown bullets marked for manual confirmation.

After findings are verified, spawn ONE mcp__ccd_session__spawn_task chip per confirmed 🔴 Critical or 🟠 High blocker — each chip is a self-contained action for a fresh session:

• title: imperative phrase under 60 chars (e.g., "Fix SQL injection in src/auth.ts:42")
• prompt: self-contained — include file path, line number, issue summary, CWE/OWASP reference if applicable, and suggested fix direction. The spawned session has no memory of this conversation.
• tldr: 1-2 sentences plain English, no code blocks.

For 🟡 Medium and ℹ️ Nit findings: surface via markdown bullets + TodoWrite only — NOT spawn_task chips. Chips are for blockers that warrant a dedicated fix session.

Response shape (EVERY time)

Output exactly these three sections in order:

1. Brand header (one line, markdown)

**CC Commander** · /ccc-review · Audit before you ship

2. Context strip (one paragraph)

Detect review context with four quick reads (parallel Bash, silent on failure):

• git rev-parse --abbrev-ref HEAD → current branch
• git rev-list --count main..HEAD 2>/dev/null → commits ahead of main
• git diff --shortstat main..HEAD 2>/dev/null → diff size
• test -d .github/workflows && echo yes → CI presence

Render one line:

🧭 Branch: <branch> · commits ahead of main · files / lines changed · CI: <yes/no>

If no diff detected: "🧭 No diff vs main — I'll audit the whole project instead (xray recommended)."

3. The picker — AskUserQuestion with 4 audit types

Read ${CODEX_PLUGIN_ROOT}/menus/ccc-review.json for canonical option data. Surface the 4 non-back choices.

question: "What should I audit?"
header: "CC Commander Review"
multiSelect: false
options:
  - label: "📊 Review current branch"
    description: "Diff vs main — PR-quality summary before you open a PR."
    preview: "<N> commits · <X> lines · reviewer agent does a full 4-dimension pass."
  - label: "🔐 Security audit"
    description: "OWASP Top 10 + secrets + dependency audit. Severity-rated report."
    preview: "security-auditor agent. Catches injection, auth flaws, exposed secrets, vulnerable deps."
  - label: "⚡ Performance"
    description: "Hot-path scan, bundle size, N+1 queries, flame-graph pointers."
    preview: "performance-engineer agent. Flags hot paths, unbounded queries, resource leaks."
  - label: "🩻 Full project x-ray"
    description: "Health scorecard across code, docs, tests, deps, CI."
    preview: "Routes to ccc-xray — full health pass, not just the diff."

Recommendation logic (prepend ⭐ to ONE label):

• Branch ahead of main + uncommitted changes → ⭐ "Review current branch"
• package.json touched in diff → ⭐ "Security audit" (new deps = supply-chain risk)
• SQL / ORM files in diff → ⭐ "Security audit"
• Empty diff → ⭐ "Full project x-ray"
• Hot-path files (*/api/*, */routes/*, */hot/*) in diff → ⭐ "Performance"

Native workflow (Claude Code v2.1.154+)

If the Workflow tool is available, prefer invoking the bundled deep-review workflow for the "Review current branch" audit type instead of the Agent-based flow:

Workflow({
  scriptPath: "${CODEX_PLUGIN_ROOT}/workflows/ccc-deep-review.workflow.js",
  args: { base: "main" }
})

The workflow reviews the diff across 4 weighted dimensions (security 35%, performance 25%, correctness 25%, maintainability 15%), adversarially verifies each finding, and returns only confirmed issues — reducing false positives before they reach you.

For the Security and Performance audit types, route through the bundled audit workflow — it already supports scoped dimensions with REFUTE-framed verification of every finding:

// Security audit
Workflow({
  scriptPath: "${CODEX_PLUGIN_ROOT}/workflows/ccc-audit.workflow.js",
  args: { dimensions: ["security", "deps"] }
})

// Performance audit
Workflow({
  scriptPath: "${CODEX_PLUGIN_ROOT}/workflows/ccc-audit.workflow.js",
  args: { dimensions: ["performance"] }
})

Only Full x-ray stays on its own route (ccc-xray skill).

If Workflow is unavailable (older client or tool not allowed), fall back to the Agent-based flow below — leave that flow intact.

Step 2 — Dispatch matching specialist agent

On user pick, immediately dispatch the right agent in background. Never block the UI.

"Review current branch" (diff):

• Agent tool, subagent_type: general-purpose, model: sonnet, run_in_background: true
• Agent: invoke reviewer persona (see commander/cowork-plugin/agents/reviewer.md)
• Prompt: "Run the 4-dimension review (Security 35% / Performance 25% / Correctness 25% / Maintainability 15%) on git diff main..HEAD. Write findings to tasks/reviews/ccc-review-<YYYYMMDD>-diff.md. Group by severity (Critical / High / Medium / Low / Nit). Include file:line citations + suggested fixes. Return the artifact path + blocker count."

"Security audit":

• Same background pattern, invoke security-auditor persona (agents/security-auditor.md)
• Prompt: "Run OWASP Top 10 sweep on the diff (or whole codebase if no diff). Check: secrets in source, SQL injection, XSS, auth/authz flaws, insecure deserialization, SSRF, path traversal. Also run npm audit / pip audit if applicable. Severity-rate (🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low / ℹ️ Info) with CWE IDs. Write findings to tasks/reviews/ccc-review-<YYYYMMDD>-security.md."

"Performance":

• Same pattern, invoke performance-engineer persona (agents/performance-engineer.md)
• Prompt: "Hot-path audit. Scan for: N+1 queries, O(n²) in hot paths, unbounded loops/queries, missing indexes, resource leaks, bundle bloat. If .next/, dist/, or build/ exists, check bundle size. Write findings to tasks/reviews/ccc-review-<YYYYMMDD>-perf.md. Flag estimated vs measured impact explicitly."

"Full project x-ray":

• Route to the ccc-xray skill — do NOT spawn the agent here. Emit: "Loading x-ray workflow — ccc-xray runs a full health scorecard across code, docs, tests, deps, CI."
• Then behave as if the user had invoked /ccc-xray directly.

Step 3 — Return progress card to user

After dispatching the agent, emit ONE short card:

🔍 Audit running in background — <audit-type> on <branch>, agent ID <id>, ETA ~1–3 min. 📂 Findings will land at tasks/reviews/ccc-review-<YYYYMMDD>-<type>.md. 💡 Come back with /ccc-review status — I'll report blocker count + artifact path when done.

Anti-patterns — DO NOT do these

• ❌ Run the review inline — ALWAYS run_in_background: true
• ❌ Write findings to stdout only — every review produces a markdown artifact
• ❌ Use a single agent for all audit types — each has a specialist persona
• ❌ Skip severity grouping — reviewers MUST rate Critical / High / Medium / Low / Nit
• ❌ Offer more than 4 audit types in the picker
• ❌ Forget tasks/reviews/ directory — create it if missing (Bash mkdir -p)

Argument handling

• /ccc-review → root picker
• /ccc-review diff → skip picker, dispatch reviewer agent immediately
• /ccc-review security → skip picker, dispatch security-auditor
• /ccc-review perf → skip picker, dispatch performance-engineer
• /ccc-review xray → route to ccc-xray skill
• /ccc-review <anything else> → treat as free-form audit question; confirm scope with one AUQ, then dispatch reviewer

Artifact format (every review writes this)

# CCC Review — <type> — <YYYY-MM-DD>

**Branch:** <branch> · **Base:** main · **Diff:** <X> files / <Y> lines
**Agent:** <persona> · **Duration:** <Nm Ns>

## Summary
- <total findings> findings — <blocker count> blocking
- Overall verdict: Approve / Request Changes / Needs Discussion
- Overall risk: Low / Medium / High

## Findings

Every finding carries a verification verdict: **CONFIRMED** (independently verified against the actual code) or **PLAUSIBLE** (reported but not yet reproduced — verify before acting).

### 🔴 Critical (N)
- `file:line` — `<issue>` — **Verdict:** `CONFIRMED|PLAUSIBLE` — **Fix:** `<suggested fix>` — **Why:** `<rationale>`

### 🟠 High (N)
...

### 🟡 Medium (N)
...

### ℹ️ Nits (N)
...

## Next actions
1. ...

Brand rules

• Emoji-forward — 🔍 for audit, 🔴🟠🟡🟢 for severity, ✅ for approve, ❌ for block
• One artifact per audit — never delete previous reviews (keep history)
• Never mention the CLI — Desktop-plugin flow
• Always write to tasks/reviews/ — Ship flow reads from there

---

Bottom line: four audit tiles → matching specialist agent → one markdown artifact. User never waits, findings always traceable.

---

⚙️ Fable contract: plan before build · verifier ≠ worker · prove before alarm · loops need gates · leave durable state — rules/fable-method.md