oh-my-codex 0.17.3 → 0.18.1

package/plugins/oh-my-codex/hooks/hooks.json

@@ -0,0 +1,77 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ],
+        "matcher": "startup|resume|clear"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ],
+        "matcher": "Bash"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,56 +1,66 @@
 ---
 name: autopilot
-description: "[OMX] Strict autonomous loop: $ralplan -> $ralph -> $code-review"
+description: "[OMX] Strict autonomous loop: $deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa"
 ---
 
 <Purpose>
-Autopilot is the strict autonomous delivery loop for non-trivial work. Its primary contract is exactly:
+Autopilot is the strict autonomous delivery loop for non-trivial work. Its recommended/default contract is exactly:
 
 ```text
-$ralplan -> $ralph -> $code-review
+$deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa
 ```
 
-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.
+If `$code-review` or `$ultraqa` is not clean, Autopilot returns to `$ralplan` with the findings as the next planning input, then continues again through `$ultragoal`, `$code-review`, and `$ultraqa` until the gates are clean or a hard blocker is reported. Ralph is a legacy/explicit alternate execution loop only; do not advertise Ralph as the default Autopilot path.
 </Purpose>
 
 <Use_When>
-- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed code
+- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed and QA-checked 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
+- Task needs clarification, planning, durable execution, verification, code review, and QA with automatic follow-up when gates are not clean
 </Use_When>
 
 <Do_Not_Use_When>
 - 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 direct executor work
+- User wants a single focused code change -- use `$ultragoal`, `$ralph` only when explicitly requested, or direct executor work
 - User wants only review/critique of existing code -- use `$code-review`
 </Do_Not_Use_When>
 
 <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:
+Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the canonical workflow phases below:
 
-1. **Phase `ralplan`** — consensus planning gate
-   - Ground the task with pre-context intake.
+1. **Phase `deep-interview`** — Socratic requirements clarification gate
+   - Run or resume `$deep-interview` to clarify intent, scope, non-goals, constraints, and decision boundaries.
+   - Required handoff artifact: a clarified spec or concise requirements summary suitable for `$ralplan`.
+
+2. **Phase `ralplan`** — consensus planning gate
+   - Ground the task with pre-context intake and the deep-interview artifact.
    - 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`.
+   - When returning from a non-clean review or QA pass, include `return_to_ralplan_reason` and the findings as first-class planning input.
+   - Required handoff artifact: an approved plan/test spec suitable for `$ultragoal`.
 
-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 `ultragoal`** — durable implementation + verification loop
+   - Run `$ultragoal` from the approved ralplan artifacts.
+   - Ultragoal owns durable Codex goal handoffs, `.omx/ultragoal` ledger checkpoints, implementation, tests, build/lint/typecheck evidence, cleanup, and final review gate discipline.
+   - Use `$team` only inside an active Ultragoal story when the story clearly benefits from coordinated parallel execution (for example independent file/module lanes, broad test matrix work, or multi-domain implementation). Team remains explicit and leader-owned; Ultragoal keeps the goal/ledger state.
+   - Required handoff artifact: implementation evidence, changed-file summary, verification evidence, and Ultragoal ledger/checkpoint references suitable for `$code-review`.
 
-3. **Phase `code-review`** — merge-readiness gate
-   - Run `$code-review` on the diff/artifacts produced by `$ralph`.
+4. **Phase `code-review`** — merge-readiness gate
+   - Run `$code-review` on the diff/artifacts produced by `$ultragoal`.
    - 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.
+5. **Phase `ultraqa`** — adversarial QA gate
+   - Run `$ultraqa` after a clean code review when user-facing behavior, workflows, CLI/runtime behavior, integration surfaces, or regression risk warrant adversarial QA.
+   - For docs-only or trivially non-runtime changes, record `ultraqa` as skipped with an explicit condition and evidence.
+   - If UltraQA finds issues, persist the QA verdict/evidence, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`.
+
+The only normal terminal state is `complete` after clean code review and a passed or explicitly skipped UltraQA gate. 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:
+Before Phase `deep-interview` or `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:
@@ -60,16 +70,18 @@ Before Phase `ralplan` starts or resumes:
    - 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`.
