graph TD
A[用户输入想法] --> B[想法处理组件]
B --> C[决策生成]
C --> D{"决策验证"}
D -->|"通过"| F[状态同步]
D -->|"失败"| E[用户反馈]
F --> G[执行业务]
G --> H[记录决策]
H --> I[输出 Markdown 计划]
Human-in-the-loop planning plugin for Claude and Codex: turn ideas into reviewed Markdown plans, record decisions, enforce explicit execution gates, and provide tested controller primitives for safer agent workflows.
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.
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
Inspect the target repository read-only.
Initialize controller state with the selected skill level.
Ask one planning question at a time, using the standard choice order: recommended option first, Other second-last, Auto-complete last.
Ask the mandatory final scope confirmation before writing PLAN_v1.md.
Write PLAN_vN.md artifacts with stable IDs and a ## Verifier Checklist.
Refine with either Reviewer or Criticizer.
Ask the native handoff question without Auto-complete:
Execute this plan now with normal Prime Agent tools, Stop after planning, or Other.
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:
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.
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
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.
评论