Optim Plans

Optim Plans

Plan before execution. The bundled controller keeps durable state under the Git common directory and public Markdown under docs/optim-plans/YYYY-MM-DD-topic/.

This flow fixes two failure modes in order: grilling the user fixes building the wrong thing; adversarial reviewer/criticizer passes fix a plan that sounds right but breaks.

QA work is not a rubber stamp: during brainstorming and criticizing, actively hunt applicable edge cases before the plan can sound settled. Do NOT write code, scaffold files, edit repo docs/config, or change target files until the plan has passed refinement or the human selects Jump to executor, and the controller has recorded immutable execution-manifest approval. Before execution approval, the only permitted writes are controller state and docs/optim-plans/YYYY-MM-DD-topic/ artifacts. Auto-complete can answer planning questions; Auto-complete never approves execution, and execution approval questions must not offer Auto-complete. The Jump to executor / skip-refinement-execute human choice is direct execution approval through the controller.

First Turn Contract

Treat the user's prompt as a planning target, not write authorization. After any read-only context check, the first visible response must be one optim-plans choice question, not a completed analysis or file edit. It must include recommended first, Other second-last, and Auto-complete last. References inform the recommended option; they never replace the user interview. One human-choice answer is necessary but not sufficient: after the answer, continue through PLAN_v1.md, refinement, and explicit execution approval before editing target files.

Language Policy

Persist language in the target repo's .git/optim-plans/config.json top-level language field as a normalized BCP47-style string. Run controller init with the original request in --request-text; it is stored in run.json. If config.language is missing or invalid, the first visible response is the controller's language-selection question, and every later controller-backed question surface must return that unanswered question until it is answered.

The language-selection option IDs and order are stable: zh-hans, en, zh-hant, other, auto. The zh-hans, en, and zh-hant options carry language_value metadata (zh-Hans, en, zh-Hant). Recommend Chinese (zh-hans) when more than 60% of the user's planning request's natural-language body is non-English Chinese; otherwise recommend English (en). Count only natural-language prose for the > 60% threshold: ignore command prefixes, option IDs, file paths, and code spans.

Use the selected language for questioning, review summaries, criticizer questions, answer choices, and optim-plans Markdown under docs/optim-plans/. Keep stable option IDs, stages, nonces, protocol labels, artifact protocol names, and exact controller-required protocol labels unchanged, but localize visible prompt text, option labels, option descriptions/reasons, and agent-written choice prose when rendering controller-backed questions. Valid unsupported BCP47-style tags fall back to English renderers; only language tags whose primary subtag is exactly zh render Chinese. Always write commit messages in English.

Plan Request Levels

Users may choose the planning depth in the prompt or via direct controller flags:

• mini-plan: 1 planning question; zero or one refinement round. The refinement choice may jump directly to executor with skip-refinement-execute.
• small-plan: 1 to 3 planning questions; exactly one refinement round.
• plan: 1 to 5 planning questions; at most three refinement rounds, 600 seconds per reviewer/criticizer pass, and at most three high-priority comments or questions per round.
• big-plan: 5 to 10 planning questions; websearch is required for brainstorming, with at most five refinement rounds, 1800 seconds per reviewer/criticizer pass, and at most five high-priority comments or questions per round.
• huge-plan / huge plan: at least 10 planning questions, no maximum; websearch is required for brainstorming and refinement, with no refinement round or timeout limit and at most five high-priority comments or questions per round.

For plan, big-plan, and huge-plan, only high-priority comments or criticisms continue refinement; if a round produces none, terminate that round.

If no level is named, auto-select the smallest level that fits the user's prompt and repo evidence before the first planning question. Do not ask the user to choose the level as that question.

After each plan version, ask one refinement mode question: recommend Reviewer first, then Criticizer, Jump to executor (skip-refinement-execute), and Auto-complete. For Reviewer or Criticizer, ask the first agent-choice follow-up for the detected agent and effort; later agent-choice asks default only from the same worker role: refinement_worker.choice, executor_worker.choice, or validator_worker.choice. Delegated workers are same-platform only: Codex must not call Claude, and Claude must not call Codex.

Anti-Pattern: "Too Small To Plan"