+4. If brownfield facts are missing, run `explore` first before or during `$deep-interview` (`$deep-interview --quick <task>` remains acceptable for bounded low-ambiguity intake); do not skip the clarification gate merely because the task sounds actionable.
 5. Carry the snapshot path in Autopilot state and all handoff artifacts.
 </Pre-context Intake>
 
 <Execution_Policy>
-- 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.
+- Always execute the recommended phases in order: `deep-interview`, then `ralplan`, then `ultragoal`, then `code-review`, then `ultraqa`.
+- `$team` is conditional and explicit: use it only within an Ultragoal story when parallel execution materially improves throughput, quality, or safety.
+- Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified and planned through `$deep-interview` and `$ralplan`.
+- A non-clean `$code-review` or failed `$ultraqa` 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.
+- Use existing hooks, `.omx/state`, `$deep-interview`, `$ralplan`, `$ultragoal`, optional `$team`, `$code-review`, `$ultraqa`, and pipeline primitives; do not invent a separate execution framework.
+- Preserve legacy compatibility: if a user explicitly requests the old Ralph execution lane, use `$ralph` as an intentional alternate execution phase, but do not present it as Autopilot's default recommended loop.
 - 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>
@@ -83,81 +95,99 @@ Required fields:
 {
   "mode": "autopilot",
   "active": true,
-  "current_phase": "ralplan",
+  "current_phase": "deep-interview",
   "iteration": 1,
   "review_cycle": 0,
   "max_iterations": 10,
-  "phase_cycle": ["ralplan", "ralph", "code-review"],
+  "phase_cycle": ["deep-interview", "ralplan", "ultragoal", "code-review", "ultraqa"],
   "handoff_artifacts": {
     "context_snapshot_path": ".omx/context/<slug>-<timestamp>.md",
+    "deep_interview": null,
     "ralplan": null,
-    "ralph": null,
-    "code_review": null
+    "ultragoal": null,
+    "code_review": null,
+    "ultraqa": null
   },
   "review_verdict": null,
+  "qa_verdict": null,
   "return_to_ralplan_reason": null
 }
 ```
 
-- **On start**: `omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ralplan","iteration":1,"review_cycle":0,"state":{"phase_cycle":["ralplan","ralph","code-review"],"handoff_artifacts":{"context_snapshot_path":"<snapshot-path>","ralplan":null,"ralph":null,"code_review":null},"review_verdict":null,"return_to_ralplan_reason":null}}' --json`
-- **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 start**: `omx state write --input '{"mode":"autopilot","active":true,"current_phase":"deep-interview","iteration":1,"review_cycle":0,"state":{"phase_cycle":["deep-interview","ralplan","ultragoal","code-review","ultraqa"],"handoff_artifacts":{"context_snapshot_path":"<snapshot-path>","deep_interview":null,"ralplan":null,"ultragoal":null,"code_review":null,"ultraqa":null},"review_verdict":null,"qa_verdict":null,"return_to_ralplan_reason":null}}' --json`
+- **On deep-interview -> ralplan**: set `current_phase:"ralplan"`, persist the clarified spec/requirements under `handoff_artifacts.deep_interview`.
+- **On ralplan -> ultragoal**: set `current_phase:"ultragoal"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
+- **On ultragoal -> code-review**: set `current_phase:"code-review"`, persist implementation/test/ledger evidence under `handoff_artifacts.ultragoal`.
+- **On code-review -> ultraqa**: set `current_phase:"ultraqa"`, persist the clean review under `handoff_artifacts.code_review`.
+- **On clean review + passed/skipped QA**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}`, `qa_verdict:{clean:true, skipped:<boolean>, reason:<string|null>}`, and `completed_at`.
+- **On non-clean review or failed QA**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict` or `qa_verdict`, persist the phase handoff, and set `return_to_ralplan_reason` to a concise findings-driven reason.
+- **Legacy Ralph state**: if a user explicitly selected the legacy Ralph execution lane, phase names and handoff keys may include `ralph`; preserve and resume them rather than rewriting history to Ultragoal.
 - **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`:
