oh-my-codex-pennix 0.18.13

package/skills/prometheus-strict/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: prometheus-strict
+description: "[OMX] Clean-room interview-driven planner: Metis clarifies, Momus challenges, Oracle synthesizes, then hands off to $ultragoal/$team."
+argument-hint: "<goal or problem statement>"
+---
+
+# Prometheus Strict
+
+Clean-room OMX planning workflow inspired by the high-level OMO Prometheus concept only. This skill does not copy implementation, prompts, wording, control flow, or runtime code from OMO. It reimplements the idea under this repository's MIT-licensed skill conventions.
+
+Credit: Inspired by OMO Prometheus (`code-yeongyu/oh-my-openagent`), reimplemented from concept under MIT.
+
+<Purpose>
+Prometheus Strict creates a rigorous plan before execution when ambiguity is still risky. It separates three planning voices: Metis clarifies requirements, Momus challenges assumptions and validation gaps, and Oracle synthesizes the handoff-ready OMX-native plan.
+
+The output is a planning-only artifact for `$ultragoal` and, when independent lanes are justified, `$team`. When a durable artifact is useful, store or request the final plan under `.omx/plans/prometheus-strict/`.
+</Purpose>
+
+<Use_When>
+- The task is important enough that a shallow plan could produce wrong work.
+- Requirements are partially known but acceptance criteria, boundaries, risks, or validation are incomplete.
+- The user wants a strict interview before execution.
+- A future `$ultragoal` story needs durable scope, tests, and handoff sequencing.
+- A team split may be needed, but the lanes are not yet safe to assign.
+</Use_When>
+
+<Do_Not_Use_When>
+- The user asks for immediate implementation of a clear, low-risk change; use the normal executor path.
+- The task is only a repository lookup or explanation; use `explore`/`analyze` as appropriate.
+- The user needs adversarial execution QA after code changes; use `$ultraqa`.
+- The user wants hook behavior, Sisyphus behavior, or a `start-work` port. Those are explicit non-goals.
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+OMX already has `$plan`, `$ralplan`, and `$deep-interview`. Prometheus Strict exists for a narrower case: an explicit clean-room strict-planning lane with named clarification, critique, and synthesis roles, plus a durable `.omx/plans/prometheus-strict/` handoff contract. It is not a replacement for execution workflows.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Stay planning-only. Do not edit source code during this skill unless the user starts a separate execution workflow afterward.
+- Preserve clean-room boundaries. Do not copy or imitate OMO wording, source, prompts, runtime behavior, or control flow.
+- Keep non-goals visible: No hook implementation. No Sisyphus/start-work port. No automatic external-production actions.
+- Ask high-leverage questions as a batched round when the answers materially change scope, safety, or validation. Reserve one-at-a-time questioning only for dependent question chains where the next question depends on the previous answer.
+- If a safe assumption is available, state it and continue.
+- Use repository reads when needed to make paths, tests, and handoff commands concrete.
+- During Metis planning, run pre-question research fan-out for every non-trivial intent unless the task is trivial, the cited spec is self-contained, or cached evidence already covers the same surface; use `explore` for repo facts and the exact cheap `gpt-5.4-mini` `researcher` lane for external docs / OSS references before asking the user. Prometheus Strict may fan out up to `2 explore + 4 researcher` agents per round so breadth comes from more citation-focused mini researchers while Metis/Momus/Oracle keep stronger judgment roles.
+- Recommend `$team` only when Oracle identifies independent, bounded, verifiable lanes.
+
+### Structured Question Surface
+
+Every Metis/Momus/Oracle question to the user MUST go through the surface-appropriate structured question path. Plain prose questioning is the last fallback, not the default.
+
+- In attached-tmux OMX runtime, use `omx question` as the OMX-owned structured question surface (this is the `AskUserQuestion` equivalent for Prometheus Strict). From attached-tmux Bash/tool paths, prefix the command with `OMX_QUESTION_RETURN_PANE=$TMUX_PANE` (or a concrete `%pane` value) so the leader-pane return target is preserved.
+- **Batch independent high-leverage questions into a single `questions[]` array call**: scope, constraints, non-goals, deliverables, safety bounds, and acceptance criteria are normally independent and MUST be batched into one structured form so the user answers them in a single panel. Reserve one-at-a-time only for dependent question chains where the next question depends on the previous answer.
+- Wait for the `omx question` JSON answer before checking the clearance rule, asking another round, or handing off; prefer `answers[]` / `answers[i].answer`, and use the legacy top-level `answer` only as a compatibility fallback. After every `answers[]` batch, run at least **two gap-fill passes** before another question or handoff: Pass 1 assimilates user answers into the checklist; Pass 2 re-scans repo context, prior turns, research fan-out evidence, and conservative defaults to absorb non-CRITICAL residual gaps.
+- Minimum two emitted question rounds: when Metis emits any user-facing question round, do not hand off after Round 1 unless hostility/`<turn_aborted>` or the round-5 cap forces exit; handoff is allowed only after Round 2 has been emitted and processed. Zero-question complete-checklist handoff remains valid when no questions were emitted.
+- Between-round planning must actively use evidence: after Round 1 answers and the two gap-fill passes, refresh or reuse `<research_fan_out>` explore/researcher evidence, re-run spec prefill, and build Round 2 from residual CRITICAL gaps only.
+- Outside tmux, use the native structured input tool when one is available.
+- When neither structured surface can render (non-tmux Codex CLI, piped runs, CI), list the round's independent questions as a numbered prose block (`Q1: ... Q2: ... Q3: ...`) and wait for all answers in one user turn; do not split into separate round-trips.
+- Multiple interview rounds ARE expected when clearance is not yet reached; each round is one batched form (or its prose fallback), never split across forms.
+
+### Checklist Clearance
+
+The interview is governed by deterministic checklist clearance, not by subjective "feels enough" judgement. Exit the Metis interview loop when the 6-item checklist is fully YES: objective / scope IN+OUT / acceptance / test strategy / handoff target / no outstanding CRITICAL. Each item is evaluated with the tri-state defined in `<Turn_Termination_Rules>`.
+
+Cap interview rounds at **5** to prevent runaway. If checklist clearance is not reached by round 5, hand the remaining UNKNOWN items to Oracle as explicitly carried-forward `<unresolved_blocker>` entries.
+
+**Hostility / non-answer exit**: if the user's responses for a round contain refusal signals (1-2 character non-answers, dismissive `알아서` / "you decide" / "whatever" patterns, profanity-laden responses, or a `<turn_aborted>` on the prior turn), the round invalidates the answers — it does NOT advance any checklist item to YES, exits the interview loop immediately, and routes the unresolved gaps either to `<silent_absorption>` (for dismissive delegation) or back to the user via `hostility_exit` (for anger / aborted turns). See `prometheus-strict-metis` `<hostility_detection>` for the full pattern list and routing rules.
+</Execution_Policy>
+
+<Turn_Termination_Rules>
+Every Prometheus Strict turn ends with EXACTLY ONE of the following terminations. Bare summaries and "I think we're done" are forbidden.
+
+The 6-item checklist is: objective / scope IN+OUT / acceptance / test strategy / handoff target / no outstanding CRITICAL. A checklist item is YES when it is USER_ANSWERED ∪ ABSORBED_WITH_CITATION ∪ INFERRED_FROM_SPEC. Only UNKNOWN (no answer, no citation, no spec inference) counts as NO.
+
+- (a) `omx question` batch: use when at least one CRITICAL question survives `<gap_triage>` and `<self_review>`. The batch is the round; the turn waits for `answers[]` before continuing.
+- (b) explicit handoff: use when the 6-item checklist is fully YES. Hand off Metis → Momus after clearance, Momus → Oracle after critique, and Oracle → user or `<unresolved_blocker>` carry-forward after Pass 2 synthesis.
+- (c) stop-blocker: use when hostility/`<turn_aborted>` is detected via `<hostility_detection>` with subtype `hostility_exit`, or when the next action is destructive, credential-gated, external-production, and cannot be defaulted safely.
+
+Edge cases:
+1. Zero-questions-but-complete-checklist → option (b) explicit handoff. Do not emit an empty `omx question` form.
+2. Round-5-cap with incomplete checklist → option (a) emit one more question batch with surviving UNKNOWN items annotated, OR option (b) handoff with UNKNOWN items carried forward to Oracle as `<unresolved_blocker>` entries.
+3. Hostility/`<turn_aborted>` → option (c) for anger, profanity, or aborted-turn via `hostility_exit`; option (b) for dismissive-delegation (`알아서` / "you decide") with absorbed gaps annotated.
+</Turn_Termination_Rules>
+
+<Steps>
+### 1. Intake and Safety Bounds
+
+Restate the target result, known constraints, deliverables, validation expectations, and stop condition. Identify whether this turn is planning-only or whether the user also requested downstream execution.
+
+If the prompt contains destructive, credential-gated, external-production, or materially scope-changing decisions, hold those decisions for explicit user confirmation. Otherwise, continue through the planning loop.
+
+### 2. Metis Interview (Iterative, Checklist Clearance)
+
+Use `prometheus-strict-metis` as the interview voice. When native subagents are available, invoke the dedicated agent; otherwise run the same role in-context without editing files.
+
+Metis discovers success criteria, non-goals, evidence versus assumptions, required artifacts, likely execution lanes, and missing decisions. Before the first user-facing question batch, Metis must actively fan out repo/external research per intent: `explore` maps local surfaces and exact `gpt-5.4-mini` `researcher` lanes gather official/upstream or OSS-reference evidence. Research-heavy intents use more cheap researchers rather than downgrading Metis/Momus/Oracle judgment.
+
+Run the interview as a bounded loop:
+
+1. Identify every currently-UNKNOWN checklist item and every CRITICAL question whose answers would materially change scope, safety, or validation.
+2. Batch the round's independent questions into a single Structured Question Surface call (`questions[]` array, or numbered prose fallback outside tmux).
+3. Collect the structured `answers[]`, then run **Gap-fill Pass 1 — answer assimilation**: update evidence vs. assumption and mark checklist items YES only when USER_ANSWERED, ABSORBED_WITH_CITATION, or INFERRED_FROM_SPEC.
+4. Run **Gap-fill Pass 2 — residual adversarial scan**: re-check every remaining UNKNOWN against repo context, prior turns, research fan-out evidence, framework/industry defaults, and conservative reversible defaults; absorb non-CRITICAL gaps with citations/assumptions and leave only CRITICAL blockers.
+5. Run **between-round planning** after Round 1: refresh or reuse `<research_fan_out>` explore/researcher evidence, re-run spec prefill, and prepare Round 2 from residual CRITICAL gaps only.
+6. Evaluate the 6-item checklist (`<Turn_Termination_Rules>` tri-state) only after BOTH gap-fill passes and the minimum two emitted question rounds gate; exit when ALL YES and either no questions were emitted or Round 2 has been emitted and processed.
+7. If checklist clearance is not reached, or only Round 1 has been processed, return to step 1 with the next round. Cap at 5 rounds; on cap, carry remaining UNKNOWN items forward to Oracle as explicit `<unresolved_blocker>` entries.
+
+### 3. Momus Challenge (Bounded Retry)
+
+Use `prometheus-strict-momus` as the adversarial critique voice. When native subagents are available, invoke the dedicated agent; otherwise run the same role in-context without editing files.
+
+Momus challenges underspecified acceptance criteria, unsafe assumptions, hidden destructive steps, overbroad scope, missing verification, ownership conflicts, and `$ultragoal`/`$team` handoff ambiguity.
+
+**Bounded retry contract**: after Oracle synthesizes in §4, re-invoke Momus on the synthesized plan to verify that Oracle's resolutions did not introduce new risks (scope addition without matching verification, lane split that creates dependency cycles, safety reinforcement that contradicts stop conditions). Repeat the Momus → Oracle re-synthesis cycle up to **3 times total**. If blocking objections remain after the 3rd cycle, mark them as carried-forward in the final plan and proceed to §5.
+
+### 4. Oracle Synthesis (Two-Pass: Synthesis + Self-Verification)
+
+Use `prometheus-strict-oracle` as the synthesis voice. When native subagents are available, invoke the dedicated agent; otherwise run the same role in-context without editing files.
+
+**Pass 1 — Synthesis.** Oracle produces the final objective, scope and non-goals, accepted assumptions, resolved critique, sequenced steps or lanes, verification matrix, rollback/escalation conditions, and recommended OMX handoff.
+
+**Pass 2 — Self-Verification (machine-checkable acceptance contract).** Oracle re-reads its own Pass 1 output and asserts:
+
+- Every claim in the verification matrix has an explicit evidence source (test/build/lint/e2e/doc).
+- Every step lists its owner / lane / executor; no shared-file conflicts between parallel lanes.
+- Stop, rollback, and acceptance criteria are mutually consistent (no acceptance criterion is satisfied by a state that also triggers rollback).
+- No destructive, credential-gated, or external-production step is unauthorized.
+- The handoff command is concrete (callable verbatim) and points at an existing workflow (`$ultragoal`, `$team`, or `none`).
+- Clean-room credit is preserved.
+
+If any Pass 2 check fails, Oracle MUST loop back to Pass 1 to repair before emitting the plan. Cap Pass 1 ↔ Pass 2 cycles at **3**; on cycle 3 failure, emit the plan with the failing gates annotated as carried-forward and escalate to the user.
+
+### 5. Post-Plan Gap Check (Metis Re-Invocation)
+
+Before handing off, re-invoke `prometheus-strict-metis` on the finalized Oracle plan with a single charge: identify ambiguities that surfaced **only after** the plan was rendered — for example, new lane assignments that overlap, verification matrix gaps revealed by stop conditions, acceptance criteria that contradict the rollback contract.
+
+If post-plan Metis surfaces any blocking gap, return to §4 Pass 1 with the new question. Otherwise proceed to §6.
+
+### 6. Handoff
+
+Prometheus Strict stops with a plan unless the user explicitly invokes or authorizes the next workflow. Prefer this sequence:
+
+```text
+$ultragoal "<Oracle plan summary or .omx/plans/prometheus-strict/<slug>.md>"
+$team <N>:executor "execute the approved Ultragoal story in parallel lanes"  # only when warranted
+```
+</Steps>
+
+<Tool_Usage>
+- Use read-only repository inspection to verify referenced files, commands, and existing conventions.
+- Treat Metis research fan-out as part of planning, not execution: dispatch `explore` / exact `gpt-5.4-mini` `researcher` evidence-gathering before question generation for non-trivial intents, then re-prefill and ask only surviving CRITICAL gaps.
+- Use `prometheus-strict-metis`, `prometheus-strict-momus`, and `prometheus-strict-oracle` sequentially; do not fan out implementation work from this skill.
+- Use `$ultragoal` only as the recommended execution handoff after the plan is ready.
+- Use `$team` only when parallel lanes are independent and verifiable.
+</Tool_Usage>
+
+## State Management
+
+Prometheus Strict does not own a long-running runtime loop. If a durable planning artifact is needed, write the final plan to `.omx/plans/prometheus-strict/<slug>.md`. Draft-only or inline plans may set the artifact path to `N/A - inline plan only`.
+
+Do not create hook state, Sisyphus state, or `start-work` compatibility state for this skill.
+
+<Final_Checklist>
+- [ ] Target result is explicit.
+- [ ] Scope and non-goals are explicit.
+- [ ] Acceptance criteria are measurable.
+- [ ] Metis interview loop reached checklist clearance only after the mandatory two gap-fill passes following every `answers[]` batch and, if any question round was emitted, after the minimum two emitted question rounds gate; otherwise the 5-round cap was reached with UNKNOWN items carried forward as `<unresolved_blocker>` entries.
+- [ ] Momus objections are resolved or carried forward as explicit blockers, with at most 3 Momus → Oracle re-synthesis cycles consumed.
+- [ ] Oracle plan includes a verification matrix.
+- [ ] Oracle Pass 2 self-verification completed; every machine-checkable contract item passes or is annotated as carried-forward.
+- [ ] Post-plan Metis gap check produced no blocking objections (or all are carried forward).
+- [ ] Handoff recommends `$ultragoal` and `$team` only when warranted.
+- [ ] Clean-room credit is preserved.
+- [ ] No hook implementation or Sisyphus/start-work port was introduced.
+</Final_Checklist>
+
+<Advanced>
+## Output Contract
+
+If writing a durable plan file, store this markdown at `.omx/plans/prometheus-strict/<slug>.md` and reference that path in the handoff.
+
+```markdown
+## Prometheus Strict Plan
+
+### Target Result
+- <one-sentence objective>
+
+### Clarified Requirements (Metis)
+- <requirement / acceptance criterion>
+
+### Critique Resolved (Momus)
+- <risk or objection> -> <resolution>
+
+### Oracle Execution Plan
+1. <sequenced step or lane>
+
+### Verification Matrix
+| Claim | Required evidence | Owner/lane |
+| --- | --- | --- |
+| <claim> | <test/build/lint/e2e/doc evidence> | <owner> |
+
+### Artifact
+- Durable plan path: `.omx/plans/prometheus-strict/<slug>.md` or `N/A - inline plan only`
+
+### Handoff
+- Recommended next workflow: <$ultragoal / $team / direct execution / none>
+- Stop condition: <what proves the plan is ready or why it is blocked>
+
+### Clean-Room Credit
+Inspired by OMO Prometheus (`code-yeongyu/oh-my-openagent`), reimplemented from concept under MIT.
+```
+
+## Failure and Escalation
+
+Escalate instead of planning when a necessary answer cannot be inferred safely, the next step is destructive or credential-gated, required repository context is unavailable, or the user asks for behavior outside the non-goals.
+</Advanced>
+
+Original task:
+{{PROMPT}}

