OpenParable
Skip to content
← Back to skills

Plan Critique Loop

Productivity
plan-critique-loop

Plan Critique Loop is an Agent Skill for productivity published in the besimple-oss/broccoli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Critique and revise an existing plan doc up to 3 iterations, using accept/reject triage and stopping early when no important feedback remains. Use when refining a plan/*.md before implementation.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/besimple-oss/broccoli/blob/HEAD/prompt-templates/skills/plan-critique-loop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/plan-critique-loop, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Plan Critique Loop (up to 3 iterations)

Input: an existing plan doc path (for example: plan/my-feature.md).

Preconditions

  • Confirm you are in the intended repo: git rev-parse --show-toplevel
  • Confirm the plan doc exists: test -f <plan-doc-path>
  • Ensure git can create commits before running the loop (user.name/user.email configured).
  • Do not start implementation in this skill; only critique and revise the plan.
  • Ensure both CLIs are available (codex and claude) because critic/responder must be different vendors.

Expected runtime

Typically runs 15–45 minutes, but allow at least 120 minutes.

Do not interrupt/restart the subagent if it looks stuck. The loop script owns stuck/timeout handling and will exit on its own when it completes or when --timeout is reached. Prefer watching the periodic heartbeat output (--heartbeat-seconds) instead of tailing logs.

If you use --progress-log, do not tail -f it into the main context unless you must debug; prefer checking progress via log line counts (for example: wc -l <progress-log>) and/or the heartbeat counters.

Why Claude sometimes looked “stuck”

Claude Code print mode can be silent in --output-format text until it finishes (including during tool work). This repo defaults Claude subprocesses to --output-format stream-json --include-partial-messages so the wrapper sees measurable progress and inactivity timeouts mainly trigger on true hangs.

Loop

Run the critique loop script:

resolve_skill_dir() {
  local name="$1"
  local repo_root=""
  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

  local candidates=(
    "$repo_root/.agents/skills/$name"
    "$repo_root/.claude/skills/$name"
    "$HOME/.agents/skills/$name"
    "$HOME/.codex/skills/$name"
    "$HOME/.claude/skills/$name"
  )

  for d in "${candidates[@]}"; do
    if [[ -d "$d" ]]; then
      echo "$d"
      return 0
    fi
  done

  echo "Error: skill '$name' not found in repo-scoped or user-scoped skill dirs." >&2
  return 1
}

PLAN_CRITIQUE_LOOP_SKILL_DIR="$(resolve_skill_dir plan-critique-loop)"
python3 "$PLAN_CRITIQUE_LOOP_SKILL_DIR/scripts/run_critique_loop.py" <plan-doc-path>

Options:

  • --max-iterations N (default: 3)
  • --cli codex|claude (pin responder provider; critic is selected from provider pool and always differs from responder)
  • --provider-pool codex,claude (provider pool for both subprocesses; critic/responder vendors are always distinct)
  • --codex-model-pool ... and --claude-model-pool ... (random model selection; supports model@effort)
  • --progress-log <path> and --heartbeat-seconds N
  • --artifacts-dir <path> (optional; stores critic outputs for responders to read)
  • --timeout N (per-subprocess timeout in seconds; default: 7200)

Claude automation knobs (env vars; defaults shown):

  • PROMPT_TEMPLATES_CLAUDE_OUTPUT_FORMAT=stream-json (text|json|stream-json)
  • PROMPT_TEMPLATES_CLAUDE_MIN_VERSION=2.1.33 (fail fast if installed Claude Code is older)
  • PROMPT_TEMPLATES_CLAUDE_STREAM_LOG_MAX_BYTES=10485760 (per invocation; set 0 for unlimited)
  • PROMPT_TEMPLATES_CLAUDE_INACTIVITY_TIMEOUT_SECONDS=180 (set 0 to disable; in text/json mode it is disabled unless explicitly set)
  • PROMPT_TEMPLATES_CLAUDE_INACTIVITY_MIN_RUNTIME_SECONDS=30
  • PROMPT_TEMPLATES_CLAUDE_PROMPT_BUDGET_BYTES=0 (disabled by default; set >0 to enforce)

Behavior:

  • Each iteration runs in two fresh subprocesses:
    • Critic subprocess: selected from the provider pool and generates critique feedback (it reads the plan doc from disk).
    • Responder subprocess: triages critic feedback (agree/reject) and applies only agreed edits using the selected responder provider/model (it reads the plan doc from disk and reads critic output from the artifacts dir).
  • The script enforces that critic and responder always run on different vendors (codex vs claude).
  • Any subprocess that runs on Codex is invoked with --sandbox danger-full-access, -a never, and --search.
  • Claude subprocesses run in non-interactive mode with --dangerously-skip-permissions, in a native PTY (when available), and have an inactivity timeout.
  • On classifiable Claude automation failures the script retries once. If critic=claude fails after retry and responder is not pinned to codex, it performs a role-swap fallback and re-runs the iteration with critic=codex,responder=claude.
  • After each iteration, the script stages and commits plan-file edits (if any) before starting the next iteration.
  • The script stops early when responder reports no actionable feedback.
  • No manual accept/reject input is required for the loop to revise the plan.
  • After completion, it appends a deterministic changelog block to the plan doc recording:
    • total iterations executed;
    • which iteration (if any) stopped due to no feedback.
  • Default model pools:
    • Codex: gpt-5.2@high
    • Claude: claude-opus-4-6[1m]@high

Troubleshooting:

  • --progress-log may include full tool outputs (plan contents, file contents). Treat it as sensitive; stream-json logs are truncated by default via PROMPT_TEMPLATES_CLAUDE_STREAM_LOG_MAX_BYTES.