+- `deep-interview`: clarify requirements and record the handoff artifact.
 - `ralplan`: run/update consensus planning from current handoffs and any `return_to_ralplan_reason`.
-- `ralph`: execute the approved plan and record verification evidence.
+- `ultragoal`: execute the approved plan durably and record verification/ledger evidence.
+- `team`: continue explicit team work only when it is nested under the active Ultragoal story and report evidence back to the leader.
 - `code-review`: review the current diff and decide clean vs return-to-ralplan.
+- `ultraqa`: run or explicitly skip adversarial QA based on the documented condition, then finish if clean or transition to `ralplan` with findings if not clean.
+- `ralph`: resume only for explicit legacy Ralph-path Autopilot state.
 - `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:
+Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The default Autopilot pipeline contract is:
 
 ```text
-ralplan -> ralph -> code-review
+deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa
 ```
 
-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 state should use `current_phase` values that match the same phase names (`deep-interview`, `ralplan`, `ultragoal`, `code-review`, `ultraqa`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, `qa_verdict`, and `return_to_ralplan_reason` alongside stage results. `$team` is not a default pipeline stage; it is an explicit conditional execution engine inside an Ultragoal story.
 </Pipeline_Orchestrator>
 
 <Escalation_And_Stop_Conditions>
 - 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 and report when the same review or QA 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.
+- Otherwise, continue the loop until `$code-review` is clean and `$ultraqa` has passed or been explicitly skipped with evidence.
 </Escalation_And_Stop_Conditions>
 
 <Final_Checklist>
+- [ ] Phase `deep-interview` produced/updated clarified requirements or a concise spec
 - [ ] Phase `ralplan` produced/updated approved planning artifacts
-- [ ] Phase `ralph` implemented and verified the plan with fresh evidence
+- [ ] Phase `ultragoal` implemented and verified the plan with fresh evidence and durable ledger/checkpoint references
+- [ ] `$team` was used only if the active Ultragoal story needed coordinated parallel work, or explicitly recorded as not needed
 - [ ] 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
+- [ ] Phase `ultraqa` passed, or was explicitly skipped because the change was docs-only/trivially non-runtime with evidence
+- [ ] `review_verdict.clean` is true, `qa_verdict.clean` is true, and `return_to_ralplan_reason` is null
+- [ ] Tests/build/lint/typecheck evidence from Ultragoal 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
+- [ ] User receives a concise summary with clarification, plan, implementation, verification, review, and QA evidence
 </Final_Checklist>
 
 <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.
+Flow: create/load context snapshot -> `$deep-interview` requirements check -> `$ralplan` issue plan -> `$ultragoal` durable implementation + tests (launch `$team` only if a story needs parallel lanes) -> `$code-review` -> `$ultraqa`; if review or QA requests changes, return to `$ralplan` with findings.
 </Good>
 
 <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.
+Flow: run `$code-review` on current diff, persist verdict, transition to `ultraqa` if clean or to `ralplan` with findings if not clean.
+</Good>
+
+<Good>
+User: `$autopilot --legacy-ralph finish the migration`
+Flow: preserve the explicit legacy Ralph execution choice and run the old Ralph execution lane as an alternate, without changing the documented default Autopilot recommendation.
 </Good>
 
 <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.
+Why bad: this bypasses the strict `$deep-interview -> $ralplan -> $ultragoal -> $code-review -> $ultraqa` contract.
 </Bad>
 </Examples>

package/plugins/oh-my-codex/skills/best-practice-research/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: best-practice-research
+description: "[OMX] Bounded best-practice research wrapper using official/upstream evidence first"
+argument-hint: "<technology|decision|practice question>"
+---
+
+# Best-Practice Research
+
+Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace `researcher`.
+
+## Purpose
+
+Produce a cited, reusable best-practice answer or handoff that separates current external evidence from repo-local facts and dependency-selection decisions.
+
+## Activate When
+
+- The user asks for best practices, recommended approach, current guidance, official recommendations, standards, or version-aware external behavior.
+- `$ralplan`, `$deep-interview`, `$team`, or another workflow needs current external evidence before planning or execution can be correct.
+- The task involves an already chosen technology and needs authoritative usage guidance, migration notes, API behavior, lifecycle rules, or current safety guidance.
+
+## Do Not Activate When
+
+- The answer is fully repo-local; use `explore` for codebase facts.
+- The main question is whether to adopt, replace, upgrade, or compare dependencies; use `dependency-expert`.
+- The user only needs implementation against already-grounded requirements; use `executor`, `$ralph`, or `$team` as appropriate.
+- The task can be answered from stable local project conventions without current external lookup.
+
+## Specialist Routing
+
+1. Use `explore` first for brownfield facts: current code usage, local constraints, versions, config, and integration points.
+2. Use `researcher` for official/upstream docs, release notes, standards, migration guides, source-backed examples, and current best-practice evidence for an already chosen technology.
+3. Use `dependency-expert` only for adoption/upgrade/replacement/comparison decisions.
+4. Return to the caller with explicit evidence, uncertainty, and any implementation handoff constraints.
+
+## Source-Quality Rules
+
+- Prefer official documentation, upstream source, release notes, changelogs, standards, and maintainer guidance.
+- Include source URLs for material claims.
+- State date/version context for current best-practice claims.
+- Label third-party summaries as supplemental; do not use them before official/upstream sources.
+- Flag stale, conflicting, undocumented, or version-mismatched evidence.
+- Do not over-fetch: gather the smallest evidence set that can support the decision.
+
+## Workflow
+
+1. Classify the question: conceptual best practice, implementation guidance, migration/version guidance, standards/compliance guidance, or mixed local + external guidance.
+2. Gather repo-local facts with `explore` when local usage or constraints affect the answer.
+3. Gather external evidence with `researcher` when current or version-aware practice affects correctness.
+4. Synthesize a concise answer with source quality, version/date context, caveats, and an implementation or planning handoff.
+5. Stop when the answer is grounded enough for the caller; otherwise report the exact blocker or specialist handoff needed.
+
+## Output Contract
+
+```md
+## Best-Practice Research: <question>
+
+### Direct Recommendation
+<actionable guidance or decision support>
+
+### Evidence Used
+- Official/upstream: <source URL> — <what it establishes>
+- Supplemental, if any: <source URL> — <why it is secondary>
+
+### Version / Date Context
+<versions, dates, release channels, or unknowns>
+
+### Repo-Local Context
+<facts from explore, or "not needed">
+
+### Boundaries / Non-goals
+<what this research does not decide>
+
+### Handoff
+<planning/execution/test implications>
+```
+
+## Stop Rules
+
+- Stop after a source-backed recommendation is reusable by the caller.
+- Stop and route upward if the task becomes dependency comparison, broad architecture, or implementation.
+- Do not continue researching when remaining work would only polish wording rather than change the recommendation.
+
+Task: {{ARGUMENTS}}

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

@@ -56,7 +56,7 @@ For Ralph-targeted cancellation (standalone or linked), completion is defined by
 See: `docs/contracts/ralph-cancel-contract.md`.
 
 Active modes are still cancelled in dependency order:
-1. Autopilot (includes linked ralph/ultraqa/ecomode cleanup)
+1. Autopilot (includes linked ultragoal/ultraqa/ecomode cleanup plus explicit legacy Ralph cleanup)
 2. Ralph (cleans its linked ultrawork or ecomode)
 3. Ultrawork (standalone)
 4. Ecomode (standalone)
@@ -374,7 +374,7 @@ Mode-specific subsections below describe what extra cleanup each handler perform
 
 ## Notes
 
-- **Dependency-aware**: Autopilot cancellation cleans up Ralph and UltraQA
+- **Dependency-aware**: Autopilot cancellation cleans up Ultragoal/UltraQA state and any explicit legacy Ralph state
 - **Link-aware**: Ralph cancellation cleans up linked Ultrawork or Ecomode
 - **Safe**: Only clears linked Ultrawork, preserves standalone Ultrawork
 - **Local-only**: Clears state files in `.omx/state/` directory

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

@@ -56,6 +56,7 @@ If no flag is provided, use **Standard**.
 - 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?"
 - Route facts before judgment in the Ouroboros style: before presenting a user-facing interview round, classify whether the needed information is a discoverable fact, a fact needing confirmation, or a human decision. The interview is with the human for judgment, not for facts the agent can inspect.
+- When unresolved ambiguity depends on current external best practices, official/upstream guidance, standards, or version-aware behavior, use `$best-practice-research` as the bounded evidence wrapper before crystallizing requirements or handing off to planning/execution.
 - Use these transcript/spec labels only; never use them as `omx question` `source` values, and never replace the runtime `source: "deep-interview"` contract for user-facing deep-interview questions:
   - `[from-code][auto-confirmed]` — exact, high-confidence codebase facts from manifests/configs or direct source evidence, with no prescription attached.
   - `[from-code]` — codebase findings that are useful but inferred, pattern-based, or low/medium confidence and therefore need a confirmation-style user-facing round before being treated as settled.
@@ -369,7 +370,7 @@ Include these product-facing suggestions when they fit the clarified spec, witho
 - **`$autoresearch-goal`** — use when the clarified context is a research project: a research question, reference/literature gathering, evaluator-backed analysis, or professor/critic-style deliverable.
 - **`$performance-goal`** — use when the clarified context is an optimization or performance project with measurable speed, latency, throughput, memory, benchmark, or evaluator criteria.
 
-Preserve `$ralph` for persistent single-owner execution/verification and `$team` for coordinated parallel implementation. Present goal-mode options as context-sensitive next steps, not as generic replacements for implementation lanes.
+Recommend `$ultragoal` as the default durable goal-mode follow-up because it supersedes Ralph for goal tracking. Preserve `$team` for coordinated parallel implementation and keep `$ralph` only as an explicit fallback for persistent single-owner execution/verification when the user specifically selects it.
 
 ### 1. **`$ralplan` (Recommended)**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md` (optionally accompanied by the transcript/context snapshot for traceability)
