optim-plans

all you need is a planning loop and an execution loop
both are elegantly featured in optim-plans
plans stay reviewable
execution stays gated
agents stay pointed at the work that matters

optim-plans turns "build me something" into a reviewed Markdown plan, records the decisions that shaped it, and keeps execution behind explicit approval. It gives Claude and Codex the two loops agentic coding actually needs: a planning-refining loop that keeps asking until the plan is real, and an execution loop that builds, verifies, and records what happened.

The Two Rings

Planning-refining ring

  question -> answer
       ^        |
       |        v
  smaller Q&A loop inside each planning decision

  PLAN_v1.md -> reviewer / criticizer -> PLAN_v2.md
       ^                                  |
       |__________________________________|

Execution ring

  prepare manifest -> approve -> start run worktree
        -> serial item checkpoint -> final audit -> auto-integrated run

The first ring fights the wrong-plan problem. It turns vague intent into a plan, then refines that plan with review or criticism. Each decision can open its own smaller question-answering ring, so uncertainty gets resolved before code changes.

The second ring fights the wrong-execution problem. It starts only from an immutable manifest-bound human approval, runs serial checkpointed work in one controller-owned worktree and branch, verifies with controller-run commands and Git audits, then automatically fast-forwards the clean checked-out destination and records integrated after the full local proof passes.

See it in action

You: $optim-plans Design a tiny browser game where a wizard redirects falling stars into constellations.

AI:  I inspected the repo. One design choice changes the whole game loop.
     What should the player optimize for?

     1. Elegant constellation shapes — best fit for a calm puzzle game
     2. Survival under pressure — better for arcade pacing
     3. High-score combos — stronger replay loop
     4. Other
     5. Auto-complete

You: 1

AI:  Recorded the answer.
     Draft plan: star physics, constellation scoring, level pacing,
     keyboard controls, visual polish, and verification screenshots.
     Pick who should refine the plan:

     1. Reviewer — fresh read-only reviewer session
     2. Criticizer — fresh read-only criticizer session
     3. Jump to executor — skip refinement and launch from this plan
     4. Auto-complete

You: 2

AI:  Choose refinement agent:

     1. Delegated foreground run — choose a standalone sub-agent with visible output
     2. Current foreground session — continue reviewing, questioning, or criticizing in this session
     3. Other
     4. Auto-complete

You: 1

AI:  Choose model and effort:

     1. Codex detected defaults — use Codex model default with effort default
     2. Codex manual model/effort — choose explicit --model and reasoning effort for Codex
     3. Other
     4. Auto-complete

You: 1

AI:  Criticizer asks: the calm puzzle goal conflicts with falling-star pressure.
     Should failed catches be harmless, score-limiting, or level-ending?

     1. Score-limiting — preserves calm play while rewarding skill
     2. Harmless — pure sandbox
     3. Level-ending — closer to arcade survival
     4. Other
     5. Auto-complete

You: 1

AI:  Wrote docs/optim-plans/2026-07-24-wizard-stars-game/PLAN_v2.md.
     Plan hash: 8b2...
     Execution manifest hash: 41f...
     Run worktree: .git/optim-plans/run-worktrees/7c9...
     Run branch: optim-plans/run/7c9...
     Approve manifest-bound execution?

     1. Execute the scoped game implementation
     2. Stop
     3. Other

Public artifacts are plain Markdown:

docs/optim-plans/YYYY-MM-DD-topic/
  PLAN_v1.md
  PLAN_v1_reviewer_comments.md
  PLAN_v2.md
  EXECUTION_SUMMARY.md

Machine state is separate and replayable:

.git/optim-plans/
  config.json
  worktrees/<worktree-id>/active.json
  runs/<run-id>/
    run.json
    events.jsonl
    runtime.json
    controller.lock

Diagnose before planning

You: $analyze-and-plan A new branch has a CI test failure in pytest;
     inspect the evidence before writing a plan.

AI:  Evidence inspected: CI log, failing traceback, recent diff,
     and the fixture that prepares the checkout.

     RCA summary: the root cause appears to be a temp-path assumption
     that passes locally from the repo root but fails in the CI workspace.

     What should happen next?

     1. Create the scoped fix plan
     2. Review the RCA only
     3. Other
     4. Auto-complete

Quick Start

Install for local Claude Code development

From this repository root:

claude plugin validate --strict .
claude plugin marketplace add ./ --scope user
claude plugin install optim-plans@optim-plans-dev --scope user

If an installed local development plugin looks stale, refresh it and restart Claude Code:

claude plugin marketplace update optim-plans-dev
claude plugin update optim-plans@optim-plans-dev --scope user
claude plugin list
claude plugin details optim-plans@optim-plans-dev

Restart is required for updated plugin code to apply. .git/optim-plans/config.json is not an install artifact; it is created per target repo when worker/model choices or execution prep need persisted config. Delegated worker choices persist under refinement_worker.choice and executor_worker.choice.

To permanently skip execution summaries for one repo, edit .git/optim-plans/config.json:

{
  "schema": 1,
  "execution_summary": {
    "mode": "always-skip"
  },
  "refinement_worker": {
    "choice": "background"
  },
  "executor_worker": {
    "choice": "background"
  }
}

Valid execution_summary.mode values are always-skip or omitted. Worker choice blocks are optional; when present, choice is background or foreground, and manual worker blocks may also include platform, mode, model, effort, and Codex execution_mode.

For one-off development without installing, load this checkout for a single Claude session:

claude --plugin-dir . '$optim-plans Turn this idea into a reviewed plan before implementation.'

Install for local Codex development

From this repository root:

codex plugin marketplace add .
codex plugin add optim-plans@optim-plans-dev

Then invoke the skill:

$optim-plans Turn this idea into a reviewed plan before implementation.

Worker configuration

.git/optim-plans/config.json stores background worker preferences, not the foreground controller. Choose the controller/main-session model and effort when launching Codex or Claude.

For cost-effective workflows, use:

You can edit this template by hand:

{
  "schema": 1,
  "refinement_worker": {
    "choice": "background",
    "platform": "codex",
    "mode": "manual",
    "model": "gpt-5.6-sol",
    "effort": "medium"
  },
  "executor_worker": {
    "choice": "background",
    "platform": "codex",
    "mode": "manual",
    "model": "gpt-5.6-terra",
    "effort": "xhigh",
    "execution_mode": "host-multi-agent"
  }
}

• refinement_worker.choice is background or foreground. Set executor_worker.choice to background: foreground executor execution is unsupported.
• platform is codex or claude, and must match the current host platform; otherwise the stored preference is ignored.
• mode is default or manual. manual requires non-empty model and effort values.
• execution_mode applies only to a Codex executor: use host-multi-agent by default or cli-adapter as a fallback. Claude executors use the CLI adapter path.

worker_launch_files and smoke_tested_workers are controller-managed internal state. Leave them out of manual configuration.

Normal $optim-plans and /optim-plans calls auto-select the smallest planning depth that fits the prompt and repo evidence. Name a level only when you want to override that choice: