/volley:review-plan

Hand a plan to Codex. Get back a review. Write it to disk, show it inline.

Steps for Claude

1. Verify .volley/ is initialized and the lock allows Claude to act.

   [ -d .volley ] || { echo "ERROR: .volley/ not found. Run /volley:setup first." >&2; exit 1; }
   [ -f .volley/STATE ] || { echo "ERROR: .volley/STATE not found. Run /volley:setup first." >&2; exit 1; }
   . "${CLAUDE_PLUGIN_ROOT}/scripts/lib.sh"
   volley_state_assert_active .volley/STATE claude || exit 1

   If the assert fails, the helper already printed a refusal message. Stop.
2. Resolve the plan path.
   • If user passed a path argument, use it.
   • Otherwise: ls -t .planning/**/PLAN.md 2>/dev/null | head -1 (or use Glob tool with pattern .planning/**/PLAN.md and take the most recent by mtime).
   • If no plan found, tell user "No PLAN.md found under .planning/. Pass an explicit path, or check that you've run /gsd:plan-phase to create one." and stop.
3. Read the plan and HANDOFF.
   • Read the plan file's full content.
   • Read .volley/HANDOFF.md for acceptance criteria.

4. Build the review prompt for Codex.

   Write this prompt to .volley/plan-review-prompt.md (gitignored; scripts/codex-exec.sh sends it to Codex on stdin):

   You are reviewing an implementation plan. Be specific and concrete.
   
   PROJECT CONTEXT: before reviewing, read these files in the repo (read-only): <list every context.required file, every context.optional file that exists, and the managedCheckpoint (default .volley/CHECKPOINT.md) if it exists>.
   
   ACCEPTANCE CRITERIA (from HANDOFF.md):
   <paste HANDOFF.md content>
   
   PLAN TO REVIEW:
   <paste plan content>
   
   Provide your review in this format:
   
   ## Verdict
   APPROVE | CONCERNS | REJECT
   
   ## Strengths
   - (specific things the plan gets right)
   
   ## Concerns
   - (specific issues, with file/line refs from the plan if applicable)
   
   ## Suggested changes
   - (concrete edits, not vague advice)
   
   Keep it under 500 words. Skip filler.

5. Resolve the review role's model/effort/context from config. Read .volley/config.json (parse it yourself; absent = defaults). Take codex.review.model, codex.review.reasoningEffort, and apply any .volley/local.json modelOverrides.review. Check context.required files all exist - if any is missing, stop with a clear error naming the file (fail early). Note which context.optional files exist; missing optional files are reported and skipped.
6. Invoke Codex via scripts/codex-exec.sh. (Codex 0.156 removed codex mcp-server, so Volley no longer uses an MCP bridge; reviews run through codex exec.)
   • Resume or fresh - follow codex.review.continuity (absent = session-only), and only ever resume when .volley/local.json has roles.planReview.threadId and the stored repository matches the live checkout (volley_repo_identity_matches "<canonicalRoot>" "<remote>"):
     • resume-if-safe: pass --resume <threadId>.
     • session-only (the default): pass --resume <threadId> only if that id was saved by a review earlier in this same Claude conversation (a follow-up round). A fresh conversation or a restart starts a new Codex session.
     • rehydrate: never pass --resume; every review starts fresh from the context files.
   • Run it with a long timeout (high-effort reviews take minutes; prefer running it in the background):

     . "${CLAUDE_PLUGIN_ROOT}/scripts/lib.sh"
     bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh" \
       --prompt-file .volley/plan-review-prompt.md --out .volley/plan-review-raw.md \
       --cwd "$(volley_repo_root)" --model "<resolved model or inherit>" --effort "<resolved effort or inherit>" \
       [--resume "<threadId>"]

     The script always runs Codex read-only (--sandbox read-only; on resume -c sandbox_mode="read-only"), validates the model/effort tokens, and prints SESSION_ID=<id> and CONTINUITY=<fresh|resumed|fallback:...> as its last lines.
   • Continuity: save SESSION_ID to .volley/local.json under roles.planReview (threadId, updatedAtUtc). If CONTINUITY starts with fallback:, tell the user the saved session could not be resumed (give the reason after the colon) and that this review started fresh from the files.
   • Errors: exit 2 = bad config (e.g. an unsafe model token) - surface it and stop; exit 3 = Codex wrote no review; any other non-zero exit = show Codex's stderr verbatim. An unavailable model or bad reasoning level is surfaced as-is - never silently substitute another model. An auth error means the user should run codex login.

7. Write the review to .volley/PLAN-REVIEW.md. Prepend a small header with the plan path and timestamp, then Codex's response:

   # Codex Plan Review
   
   **Plan:** <plan path>
   **Reviewed:** <ISO timestamp>
   
   ---
   
   <Codex's response verbatim, i.e. the contents of .volley/plan-review-raw.md>

8. Surface the review inline. Print the file content (or a clean summary if it's long) so the user reads it without opening another editor.
9. Print the next-step block. Decide based on Codex's verdict:
   • If APPROVE: volley_next_step "/volley:implement" "Plan approved by Codex. Open Codex in a new terminal tab to build."
   • If CONCERNS: volley_next_step_options "Option A|/volley:implement|Accept review and proceed anyway" "Option B|edit PLAN.md|Address concerns then re-run /volley:review-plan"
   • If REJECT: volley_next_step "edit PLAN.md" "Address Codex's concerns and re-run /volley:review-plan."