@@ -378,7 +379,7 @@ Preserve `$ralph` for persistent single-owner execution/verification and `$team`
 - **Skipped / Already-Satisfied Stages:** Requirements discovery, ambiguity clarification, and early intent-boundary elicitation
 - **Expected Output:** Canonical planning artifacts under `.omx/plans/`, especially `prd-*.md` and `test-spec-*.md`
 - **Best When:** Requirements are clear enough to stop interviewing, but architectural validation / consensus planning is still desirable
-- **Next Recommended Step:** Use the approved planning artifacts with `$autopilot`, `$ralph`, `$team`, or `$ultragoal` as the default goal-mode follow-up; choose `$autoresearch-goal` for research validation or `$performance-goal` for measurable optimization
+- **Next Recommended Step:** Use the approved planning artifacts with `$ultragoal` as the default durable goal-mode follow-up (optionally with `$team` for parallel lanes); choose `$autoresearch-goal` for research validation or `$performance-goal` for measurable optimization, and use `$ralph` only as an explicit fallback when a narrow single-owner persistence loop is requested
 
 ### 2. **`$autopilot`**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
@@ -387,25 +388,25 @@ Preserve `$ralph` for persistent single-owner execution/verification and `$team`
 - **Skipped / Already-Satisfied Stages:** Initial requirement discovery and ambiguity reduction
 - **Expected Output:** Planning/execution progress, QA evidence, and validation artifacts produced by autopilot
 - **Best When:** The clarified spec is already strong enough for direct planning + execution without an additional consensus gate
