optim-plans

Human-in-the-loop planning and refinement with a current-session execution handoff.

optim-plans turns a rough repository-change request into a traceable Markdown plan, refines that plan with reviewer or criticizer passes, and then hands an accepted plan back to the current agent session for implementation. Version 0.3.0 is intentionally smaller: it removes the separate controller execution engine and keeps the product focused on planning quality.

Repository: https://github.com/Optim-Agent/optim-plans

Skill Set

The public plugin surface is exactly five skills:

Skill	Use it when
create-a-small-plan	A small scoped repo change needs 1 to 3 planning questions and one refinement pass.
create-a-plan	A broad or risky change needs 5 to 10 planning questions, research, and bounded refinement.
create-a-big-plan	A high-risk or open-ended effort needs at least 10 planning questions and refinement until convergence.
diagnose-before-plan	A bug, CI failure, regression, incident, RCA, or broken behavior needs diagnosis before planning.
reference-before-plan	Downloaded projects, articles, papers, or docs must be analyzed before planning choices are safe.

The old aggregate and alias skills were removed. Invoke the skill that matches the depth of the planning job.

Workflow

1. Inspect the target repository read-only.
2. Initialize controller state with the selected skill level.
3. Ask one planning question at a time, using the standard choice order: recommended option first, Other second-last, Auto-complete last.
4. Ask the mandatory final scope confirmation before writing PLAN_v1.md.
5. Write PLAN_vN.md artifacts with stable IDs and a ## Verifier Checklist.
6. Refine with either Reviewer or Criticizer.
7. Ask the native handoff question without Auto-complete: Execute this plan now with normal Prime Agent tools, Stop after planning, or Other.
8. If approved, leave the planning workflow and implement normally in the current session.

There is no separate manifest, run worktree, delegated implementation role, verification role, retry loop, checkpoint lifecycle, or terminal finish gate in 0.3.0.

Runtime Layout

Machine state stays outside the monitored worktree in the Git common directory:

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

Public artifacts stay in the repository:

docs/optim-plans/YYYY-MM-DD-topic/
  DECISIONS.md
  PROBLEM_ANALYSIS.md
  REF_ANALYSIS.md
  PLAN_v1.md
  PLAN_v1_reviewer_comments.md
  PLAN_v2.md

Only the files that apply to the selected workflow are created.

Controller Commands

The controller CLI is intentionally small:

python3 scripts/optim_plans.py init --repo <repo> --topic "<topic>" --plan-level create-a-plan --request-text "<original request>"
python3 scripts/optim_plans.py ask --repo <repo> --prompt "Choose refinement"
python3 scripts/optim_plans.py answer --repo <repo> --nonce <nonce> --choice <option-id>
python3 scripts/optim_plans.py status --repo <repo>
python3 scripts/optim_plans.py worker-config --repo <repo> --role reviewer --cwd <repo>
python3 scripts/optim_plans.py worker-config --repo <repo> --role criticizer --cwd <repo>
python3 scripts/optim_plans.py register-plan --repo <repo> --path docs/optim-plans/<run>/PLAN_v1.md --version 1
python3 scripts/optim_plans.py record-reference --repo <repo> --ref-id r1 --title "Reference" --url "https://example.invalid" --kind project --local-path refs/r1 --retrieval-method clone
python3 scripts/optim_plans.py record-reference-analysis --repo <repo> --ref-id r1 --analysis-artifact docs/optim-plans/<run>/REF_ANALYSIS.md --coverage manual
python3 scripts/optim_plans.py record-reference-waiver --repo <repo> --ref-id r1 --waiver-type parser-unavailable --reason "manual read is sufficient" --answer-nonce <nonce>

worker-config is restricted to reviewer and criticizer roles. Same-platform CLI adapter support is retained for those read-only roles, including Codex provider/profile handling.

Reference Planning

reference-before-plan records reference metadata separately from planning decisions. A reference idea is not eligible for PLAN_v1.md until the source metadata, analysis artifact, and adoption-question answers are recorded.

The reference flow expects at least three credible references. If fewer exist, the planner must block, narrow scope with the user, or record an explicit user waiver. Auto-complete cannot grant that waiver.

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 language, reviewer, or criticizer settings need persisted config.

Install For Local Codex Development

From this repository root:

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

Then invoke one of the public skills, for example:

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

Safety Model

run.json is immutable after initialization. events.jsonl is append-only, strictly sequenced, and replayed to derive state. active.json is a rebuildable index for the current worktree.

The supported boundary is planning discipline, durable state, and explicit handoff. Hooks are defense in depth for scoped read-only refinement sessions; they inject context and deny out-of-scope writes or reserved Git state changes, but they are not a sandbox and they do not continue a run.

Auto-complete may answer planning and refinement questions. It must not approve the native handoff, destructive cleanup, tool installation waivers, deployment, merge, push, credential use, or any external state change.

Project Layout

.codex-plugin/plugin.json          Codex plugin manifest
.claude-plugin/plugin.json         Claude plugin manifest
.agents/plugins/marketplace.json   Local Codex marketplace entry
skills/create-a-small-plan/        Small planning skill
skills/create-a-plan/              Standard planning skill
skills/create-a-big-plan/          Large planning skill
skills/diagnose-before-plan/       Diagnosis before planning
skills/reference-before-plan/      Reference research before planning
skills/_shared/references/         Shared planning contracts and templates
scripts/optim_plans.py             Controller CLI
scripts/optim_plans_core.py        State, questions, references, artifacts
scripts/agent_adapters.py          Claude/Codex read-only refinement adapters
hooks/                             Hook configs and dispatcher
tests/                             Standard-library unittest suite
evals/                             Skill pressure cases

Verification

Run the repo-native proof:

python3 -m py_compile scripts/*.py hooks/*.py
python3 scripts/validate_structure.py
python3 -m unittest discover -s tests -p 'test_*.py' -v
git diff --check

CI runs Python compilation, structure validation, and the unittest suite on Linux and macOS.

Contributing

Small fixes can go straight to PR. For larger behavior changes, create or update a docs/optim-plans/ plan artifact first so the intent is reviewable before code changes.

Development rules:

• keep controller code standard-library only;
• keep public skill inventory to the five skills above unless a release plan explicitly changes it;
• preserve .git/optim-plans and docs/optim-plans runtime paths;
• do not broaden Auto-complete across native handoff or external state changes;
• keep reviewer and criticizer sessions read-only;
• update tests and CHANGELOG.md for user-visible behavior changes.

Acknowledgements

Thanks to chaseai-yt/grill-me-codex, mattpocock/skills, and leo-lilinxiao/codex-autoresearch for related ideas and prior art.

License

MIT. See LICENSE.