Oh-my-codex plan

<Use_When>

• User wants to plan before implementing -- "plan this", "plan the", "let's plan"
• User wants structured requirements gathering for a vague idea
• User wants an existing plan reviewed -- "review this plan",

  --review

• User wants multi-perspective consensus on a plan --

  --consensus

  , "ralplan"
• Task is broad or vague and needs scoping before any code is written </Use_When>

<Do_Not_Use_When>

• User wants autonomous end-to-end execution -- use

  autopilot

  instead
• User wants to start coding immediately with a clear task -- use

  ralph

  or delegate to executor
• User asks a simple question that can be answered directly -- just answer it
• Task is a single focused fix with obvious scope -- skip planning, just do it </Do_Not_Use_When>

<Why_This_Exists> Jumping into code without understanding requirements leads to rework, scope creep, and missed edge cases. Plan provides structured requirements gathering, expert analysis, and quality-gated plans so that execution starts from a solid foundation. The consensus mode adds multi-perspective validation for high-stakes projects. </Why_This_Exists>

<Execution_Policy>

• Auto-detect interview vs direct mode based on request specificity
• Ask one question at a time during interviews -- never batch multiple questions
• Gather codebase facts via

  explore

  agent before asking the user about them
• When session guidance enables

  USE_OMX_EXPLORE_CMD

  , prefer

  omx explore

  for simple read-only repository lookups during planning; keep prompts narrow and concrete, and keep prompt-heavy or ambiguous planning work on the richer normal path and fall back normally if

  omx explore

  is unavailable.
• Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
• Implementation step count must be right-sized to task scope; avoid defaulting to exactly five steps when the work is clearly smaller or larger
• Consensus mode outputs the final plan by default; add

  --interactive

  to enable execution handoff
• Consensus mode uses RALPLAN-DR short mode by default; switch to deliberate mode with

  --deliberate

  or when the request explicitly signals high risk (auth/security, data migration, destructive/irreversible changes, production incident, compliance/PII, public API breakage)
• Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail
• Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints
• If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the plan is grounded
• Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent </Execution_Policy>

Mode Selection

--direct

--consensus

--deliberate

--consensus --interactive

--review

Interview Mode (broad/vague requests)

1. Classify the request: Broad (vague verbs, no specific files, touches 3+ areas) triggers interview mode
2. Ask one focused question using

   AskUserQuestion

   for preferences, scope, and constraints
3. Gather codebase facts first: Before asking "what patterns does your code use?", spawn an

   explore

   agent to find out, then ask informed follow-up questions
4. Build on answers: Each question builds on the previous answer
5. Consult Analyst (THOROUGH tier) for hidden requirements, edge cases, and risks
6. Create plan when the user signals readiness: "create the plan", "I'm ready", "make it a work plan"

Direct Mode (detailed requests)

1. Quick Analysis: Optional brief Analyst consultation
2. Create plan: Generate comprehensive work plan immediately
3. Review (optional): Critic review if requested

Consensus Mode (

--consensus

/ "ralplan")

