olliecrow/codex-custom-review

codex-custom-review

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): preflight -> custom review -> summarize findings -> run any requested follow-up review -> final synthesis.
• Keep looping until actual completion criteria are met: the requested custom review has run, the result is captured, and no in-scope follow-up review remains.
• Run organise-docs frequently during execution when durable review-routing decisions or reusable prompt patterns appear.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time.
• Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the requested custom review has run, or the run is explicitly marked blocked with concrete blocker evidence.
• Workflow completion: every required workflow step is resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (command output, exit status, or written rationale) before advancing.
• Verification completion: the command path used is stated, the review process reached a terminal exit state, and the final review output is summarized.
• Findings completion: findings are reported as review output, and lack of findings is stated clearly when the review returns none.
• Loop completion: no actionable in-scope next step remains under the current custom review request.

Terminal state examples (adapt to skill)

• done: multicodex exec review - or fallback codex exec review - exited successfully, and the custom review result has been summarized.
• blocked: neither multicodex nor codex is available, auth fails after bounded retry, or the CLI exits repeatedly with a non-transient error; include the exact command and failure.
• not-applicable: the user explicitly wanted a branch/commit/uncommitted diff review rather than custom review; route to git-review or the relevant Codex diff-review command instead.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Overview

Use this skill for Codex's custom review mode: a free-form review prompt supplied directly to the review subcommand.

This is different from diff-bound review modes:

• Do not use --commit.
• Do not use --uncommitted.
• Do not use --base.
• Do not pass a literal /review ... prompt to codex exec; in non-interactive CLI use, that arrives as normal prompt text, not as the slash command.

The default command must be profile-neutral:

multicodex exec review - <<'EOF'
<custom review instructions>
EOF

If multicodex is unavailable, fall back to:

codex exec review - <<'EOF'
<custom review instructions>
EOF

Trigger phrases

Use this skill when the user asks for intents like:

• use /review
• custom review
• run Codex review with these instructions
• use the custom review feature
• review this with a custom prompt
• do not review a commit/diff; use custom review

Skill composition

• Use codex-custom-review for free-form Codex review instructions.
• Use git-review for branch-vs-main readiness reviews, merge-risk reviews, or severity-first repo review that should be performed by the current agent.
• Use deepreview only when the user asks for DeepReview or a monitored DeepReview run.
• If multiple review skills might apply, prefer the one matching the review mechanism the user named. For /review or custom Codex review, use this skill.

Workflow

1. Preflight:

   • Check command -v multicodex.
   • If missing, check command -v codex.
   • If neither exists, mark the run blocked.
   • If behavior is uncertain, inspect codex exec review --help and confirm the prompt argument supports - for stdin.

2. Build the custom review prompt:

   • Use the user's review instructions as the main prompt.
   • Add missing operational guardrails only when they preserve the user's intent, for example: "This is a custom review. Do not bind the review to --commit, --uncommitted, or --base unless the prompt explicitly asks to inspect such a diff."
   • Include scope, files, risk areas, desired severity format, and verification expectations when the user provided them.
   • Keep the prompt custom-review-specific. Do not convert it into a commit, branch, or uncommitted-change review.

3. Execute the review:

   • Prefer multicodex exec review - with the prompt on stdin.
   • Do not specify a multicodex account or profile by default.
   • Use codex exec review - only when multicodex is not available or cannot launch after a bounded retry.
   • Do not use multicodex run <profile> -- ... unless the user explicitly asks for a specific account/profile.
   • Do not include --commit, --uncommitted, --base, or --title for custom review.

4. Monitor to completion:

   • Keep the command attached until it exits.
   • If it starts a long review, provide short progress updates and continue polling.
   • If it fails because multicodex is missing or unavailable, retry once with codex exec review -.

5. Report:

   • State which command path was used: multicodex exec review or codex exec review.
   • Summarize the review's findings in plain English.
   • Include the exact blocker and fallback attempted if the run failed.
   • If the custom review returned no findings, say that clearly.

Prompt templates

Use stdin for robust quoting:

multicodex exec review - <<'EOF'
Custom review task:
- Scope: <files, repo area, artifact, or question>
- Review for: <correctness, security, realism, race conditions, data leakage, etc.>
- Output: findings first, ordered by severity, with file/line evidence where applicable.
- This is custom review mode. Do not bind the review to --commit, --uncommitted, or --base.
EOF

Fallback only when multicodex is unavailable:

codex exec review - <<'EOF'
Custom review task:
- Scope: <files, repo area, artifact, or question>
- Review for: <correctness, security, realism, race conditions, data leakage, etc.>
- Output: findings first, ordered by severity, with file/line evidence where applicable.
- This is custom review mode. Do not bind the review to --commit, --uncommitted, or --base.
EOF