package/skills/ralph/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: ralph
+description: Self-referential loop until task completion with architect verification
+---
+
+[RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]
+
+Your previous attempt did not output the completion promise. Continue working on the task.
+
+<Purpose>
+Ralph is a persistence loop that keeps working on a task until it is fully complete and architect-verified. It wraps ultrawork's parallel execution with session persistence, automatic retry on failure, and mandatory verification before completion.
+</Purpose>
+
+<Use_When>
+- Task requires guaranteed completion with verification (not just "do your best")
+- User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
+- Work may span multiple iterations and needs persistence across retries
+- Task benefits from parallel execution with architect sign-off at the end
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants a full autonomous pipeline from idea to code -- use `autopilot` instead
+- User wants to explore or plan before committing -- use `plan` skill instead
+- User wants a quick one-shot fix -- delegate directly to an executor agent
+- User wants manual control over completion -- use `ultrawork` directly
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by looping until work is genuinely complete, requiring fresh verification evidence before allowing completion, and using explicit architect native-subagent verification to confirm quality.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Fire independent agent calls simultaneously -- never wait sequentially for independent work
+- Use `run_in_background: true` for long operations (installs, builds, test suites)
+- Always set `agent_type` when spawning native subagents; use `reasoning_effort` for per-dispatch intensity when needed
+- Preserve legacy Ralph tier intent through native reasoning effort: LOW -> `low`, STANDARD -> `medium`, THOROUGH -> `xhigh`
+- Deliver the full implementation: no scope reduction, no partial completion, no deleting tests to make them pass
+- 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.
+- Integrate with Codex goal mode when goal tools are available: inspect the active thread goal with `get_goal`, preserve it as the top-level stop condition, and only call `update_goal({status: "complete"})` after a Ralph completion audit proves the objective is actually achieved.
+</Execution_Policy>
+
+<Steps>
+0. **Pre-context intake (required before planning/execution loop starts)**:
+   - Assemble or load a context snapshot at `.omx/context/{task-slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`).
+   - Minimum snapshot fields:
+     - task statement
+     - desired outcome
+     - known facts/evidence
+     - constraints
+     - unknowns/open questions
+     - likely codebase touchpoints
+   - If an existing relevant snapshot is available, reuse it and record the path in Ralph state.
+   - If request ambiguity is high, gather brownfield facts first. `omx explore` is deprecated; use normal repository inspection tools/subagents for simple read-only repository lookups and `omx sparkshell` only for explicit shell-native read-only evidence. Then run `$deep-interview --quick <task>` to close critical gaps.
+   - Do not begin Ralph execution work (delegation, implementation, or verification loops) until snapshot grounding exists. If forced to proceed quickly, note explicit risk tradeoffs.
+1. **Review progress**: Check TODO list and any prior iteration state
+2. **Continue from where you left off**: Pick up incomplete tasks
+3. **Delegate in parallel**: Route tasks to specialist native agents with explicit `agent_type` and appropriate `reasoning_effort`
+   - Simple lookups: `reasoning_effort="low"` -- "What does this function return?"
+   - Standard work: `reasoning_effort="medium"` -- "Add error handling to this module"
+   - Complex analysis: `reasoning_effort="xhigh"` -- "Debug this race condition"
+   - When Ralph is entered as a ralplan follow-up, start from the approved **available-agent-types roster** and make the delegation plan explicit: implementation lane, evidence/regression lane, and final sign-off lane using only known agent types
+4. **Run long operations in background**: Builds, installs, test suites use `run_in_background: true`
+5. **Visual task gate (when screenshot/reference images are present)**:
+   - Run the Visual Ralph verdict step **before every next edit**.
+   - Require structured JSON output: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, `reasoning`.
+   - Persist verdict to `.omx/state/{scope}/ralph-progress.json` including numeric + qualitative feedback.
+   - Default pass threshold: `score >= 90`.
+   - **URL-based visual cloning tasks**: When the task description contains a target URL (e.g., "clone https://example.com"), route the work through `$visual-ralph`. `$web-clone` is hard-deprecated; Visual Ralph owns the migrated live-URL visual implementation use case and uses its built-in visual verdict step for measured visual scoring.
+6. **Verify completion with fresh evidence**:
+   - If Codex goal mode is available, call `get_goal` before final verification to restate the active objective and include it in the evidence checklist.
+   a. Identify what command proves the task is complete
+   b. Run verification (test, build, lint)
+   c. Read the output -- confirm it actually passed
+   d. Check: zero pending/in_progress TODO items
+7. **Architect verification** (native role):
+   - <5 files, <100 lines with full tests: `task(agent_type="architect", reasoning_effort="medium", prompt="...")` minimum
+   - Standard changes: `task(agent_type="architect", reasoning_effort="medium", prompt="...")`
+   - >20 files or security/architectural changes: `task(agent_type="architect", reasoning_effort="xhigh", prompt="...")`
+   - Ralph floor: always run an explicit `architect` native subagent, even for small changes
+7.5 **Mandatory Deslop Pass**:
+   - After Step 7 passes, run `oh-my-codex:ai-slop-cleaner` on **all files changed during the Ralph session**.
+   - Scope the cleaner to **changed files only**; do not widen the pass beyond Ralph-owned edits.
+   - Run the cleaner in **standard mode** (not `--review`).
+   - If the prompt contains `--no-deslop`, skip Step 7.5 entirely and proceed with the most recent successful verification evidence.
+7.6 **Regression Re-verification**:
+   - After the deslop pass, re-run all tests/build/lint and read the output to confirm they still pass.
+   - If post-deslop regression fails, roll back cleaner changes or fix and retry. Then rerun Step 7.5 and Step 7.6 until the regression is green.
+   - Do not proceed to completion until post-deslop regression is green (unless `--no-deslop` explicitly skipped the deslop pass).
+8. **On approval**: If Codex goal mode is active, call `update_goal({status: "complete"})` before `/cancel`; report final elapsed time and token-budget usage when the tool returns it. Then run `/cancel` to cleanly exit and clean up all state files.
+9. **On rejection**: Fix the issues raised, then re-verify with the same `agent_type` and `reasoning_effort` profile
+</Steps>
+
+<Tool_Usage>
+- Use `ask_codex` with `agent_role: "architect"` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
+- Skip Codex consultation for simple feature additions, well-tested changes, or time-critical verification
+- If MCP compatibility tools are unavailable, proceed with CLI/agent verification alone -- never block on external tools
+- Use `omx state write/read --input '<json>' --json` for ralph mode state persistence between iterations
+- Use Codex goal tools when present: `get_goal` to discover or re-check the active objective, `create_goal` only when the user/system explicitly requested a new goal and no active goal exists, and `update_goal` only after the audited objective is fully achieved.
+- Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
+- Prefer CLI state commands. If an explicit MCP compatibility `omx_state` call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `omx state write --input '<json>' --json`, `omx state read --input '<json>' --json`, or `omx state clear --input '<json>' --json`. If the CLI path also fails, continue with `.omx/context` / `.omx/plans` file-backed artifacts and report the state persistence blocker.
+</Tool_Usage>
+
+## Goal Mode Integration
+
+Codex goal mode is the thread-level completion contract for long-running Ralph work. Ralph state tracks workflow mechanics; goal mode tracks whether the user objective is truly done. When the goal tools are available:
+
+1. Call `get_goal` during intake or before the first execution loop when the prompt/hook says an active thread goal exists.
+2. If no goal exists, call `create_goal` only when the user or system explicitly asked for goal tracking; otherwise continue with Ralph state alone.
+3. Treat `goal.objective` as binding acceptance scope. Newer user updates can refine the current branch, but do not silently narrow the goal.
+4. Before completion, perform a prompt-to-artifact checklist and completion audit against real evidence:
+   - restate the objective as deliverables/success criteria
+   - map every prompt requirement, named workflow (`$ralplan`, `$ralph`), file, command, test, gate, and deliverable to evidence
+   - inspect the actual files, command output, state, and tests behind each checklist item
+   - identify missing, weakly verified, or uncovered requirements and continue if any remain
+5. Call `update_goal({status: "complete"})` only when the audit shows no required work remains. Do not use passing tests, Ralph state, or architect approval as proxy proof unless they cover the whole goal.
+6. If goal tools are unavailable, keep working through Ralph state and mention the missing goal-mode evidence in the final report.
+
+## State Management
+
+Use the CLI-first state surface for Ralph lifecycle state (`omx state write/read/clear --input '<json>' --json`). Explicit MCP compatibility tools (`state_write`, `state_read`, `state_clear`) remain acceptable only when already enabled.
+
+- **On start**:
+  `omx state write --input '{"mode":"ralph","active":true,"iteration":1,"max_iterations":10,"current_phase":"executing","started_at":"<now>","state":{"context_snapshot_path":"<snapshot-path>"}}' --json`
+- **On each iteration**:
+  `omx state write --input '{"mode":"ralph","iteration":<current>,"current_phase":"executing"}' --json`
+- **On verification/fix transition**:
+  `omx state write --input '{"mode":"ralph","current_phase":"verifying"}' --json` or `omx state write --input '{"mode":"ralph","current_phase":"fixing"}' --json`
+- **On completion** (only after the completion audit passes with real evidence):
+  `omx state write --input '{"mode":"ralph","active":false,"current_phase":"complete","completed_at":"<now>","completion_audit":{"passed":true,"prompt_to_artifact_checklist":["<requirement mapped to artifact/evidence>"],"verification_evidence":["<fresh test/build/lint command and result>"]}}' --json`
+- **Before the final answer**:
+  1. Run fresh verification and read the output.
+  2. Build `prompt_to_artifact_checklist` entries that map every user requirement, workflow gate, named file, command, PR/delivery requirement, and stop condition to a concrete artifact or evidence item.
+  3. Build `verification_evidence` entries with concrete commands, exit status, files inspected, PR URLs, or other machine-checkable evidence.
+  4. Write the Ralph completion state with a top-level `completion_audit` field on the Ralph state object. Do not write bare top-level `prompt_to_artifact_checklist` or `verification_evidence` fields by themselves; the Stop gate will reject them.
+  5. Read the state back with `omx state read --input '{"mode":"ralph"}' --json` and verify `completion_audit.passed === true`, a non-empty checklist, and non-empty verification evidence before producing the final answer.
+  6. If Codex goal mode is active, call `update_goal({status:"complete"})` only after this Ralph audit read-back succeeds.
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `omx state clear --input '{"mode":"ralph"}' --json`)
+
+
+## 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>
+Correct parallel delegation:
+```
+task(agent_type="executor", reasoning_effort="low", prompt="Add type export for UserConfig")
+task(agent_type="executor", reasoning_effort="medium", prompt="Implement the caching layer for API responses")
+task(agent_type="executor", reasoning_effort="xhigh", prompt="Refactor auth module to support OAuth2 flow")
+```
+Why good: Three independent tasks fired simultaneously while explicitly selecting the installed `executor` native role, so the UI/tracker does not show default subagents; legacy tier intent is preserved through native reasoning effort (`LOW` -> `low`, `STANDARD` -> `medium`, `THOROUGH` -> `xhigh`).
+</Good>
+
+<Good>
+Correct verification before completion:
+```
+1. Run: npm test           → Output: "42 passed, 0 failed"
+2. Run: npm run build      → Output: "Build succeeded"
+3. Run: lsp_diagnostics    → Output: 0 errors
+4. task(agent_type="architect", reasoning_effort="medium", prompt="verify completion") → Verdict: "APPROVED"
+5. Run /cancel
+```
+Why good: Fresh evidence at each step, architect verification, then clean exit.
+</Good>
+
+<Bad>
+Claiming completion without verification:
+"All the changes look good, the implementation should work correctly. Task complete."
+Why bad: Uses "should" and "look good" -- no fresh test/build output, no architect verification.
+</Bad>
+
+<Bad>
+Sequential execution of independent tasks:
+```
+task(agent_type="executor", reasoning_effort="low", prompt="Add type export") → wait →
+task(agent_type="executor", reasoning_effort="medium", prompt="Implement caching") → wait →
+task(agent_type="executor", reasoning_effort="xhigh", prompt="Refactor auth")
+```
+Why bad: These are independent tasks that should run in parallel, not sequentially.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- Stop and report when a fundamental blocker requires user input (missing credentials, unclear requirements, external service down)
+- Stop when the user says "stop", "cancel", or "abort" -- run `/cancel`
+- Continue working when the hook system sends "The boulder never stops" -- this means the iteration continues
+- If architect rejects verification, fix the issues and re-verify (do not stop)
+- If the same issue recurs across 3+ iterations, report it as a potential fundamental problem
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] All requirements from the original task are met (no scope reduction)
+- [ ] Zero pending or in_progress TODO items
+- [ ] Fresh test run output shows all tests pass
+- [ ] Fresh build output shows success
+- [ ] lsp_diagnostics shows 0 errors on affected files
+- [ ] Architect verification passed through explicit `task(agent_type="architect", reasoning_effort="medium"...)` minimum
+- [ ] Codex goal-mode completion audit passed, and `update_goal({status: "complete"})` was called when an active goal exists
+- [ ] ai-slop-cleaner pass completed on changed files (or --no-deslop specified)
+- [ ] Post-deslop regression tests pass
+- [ ] `/cancel` run for clean state cleanup
+</Final_Checklist>
+
+<Advanced>
+## PRD Mode (Optional)
+
+When the user provides the `--prd` flag, initialize a Product Requirements Document before starting the ralph loop.
+
+### Detecting PRD Mode
+Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
+
+Prompt-side `$ralph` workflow activation is lighter-weight than `omx ralph --prd ...`.
+It seeds Ralph workflow state and guidance, but it does not implicitly launch the
+CLI entrypoint or apply the PRD startup gate. Treat `omx ralph --prd ...` as the
+explicit PRD-gated path.
+
+### Detecting `--no-deslop`
+Check if `{{PROMPT}}` contains `--no-deslop`.
+If `--no-deslop` is present, skip the deslop pass entirely after Step 7 and continue using the latest successful pre-deslop verification evidence.
+
+### Visual Reference Flags (Optional)
+Ralph execution supports visual reference flags for screenshot tasks:
+- Repeatable image inputs: `-i <image-path>` (can be used multiple times)
+- Image directory input: `--images-dir <directory>`
+
+Example:
+`ralph -i refs/hn.png -i refs/hn-item.png --images-dir ./screenshots "match HackerNews layout"`
+
+### PRD Workflow
+1. Run deep-interview in quick mode before creating PRD artifacts:
+   - Execute: `$deep-interview --quick <task>`
+   - Complete a compact requirements pass (context, goals, scope, constraints, validation)
+   - Persist interview output to `.omx/interviews/{slug}-{timestamp}.md`
+2. Create canonical PRD/progress artifacts:
+   - PRD: `.omx/plans/prd-{slug}.md`
+   - Progress ledger: `.omx/state/{scope}/ralph-progress.json` (session scope when available, else root scope)
+3. Parse the task (everything after `--prd` flag)
+4. Break down into user stories:
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Short title]",
+      "description": "As a [user], I want to [action] so that [benefit].",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false
+    }
+  ]
+}
+```
+
+5. Initialize canonical progress ledger at `.omx/state/{scope}/ralph-progress.json`
+6. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
+7. Proceed to normal ralph loop using user stories as the task list
+
+### Example
+User input: `--prd build a todo app with React and TypeScript`
+Workflow: Detect flag, extract task, create `.omx/plans/prd-{slug}.md`, create `.omx/state/{scope}/ralph-progress.json`, begin ralph loop.
+
+### Legacy compatibility
+- During the compatibility window, Ralph `--prd` startup still validates machine-readable story state from `.omx/prd.json`.
+- `.omx/plans/prd-{slug}.md` remains the canonical storage/documentation artifact, but it is not yet the startup validation source.
+- If `.omx/prd.json` exists and canonical PRD is absent, migrate one-way into `.omx/plans/prd-{slug}.md`.
+- If `.omx/progress.txt` exists and canonical progress ledger is absent, import one-way into `.omx/state/{scope}/ralph-progress.json`.
+- Keep legacy files unchanged for one release cycle.
+
+## Background Execution Rules
+
+**Run in background** (`run_in_background: true`):
+- Package installation (npm install, pip install, cargo build)
+- Build processes (make, project build commands)
+- Test suites
+- Docker operations (docker build, docker pull)
+
+**Run blocking** (foreground):
+- Quick status checks (git status, ls, pwd)
+- File reads and edits
+- Simple commands
+</Advanced>
+
+Original task:
+{{PROMPT}}

package/skills/ralph-init/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: ralph-init
+description: Ralph Init deprecated skill
+---
+
+# Ralph Init deprecated
+
+Hard-deprecated. Do not invoke or route this skill. Use `$ralph` directly after PRD/test-spec planning is complete.
+
+Task: {{ARGUMENTS}}