ExecPlan Review Loop (Orchestrator)

Invocation keyword: $execplan-review-loop

When to use

Use when you must create or refine an ExecPlan.md and run a strict, headless Codex CLI review loop (draft → review → fix → re-review) until PASS or max-iterations is reached.

Inputs and outputs

Inputs:

• •ExecPlan path (default: ./ExecPlan.md)
• •Review output path (default: ./.codex/execplan_review.json)
• •PLANS.md at repo root (must be read and followed to the letter)

Outputs:

• •Updated ExecPlan.md that passes review
• •JSON review output at the configured path

Step-by-step procedure

1. •Read PLANS.md from repo root fully. If it is not already in context, explicitly open and re-read it before drafting the plan.
2. •Draft or update ExecPlan.md to comply with PLANS.md and the hard requirements below.
3. •Run the review script:
   • •bash skills/execplan-review-loop/bin/review_execplan.sh ./ExecPlan.md
4. •Interpret review JSON:
   • •PASS: stop.
   • •PASS_WITH_FIXES: apply fixes, update living sections, re-run.
   • •FAIL: apply fixes, update living sections, add revision note, re-run.
5. •Repeat until PASS or max-iterations is hit.

Loop algorithm (max-iterations guard)

Default max-iterations: 8

Algorithm:

• •For i in 1..max-iterations:
  • •Ensure ExecPlan.md is current.
  • •Run review_execplan.sh.
  • •If verdict == PASS: stop successfully.
  • •If verdict == PASS_WITH_FIXES: revise and continue.
  • •If verdict == FAIL: revise and continue.
• •If max-iterations exceeded: stop and surface unresolved blocker/high issues.

Hard requirements for ExecPlan content (must pass review)

A) Follow PLANS.md

• •Read PLANS.md from repo root and follow it to the letter.
• •State early in ExecPlan.md that PLANS.md was read and followed.

B) Self-contained and novice-friendly

• •ExecPlan.md must be fully self-contained; assume only the working tree and this plan.
• •No “as discussed earlier” or external docs for key steps.
• •Define any term-of-art immediately or avoid it.

C) Living document sections (mandatory)

• •

  Progress (checkbox list with timestamps)

• •

  Surprises & Discoveries

• •

  Decision Log

• •

  Outcomes & Retrospective

D) Outcome-first acceptance (observable behavior)

• •Purpose and user-visible behavior come first.
• •Acceptance criteria must be observable/testable with exact commands and expected outputs (or fail-before/pass-after tests).

E) Formatting rules for ExecPlan.md

• •ExecPlan.md contains only the plan; omit outer triple backticks.
• •No triple-backtick fences anywhere.
• •Use indented blocks for commands/transcripts/diffs/code.
• •Use proper Markdown headings (#, ##, ...).
• •Include two blank lines after every heading.
• •Prefer plain prose. Use lists only when needed; checklists only in Progress.

F) Revision discipline during the loop

• •Update all affected sections consistently.
• •Add Decision Log entries for substantive design changes with date/author.
• •Add timestamped Progress entry for each revision cycle.
• •Append a short “Revision note” at the bottom: what changed and why.

Troubleshooting

Common FAIL causes and fixes:

• •Missing living sections: add them verbatim and keep updated.
• •Progress missing timestamps or checkbox list: convert to checkboxes with dates.
• •Triple-backtick fences present: replace with indented blocks.
• •Acceptance not testable: add commands + expected outputs or fail→pass tests.
• •Relies on external docs: embed necessary steps in the plan.
• •Missing PLANS.md compliance statement: add early and align content.

Safety rules

• •Review runs must be read-only: use codex exec with --sandbox read-only.
• •Do not run destructive commands without explicit backups/rollback steps.
• •Keep review output and plan edits separate; never modify repo during review.

Bundled resources

• •review/review_schema.json: JSON schema for review output
• •review/review_prompt.md: reviewer prompt with rubric and output contract
• •bin/review_execplan.sh: headless review runner
• •bin/iterative_review.md: runbook
• •bin/parse_review.py: optional JSON parser