-- **Next Recommended Step:** Continue through autopilot's execution/QA/validation flow; if coordination-heavy execution emerges, prefer a follow-up `$team` or `$ralph` lane as appropriate
+- **Next Recommended Step:** Continue through autopilot's execution/QA/validation flow; if coordination-heavy execution emerges, prefer `$team` under a leader-owned `$ultragoal` ledger, using `$ralph` only as an explicit fallback when a narrow single-owner persistence loop is requested
 
-### 3. **`$ralph`**
+### 3. **`$ralph` (Explicit fallback only)**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
 - **Invocation:** `$ralph <spec-path>`
 - **Consumer Behavior:** Use the spec's acceptance criteria and boundary constraints as the persistence target. Do not reopen requirements discovery unless the user explicitly asks to refine further.
 - **Skipped / Already-Satisfied Stages:** Requirement interview, ambiguity clarification, and initial scope-definition work
 - **Expected Output:** Iterative execution progress and verification evidence tracked against the clarified criteria
-- **Best When:** The task benefits from persistent sequential completion pressure and the user wants execution to keep moving until the criteria are satisfied or a real blocker exists
-- **Next Recommended Step:** Continue Ralph's persistence loop; if work expands into coordination-heavy lanes, hand off to `$team` and keep Ralph for verification continuity
+- **Best When:** The user explicitly asks for Ralph's persistent sequential completion pressure; otherwise use `$ultragoal` for durable goal tracking and completion checkpoints
+- **Next Recommended Step:** If this explicit fallback is selected, continue Ralph's persistence loop; if work expands into coordination-heavy lanes, hand off to `$team` under `$ultragoal` checkpointing rather than promoting Ralph as the next default
 
 ### 4. **`$team`**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
 - **Invocation:** `$team <spec-path>`
 - **Consumer Behavior:** Treat the spec as shared execution context for coordinated parallel work. Preserve the clarified intent, non-goals, decision boundaries, and acceptance criteria as common lane constraints.
 - **Skipped / Already-Satisfied Stages:** Requirement clarification and early ambiguity reduction
