oh-my-codex 0.15.0 → 0.15.2

package/plugins/oh-my-codex/skills/autopilot/SKILL.md

@@ -1,234 +1,163 @@
 ---
 name: autopilot
-description: Full autonomous execution from idea to working code
+description: "[OMX] Strict autonomous loop: $ralplan -> $ralph -> $code-review"
 ---
 
 <Purpose>
-Autopilot takes a brief product idea and autonomously handles the full lifecycle: requirements analysis, technical design, planning, parallel implementation, QA cycling, and multi-perspective validation. It produces working, verified code from a 2-3 line description.
+Autopilot is the strict autonomous delivery loop for non-trivial work. Its primary contract is exactly:
+
+```text
+$ralplan -> $ralph -> $code-review
+```
+
+If `$code-review` is not clean, Autopilot returns to `$ralplan` with the review findings as the next planning input, then continues again through `$ralph` and `$code-review` until the review is clean or a hard blocker is reported.
 </Purpose>
 
 <Use_When>
-- User wants end-to-end autonomous execution from an idea to working code
-- User says "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
-- Task requires multiple phases: planning, coding, testing, and validation
-- User wants hands-off execution and is willing to let the system run to completion
+- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed code
+- User says `$autopilot`, "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
+- Task needs planning, implementation, verification, and code review with automatic follow-up when review is not clean
 </Use_When>
 
 <Do_Not_Use_When>
-- User wants to explore options or brainstorm -- use `plan` skill instead
+- User wants to explore options or brainstorm -- use `$plan` / `$ralplan`
 - User says "just explain", "draft only", or "what would you suggest" -- respond conversationally
-- User wants a single focused code change -- use `ralph` or delegate to an executor agent
-- User wants to review or critique an existing plan -- use `plan --review`
-- Task is a quick fix or small bug -- use direct executor delegation
+- User wants a single focused code change -- use `$ralph` or direct executor work
+- User wants only review/critique of existing code -- use `$code-review`
 </Do_Not_Use_When>
 
-<Why_This_Exists>
-Most non-trivial software tasks require coordinated phases: understanding requirements, designing a solution, implementing in parallel, testing, and validating quality. Autopilot orchestrates all of these phases automatically so the user can describe what they want and receive working code without managing each step.
-</Why_This_Exists>
+<Strict_Loop_Contract>
+Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the three canonical workflow phases below:
+
+1. **Phase `ralplan`** — consensus planning gate
+   - Ground the task with pre-context intake.
+   - Run or resume `$ralplan` to produce/update PRD and test-spec artifacts.
+   - When returning from a non-clean review, include `return_to_ralplan_reason` and the review findings as first-class planning input.
+   - Required handoff artifact: an approved plan/test spec suitable for `$ralph`.
+
+2. **Phase `ralph`** — implementation + verification loop
+   - Run `$ralph` from the approved ralplan artifacts.
+   - Ralph owns implementation, tests, build/lint/typecheck evidence, deslop where applicable, and architect verification.
+   - Required handoff artifact: implementation evidence and changed-file summary suitable for `$code-review`.
+
+3. **Phase `code-review`** — merge-readiness gate
+   - Run `$code-review` on the diff/artifacts produced by `$ralph`.
+   - A clean review means final recommendation `APPROVE` with architectural status `CLEAR`.
+   - `COMMENT`, `REQUEST CHANGES`, any architectural `WATCH`/`BLOCK`, or any unresolved finding is not clean.
+   - If not clean, increment the review cycle, persist `review_verdict`, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`.
+
+The only normal terminal state is `complete` after a clean code review. Cancellation, blocked credentials, unrecoverable repeated failures, or explicit user stop may terminate earlier with preserved state.
+</Strict_Loop_Contract>
+
+<Pre-context Intake>
+Before Phase `ralplan` starts or resumes:
+1. Derive a task slug from the request.
+2. Reuse the latest relevant `.omx/context/{slug}-*.md` snapshot when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, run `explore` first for brownfield facts, then run the Socratic `$deep-interview --quick <task>` before `$ralplan`.
+5. Carry the snapshot path in Autopilot state and all handoff artifacts.
+</Pre-context Intake>
 
 <Execution_Policy>
-- Each phase must complete before the next begins
-- Parallel execution is used within phases where possible (Phase 2 and Phase 4)
-- QA cycles repeat up to 5 times; if the same error persists 3 times, stop and report the fundamental issue
-- Validation requires approval from all reviewers; rejected items get fixed and re-validated
-- Cancel with `/cancel` at any time; progress is preserved for resume
-- If a deep-interview spec exists, use it as high-clarity phase input instead of re-expanding from scratch
-- If input is too vague for reliable expansion, offer/trigger `$deep-interview` first
-- Do not enter expansion/planning/execution-heavy phases until pre-context grounding exists; if fast execution is forced, proceed only with explicit risk notes
-- 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 workflow is grounded
-- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent
+- Always execute phases in order: `ralplan`, then `ralph`, then `code-review`.
+- Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified or planned through `$ralplan`.
+- A non-clean `$code-review` always returns to `$ralplan`; do not patch findings ad hoc outside the loop.
+- Each phase must write/update Autopilot state before handing off.
+- Use existing hooks, `.omx/state`, `$ralplan`, `$ralph`, `$code-review`, and pipeline primitives; do not invent a separate execution framework.
+- Continue automatically through safe reversible phase transitions. Ask only for destructive, credential-gated, or materially preference-dependent branches.
+- Apply the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step execution, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
 </Execution_Policy>
 
-<Steps>
-0. **Pre-context Intake (required before Phase 0 starts)**:
-   - Derive a task slug from the request.
-   - Load the latest relevant snapshot from `.omx/context/{slug}-*.md` when available.
-   - If no snapshot exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
-     - Task statement
-     - Desired outcome
-     - Known facts/evidence
-     - Constraints
-     - Unknowns/open questions
-     - Likely codebase touchpoints
-   - If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before proceeding.
-   - Carry the snapshot path into autopilot artifacts/state so all phases share grounded context.
-
-1. **Phase 0 - Expansion**: Turn the user's idea into a detailed spec
-   - If `.omx/specs/deep-interview-*.md` exists for this task: reuse it and skip redundant expansion work
-   - If prompt is highly vague: route to `$deep-interview` for Socratic ambiguity-gated clarification
-   - Analyst (THOROUGH tier): Extract requirements
-   - Architect (THOROUGH tier): Create technical specification
-   - Output: `.omx/plans/autopilot-spec.md`
-
-2. **Phase 1 - Planning**: Create an implementation plan from the spec
-   - Architect (THOROUGH tier): Create plan (direct mode, no interview)
-   - Critic (THOROUGH tier): Validate plan
-   - Output: `.omx/plans/autopilot-impl.md`
-
-3. **Phase 2 - Execution**: Implement the plan using Ralph + Ultrawork
-   - LOW-tier executor/search roles: Simple tasks
-   - STANDARD-tier executor roles: Standard tasks
-   - THOROUGH-tier executor/architect roles: Complex tasks
-   - Run independent tasks in parallel
-
-4. **Phase 3 - QA**: Cycle until all tests pass (UltraQA mode)
-   - Build, lint, test, fix failures
-   - Repeat up to 5 cycles
-   - Stop early if the same error repeats 3 times (indicates a fundamental issue)
-
-5. **Phase 4 - Validation**: Multi-perspective review in parallel
-   - Architect: Functional completeness
-   - Security-reviewer: Vulnerability check
-   - Code-reviewer: Quality review
-   - All must approve; fix and re-validate on rejection
-
-6. **Phase 5 - Cleanup**: Clear all mode state via OMX MCP tools on successful completion
-   - `state_clear({mode: "autopilot"})`
-   - `state_clear({mode: "ralph"})`
-   - `state_clear({mode: "ultrawork"})`
-   - `state_clear({mode: "ultraqa"})`
-   - Or run `/cancel` for clean exit
-</Steps>
-
-<Tool_Usage>
-- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
-- Use `ask_codex` with `agent_role: "architect"` for Phase 4 architecture validation
-- Use `ask_codex` with `agent_role: "security-reviewer"` for Phase 4 security review
-- Use `ask_codex` with `agent_role: "code-reviewer"` for Phase 4 quality review
-- Agents form their own analysis first, then consult Codex for cross-validation
-- If ToolSearch finds no MCP tools or Codex is unavailable, proceed without it -- never block on external tools
-</Tool_Usage>
-
-## State Management
-
-Use `omx_state` MCP tools for autopilot lifecycle state.
-
-- **On start**:
-  `state_write({mode: "autopilot", active: true, current_phase: "expansion", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
-- **On phase transitions**:
-  `state_write({mode: "autopilot", current_phase: "planning"})`
-  `state_write({mode: "autopilot", current_phase: "execution"})`
-  `state_write({mode: "autopilot", current_phase: "qa"})`
-  `state_write({mode: "autopilot", current_phase: "validation"})`
-- **On completion**:
-  `state_write({mode: "autopilot", active: false, current_phase: "complete", completed_at: "<now>"})`
-- **On cancellation/cleanup**:
-  run `$cancel` (which should call `state_clear(mode="autopilot")`)
-
-
-## Scenario Examples
-
-**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
-
-**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
-
-**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
-
-<Examples>
-<Good>
-User: "autopilot A REST API for a bookstore inventory with CRUD operations using TypeScript"
-Why good: Specific domain (bookstore), clear features (CRUD), technology constraint (TypeScript). Autopilot has enough context to expand into a full spec.
-</Good>
-
-<Good>
-User: "build me a CLI tool that tracks daily habits with streak counting"
-Why good: Clear product concept with a specific feature. The "build me" trigger activates autopilot.
-</Good>
+<State_Management>
+Use `omx_state` MCP tools (or `omx state ... --json` fallback if MCP transport is unavailable) for Autopilot lifecycle state. State must be session-aware when a session id exists.
+
+Required fields:
+
+```json
+{
+  "mode": "autopilot",
+  "active": true,
+  "current_phase": "ralplan",
+  "iteration": 1,
+  "review_cycle": 0,
+  "max_iterations": 10,
+  "phase_cycle": ["ralplan", "ralph", "code-review"],
+  "handoff_artifacts": {
+    "context_snapshot_path": ".omx/context/<slug>-<timestamp>.md",
+    "ralplan": null,
+    "ralph": null,
+    "code_review": null
+  },
+  "review_verdict": null,
+  "return_to_ralplan_reason": null
+}
+```
 
-<Bad>
-User: "fix the bug in the login page"
-Why bad: This is a single focused fix, not a multi-phase project. Use direct executor delegation or ralph instead.
-</Bad>
+- **On start**: `state_write({mode:"autopilot", active:true, current_phase:"ralplan", iteration:1, review_cycle:0, state:{phase_cycle:["ralplan","ralph","code-review"], handoff_artifacts:{context_snapshot_path, ralplan:null, ralph:null, code_review:null}, review_verdict:null, return_to_ralplan_reason:null}})`
+- **On ralplan -> ralph**: set `current_phase:"ralph"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
+- **On ralph -> code-review**: set `current_phase:"code-review"`, persist implementation/test evidence under `handoff_artifacts.ralph`.
+- **On clean review**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}` and `completed_at`.
+- **On non-clean review**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict:{..., clean:false}`, persist `handoff_artifacts.code_review`, and set `return_to_ralplan_reason` to a concise review-driven reason.
+- **On cancellation**: run `$cancel`; preserve progress for resume rather than deleting handoff artifacts.
+</State_Management>
+
+<Continuation_And_Resume>
+When the user says `continue`, `resume`, or `keep going` while Autopilot is active, read `autopilot-state.json` and continue from `current_phase`:
+- `ralplan`: run/update consensus planning from current handoffs and any `return_to_ralplan_reason`.
+- `ralph`: execute the approved plan and record verification evidence.
+- `code-review`: review the current diff and decide clean vs return-to-ralplan.
+- `complete`: report completion evidence; do not restart.
+
+Do not restart discovery or discard handoff artifacts on continuation.
+</Continuation_And_Resume>
+
+<Pipeline_Orchestrator>
+Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The Autopilot pipeline contract is:
+
+```text
+ralplan -> ralph -> code-review
+```
 
-<Bad>
-User: "what are some good approaches for adding caching?"
-Why bad: This is an exploration/brainstorming request. Respond conversationally or use the plan skill.
-</Bad>
-</Examples>
+Pipeline state should use `current_phase` values that match the same phase names (`ralplan`, `ralph`, `code-review`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, and `return_to_ralplan_reason` alongside stage results.
+</Pipeline_Orchestrator>
 
 <Escalation_And_Stop_Conditions>
-- Stop and report when the same QA error persists across 3 cycles (fundamental issue requiring human input)
-- Stop and report when validation keeps failing after 3 re-validation rounds
-- Stop when the user says "stop", "cancel", or "abort"
-- If requirements were too vague and expansion produces an unclear spec, pause and redirect to `$deep-interview` before proceeding
+- Stop and report a blocker when required credentials/authority are missing.
+- Stop and report when the same review or verification failure recurs across 3 review cycles with no meaningful new plan.
+- Stop when the user says "stop", "cancel", or "abort" and run `$cancel`.
+- Otherwise, continue the loop until `$code-review` is clean.
 </Escalation_And_Stop_Conditions>
 
 <Final_Checklist>
-- [ ] All 5 phases completed (Expansion, Planning, Execution, QA, Validation)
-- [ ] All validators approved in Phase 4
-- [ ] Tests pass (verified with fresh test run output)
-- [ ] Build succeeds (verified with fresh build output)
-- [ ] State files cleaned up
-- [ ] User informed of completion with summary of what was built
+- [ ] Phase `ralplan` produced/updated approved planning artifacts
+- [ ] Phase `ralph` implemented and verified the plan with fresh evidence
+- [ ] Phase `code-review` returned a clean verdict (`APPROVE` + `CLEAR`)
+- [ ] `review_verdict.clean` is true and `return_to_ralplan_reason` is null
+- [ ] Tests/build/lint/typecheck evidence from Ralph is available in handoff artifacts
+- [ ] Autopilot state is marked `complete` or cancellation state is preserved coherently
+- [ ] User receives a concise summary with plan, implementation, verification, and review evidence
 </Final_Checklist>
 
-<Advanced>
-## Configuration
-
-Optional settings in `~/.codex/config.toml`:
-
-```toml
-[omx.autopilot]
-maxIterations = 10
-maxQaCycles = 5
-maxValidationRounds = 3
-pauseAfterExpansion = false
-pauseAfterPlanning = false
-skipQa = false
-skipValidation = false
-```
-
-## Resume
-
-If autopilot was cancelled or failed, run `/autopilot` again to resume from where it stopped.
-
-## Recommended Clarity Pipeline
-
-For ambiguous requests, prefer:
-
-```
-deep-interview -> ralplan -> autopilot
-```
-
-- `deep-interview`: ambiguity-gated Socratic requirements
-- `ralplan`: consensus planning (planner/architect/critic)
-- `autopilot`: execution + QA + validation
-
-## Best Practices for Input
-
-1. Be specific about the domain -- "bookstore" not "store"
-2. Mention key features -- "with CRUD", "with authentication"
-3. Specify constraints -- "using TypeScript", "with PostgreSQL"
-4. Let it run -- avoid interrupting unless truly needed
-
-## Pipeline Orchestrator (v0.8+)
-
-Autopilot can be driven by the configurable pipeline orchestrator (`src/pipeline/`), which
-sequences stages through a uniform `PipelineStage` interface:
-
-```
-RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (architect verification)
-```
-
-Pipeline configuration options:
-
-```toml
-[omx.autopilot.pipeline]
-maxRalphIterations = 10    # Ralph verification iteration ceiling
-workerCount = 2            # Number of Codex CLI team workers
-agentType = "executor"     # Agent type for team workers
-```
-
-The pipeline persists state via `pipeline-state.json` and supports resume from the last
-incomplete stage. See `src/pipeline/orchestrator.ts` for the full API.
-
-## Troubleshooting
-
-**Stuck in a phase?** Check TODO list for blocked tasks, run `state_read({mode: "autopilot"})`, or cancel and resume.
+<Examples>
+<Good>
+User: `$autopilot implement GitHub issue #42`
+Flow: create/load context snapshot -> `$ralplan` issue plan -> `$ralph` implementation + tests -> `$code-review`; if review requests changes, return to `$ralplan` with findings.
+</Good>
 
-**QA cycles exhausted?** The same error 3 times indicates a fundamental issue. Review the error pattern; manual intervention may be needed.
+<Good>
+User: `continue`
+Context: Autopilot state says `current_phase:"code-review"`.
+Flow: run `$code-review` on current diff, persist verdict, finish if clean or transition to `ralplan` with findings if not clean.
+</Good>
 
-**Validation keeps failing?** Review the specific issues. Requirements may have been too vague -- cancel and provide more detail.
-</Advanced>
+<Bad>
+Autopilot invents independent "Expansion", "QA", and "Validation" phases and treats them as the primary lifecycle.
+Why bad: this bypasses the strict `$ralplan -> $ralph -> $code-review` contract.
+</Bad>
+</Examples>

package/plugins/oh-my-codex/skills/code-review/SKILL.md

@@ -15,12 +15,12 @@ This skill activates when:
 - After implementing a major feature
 - User wants quality assessment
 
-## GPT-5.4 Guidance Alignment
+## GPT-5.5 Guidance Alignment
 
-- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.
+- Default to outcome-first progress and completion reporting: state the target result, evidence, validation status, and stop condition before adding process 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 review is grounded.
-- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.
+- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the review is grounded; stop once enough evidence exists.
+- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, credentialed, external-production, or preference-dependent.
 
 Delegates to the `code-reviewer` and `architect` agents in parallel for a two-lane review:
 

package/plugins/oh-my-codex/skills/deep-interview/SKILL.md

@@ -40,7 +40,7 @@ If no flag is provided, use **Standard**.
 </Depth_Profiles>
 
 <Execution_Policy>
-- Ask ONE question per round (never batch)
+- Ask ONE question per round (never batch multiple interview rounds into one `questions[]` form)
 - Ask about intent and boundaries before implementation detail
 - Target the weakest clarity dimension each round after applying the stage-priority rules below
 - Treat every answer as a claim to pressure-test before moving on: the next question should usually demand evidence or examples, expose a hidden assumption, force a tradeoff or boundary, or reframe root cause vs symptom
@@ -55,9 +55,11 @@ If no flag is provided, use **Standard**.
 - Keep total prompt payloads within a safe budget by summarizing or trimming retained history; preserve newest/highest-signal answers and never let raw oversized context crowd out the current question
 - Reduce user effort: ask only the highest-leverage unresolved question, and never ask the user for codebase facts that can be discovered directly
 - For brownfield work, prefer evidence-backed confirmation questions such as "I found X in Y. Should this change follow that pattern?"
-- In Codex CLI, deep-interview uses `omx question` as the required OMX-owned structured questioning path for every interview round
+- In attached-tmux Codex CLI, deep-interview uses `omx question` as the required OMX-owned structured questioning path for every interview round
+- When invoking `omx question` through attached-tmux Bash/tool paths, preserve the leader-pane return target by prefixing the command with `OMX_QUESTION_RETURN_PANE=$TMUX_PANE` (or a concrete `%pane` value)
 - If you launch `omx question` in a background terminal, immediately wait for that background terminal to finish and read its JSON answer before scoring ambiguity, asking another round, or handing off
-- If `omx question` is unavailable in the current runtime, treat that as a blocker/error for deep-interview rather than falling back to `request_user_input` or plain-text questioning
+- Treat `answers[]` as the primary `omx question` success contract. For a single interview round, read `answers[0].answer`; use legacy top-level `answer` only as a compatibility fallback when needed.
+- If the current runtime is outside tmux and cannot render `omx question`, use the native structured question tool when available; otherwise ask exactly one concise plain-text question and wait for the answer
 - Re-score ambiguity after each answer and show progress transparently
 - Do not hand off to execution while ambiguity remains above threshold unless user explicitly opts to proceed with warning
 - Do not crystallize or hand off while `Non-goals` or `Decision Boundaries` remain unresolved, even if the weighted ambiguity threshold is met
@@ -155,7 +157,7 @@ Detailed dimensions:
 `Non-goals` and `Decision Boundaries` are mandatory readiness gates. Ask about them early and keep revisiting them until they are explicit.
 
 ### 2b) Ask the question
-Use OMX-owned structured questioning via `omx question` for every interview round (this is the required `AskUserQuestion` equivalent for deep-interview) and present:
+Use the surface-appropriate structured questioning path for every interview round. In attached-tmux sessions, use OMX-owned structured questioning via `omx question` (this is the required structured-question equivalent and required `AskUserQuestion` equivalent for deep-interview). Outside tmux, use native structured input when available; otherwise ask exactly one concise plain-text question and wait for the answer. Present:
 
 ```
 Round {n} | Target: {weakest_dimension} | Ambiguity: {score}%
@@ -164,12 +166,14 @@ Round {n} | Target: {weakest_dimension} | Ambiguity: {score}%
 ```
 
 `omx question` payload guidance for interview rounds:
+- Deep-interview is Socratic: ask one focused round at a time. Do not use batch `questions[]` to combine multiple interview rounds, even though `omx question` supports batch forms for other workflows.
 - Use canonical `type` values instead of authoring raw `multi_select` flags by hand. `type: "single-answerable"` is the default for one-path decisions; `type: "multi-answerable"` is the canonical shape for bounded multi-select rounds. The runtime will keep `multi_select` aligned with `type`.
 - Use `single-answerable` when exactly one answer should drive the next branch, the options are mutually exclusive, or selecting more than one answer would blur the decision boundary. Typical cases: handoff lane selection, choosing the primary failure mode, or confirming which of several competing interpretations is correct.
 - Use `multi-answerable` when multiple options may all be true at once and you need to capture a bounded set of coexisting constraints, non-goals, risks, or acceptance checks in one round. Typical cases: selecting all out-of-scope items, all success metrics that must hold, or all deployment constraints that apply together.
 - If one selected option would immediately require a follow-up question to disambiguate the others, prefer a `single-answerable` round now and ask the follow-up next. Do not hide a branching interview tree inside one overloaded multi-select prompt.
 - Keep interview options bounded and concrete. If the valid answers are already known, set `allow_other: false`; only leave `allow_other: true` when the interview genuinely needs one user-supplied option that cannot be enumerated in advance.
-- Read answers structurally. For `single-answerable`, expect one decisive selection in `answer.value` plus `answer.selected_values`. For `multi-answerable`, treat `answer.selected_values` as the source of truth for all chosen constraints/non-goals and preserve the full set in the transcript/spec.
+- Read answers structurally from the primary `answers[]` array. For a normal single-round interview response, use `answers[0].answer` as the source of truth; the top-level `answer` field is a legacy single-question projection/fallback only.
+- For `single-answerable`, expect one decisive selection in the `value` field of `answers[0].answer` plus its selected-values metadata. For `multi-answerable`, treat the selected-values field inside `answers[0].answer` as the source of truth for all chosen constraints/non-goals and preserve the full set in the transcript/spec. In legacy single-question projections, this is equivalent to: For `multi-answerable`, treat `answer.selected_values` as the source of truth.
 
 Canonical bounded single-choice payload:
 
@@ -397,9 +401,12 @@ Present execution options after artifact generation using explicit handoff contr
 
 <Tool_Usage>
 - Use `explore` for codebase fact gathering
-- Use `omx question` as the OMX-native structured user-input tool for each interview round
-- If `omx question` is unavailable in the current runtime, stop and surface that deep-interview requires the OMX question tool rather than falling back to another questioning path
+- Use `omx question` as the OMX-native structured user-input tool for each interview round when an attached tmux renderer is available
+- From attached-tmux Bash/tool paths, call it as `OMX_QUESTION_RETURN_PANE=$TMUX_PANE omx question ...` unless an explicit `%pane` return target is already known
+- If the current runtime is outside tmux and cannot render `omx question`, use native structured input when available; otherwise ask exactly one concise plain-text question and wait for the answer
+- After `omx question` returns JSON, prefer `answers[0].answer` / `answers[]`; use legacy `answer` only as a fallback for older records
 - Use `state_write` / `state_read` for resumable mode state
+- If the interview cannot ask a required `omx question` round, persist the blocker as terminal state with `active: false` and `current_phase: "blocked"`; do not write a terminal blocked phase with `active: true`
 - Read/write context snapshots under `.omx/context/`
 - Record whether the oversized-context summary gate is not needed, pending, or satisfied before any scoring or handoff step
 - Save transcript/spec artifacts under `.omx/interviews/` and `.omx/specs/`

package/plugins/oh-my-codex/skills/doctor/SKILL.md

@@ -123,7 +123,7 @@ ls -la ~/.agents/skills/ 2>/dev/null
 ```
 
 **Diagnosis**:
-- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for MCP/apps, but `omx setup` remains responsible for native agents/config/hooks.
+- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
 - If `~/.codex/commands/` exists with oh-my-codex-related files: WARN - legacy command files from older installs. Current OMX uses skills/workflows plus setup-managed native surfaces.
 - If `${CODEX_HOME:-~/.codex}/skills/` exists with OMX skills: OK - canonical current user skill root
 - If `~/.agents/skills/` exists: WARN - historical legacy skill root that can overlap with `${CODEX_HOME:-~/.codex}/skills/` and cause duplicate Enable/Disable Skills entries

package/plugins/oh-my-codex/skills/help/SKILL.md

@@ -49,7 +49,7 @@ If you haven't configured OMX yet:
 /omx-setup
 ```
 
-This is the primary setup command for full OMX runtime wiring. Codex plugin install/discovery can expose packaged skills/workflows plus plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks remain setup-owned; it is not a replacement for `npm install -g oh-my-codex` plus `omx setup`. `omx setup` remains responsible for native agents, prompts/config/hooks/AGENTS.md/HUD/runtime wiring, including native `.codex/hooks.json` coverage. Plugin caches may appear under `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/` (or `local` for local installs).
+This is the primary setup command for full OMX runtime wiring. Codex plugin install/discovery can expose packaged skills/workflows plus plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks remain setup-owned; it is not a replacement for `npm install -g oh-my-codex` plus `omx setup`. Legacy setup mode installs native agents/prompts; plugin setup mode archives stale legacy prompt/native-agent files and keeps config/hooks/optional AGENTS.md/HUD/runtime wiring current, including native `.codex/hooks.json` coverage. Plugin caches may appear under `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/` (or `local` for local installs).
 
 If you only need lightweight directory guidance scaffolding for `AGENTS.md` files, use:
 

package/plugins/oh-my-codex/skills/omx-setup/SKILL.md

@@ -10,17 +10,20 @@ Use this skill when users want to install or refresh oh-my-codex for the **curre
 ## Command
 
 ```bash
-omx setup [--force] [--dry-run] [--verbose] [--scope <user|project>] [--plugin]
+omx setup [--force] [--merge-agents] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>]
 ```
 
 If you only want lightweight `AGENTS.md` scaffolding for an existing repo or subtree, use `omx agents-init [path]` instead of full setup.
 
 Supported setup flags (current implementation):
 - `--force`: overwrite/reinstall managed artifacts where applicable
+- `--merge-agents`: when `AGENTS.md` already exists, preserve user-authored content and insert/refresh OMX-managed generated sections between explicit `<!-- OMX:AGENTS:START -->` / `<!-- OMX:AGENTS:END -->` markers
 - `--dry-run`: print actions without mutating files
 - `--verbose`: print per-file/per-step details
 - `--scope`: choose install scope (`user`, `project`)
-- `--plugin`: use Codex plugin delivery for skills/prompts/agents while keeping setup-owned runtime hooks
+- `--plugin`: use Codex plugin delivery for bundled skills while archiving/removing legacy OMX-managed prompts/native agents and keeping setup-owned runtime hooks
+- `--legacy`: use legacy setup delivery, overriding any persisted plugin install mode
+- `--install-mode`: explicitly choose setup delivery mode (`legacy` or `plugin`); canonical form for scripted setup
 
 ## What this setup actually does
 
@@ -29,38 +32,65 @@ Supported setup flags (current implementation):
 1. Resolve setup scope:
    - `--scope` explicit value
    - else persisted `./.omx/setup-scope.json` (with automatic migration of legacy values)
+   - if a TTY user has persisted setup preferences, `omx setup` first summarizes the recorded choices and asks whether to **keep**, **review/change**, or **reset** them
    - else interactive prompt on TTY (default `user`)
    - else default `user` (safe for CI/tests)
 2. If scope is `user`, resolve user skill delivery mode:
-   - explicit `--plugin`, if present
-   - persisted install mode in `./.omx/setup-scope.json`, if present
+   - explicit `--plugin`, `--legacy`, or `--install-mode legacy|plugin`, if present
+   - persisted install mode in `./.omx/setup-scope.json`, if present and the TTY review decision is `keep`
    - else discovered installed plugin cache under `${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json` with `name: oh-my-codex` makes `plugin` the default
    - else interactive prompt on TTY (`legacy` by default, or `plugin` when a plugin cache is discovered)
    - else default `legacy` unless a plugin cache is discovered
 3. Create directories and persist effective scope/install mode
-4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, remove matching legacy OMX-managed prompts/native agents/skills but keep native Codex hooks installed.
+4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, archive/remove legacy OMX-managed prompts/native agents/skills but keep native Codex hooks installed.
 5. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
 6. Generate AGENTS.md defaults only when selected/allowed (or legacy behavior outside plugin mode)
 7. Configure notify hook references outside plugin mode and write `./.omx/hud-config.json`
 
 ## Important behavior notes
 
-- `omx setup` only prompts for scope when no scope is provided/persisted and stdin/stdout are TTY.
-- In `user` scope, `omx setup` also prompts for skill delivery mode when no prior install mode is persisted; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice.
+- `omx setup` prompts for scope when no scope is provided and stdin/stdout are TTY. If `./.omx/setup-scope.json` already exists, setup now summarizes the saved choices first and asks whether to keep them, review/change them, or reset and behave like a fresh setup run.
+- Non-interactive setup never blocks for this review prompt: it keeps deterministic CLI/persisted/default behavior for CI and scripted installs.
+- In `user` scope, `omx setup` also prompts for skill delivery mode when no prior install mode is kept; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice.
 - Local project orchestration file is `./AGENTS.md` (project root).
-- If `AGENTS.md` exists and `--force` is not used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
+- If `AGENTS.md` exists and neither `--force` nor `--merge-agents` is used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
+- Use `--merge-agents` to keep existing project guidance while allowing setup to refresh OMX-managed AGENTS sections and the generated model capability table idempotently.
 - Scope targets:
   - `user`: user directories (`~/.codex`, `~/.codex/skills`, `~/.omx/agents`)
   - `project`: local directories (`./.codex`, `./.codex/skills`, `./.omx/agents`)
 - User-scope skill delivery targets:
   - `legacy`: keep installing/updating OMX skills in the resolved user skill root
-  - `plugin`: rely on Codex plugin discovery for bundled skills and remove only matching OMX-managed legacy prompts/skills/native agents; setup still installs native Codex hooks and `codex_hooks = true` because plugins do not carry hooks.
+  - `plugin`: rely on Codex plugin discovery for bundled skills and archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and `codex_hooks = true` because plugins do not carry hooks.
 - Migration hint: in `user` scope, if historical `~/.agents/skills` still exists alongside `${CODEX_HOME:-~/.codex}/skills`, current setup prints a cleanup hint. **Why the paths differ**: `${CODEX_HOME:-~/.codex}/skills/` is the path current Codex CLI natively loads as its skill root; `~/.agents/skills/` was the skill root in an older Codex CLI release before `~/.codex` became the standard home directory. OMX writes only to the canonical `${CODEX_HOME:-~/.codex}/skills/` path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove `~/.agents/skills/` to resolve this.
 - If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
 - Plugin mode prompts separately for optional AGENTS.md defaults and optional `developer_instructions` defaults. If `developer_instructions` already exists, setup asks before overwriting it; non-interactive runs preserve it.
-- With `--force`, AGENTS overwrite may still be skipped if an active OMX session is detected (safety guard).
+- With `--force` or `--merge-agents`, AGENTS updates may still be skipped if an active OMX session is detected (safety guard).
 - Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
 
+## Setup-owned configuration surfaces
+
+Use this map when reconciling setup behavior or debugging a confusing install:
+
+| Surface | Owner | Notes |
+| --- | --- | --- |
+| `./.omx/setup-scope.json` | `omx setup` | Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset. |
+| `~/.codex/config.toml` / `./.codex/config.toml` | `omx setup` generated blocks + user edits | Setup refreshes OMX-managed blocks while preserving supported manual content. |
+| `~/.codex/hooks.json` / `./.codex/hooks.json` | `omx setup` shared ownership | Setup owns OMX native hook wrappers and preserves user-owned hooks. |
+| prompts, skills, native agents | `omx setup` or Codex plugin delivery | Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills and archives/removes legacy OMX-managed prompt/native-agent copies. |
+| `AGENTS.md` | `omx setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
+| `./.omx/hud-config.json` | `omx setup` / `$hud` | Setup creates the focused default; `$hud` can adjust it later. |
+| notification hooks | `omx setup` / `$configure-notifications` | Setup wires defaults outside plugin skill delivery; notification skill owns deeper provider configuration. |
+
+## If `$omx-setup` is missing or stale
+
+The source repo ships `skills/omx-setup/SKILL.md` and the catalog marks it active. If Codex does not show `$omx-setup`, treat it as an installation/discovery issue rather than a missing source skill:
+
+1. Run `omx setup --verbose` in the intended scope.
+2. Run `omx doctor` and check the reported setup scope, Codex home, skill root, and hook/config status.
+3. If using project scope, confirm `./.codex/skills/omx-setup/SKILL.md` exists.
+4. If using user scope, confirm `${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md` exists in legacy mode, or that the oh-my-codex plugin is installed/discovered in plugin mode.
+5. If duplicate/stale skills appear, check for legacy `~/.agents/skills` overlap and follow the cleanup hint printed by setup/doctor.
+
 ## Recommended workflow
 
 1. Run setup:
@@ -102,3 +132,4 @@ node bin/omx.js doctor
 ```
 
 - If AGENTS.md was not overwritten during `--force`, stop active OMX session and rerun setup.
+- If AGENTS.md was not merged during `--merge-agents`, stop active OMX session and rerun setup.