Plan and Execute

Mission

Create bite-sized implementation plans and proactively dispatch execution to the cheapest capable backend.

Hard Rules

1. •Route first. Do not self-implement Codex-eligible tasks before trying Codex.
2. •Route repository exploration for code tasks to Codex (read-only) before using Claude-native Explore/Task subagents.
3. •Route external research first. Do not do Gemini-eligible research in Claude by default.
4. •Keep architecture and product decisions in Claude.
5. •Codex is fail-closed by default. On Codex failure, ask the user for explicit approval before Claude/Sonnet fallback.
6. •Verify outputs before handoff.

1) Backend Readiness Check

Before execution, check availability:

command -v codex >/dev/null && echo "codex:ok" || echo "codex:missing"
command -v gemini >/dev/null && echo "gemini:ok" || echo "gemini:missing"

If Codex is missing for code tasks, stop and ask the user whether to proceed on Claude/Sonnet fallback.
If both backends are missing, report routing unavailability and ask before fallback.

2) Planning Requirements

• •Save plan as docs/plans/YYYY-MM-DD-feature.md.
• •Keep tasks 2-5 min each.
• •Every task must include:
  • •objective
  • •concrete file paths
  • •command(s)
  • •routed backend
  • •done criteria
• •Add a routing summary table to the plan.

3) Routing Policy

4) Prompt Contract for Routed Tasks

For every routed task prompt, include:

1. •Goal and acceptance criteria
2. •File paths and constraints
3. •Required commands/tests
4. •Expected output format (patch, summary, citations, etc.)

5) Execution Loop

1. •Load the plan.
2. •Execute in batches of up to 3 independent tasks.
3. •For independent option/research tasks, run Codex + Gemini concurrently with parallel-runner.sh.
4. •For all other tasks, dispatch to mapped backend first.
5. •Handle exit codes per fallback policy.
6. •Review and verify outputs between batches.
7. •Continue until all tasks are complete.

6) Codex CLI Usage

Accepted invocation formats:

• •Standard: codex-runner.sh "<prompt>" [sandbox-mode] [working-dir]
• •Legacy-compatible: codex-runner.sh "<prompt>" <working-dir> [sandbox-mode]
• •Legacy default: if only <working-dir> is provided, sandbox defaults to workspace-write

"${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/codex-runner.sh" \
  "$PROMPT" \
  workspace-write \
  /path/to/project

"${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/codex-runner.sh" \
  "$PROMPT" \
  read-only \
  /path/to/project

"${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/codex-runner.sh" \
  "$PROMPT" \
  /path/to/project

"${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/codex-runner.sh" \
  "$PROMPT" \
  /path/to/project \
  read-only

7) Gemini CLI Usage

"${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/gemini-runner.sh" \
  "$PROMPT"

8) Parallel Multi-Model Option Mode

Use this when you want diverse options from both models for the same objective.

/bin/bash "${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/parallel-runner.sh" \
  "$PROMPT" \
  /path/to/project \
  read-only

Advanced form with different prompts:

/bin/bash "${CLAUDE_PLUGIN_ROOT}/skills/plan-and-execute/parallel-runner.sh" \
  --codex-prompt "Analyze implementation trade-offs in this repository." \
  --gemini-prompt "Research latest external best practices and cite sources." \
  --workdir /path/to/project \
  --codex-sandbox read-only

9) Fallback and Error Handling

10) Environment Defaults

Telemetry note:

• •Router metrics now track token offload plus backend attempt/success/failure health.
• •Statusline format: Offload C:<tokens> G:<tokens> Σ:<tokens> | S/F C:<s>/<f> G:<s>/<f> | RL C:<remaining> G:<remaining|retry|N/A>.
• •Gemini rate-limit is best-effort (retry in Xs parsing); N/A means unavailable.

11) Anti-Patterns

• •Creating a plan without a backend route per task
• •Using Claude-native Explore/Task subagents for Codex/Gemini-eligible work before attempting routed runners
• •Implementing code directly in Claude when Codex is available
• •Doing external research directly in Claude when Gemini is available
• •Skipping parallel-runner.sh for independent option-gathering tasks
• •Skipping verification between batches
• •Falling back without first attempting the mapped backend
• •Proceeding on Claude/Sonnet after Codex failure without explicit user approval