RALPLAN-DR modes: Short (default, bounded structure) and Deliberate (for

--deliberate

1. Planner creates initial plan and a compact RALPLAN-DR summary before any Architect review. The summary MUST include:
   • Principles (3-5)
   • Decision Drivers (top 3)
   • Viable Options (>=2) with bounded pros/cons for each option
   • If only one viable option remains, an explicit invalidation rationale for the alternatives that were rejected
   • In deliberate mode: a pre-mortem (3 failure scenarios) and an expanded test plan covering unit / integration / e2e / observability
2. User feedback (--interactive only): If running with

   --interactive

   , MUST use

   AskUserQuestion

   to present the draft plan plus the RALPLAN-DR Principles / Decision Drivers / Options summary for early direction alignment with these options:
   • Proceed to review — send to Architect and Critic for evaluation
   • Request changes — return to step 1 with user feedback incorporated
   • Skip review — go directly to final approval (step 7) If NOT running with

     --interactive

     , automatically proceed to review (step 3).
3. Architect reviews for architectural soundness using

   ask_codex

   with

   agent_role: "architect"

   . Architect review MUST include: strongest steelman counterargument (antithesis) against the favored option, at least one meaningful tradeoff tension, and (when possible) a synthesis path. In deliberate mode, Architect should explicitly flag principle violations. Wait for this step to complete before proceeding to step 4. Do NOT run steps 3 and 4 in parallel.
4. Critic evaluates against quality criteria using

   ask_codex

   with

   agent_role: "critic"

   . Critic MUST verify principle-option consistency, fair alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. Critic MUST explicitly reject shallow alternatives, driver contradictions, vague risks, or weak verification. In deliberate mode, Critic MUST reject missing/weak pre-mortem or missing/weak expanded test plan. Run only after step 3 is complete.
5. Re-review loop (max 5 iterations): If Critic rejects or iterates, execute this closed loop: a. Collect all feedback from Architect + Critic b. Pass feedback to Planner to produce a revised plan c. Return to Step 3 — Architect reviews the revised plan d. Return to Step 4 — Critic evaluates the revised plan e. Repeat until Critic approves OR max 5 iterations reached f. If max iterations reached without approval, present the best version to user via

   AskUserQuestion

   with note that expert consensus was not reached
6. Apply improvements: When reviewers approve with improvement suggestions, merge all accepted improvements into the plan file before proceeding. Final consensus output MUST include an ADR section with: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups. Specifically: a. Collect all improvement suggestions from Architect and Critic responses b. Deduplicate and categorize the suggestions c. Update the plan file in

   .omx/plans/

   with the accepted improvements (add missing details, refine steps, strengthen acceptance criteria, ADR updates, etc.) d. Note which improvements were applied in a brief changelog section at the end of the plan e. Before any execution handoff, derive an explicit available-agent-types roster from the known prompt catalog and add concrete follow-up staffing guidance for both

   $ralph

   and

   $team

   (recommended roles, counts, suggested reasoning levels by lane, and why each lane exists) f. For the

   $team

   path, add an explicit launch-hint block with concrete

   omx team

   /

   $team

   commands and a team verification path (what team proves before shutdown, what Ralph verifies after handoff)
7. On Critic approval (with improvements applied): (--interactive only) If running with

   --interactive

   , use

   AskUserQuestion

   to present the plan with these options:
   • Approve and execute — proceed to implementation via ralph+ultrawork
   • Approve and implement via team — proceed to implementation via coordinated parallel team agents
   • Request changes — return to step 1 with user feedback
   • Reject — discard the plan entirely If NOT running with

     --interactive

     , output the final approved plan and stop. Do NOT auto-execute.
8. (--interactive only) User chooses via the structured

   AskUserQuestion

   UI (never ask for approval in plain text)
9. On user approval (--interactive only):
   • Approve and execute: MUST invoke

     $ralph

     with the approved plan path from

     .omx/plans/

     as context plus the explicit available-agent-types roster, suggested reasoning levels, concrete role allocation guidance, and direct launch hints for Ralph follow-up work. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
   • Approve and implement via team: MUST invoke

     $team

     with the approved plan path from

     .omx/plans/

     as context plus the explicit available-agent-types roster, suggested reasoning levels, concrete staffing / worker-role allocation guidance, explicit

     omx team

     /

     $team

     launch hints, and the team verification path. Do NOT implement directly. The team skill coordinates parallel agents across the staged pipeline for faster execution on large tasks.

Review Mode (

--review

)

0. Treat review as a reviewer-only pass. The context that wrote the plan, cleanup proposal, or diff MUST NOT be the context that approves it.
1. Read plan file from

   .omx/plans/

2. Evaluate via Critic using

   ask_codex

   with

   agent_role: "critic"

3. For cleanup/refactor/anti-slop work, verify that the artifact includes a cleanup plan, regression tests or an explicit test gap, smell-by-smell passes, and quality gates.
4. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
5. If the current context authored the artifact, hand the review to

   /review

   ,

   critic

   ,

   quality-reviewer

   ,

   security-reviewer

   , or

   verifier

   as appropriate.

Plan Output Format

Every plan includes:

• Requirements Summary
• Acceptance Criteria (testable)
• Implementation Steps (with file references)
• Adaptive step count sized to the actual scope (not a fixed five-step template)
• Risks and Mitigations
• Verification Steps
• For consensus/ralplan: RALPLAN-DR summary (Principles, Decision Drivers, Options)
• For consensus/ralplan final output: ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups)
• For consensus/ralplan execution handoff: Available-Agent-Types Roster, Follow-up Staffing Guidance (including suggested reasoning levels by lane), explicit

  omx team

  /

  $team

  Launch Hints, and Team Verification Path