-- **Expected Output:** Coordinated multi-agent execution against the shared spec, with evidence that can later feed a Ralph verification pass when appropriate
+- **Expected Output:** Coordinated multi-agent execution against the shared spec, with evidence that can later feed Ultragoal checkpoints by default, or an explicit Ralph verification pass only when requested
 - **Best When:** The task is large, multi-lane, or blocker-sensitive enough to justify coordinated parallel execution instead of a single persistent loop
-- **Next Recommended Step:** Follow the team verification path when the coordinated execution phase finishes; escalate to a separate Ralph loop only when a later persistent verification/fix owner is still needed
+- **Next Recommended Step:** Follow the team verification path when the coordinated execution phase finishes; checkpoint completion through `$ultragoal` by default, escalating to a separate Ralph loop only when the user explicitly asks for that persistent verification/fix owner
 
 ### 5. **Refine further**
 - **Input Artifact:** Existing transcript, context snapshot, and current spec draft

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

@@ -60,7 +60,7 @@ Supported setup flags (current implementation):
   - `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 archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and setup-owned runtime feature flags (`hooks = true` on current Codex, legacy `codex_hooks = true` when that is the only reported hook feature, plus `goals = true`) because plugins do not carry hooks or enable Codex goal mode by themselves.
+  - `plugin`: rely on Codex plugin discovery for bundled skills and plugin-scoped lifecycle hooks when Codex reports `plugin_hooks`; archive/remove legacy OMX-managed prompts/skills/native agents. Setup still enables setup-owned runtime feature flags (`plugin_hooks = true` and `goals = true` when supported, or legacy setup-managed `hooks`/`codex_hooks` fallback when plugin hooks are not reported).
 - 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.

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

@@ -10,19 +10,21 @@ through a uniform `PipelineStage` interface, with state persistence and resume s
 
 ## Default Autopilot Pipeline
 
-The canonical OMX pipeline sequences:
+The default Autopilot pipeline sequences:
 
 ```
-RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (architect verification)
+deep-interview -> ralplan -> ultragoal (+ team if needed) -> code-review -> ultraqa
 ```
 
+`$team` is conditional: use it only inside an active Ultragoal story when independent lanes or broad verification make coordinated parallel execution useful. Explicit legacy Ralph pipelines remain available through custom stages, but Ralph is not the advertised default Autopilot loop.
+
 ## Configuration
 
 Pipeline parameters are configurable per run:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `maxRalphIterations` | 10 | Ralph verification iteration ceiling |
+| `maxRalphIterations` | 10 | Quality-gate retry ceiling; legacy option name retained for compatibility |
 | `workerCount` | 2 | Number of Codex CLI team workers |
 | `agentType` | `executor` | Agent type for team workers |
 
@@ -43,9 +45,12 @@ return a `StageResult` with status, artifacts, and duration.
 
 ## Built-in Stages
 
+- **deep-interview**: Requirements clarification and ambiguity gate.
 - **ralplan**: Consensus planning (planner + architect + critic). Skips only when both `prd-*.md` and `test-spec-*.md` planning artifacts already exist, and carries any `deep-interview-*.md` spec paths forward for traceability.
-- **team-exec**: Team execution via Codex CLI workers. Always the OMX execution backend.
-- **ralph-verify**: Ralph verification loop with configurable iteration count.
+- **ultragoal**: Durable goal-mode execution with `.omx/ultragoal` ledgers. Launch `$team` only from inside an Ultragoal story when parallel lanes are warranted.
+- **code-review**: Merge-readiness review gate.
+- **ultraqa**: Adversarial QA gate after a clean review; docs-only/trivially non-runtime changes may record an explicit skip reason.
+- **team-exec** and **ralph-verify**: Legacy/custom pipeline adapters retained for explicit non-default pipelines.
 
 ## State Management
 
@@ -62,16 +67,20 @@ The HUD renders pipeline phase automatically. Resume is supported from the last
 import {
   runPipeline,
   createAutopilotPipelineConfig,
+  createDeepInterviewStage,
   createRalplanStage,
-  createTeamExecStage,
-  createRalphVerifyStage,
+  createUltragoalStage,
+  createCodeReviewStage,
+  createUltraqaStage,
 } from './pipeline/index.js';
 
 const config = createAutopilotPipelineConfig('build feature X', {
   stages: [
+    createDeepInterviewStage(),
     createRalplanStage(),
-    createTeamExecStage({ workerCount: 3, agentType: 'executor' }),
-    createRalphVerifyStage({ maxIterations: 15 }),
+    createUltragoalStage(),
+    createCodeReviewStage(),
+    createUltraqaStage(),
   ],
 });
 
@@ -82,5 +91,7 @@ const result = await runPipeline(config);
 
 - **autopilot**: Autopilot can use pipeline as its execution engine (v0.8+)
 - **team**: Pipeline delegates execution to team mode (Codex CLI workers)
-- **ralph**: Pipeline delegates verification to ralph (configurable iterations)
-- **ralplan**: Pipeline's first stage runs RALPLAN consensus planning
+- **ultragoal**: Autopilot delegates durable execution to Ultragoal by default
+- **team**: Optional execution engine inside an Ultragoal story when parallel lanes are needed
+- **ralph**: Available only for explicit legacy/custom pipelines
+- **ralplan**: Pipeline planning runs RALPLAN consensus planning