• For deliberate consensus mode: Pre-mortem (3 scenarios) and Expanded Test Plan (unit/integration/e2e/observability)

Plans are saved to

.omx/plans/

.omx/drafts/

<Tool_Usage>

• Before first MCP tool use, call

  ToolSearch("mcp")

  to discover deferred MCP tools
• Use

  AskUserQuestion

  for preference questions (scope, priority, timeline, risk tolerance) -- provides clickable UI
• Use plain text for questions needing specific values (port numbers, names, follow-up clarifications)
• Use the

  explore

  agent (LOW tier, bounded quick pass) to gather codebase facts before asking the user
• Use

  ask_codex

  with

  agent_role: "planner"

  for planning validation on large-scope plans
• Use

  ask_codex

  with

  agent_role: "analyst"

  for requirements analysis
• Use

  ask_codex

  with

  agent_role: "critic"

  for plan review in consensus and review modes
• If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent OMX prompt agents -- never block on external tools
• CRITICAL — Consensus mode agent calls MUST be sequential, never parallel. Always await the Architect result before issuing the Critic call.
• In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on

  --deliberate

  or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
• In consensus mode with

  --interactive

  : use

  AskUserQuestion

  for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text. Without

  --interactive

  , auto-proceed through planning steps without pausing. Output the final plan without execution.
• In consensus mode with

  --interactive

  , on user approval MUST invoke

  $ralph

  for execution (step 9) -- never implement directly in the planning agent
• In consensus mode, execution follow-up handoff MUST include an explicit available-agent-types roster plus concrete staffing / role-allocation guidance grounded in that roster, suggested reasoning levels by lane, explicit

  omx team

  /

  $team

  launch hints, and a team verification path </Tool_Usage>

Scenario Examples

Good: The user says

continue

Good: The user changes only the output shape or downstream delivery step (for example

make a PR

Bad: The user says

continue

<Escalation_And_Stop_Conditions>

• Stop interviewing when requirements are clear enough to plan -- do not over-interview
• In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
• Consensus mode outputs the plan by default; with

  --interactive

  , user can approve and hand off to ralph/team
• If the user says "just do it" or "skip planning", MUST invoke

  $ralph

  to transition to execution mode. Do NOT implement directly in the planning agent.
• Escalate to the user when there are irreconcilable trade-offs that require a business decision </Escalation_And_Stop_Conditions>

<Final_Checklist>

• Plan has testable acceptance criteria (90%+ concrete)
• Plan references specific files/lines where applicable (80%+ claims)
• All risks have mitigations identified
• No vague terms without metrics ("fast" -> "p99 < 200ms")
• Plan saved to

  .omx/plans/

• In consensus mode: RALPLAN-DR summary includes 3-5 principles, top 3 drivers, and >=2 viable options (or explicit invalidation rationale)
• In consensus mode final output: ADR section included (Decision / Drivers / Alternatives considered / Why chosen / Consequences / Follow-ups)
• In deliberate consensus mode: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability) included
• In consensus mode with

  --interactive

  : user explicitly approved before any execution; without

  --interactive

  : output final plan after Critic approval (no auto-execution) </Final_Checklist>

When presenting design choices during interviews, chunk them:

1. Overview (2-3 sentences)
2. Option A with trade-offs
3. [Wait for user reaction]
4. Option B with trade-offs
5. [Wait for user reaction]
6. Recommendation (only after options discussed)

Format for each option:

### Option A: [Name]
**Approach:** [1 sentence]
**Pros:** [bullets]
**Cons:** [bullets]

What's your reaction to this approach?

Question Classification

Before asking any interview question, classify it:

Review Quality Criteria

Deprecation Notice

The separate

/planner

/ralplan

/review

$plan

$plan