oh-my-codex Documentation

File: README.md Copy Chapter

oh-my-codex (OMX)

Website: https://yeachan-heo.github.io/oh-my-codex-website/

Docs: Getting Started · Agents · Skills · Integrations · Demo · OpenClaw guide

Community: Discord — shared Gajae community server for oh-my-codex, gajae-code, and related tooling.

Official project and package Copy Chapter

The official/original OMX project is this repository, Yeachan-Heo/oh-my-codex, and the official npm package for this project is oh-my-codex. Install this project with npm install oh-my-codex (or alongside Codex CLI as shown below).

Third-party projects or forks that use names such as “OMX v2” are not official continuations, replacements, or release lines for this repository unless this README or the docs explicitly say so. When in doubt, trust this repository and the oh-my-codex package as the official install target.

OMX is a workflow layer for OpenAI Codex CLI.

It keeps Codex as the execution engine and makes it easier to:

• start a stronger Codex session by default
• run one consistent workflow from clarification to completion
• invoke the canonical workflow with $plan, $ultragoal, $team, $code-review, and $ultraqa — each independently, no fixed chain
• keep project guidance, plans, logs, and state in .omx/

Core Maintainers Copy Chapter

Ambassadors Copy Chapter

Top Collaborators Copy Chapter

Recommended default flow Copy Chapter

If you want the default OMX experience, start here:

Choose one install path. If Codex CLI is already installed (Homebrew, npm, or another supported method):

codex --version
npm install oh-my-codex
# from the git project you want Codex to edit; choose a task-specific name
omx --worktree=feat/task --madmax --xhigh

If you do not have Codex CLI yet and want npm to manage it:

npm install @openai/codex
npm install oh-my-codex

Do not run a combined npm install @openai/codex oh-my-codex over an existing Homebrew-owned codex binary such as /opt/homebrew/bin/codex; npm may fail with EEXIST when @openai/codex tries to create the same binary. OMX only needs a working, authenticated codex command on PATH; it does not require Codex to be installed through npm.

On a real oh-my-codex version bump, the global npm install now prints an explicit reminder instead of launching setup automatically. When you're ready, run the scoped setup command below or use omx update to check npm and then run the same setup refresh path.

OMX also checks for npm updates at launch on a throttled cadence and prompts before scheduling the update after the current session exits. Set OMX_AUTO_UPDATE=0 to disable the launch-time check, or set OMX_AUTO_UPDATE=defer to schedule the same deferred update without prompting.

Choose the setup scope deliberately:

• Use omx setup --scope project --merge-agents from the git project you want OMX to operate on when that repository should own the durable AGENTS.md guidance.
• Use omx setup --scope user for user-level Codex setup when you are not preparing the current directory as an OMX project.
• Avoid running project-scoped setup from a broad home directory or operating hub unless that directory is intentionally the project under review. A home-level AGENTS.md often contains global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead.

Persisting an explicit AGENTS merge policy Copy Section

omx setup --merge-agents, omx setup --no-merge-agents, and omx setup --clear-merge-agents-policy are the only policy selectors; use their bare forms (not =value spellings). Repeating an identical selector is harmless, but mixing set and clear choices fails before setup changes anything. An explicit set overrides a saved policy. A successful explicit set records mergeAgents: true or false in the current working root's ./.omx/setup-scope.json, even when setup scope is user; it never becomes a global user preference or leaks to another root. Later omx update replays a valid matching policy for both immediate and deferred refreshes.

true takes the existing merge branch. false only suppresses that branch: it does not promise preservation, replacement, or any new safety mode, so the existing prompt, skip, managed-refresh, plugin-default, and force behavior still applies. A matching-scope review retains the policy while unrelated settings change. Reset or a scope change removes the inherited policy unless the same setup run explicitly sets true or false; clear always removes the policy and cannot be combined with a set selector. Malformed, unknown, nonboolean, or wrong-scope saved data is ignored safely.

--force is independent and transient: it is neither recorded nor replayed, and does not override an explicit merge policy. Setup atomically commits explicit set or clear intent only after all setup work succeeds, including when active-session or plugin-symlink safeguards skip the current AGENTS.md write, so the next refresh can honor the requested policy. This does not make merge the default or revive the rejected #2892 merge-by-default approach. Older OMX versions safely ignore the field, but may erase it when rewriting their known setup preferences.

Codex plugin install note: this repo also ships an official Codex plugin layout at plugins/oh-my-codex with marketplace metadata in .agents/plugins/marketplace.json. That plugin bundles the mirrored skill surface plus plugin-scoped companion metadata for official Codex lifecycle hooks, optional MCP compatibility servers, and apps. It is still not a replacement for the global oh-my-codex CLI plus scoped setup: plugin-scoped hooks launch the installed omx CLI, legacy setup mode installs native agents and prompts, and plugin setup mode relies on plugin discovery for bundled skills while archiving/removing legacy OMX-managed prompts/native-agent TOMLs so stale role files cannot shadow plugin behavior. Plugin mode still needs a persistent scope AGENTS.md (~/.codex/AGENTS.md for user setup or ./AGENTS.md for project setup) as the durable orchestration guidance layer; session-scoped AGENTS files only compose that durable guidance with runtime overlays and are not a replacement.

Then work normally inside Codex:

# Durable objective/checkpoints for a long task:
/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior.

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "turn the approved plan into durable Codex goals"

That is the main path.
Before you treat the runtime as ready, run the quick-start smoke test below: omx doctor verifies the install shape, while omx exec proves the active Codex runtime can actually authenticate and complete a model call from the current environment.
Start OMX strongly, clarify first when needed, approve the plan, then use $ultragoal as the default durable completion wrapper. Use $team inside that execution path only when a specific Ultragoal story needs coordinated parallel work.

What OMX is for Copy Chapter

Use OMX if you already like Codex and want a better day-to-day runtime around it:

• a standard workflow built around $deep-interview -> $ralplan -> $ultragoal
• research boundaries: use $best-practice-research for ordinary pre-planning official/upstream evidence, $autoresearch for bounded validator-gated research artifacts ($deep-interview --autoresearch for intake, then $autoresearch with the chosen validation mode) for research missions, and feed any research findings into $ralplan for architecture synthesis
• durable multi-goal handoffs with $ultragoal and .omx/ultragoal artifacts as the default completion path after planning
• specialist roles and supporting skills when the task needs them
• project guidance through scoped AGENTS.md
• durable state under .omx/ for plans, logs, memory, and mode tracking

If you want plain Codex with no extra workflow layer, you probably do not need OMX.

Quick start Copy Chapter

Requirements Copy Section

• Node.js 20+
• Codex CLI installed, verified with codex --version, and authenticated (Homebrew or npm are both fine; do not reinstall @openai/codex with npm if Homebrew already owns codex)
• Codex auth configured and visible in the same shell/profile that will run OMX
• tmux on macOS/Linux if you want the recommended durable team runtime
• psmux on native Windows only if you intentionally want the less-supported Windows team path

A good first session Copy Section

After install, check both boundaries:

omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

omx doctor catches missing OMX files, hooks, and runtime prerequisites. The real smoke test catches auth, profile, and provider/base-URL problems that only appear when Codex performs an actual request.

Launch OMX the recommended way from a git project:

omx --worktree=feat/task --madmax --xhigh

On macOS/Linux interactive terminals with tmux available, this starts the
leader in OMX-managed detached tmux by default so the HUD/runtime panes can be
created and recovered. --worktree also moves the launch into a separate git
checkout, which is the safer default when using --madmax. Replace
feat/task with a branch-like name for the task.

Concurrent standard conversations Copy Section

A standard launch owns one writable session pointer under its selected OMX_ROOT. A second ordinary omx launch from the same checkout therefore fails closed instead of sharing or silently changing that root. Give each additional conversation an explicit, distinct root:

omx
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx
OMX_ROOT="$HOME/.omx/instances/third-conversation" omx

PowerShell:

$env:OMX_ROOT = "$HOME/.omx/instances/second-conversation"
omx

Command Prompt:

set "OMX_ROOT=%USERPROFILE%\.omx\instances\second-conversation"
omx

User-specified roots are literal: launching twice with the same explicit OMX_ROOT remains a fatal owner conflict. Separate checkouts have separate default roots, while --worktree and --madmax keep their existing isolation behavior.

Madmax and worktree launch safety Copy Section

--madmax is OMX shorthand for Codex
--dangerously-bypass-approvals-and-sandbox. It removes the normal approval and
sandbox guardrails, so only use it in trusted repositories and environments.
--high and --xhigh are shorthand for -c model_reasoning_effort="high|xhigh"; a normal strong session is omx --madmax --xhigh (or omx --worktree=feat/task --madmax --xhigh from a git project).

When you use --madmax from a git repository, prefer a worktree launch instead
of running directly in the current checkout. For repeatable or concurrent work,
use a named worktree:

omx --worktree=feature/auth --madmax --xhigh

If you are outside a git repository, omit --worktree; worktree launches
require Git.

For concurrent --madmax sessions, do not run them all in the same
directory. Give each session its own named worktree:

omx --worktree=feature/auth --madmax --xhigh
omx --worktree=fix/flaky-tests --madmax --xhigh

--worktree / -w with no name creates or reuses a detached launch worktree at
../<repo>.omx-worktrees/launch-detached. --worktree=<name>,
--worktree <name>, or -w <name> creates or reuses a named launch worktree
under ../<repo>.omx-worktrees/ and checks out that branch name. OMX consumes
the worktree flag before starting Codex; it is not forwarded to Codex itself.
Treat the unnamed detached form as a one-off convenience: if the source checkout
advances after that worktree is created, a later unnamed launch can fail with
worktree_target_mismatch because launch-detached still points at the old
HEAD. Use a named worktree for repeated work, or remove the old detached
worktree before retrying.
If the target launch worktree is already dirty, OMX warns and launches as-is, so
clean, commit, or stash that worktree before relying on it for isolation.

For omx team, workers already use dedicated worktrees automatically by
default; --worktree on omx team is only a legacy-compatible override.

Repo-aware tools receive the same canonical context in launch, team-worker, and autoresearch runtimes: OMX_REPO_ROOT, OMX_WORKTREE_ROOT, OMX_GIT_COMMON_DIR, OMX_WORKTREE_SCOPE, OMX_CODEGRAPH_MODE, and OMX_CODEGRAPH_PROJECT_PATH. OMX_CODEGRAPH_MODE=auto prefers a worktree-local .codegraph/codegraph.db, then a leader/repo .codegraph/codegraph.db, otherwise resolves to off. Explicit shared, local, and off are honored. OMX does not install CodeGraph, auto-index worktrees, or copy/symlink .codegraph; shared leader indexes are useful for baseline navigation but are not branch-accurate for worktree-only changes.

If you want a one-off launch with no OMX tmux/HUD management, use --direct:

omx --direct --yolo

For a persistent shell/profile preference, set an environment policy:

OMX_LAUNCH_POLICY=direct omx --yolo

Return to the auto/default behavior with:

unset OMX_LAUNCH_POLICY

CLI policy flags win over the environment, and the last CLI policy flag before
-- wins:

OMX_LAUNCH_POLICY=direct omx --tmux --yolo

Use OMX_LAUNCH_POLICY=direct|tmux|detached-tmux|auto. This iteration only
adds CLI and environment controls; it intentionally does not add a config-file
setting. If you run --direct from inside an existing tmux pane, OMX will not
create HUD splits, enable mouse mode, or wrap extended-key handling, but the
process still runs inside that already-open terminal pane.

Then try the canonical workflow:

# Copy/pasteable durable-goal example:
/goal Ship the checkout bug fix with a durable objective, checkpoints for reproduction, implementation, regression tests, and final verification.

$plan "approve the checkout bug-fix plan and review tradeoffs"
$ultragoal "execute the approved checkout fix with checkpoint evidence"

Use $team when an active Ultragoal story needs coordinated parallel work.

`/goal` and skill selection Copy Section

Start a normal strong session with omx --madmax --xhigh (or add --worktree=<task> in a git repo). Inside that session, execute directly or use $ultragoal for durable multi-goal runs, $team for coordinated parallel work, or $plan when the task needs explicit planning first. Use /goal when the task itself needs a durable objective/checkpoint structure that Codex should keep reconciling across turns.

Add only 2-5 relevant skills by default. More skills are allowed when the task scope justifies them, but loading a large catalog is usually a context-budget and attention-quality problem, not a hard parser/runtime blocker. Treat it as a concrete runtime blocker only when a command actually errors.

Anti-pattern:

omx --madmax --xhigh
# Then immediately load 20 skills "just in case" before stating the task.
# This bloats session context and makes the model spend attention on irrelevant workflows.

A simple mental model Copy Chapter

OMX does not replace Codex.

It adds a better working layer around it:

• Codex does the actual agent work
• OMX role keywords make useful roles reusable
• OMX skills make common workflows reusable
• .omx/ stores plans, logs, memory, and runtime state

Most users should think of OMX as better task routing + better workflow + better runtime, not as a command surface to operate manually all day.

Start here if you are new Copy Chapter

1. If Codex CLI already exists, verify it with codex --version and install or update OMX with npm install oh-my-codex; otherwise install @openai/codex separately first if you want npm to manage Codex
2. After install or real OMX version bumps, run omx setup --scope project --merge-agents from the target git project or omx setup --scope user for user-level Codex setup, or use omx update when you also want npm to check for and install the latest build before refreshing setup
3. Run omx doctor
4. Run a real execution smoke test: codex login status and omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
5. Launch with a named worktree from a git repo, for example omx --worktree=feat/task --madmax --xhigh; if you run concurrent --madmax sessions, use distinct named worktrees such as --worktree=feature/auth
6. Use $deep-interview "..." when the request or boundaries are still unclear
7. Use $ralplan "..." to approve the plan and review tradeoffs
8. Use $ultragoal or $team when the task needs durable or parallel execution; add /goal when durable objective/checkpoint structure should be explicit

Recommended workflow Copy Chapter

$autopilot is the first-class canonical orchestrator for the staged workflow $deep-interview -> $ralplan -> $ultragoal. The chain is its defining default, while each stage remains independently invocable when earlier input contracts are already satisfied.

1. $deep-interview — iterative Socratic ambiguity clearance, resumable state, and execution-ready requirements artifacts.
2. $ralplan — architecture, feasibility, and consensus planning over the deep-interview artifact.
3. $ultragoal — durable multi-goal execution with .omx/ultragoal ledger checkpoints.
4. $team — coordinated parallel execution when a story benefits from multiple lanes.

$deep-interview is an independent requirements stage, not an alias for $plan --interview, and never implements directly. Planning skills stop at planning artifacts; code changes require an explicit execution lane ($ultragoal or $team).

Inside an Ultragoal story, use $team only when that story benefits from coordinated parallel execution.

Common in-session surfaces Copy Chapter

Advanced / operator surfaces Copy Chapter

These are useful, but they are not the main onboarding path.

Mission queue runner Copy Section

Use omx mission when you have a short checklist of OmX/Codex prompts that should run one after another instead of opening a separate shell command for each prompt. Start with omx mission plan ./mission.md or omx mission ./mission.md --dry-run to validate parsing and inspect the durable summary, then run omx mission run ./mission.md -- --model gpt-5 when the prompts are ready. Interrupted runs can be inspected with omx mission status ./mission.md, continued with omx mission resume ./mission.md, operator-blocked with omx mission mark ./mission.md --task task-002 --status blocked, and repaired task-by-task with omx mission rerun ./mission.md --task task-002. See docs/mission.md for input format, status output, and artifact details.

Export a previous conversation Copy Section

Use omx session search "a phrase you remember" to find a session ID, then
omx session export <session-id> --output conversation.md to save its conversation.
Export accepts an exact ID or a unique prefix and includes active and archived
transcripts from the same Codex homes discovered by session search. Use
--format json for structured output, --include-tools for tool arguments and
outputs, or --codex-home to select one home. Omitting --output writes
to stdout; an existing output file is never overwritten.

Only user and assistant messages are included by default. System/developer
instructions and reasoning records are excluded; message text is not redacted.
See session export for supported records and examples.

Team runtime Copy Section

Use the team runtime when you specifically need durable tmux/worktree coordination, not as the default way to begin using OMX. In Codex App or plain outside-tmux sessions, treat omx team as a tmux-runtime shell surface rather than a directly available in-app workflow; launch OMX CLI from shell first if you actually want team execution.

When Team runs inside an Ultragoal story, Ultragoal remains leader-owned state: workers report checkpoint-ready evidence upward instead of mutating .omx/ultragoal directly. Team startup tolerates stale or malformed Ultragoal artifacts for unrelated work, but explicitly Ultragoal-linked Team launches stay fail-closed. Team startup also writes .omx/state/team/<team-name>/preflight-context.json so large Team runs can be resumed after compaction with the original task, worker split, Ultragoal context, and verification checklist.

For very small atomic work, Team may cap implicit fanout to one worker and print an over-orchestration warning; pass an explicit worker count only when the extra coordination cost is intentional.

omx team 3:executor "fix the failing tests with verification"
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

Setup, doctor, and HUD Copy Section

These are operator/support surfaces:

• Codex plugin marketplace install/discovery can cache the plugin under ${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/ (local installs may use local as the version identifier); that packaged plugin includes plugin-scoped companion metadata for official Codex lifecycle hooks, optional MCP compatibility servers, and apps (MCP/apps disabled by default), so it is still paired with the installed omx CLI for runtime execution
• Scoped setup installs prompts, skills, AGENTS scaffolding, .codex/config.toml, and (for legacy installs or older Codex without plugin_hooks) OMX-managed native Codex hooks in .codex/hooks.json
  • setup refresh preserves non-OMX hook entries in .codex/hooks.json and only rewrites OMX-managed wrappers
  • plugin setup keeps AGENTS.md as persistent durable guidance even though bundled skills/hooks come from the plugin cache; omx doctor treats a missing persistent scope AGENTS.md in plugin mode as a failed check because the session-scoped AGENTS file would otherwise contain only runtime overlay guidance
  • omx setup --merge-agents preserves existing project AGENTS.md guidance while inserting or refreshing generated OMX sections between /; --no-merge-agents records an explicit contextual non-merge choice, and --clear-merge-agents-policy always removes the recorded choice and cannot combine with a set selector. The policy is stored per working root (even for user scope), replayed by immediate and deferred updates only when its saved scope is valid and matches, and is never a force/default policy.
  • omx uninstall removes OMX-managed wrappers from .codex/hooks.json but keeps the file when user hooks remain
• omx update checks npm immediately, installs the newest global OMX build, then reruns the same interactive setup refresh path
• launch-time update checks are throttled and prompt by default; use OMX_AUTO_UPDATE=0 to disable them or OMX_AUTO_UPDATE=defer to schedule deferred updates without a prompt
• fresh OMX setup defaults to gpt-6-astra across frontier, standard, and spark/fast agents, with the same role reasoning defaults; existing user model configuration and explicit overrides are preserved
• .omx-config.json model/env routing is documented in the model/env routing reference; only edit keys supported by your installed OMX version
• omx doctor verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model call
• omx hud --watch is a monitoring/status surface, not the primary user workflow
• Active session teams show their name and worker count beside the OMX version (for example, [OMX#0.21.4] team:checkout (3 workers) | repo/branch) in every HUD preset, before long repository labels. When ultragoal is active, the combined ultragoal/team summary also takes priority over repository labels and other modes. Team discovery remains session-scoped; this does not show teams from other sessions or change when team startup publishes active state.
• Below the summary, each team agent gets a live-refreshing row with its name, last reported state (working, idle, blocked, done, failed, draining, or unknown), current task ID, role, tmux pane ID, and update age when available. Columns stay aligned across different name lengths and missing fields; working and done are green, while blocked and failed are yellow. The HUD grows to fit the roster and shrinks after the team stops. Missing or malformed status files display unknown; a reported working state is not a process-liveness check. Membership and status are read without modifying team files.
• GitGuardex finish progress is opt-in. Add "guardex": { "enabled": true } to the project-local .omx/hud-config.json to show gx:<step>/<total> ; running review/autofix phases animate in the HUD. OMX does not read Guardex state when this flag is absent or false.

Tmux roster height is bounded by live window and leader/HUD geometry, reserving at least half of their shared rows for the leader. Workers that do not fit are represented by a +N workers overflow row. The watch loop remeasures after resizing; unknown geometry keeps the HUD compact rather than expanding it unchecked.

For non-team sessions, native Codex hooks are now the canonical lifecycle surface:

• plugins/oh-my-codex/hooks/hooks.json = official plugin-scoped hook registrations for plugin installs
• .codex/hooks.json = legacy/fallback native Codex hook registrations preserved for legacy installs and older Codex versions
• .omx/hooks/*.mjs = OMX plugin hooks
• omx tmux-hook / notify-hook / derived watcher = tmux + runtime fallback paths

See Codex native hook mapping for the current native / fallback matrix.

Troubleshooting false-green readiness Copy Section

A green omx doctor means the install and local runtime wiring look sane. If real execution still fails, check the environment Codex actually uses:

• Run codex login status and omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" from the same shell/profile that will launch OMX.
• In custom HOME, profile, container, or service shells, confirm the active ~/.codex (or CODEX_HOME) is the one with the expected auth and config. Do not assume your normal user ~/.codex is visible there.
• If you depend on a local OpenAI-compatible proxy, confirm the active ~/.codex/config.toml includes the expected openai_base_url; otherwise a proxy-issued key can be sent to the default endpoint and fail with 401 Unauthorized, Missing bearer or basic authentication in header, or Incorrect API key provided.
• If omx doctor --team or resume reports a stale team such as resume_blocker or a missing tmux session, clean the dead runtime state before retrying:

omx team shutdown <team-name> --force --confirm-issues
omx cancel
omx doctor --team

Only use the forced team shutdown for a team you have confirmed is dead or intentionally abandoned.

If Shift+Enter still submits instead of inserting a newline inside an OMX-managed tmux session, see Troubleshooting execution readiness. Current OMX already enables tmux extended-key forwarding around its own Codex launch paths, so a persistent failure is usually a tmux terminal-capability/discoverability problem rather than a net-new OMX feature gap.

Sparkshell Copy Section

• omx sparkshell <command> is for shell-native inspection and bounded verification
• for read-only repository lookups, use normal Codex repository inspection tools/subagents (the deprecated omx explore command has been removed)
• primary and fallback Sparkshell summary models both default to gpt-6-astra; set OMX_SPARKSHELL_FALLBACK_MODEL to a different model to enable a distinct fallback
• sparkshell env overrides are intentionally narrow: OMX_SPARKSHELL_BIN selects a native sidecar path, OMX_SPARKSHELL_MODEL selects the primary summary model, OMX_SPARKSHELL_FALLBACK_MODEL selects the retry model, OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE selects summary instructions, and OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS controls the local API summary timeout

Examples:

omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

Wiki Copy Section

• omx wiki is the CLI-first JSON surface for wiki operations; omx_wiki MCP is explicit compatibility only
• wiki data lives as repository project knowledge under omx_wiki/
• the wiki is markdown-first and search-first, not vector-first

Examples:

omx wiki list --json
omx wiki query --input '{"query":"session-start lifecycle"}' --json
omx wiki lint --json
omx wiki refresh --json

Platform notes for team mode Copy Section

omx team works best on macOS/Linux with tmux.
Native Windows remains a secondary path, and WSL2 is generally the better choice if you want a Windows-hosted setup.
On native Windows, OMX accepts psmux as the tmux-compatible binary for the existing tmux-backed paths it already uses.

Known issues Copy Chapter

Intel Mac: high `syspolicyd` / `trustd` CPU during startup Copy Section

On some Intel Macs, OMX startup — especially with --madmax --high — can spike syspolicyd / trustd CPU usage while macOS Gatekeeper validates many concurrent process launches.

If this happens, try:

• xattr -dr com.apple.quarantine $(which omx)
• adding your terminal app to the Developer Tools allowlist in macOS Security settings
• using lower concurrency (for example, avoid --madmax --high)

Documentation Copy Chapter

• Getting Started
• Demo guide
• Wiki feature
• Agent catalog
• Skills reference
• Codex native hook mapping
• GitHub / PR / package identity pipeline
• Integrations
• Troubleshooting execution readiness
• OpenClaw / notification gateway guide
• Contributing
• Changelog

Languages Copy Chapter

• English
• 한국어
• 日本語
• 简体中文
• 繁體中文
• Tiếng Việt
• Español
• Português
• Русский
• Türkçe
• Deutsch
• Français
• Italiano
• Ελληνικά
• Polski
• Українська
• Bahasa Indonesia

Contributors Copy Chapter

Star History Copy Chapter

License Copy Chapter

MIT

GEO visibility benchmark Copy Chapter

OmX includes a geobench product spec for measuring LLM hit rate, MRR, share of voice, and citations.

• Spec: geobench/oh-my-codex.yaml
• Runbook: docs/geobench.md

File: docs/architecture/cli-first-mcp-taxonomy.md Copy Chapter

CLI-first MCP taxonomy

Issue #2214 establishes a runtime-support boundary for OMX: CLI/JSON is the canonical durable runtime and control-plane contract. MCP remains useful, but it is an optional integration and compatibility layer rather than the authority for stateful orchestration.

This page is intentionally a taxonomy and recovery guide. It does not change setup defaults, remove first-party MCP servers, or deprecate compatibility surfaces by itself.

Contract levels Copy Chapter

Stateful control plane vs. read-only inspection Copy Chapter

Stateful lifecycle and mutation surfaces have stricter requirements than read-only inspection because they make decisions that can start, stop, resume, mutate, or recover a runtime.

Stateful lifecycle and mutation surfaces Copy Section

These surfaces should have one canonical CLI/JSON owner:

• mode/session state: omx state ... --json
• team lifecycle and mutation: omx team ... and omx team api ... --json
• durable memory writes: omx notepad ... --json, omx project-memory ... --json, and omx wiki ... --json
• trace/runtime event mutation or cleanup paths where supported by the CLI

MCP tools for these areas are compatibility or host-integration surfaces. If MCP transport or process lifecycle fails, retry through the documented CLI/JSON parity command rather than looping on the same MCP call.

Read-only inspection surfaces Copy Section

Read-only inspection can remain broader and more convenient:

• trace viewing and summaries
• code-intel diagnostics/search
• wiki reads and project-memory reads
• status or inventory commands

Inspection surfaces may expose both CLI parity and optional MCP integration. They should not be treated as runtime control-plane authority unless the operation mutates state or lifecycle.

Canonical surface requirements Copy Chapter

A surface marked canonical should provide:

1. a stable omx ... CLI entrypoint,
2. machine-readable --json output for automation,
3. explicit MCP status such as parity, compat, integration, or deprecated,
4. documented fallback guidance for MCP stdio/process failures,
5. clear lifecycle ownership when the command can mutate runtime state.

Compatibility and recovery matrix Copy Chapter

Setup and migration posture Copy Chapter

Current safe sequencing is:

1. document the CLI-first taxonomy and recovery rules,
2. keep setup defaults stable unless a later product decision explicitly changes them,
3. support no-MCP or compatibility profiles with tests before any default flip,
4. update skills/templates/plugin wording after the taxonomy is accepted,
5. only consider fresh-default changes after owner approval, release notes, and compatibility coverage.

This preserves MCP for users and clients that need it while making the durable automation path unambiguous.

File: docs/audit/skills-agents-bloat-audit/bloat-audit.md Copy Chapter

Bloat audit — skills + agents (omx)

Generated 2026-05-23. Companion to inventory.md. Each entry is classified into one of:

• KEEP-AS-IS — actively used, fits cleanly with neighbors.
• CONSOLIDATE — duplicated or redundant with another surface; merge into the canonical entry.
• STREAMLINE — useful but bloated; cut boilerplate or dead branches.
• DEPRECATE — not used anywhere or superseded; remove from disk + manifest after a grace cycle.
• AMBIGUOUS — NEEDS OWNER DECISION — could go either way; flagged for owner.

Evidence per entry: catalog status (src/catalog/manifest.json), reference count (rg -l -F outside the entry's own directory), and where applicable LOC + most-recent commit. Risk level is the auditor's estimate of what could break if the entry were removed as-is. The full reference set per item is in inventory.md.

Style: classifications are deterministic functions of the data, not subjective. The same inputs would produce the same labels next month. Disagreement should be resolved against the data, not the prose.

Inventory anomalies (resolve before per-entry triage) Copy Chapter

These are not classifications — they are catalog/disk consistency findings the owner should resolve before any deletion PR lands.

A1. `wiki` skill is on disk but missing from `src/catalog/manifest.json` Copy Section

• Evidence: find ./skills -maxdepth 2 -name 'SKILL.md' returns skills/wiki/SKILL.md. python3 -c "import json; m=json.load(open('src/catalog/manifest.json')); print(['wiki' in [s['name'] for s in m['skills']]])" → [False]. The catalog hygiene test in src/hooks/__tests__/skill-catalog-hygiene.test.ts is the most likely surface to flag this.
• Impact: any code that iterates the catalog manifest (e.g. setup flow, doctor checks, installable.ts) will not see wiki, so it may not be installed by omx setup. Direct invocation via $wiki still works because the prompt loader resolves by filename.
• Decision needed: add the manifest row ({ "name": "wiki", "category": "utility", "status": "active" }) OR remove skills/wiki/. Pick by intent — is $wiki a supported user-facing surface, or an internal scratchpad?
• Owner default recommendation: ADD the manifest row. The skill body is 43-reference-rich and is invoked from documented places.

A2. Four manifest entries with no disk counterpart Copy Section

• Names: configure-discord, configure-openclaw, configure-slack, configure-telegram
• Status: all merged → configure-notifications.
• Impact: this is by design — configure-notifications is the canonical, and the four alias rows let omx setup accept legacy invocations. No action needed, listed here only so the next owner doesn't think it's a bug.

A3. 17 on-disk skills not shipped via `plugins/oh-my-codex/skills/` Copy Section

• Deprecated (no longer shipped, by design) (16): ask-claude, ask-gemini, build-fix, deepsearch, ecomode, frontend-ui-ux, help, note, ralph-init, review, security-review, swarm, tdd, trace, visual-verdict, web-clone
• Other (1): git-master
• Impact: these directories exist only as tombstones so src/catalog/__tests__/schema.test.ts and src/catalog/manifest.json stay consistent. They are not installed for users; the only consumer is the lint+catalog test surface.
• Decision needed: once the deprecated grace period passes, all 17 can be removed in a single sweep (PR-1 in the roadmap). Until then, leave alone.

Skills Copy Chapter

Entries grouped by classification, then alphabetical. Each entry: <name> → status → LOC, refs → classification → evidence → risk → one-line rationale.

KEEP-AS-IS (16) Copy Section

`ai-slop-cleaner`

• catalog: status=active canonical=— category=shortcut
• shape: LOC=148 · ref_count=16 · shipped=yes
• last commit: 2026-05-08 · docs: add UI design anti-slop signals (#2168)
• evidence: Active skill, 148 LOC, 16 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`analyze`

• catalog: status=active canonical=— category=shortcut
• shape: LOC=146 · ref_count=28 · shipped=yes
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Active skill, 146 LOC, 28 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`ask`

• catalog: status=active canonical=— category=shortcut
• shape: LOC=58 · ref_count=295 · shipped=yes
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Active skill, 58 LOC, 295 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`autopilot`

• catalog: status=active canonical=— category=execution
• shape: LOC=205 · ref_count=65 · shipped=yes
• last commit: 2026-05-22 · Guard autopilot ralplan consensus handoff (review fixes) (#2
• evidence: Active skill, 205 LOC, 65 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`autoresearch`

• catalog: status=active canonical=— category=execution
• shape: LOC=72 · ref_count=72 · shipped=yes
• last commit: 2026-05-22 · Clarify research planning boundaries
• evidence: Active skill, 72 LOC, 72 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`autoresearch-goal`

• catalog: status=active canonical=— category=execution
• shape: LOC=36 · ref_count=20 · shipped=yes
• last commit: 2026-05-22 · Clarify research planning boundaries
• evidence: Active skill, 36 LOC, 20 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`design`

• catalog: status=active canonical=designer category=shortcut
• shape: LOC=180 · ref_count=62 · shipped=yes
• last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow
• evidence: Active skill, 180 LOC, 62 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`doctor`

• catalog: status=active canonical=— category=utility
• shape: LOC=239 · ref_count=34 · shipped=yes
• last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258)
• evidence: Active skill, 239 LOC, 34 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`hud`

• catalog: status=active canonical=— category=utility
• shape: LOC=98 · ref_count=86 · shipped=yes
• last commit: 2026-03-11 · draft: bootstrap Rust CLI parity harness and initial omx com
• evidence: Active skill, 98 LOC, 86 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`performance-goal`

• catalog: status=active canonical=— category=execution
• shape: LOC=65 · ref_count=18 · shipped=yes
• last commit: 2026-05-05 · Protect goal workflows with snapshot reconciliation
• evidence: Active skill, 65 LOC, 18 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`pipeline`

• catalog: status=active canonical=— category=execution
• shape: LOC=97 · ref_count=32 · shipped=yes
• last commit: 2026-05-22 · Guard autopilot ralplan consensus handoff (review fixes) (#2
• evidence: Active skill, 97 LOC, 32 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`ralplan`

• catalog: status=active canonical=plan category=planning
• shape: LOC=187 · ref_count=77 · shipped=yes
• last commit: 2026-05-23 · Merge branch 'dev' into omx-issue-2453-ralplan-ultragoal-doc
• evidence: Active skill, 187 LOC, 77 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`ultragoal`

• catalog: status=active canonical=— category=execution
• shape: LOC=131 · ref_count=68 · shipped=yes
• last commit: 2026-05-20 · Avoid noisy fresh-session guidance in Ultragoal
• evidence: Active skill, 131 LOC, 68 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`ultraqa`

• catalog: status=active canonical=— category=execution
• shape: LOC=254 · ref_count=36 · shipped=yes
• last commit: 2026-05-11 · Ensure UltraQA catches adversarial e2e regressions (#2276)
• evidence: Active skill, 254 LOC, 36 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`ultrawork`

• catalog: status=active canonical=— category=execution
• shape: LOC=175 · ref_count=46 · shipped=yes
• last commit: 2026-05-20 · Make autopilot default to Ultragoal
• evidence: Active skill, 175 LOC, 46 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

`visual-ralph`

• catalog: status=active canonical=designer category=shortcut
• shape: LOC=161 · ref_count=17 · shipped=yes
• last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow
• evidence: Active skill, 161 LOC, 17 refs. Sits cleanly in the current workflow set.
• action: No action.
• risk if removed: low
• rationale: Active and well-connected; nothing to change.

KEEP-AS-IS (alias) (1) Copy Section

`git-master`

• catalog: status=alias canonical=git-master category=shortcut
• shape: LOC=27 · ref_count=8 · shipped=no
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Alias for git-master. Shim is intentional. 27 LOC.
• action: No action unless the canonical is itself being changed.
• risk if removed: low
• rationale: Alias entry redirects to git-master; intentional surface.

KEEP-AS-IS (internal) (1) Copy Section

`worker`

• catalog: status=internal canonical=— category=utility
• shape: LOC=106 · ref_count=165 · shipped=yes
• last commit: 2026-03-17 · fix: stop generating skill agents (#897)
• evidence: Internal skill (106 LOC, refs 165). Used by an internal surface — do not expose, do not delete.
• action: No action.
• risk if removed: low
• rationale: Internal-only utility; ship-blocked by design.

STREAMLINE (optional) (7) Copy Section

`cancel`

• catalog: status=active canonical=— category=utility
• shape: LOC=399 · ref_count=67 · shipped=yes
• last commit: 2026-05-20 · Make autopilot default to Ultragoal
• evidence: Active and well-connected (67 refs) but heavy (399 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`code-review`

• catalog: status=active canonical=code-reviewer category=shortcut
• shape: LOC=288 · ref_count=54 · shipped=yes
• last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258)
• evidence: Active and well-connected (54 refs) but heavy (288 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`deep-interview`

• catalog: status=active canonical=— category=planning
• shape: LOC=490 · ref_count=74 · shipped=yes
• last commit: 2026-05-21 · Prefer Ultragoal for durable follow-up guidance
• evidence: Active and well-connected (74 refs) but heavy (490 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`plan`

• catalog: status=active canonical=— category=planning
• shape: LOC=277 · ref_count=204 · shipped=yes
• last commit: 2026-05-22 · Clarify research planning boundaries
• evidence: Active and well-connected (204 refs) but heavy (277 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`ralph`

• catalog: status=active canonical=— category=execution
• shape: LOC=294 · ref_count=141 · shipped=yes
• last commit: 2026-05-19 · fix(ralph): enforce completion audit state contract (#2385)
• evidence: Active and well-connected (141 refs) but heavy (294 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`skill`

• catalog: status=active canonical=— category=utility
• shape: LOC=836 · ref_count=160 · shipped=yes
• last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow
• evidence: Active and well-connected (160 refs) but heavy (836 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

`team`

• catalog: status=active canonical=— category=execution
• shape: LOC=520 · ref_count=270 · shipped=yes
• last commit: 2026-05-21 · Prefer Ultragoal for durable follow-up guidance
• evidence: Active and well-connected (270 refs) but heavy (520 LOC). Streamline is optional — only worth doing if the content rotted relative to current contracts.
• action: Defer until after the tombstone-deletion PR lands so the diff is easier to read.
• risk if removed: low
• rationale: Sized for its load, but a quality pass could still help.

CONSOLIDATE — already collapsed (4) Copy Section

`configure-discord`

• catalog: status=merged canonical=configure-notifications category=utility
• shape: LOC=— · ref_count=0 · shipped=—
• last commit: — (no dir)
• evidence: Skill configure-discord exists only in the manifest, merged into configure-notifications. Manifest entry preserves the alias for omx setup lookups.
• action: No directory under ./skills/configure-discord/ — already done. Keep manifest row unless owner decides to fully drop the public name.
• risk if removed: low
• rationale: Already merged into configure-notifications; manifest row is the only remaining surface.

`configure-openclaw`

• catalog: status=merged canonical=configure-notifications category=utility
• shape: LOC=— · ref_count=0 · shipped=—
• last commit: — (no dir)
• evidence: Skill configure-openclaw exists only in the manifest, merged into configure-notifications. Manifest entry preserves the alias for omx setup lookups.
• action: No directory under ./skills/configure-openclaw/ — already done. Keep manifest row unless owner decides to fully drop the public name.
• risk if removed: low
• rationale: Already merged into configure-notifications; manifest row is the only remaining surface.

`configure-slack`

• catalog: status=merged canonical=configure-notifications category=utility
• shape: LOC=— · ref_count=0 · shipped=—
• last commit: — (no dir)
• evidence: Skill configure-slack exists only in the manifest, merged into configure-notifications. Manifest entry preserves the alias for omx setup lookups.
• action: No directory under ./skills/configure-slack/ — already done. Keep manifest row unless owner decides to fully drop the public name.
• risk if removed: low
• rationale: Already merged into configure-notifications; manifest row is the only remaining surface.

`configure-telegram`

• catalog: status=merged canonical=configure-notifications category=utility
• shape: LOC=— · ref_count=0 · shipped=—
• last commit: — (no dir)
• evidence: Skill configure-telegram exists only in the manifest, merged into configure-notifications. Manifest entry preserves the alias for omx setup lookups.
• action: No directory under ./skills/configure-telegram/ — already done. Keep manifest row unless owner decides to fully drop the public name.
• risk if removed: low
• rationale: Already merged into configure-notifications; manifest row is the only remaining surface.

DEPRECATE (16) Copy Section

`ask-claude`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=12 · ref_count=9 · shipped=no
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (9) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`ask-gemini`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=12 · ref_count=10 · shipped=no
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`build-fix`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=10 · ref_count=8 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (8) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`deepsearch`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=10 · ref_count=5 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (5) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`ecomode`

• catalog: status=deprecated canonical=— category=execution
• shape: LOC=114 · ref_count=10 · shipped=no
• last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258)
• evidence: Hard-deprecated stub (114 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`frontend-ui-ux`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=16 · ref_count=10 · shipped=no
• last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow
• evidence: Hard-deprecated stub (16 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`help`

• catalog: status=deprecated canonical=— category=utility
• shape: LOC=10 · ref_count=161 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (161) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: medium
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`note`

• catalog: status=deprecated canonical=— category=utility
• shape: LOC=10 · ref_count=74 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (74) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: medium
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`ralph-init`

• catalog: status=deprecated canonical=— category=utility
• shape: LOC=10 · ref_count=6 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (6) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`review`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=10 · ref_count=163 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (163) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: medium
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`security-review`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=10 · ref_count=8 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (8) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`swarm`

• catalog: status=deprecated canonical=— category=execution
• shape: LOC=12 · ref_count=17 · shipped=no
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (17) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`tdd`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=104 · ref_count=6 · shipped=no
• last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258)
• evidence: Hard-deprecated stub (104 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (6) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`trace`

• catalog: status=deprecated canonical=— category=utility
• shape: LOC=10 · ref_count=41 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (41) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: medium
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`visual-verdict`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=10 · ref_count=9 · shipped=no
• last commit: 2026-05-06 · Retire obsolete OMX skills (#2132)
• evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (9) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

`web-clone`

• catalog: status=deprecated canonical=— category=shortcut
• shape: LOC=357 · ref_count=10 · shipped=no
• last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries
• evidence: Hard-deprecated stub (357 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers.
• action: Once owner confirms no external $<name> users remain, remove the directory and the manifest row in a single sweep.
• risk if removed: low
• rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period.

AMBIGUOUS — NEEDS OWNER DECISION (5) Copy Section

`best-practice-research`

• catalog: status=active canonical=— category=planning
• shape: LOC=83 · ref_count=12 · shipped=yes
• last commit: 2026-05-22 · Clarify research planning boundaries
• evidence: Active skill but low connectivity (12 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned.
• action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body.
• risk if removed: medium
• rationale: Data is inconclusive; owner sees the case better than the auditor.

`configure-notifications`

• catalog: status=active canonical=— category=utility
• shape: LOC=287 · ref_count=6 · shipped=yes
• last commit: 2026-04-13 · Release 0.12.6
• evidence: Active skill but low connectivity (6 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned.
• action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body.
• risk if removed: medium
• rationale: Data is inconclusive; owner sees the case better than the auditor.

`omx-setup`

• catalog: status=active canonical=— category=utility
• shape: LOC=135 · ref_count=15 · shipped=yes
• last commit: 2026-05-21 · Unblock plugin-scoped hooks from verifier
• evidence: Active skill but low connectivity (15 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned.
• action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body.
• risk if removed: medium
• rationale: Data is inconclusive; owner sees the case better than the auditor.

`prometheus-strict`

• catalog: status=active canonical=— category=planning
• shape: LOC=219 · ref_count=11 · shipped=yes
• last commit: 2026-05-23 · feat(prometheus-strict): require second planning round
• evidence: Active skill but low connectivity (11 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned.
• action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body.
• risk if removed: medium
• rationale: Data is inconclusive; owner sees the case better than the auditor.

`wiki`

• catalog: status=NOT_IN_MANIFEST canonical=— category=—
• shape: LOC=57 · ref_count=43 · shipped=yes
• last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258)
• evidence: On-disk skill wiki is not registered in src/catalog/manifest.json. Either add a manifest entry (so install/lint surfaces see it) or remove the directory.
• action: Tests in src/catalog/__tests__/schema.test.ts reject unknown skills if they are not core; consistency tests in src/hooks/__tests__/skill-catalog-hygiene.test.ts may already flag this. Verify before adding.
• risk if removed: medium
• rationale: Data is inconclusive; owner sees the case better than the auditor.

Agents Copy Chapter

Same format as skills. The 3 entries with status=NOT_IN_MANIFEST are the non-installable prompt assets listed in src/agents/policy.ts (explore-harness, sisyphus-lite, team-orchestrator).

KEEP-AS-IS (18) Copy Section

`analyst`

• catalog: status=active canonical=— category=build
• shape: ref_count=15
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis
• evidence: Active agent, 15 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`architect`

• catalog: status=active canonical=— category=build
• shape: ref_count=111
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only
• evidence: Active agent, 111 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`code-reviewer`

• catalog: status=active canonical=— category=review
• shape: ref_count=21
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only
• evidence: Active agent, 21 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`critic`

• catalog: status=active canonical=— category=coordination
• shape: ref_count=56
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only
• evidence: Active agent, 56 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`debugger`

• catalog: status=active canonical=— category=build
• shape: ref_count=25
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=standard · routingRole=executor · tools=analysis
• evidence: Active agent, 25 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`dependency-expert`

• catalog: status=active canonical=— category=domain
• shape: ref_count=14
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis
• evidence: Active agent, 14 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`designer`

• catalog: status=active canonical=— category=domain
• shape: ref_count=24
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution
• evidence: Active agent, 24 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`executor`

• catalog: status=active canonical=— category=build
• shape: ref_count=114
• definition (src/agents/definitions.ts): posture=— · modelClass=— · routingRole=— · tools=—
• evidence: Active agent, 114 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`explore`

• catalog: status=active canonical=— category=build
• shape: ref_count=99
• definition (src/agents/definitions.ts): posture=fast-lane · modelClass=fast · routingRole=specialist · tools=read-only
• evidence: Active agent, 99 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`planner`

• catalog: status=active canonical=— category=build
• shape: ref_count=35
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis
• evidence: Active agent, 35 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`prometheus-strict-metis`

• catalog: status=active canonical=— category=coordination
• shape: ref_count=7
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis
• evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`prometheus-strict-momus`

• catalog: status=active canonical=— category=coordination
• shape: ref_count=7
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis
• evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`prometheus-strict-oracle`

• catalog: status=active canonical=— category=coordination
• shape: ref_count=7
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis
• evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`researcher`

• catalog: status=active canonical=— category=domain
• shape: ref_count=33
• definition (src/agents/definitions.ts): posture=fast-lane · modelClass=standard · routingRole=specialist · tools=analysis
• evidence: Active agent, 33 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`test-engineer`

• catalog: status=active canonical=— category=domain
• shape: ref_count=28
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=frontier · routingRole=executor · tools=execution
• evidence: Active agent, 28 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`verifier`

• catalog: status=active canonical=— category=build
• shape: ref_count=23
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis
• evidence: Active agent, 23 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`vision`

• catalog: status=active canonical=— category=coordination
• shape: ref_count=17
• definition (src/agents/definitions.ts): posture=fast-lane · modelClass=frontier · routingRole=specialist · tools=read-only
• evidence: Active agent, 17 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

`writer`

• catalog: status=active canonical=— category=domain
• shape: ref_count=21
• definition (src/agents/definitions.ts): posture=fast-lane · modelClass=standard · routingRole=specialist · tools=execution
• evidence: Active agent, 21 refs. Loaded into the current routing/pipeline narrative.
• action: No action.
• risk if removed: low
• rationale: Used by current routing/pipeline.

KEEP-AS-IS (internal) (2) Copy Section

`code-simplifier`

• catalog: status=internal canonical=— category=domain
• shape: ref_count=11
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=frontier · routingRole=executor · tools=execution
• evidence: Intentional internal-only agent. Not surfaced for direct routing.
• action: No action.
• risk if removed: low
• rationale: Intentional internal-only.

`team-executor`

• catalog: status=internal canonical=— category=build
• shape: ref_count=9
• definition (src/agents/definitions.ts): posture=— · modelClass=— · routingRole=— · tools=—
• evidence: Intentional internal-only agent. Not surfaced for direct routing.
• action: No action.
• risk if removed: low
• rationale: Intentional internal-only.

KEEP-AS-IS (non-installable asset) (3) Copy Section

`explore-harness`

• catalog: status=NOT_IN_MANIFEST canonical=— category=—
• shape: ref_count=12
• definition (src/agents/definitions.ts): posture=— · modelClass=— · routingRole=— · tools=—
• evidence: Listed in NON_NATIVE_AGENT_PROMPT_ASSETS (src/agents/policy.ts). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent.
• action: Verify the consuming skill (e.g. sisyphus-lite → ralph, team-orchestrator → team, explore-harness → explore) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep.
• risk if removed: medium
• rationale: Prompt asset for an embedded role; not directly installed.

`sisyphus-lite`

• catalog: status=NOT_IN_MANIFEST canonical=— category=—
• shape: ref_count=5
• definition (src/agents/definitions.ts): posture=— · modelClass=— · routingRole=— · tools=—
• evidence: Listed in NON_NATIVE_AGENT_PROMPT_ASSETS (src/agents/policy.ts). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent.
• action: Verify the consuming skill (e.g. sisyphus-lite → ralph, team-orchestrator → team, explore-harness → explore) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep.
• risk if removed: medium
• rationale: Prompt asset for an embedded role; not directly installed.

`team-orchestrator`

• catalog: status=NOT_IN_MANIFEST canonical=— category=—
• shape: ref_count=2
• definition (src/agents/definitions.ts): posture=— · modelClass=— · routingRole=— · tools=—
• evidence: Listed in NON_NATIVE_AGENT_PROMPT_ASSETS (src/agents/policy.ts). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent.
• action: Verify the consuming skill (e.g. sisyphus-lite → ralph, team-orchestrator → team, explore-harness → explore) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep.
• risk if removed: low
• rationale: Prompt asset for an embedded role; not directly installed.

CONSOLIDATE (10) Copy Section

`api-reviewer`

• catalog: status=merged canonical=code-reviewer category=review
• shape: ref_count=9
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only
• evidence: Already merged into code-reviewer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/api-reviewer.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/api-reviewer.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into code-reviewer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`information-architect`

• catalog: status=merged canonical=designer category=product
• shape: ref_count=7
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis
• evidence: Already merged into designer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/information-architect.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/information-architect.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into designer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`performance-reviewer`

• catalog: status=merged canonical=code-reviewer category=review
• shape: ref_count=13
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only
• evidence: Already merged into code-reviewer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/performance-reviewer.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/performance-reviewer.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into code-reviewer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`product-analyst`

• catalog: status=merged canonical=analyst category=product
• shape: ref_count=8
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis
• evidence: Already merged into analyst per catalog. Entry kept in AGENT_DEFINITIONS + prompts/product-analyst.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/product-analyst.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into analyst; entry stays for upgrade-path parity, schedule removal after grace cycle.

`product-manager`

• catalog: status=merged canonical=analyst category=product
• shape: ref_count=11
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis
• evidence: Already merged into analyst per catalog. Entry kept in AGENT_DEFINITIONS + prompts/product-manager.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/product-manager.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into analyst; entry stays for upgrade-path parity, schedule removal after grace cycle.

`qa-tester`

• catalog: status=merged canonical=test-engineer category=domain
• shape: ref_count=9
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution
• evidence: Already merged into test-engineer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/qa-tester.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/qa-tester.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into test-engineer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`quality-reviewer`

• catalog: status=merged canonical=code-reviewer category=review
• shape: ref_count=17
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only
• evidence: Already merged into code-reviewer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/quality-reviewer.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/quality-reviewer.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: medium
• rationale: Already collapsed into code-reviewer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`quality-strategist`

• catalog: status=merged canonical=verifier category=domain
• shape: ref_count=6
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis
• evidence: Already merged into verifier per catalog. Entry kept in AGENT_DEFINITIONS + prompts/quality-strategist.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/quality-strategist.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into verifier; entry stays for upgrade-path parity, schedule removal after grace cycle.

`style-reviewer`

• catalog: status=merged canonical=code-reviewer category=review
• shape: ref_count=15
• definition (src/agents/definitions.ts): posture=fast-lane · modelClass=fast · routingRole=specialist · tools=read-only
• evidence: Already merged into code-reviewer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/style-reviewer.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/style-reviewer.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into code-reviewer; entry stays for upgrade-path parity, schedule removal after grace cycle.

`ux-researcher`

• catalog: status=merged canonical=designer category=product
• shape: ref_count=8
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis
• evidence: Already merged into designer per catalog. Entry kept in AGENT_DEFINITIONS + prompts/ux-researcher.md only for omx setup parity with older installs.
• action: After ≥1 release cycle of merged status, remove the AGENT_DEFINITIONS entry and the prompts/ux-researcher.md file. Keep the manifest row as merged for upgrade-path stability.
• risk if removed: low
• rationale: Already collapsed into designer; entry stays for upgrade-path parity, schedule removal after grace cycle.

DEPRECATE (2) Copy Section

`build-fixer`

• catalog: status=deprecated canonical=— category=domain
• shape: ref_count=5
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution
• evidence: Catalog marks this agent deprecated. ref_count 5 is mostly catalog/test boilerplate.
• action: Confirm no skill body still names it; if clean, remove AGENT_DEFINITIONS entry, prompts/build-fixer.md, and any policy carve-outs.
• risk if removed: low
• rationale: Catalog says deprecated and references are catalog/test boilerplate.

`security-reviewer`

• catalog: status=deprecated canonical=— category=review
• shape: ref_count=5
• definition (src/agents/definitions.ts): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only
• evidence: Catalog marks this agent deprecated. ref_count 5 is mostly catalog/test boilerplate.
• action: Confirm no skill body still names it; if clean, remove AGENT_DEFINITIONS entry, prompts/security-reviewer.md, and any policy carve-outs.
• risk if removed: low
• rationale: Catalog says deprecated and references are catalog/test boilerplate.

AMBIGUOUS — NEEDS OWNER DECISION (1) Copy Section

`git-master`

• catalog: status=active canonical=— category=domain
• shape: ref_count=8
• definition (src/agents/definitions.ts): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution
• evidence: Active agent with low connectivity (8 refs). Either underused or the work is delegated implicitly via routing.
• action: Owner should confirm the agent has a live consumer. If not, downgrade to internal or merge into the closest neighbor.
• risk if removed: medium
• rationale: Active in catalog but low connectivity in code+skill bodies.

Summary Copy Chapter

Skills Copy Section

Agents Copy Section

Read this alongside connectivity-roadmap.md for the proposed PR-by-PR sequence to act on these classifications.

Generated for owner review. Re-run by regenerating notes/combined.json and re-running the bloat-audit generator.

File: docs/audit/skills-agents-bloat-audit/connectivity-roadmap.md Copy Chapter

Connectivity roadmap — skills + agents (omx)

Generated 2026-05-23. Companion to inventory.md and bloat-audit.md. This document is about the organic connectivity between skills and agents that the owner asked about: where a useful surface exists but the next-step links to its neighbors are missing, so the model can't find it during routing.

It also lays out the recommended PR-by-PR sequence to land the bloat-audit cleanup safely. Every PR is scoped to be ≤30-minute review.

How the data was collected Copy Chapter

Three signals were combined:

1. rg -l -F '<name>' skills/ src/ prompts/ templates/ — total reference count per skill and per agent (from inventory.md). False positives possible for English-word names (ask, plan, team, note, review, help).
2. Skill body → agent name — does each SKILL.md textually mention any agent name? Builds the narrative coupling matrix (in inventory.md § Skill → agent reference matrix).
3. Agent prompt → skill name — does each prompts/<name>.md textually mention any skill name?

Read against this evidence: a skill or agent is orphan-ish if it is status=active in the catalog AND it falls into ≥1 of the following:

• zero other-skill bodies reference it,
• zero active agents reference it (and it is a workflow/orchestration skill where agent routing would be expected),
• zero active skills reference it (and it is a workflow/specialist agent where skill orientation would be expected),
• its total ref_count is ≤ 15 AND it isn't a core skill.

False-positive caveat: ask and cancel and configure-notifications and omx-setup mention no agents — but this is not orphan behavior, it is correct (they are infrastructure surfaces below the routing layer). Treat them as KEEP-AS-IS.

Section 1 — Orphan analysis (the data) Copy Chapter

1.1 Active skills whose body mentions zero active agents Copy Section

1.2 Active skills NOT referenced by any other skill body Copy Section

1.3 Active skills with weak inter-skill connectivity (≤ 2 other-skill refs) Copy Section

1.4 Active agents with low total reference count Copy Section

1.5 Agents with empty `prompts/.md` skill mentions Copy Section

All 33 active agents mention at least one active skill in their prompt body (ag_to_sk returned no empty sets). The most-common backlink is to $ask, which is mentioned by every agent prompt — confirming ask is the canonical advisor backstop. No orphan agents on this signal.

Section 2 — Connectivity fixes Copy Chapter

Recommendations are grouped by effort. Each carries the proposed concrete edit and which file would change. No edits are made in this PR — they are queued for follow-ups.

2.1 Quick wins (single-file edit, <30 min each) Copy Section

2.2 Medium-effort (multi-file or requires test) Copy Section

2.3 Strategic items (owner judgment required) Copy Section

Section 3 — Suggested PR-split Copy Chapter

The proposed sequence is deprecations first, consolidations second, connectivity edits third. This ordering ensures every connectivity fix lands against the final shape of the catalog rather than a transitional one, and avoids the wasted review-time of editing a soon-to-be-removed file.

Each PR is sized so the review is ≤30 min for someone who has read this document. All PRs target dev, not main.

Phase A — Tombstone deletion (clears the floor) Copy Section

PR-1 — chore(skills): remove 16 deprecated tombstone skills

• Type: chore (deletion)
• Touches: 16 skill directories + src/catalog/manifest.json + 2 catalog tests
• Scope: delete the 16 directories listed in M1; for each, either remove the manifest row entirely or change its status to a new removed value (owner picks one).
• Pre-flight: grep rg -l -F '<name>' for each before deletion — if any source file (not test) still hard-codes the name, fix that source file in the same PR or pull it into a follow-up.
• Risk: medium. Catalog tests are the only real surface.
• Depends on: nothing.

PR-2 — chore(agents): remove 10 merged + 2 deprecated agents

• Type: chore (deletion)
• Touches: src/agents/definitions.ts (12 entries), 12 prompts/*.md, possibly src/agents/__tests__/definitions.test.ts
• Scope: remove the 10 merged agents (api-reviewer, quality-reviewer, style-reviewer, performance-reviewer, quality-strategist, qa-tester, product-manager, product-analyst, ux-researcher, information-architect) and the 2 deprecated agents (security-reviewer, build-fixer) from both AGENT_DEFINITIONS and the prompts/ tree. Keep the manifest rows as merged → <canonical> for upgrade-path stability.
• Pre-flight: grep each agent name in skills/*/SKILL.md — they should not appear in any active skill body. If they do, that's actually an M2 follow-up — bring it into this PR or split.
• Risk: medium. Some agents may still be in lint tests as expected entries.
• Depends on: PR-1 (so the cleanup is a single bloat-removal phase rather than two interleaved ones).

Phase B — Inventory anomaly resolution Copy Section

PR-3 — chore(catalog): add wiki to manifest OR remove skills/wiki

• Type: chore (catalog) OR chore (deletion)
• Touches: src/catalog/manifest.json + src/catalog/__tests__/ (one row OR a directory removal + test rule)
• Scope: resolve anomaly A1. Default recommendation in bloat-audit.md is ADD the row. Owner picks.
• Depends on: nothing (can land before, during, or after PR-1/PR-2). Listed here for the sequence.

Phase C — Connectivity quick wins (docs-only) Copy Section

These are all SKILL.md edits. They can land as a single PR or split — but they should land after Phase A so the editor isn't writing references to dead skills.

PR-4 — docs(skills): wire orphan-ish surfaces into their neighbors

• Type: docs
• Touches: skills/{performance-goal,omx-setup,doctor,configure-notifications,autopilot,code-review,analyze,ralplan,design}/SKILL.md (≈9 single-line additions per Q1–Q9)
• Scope: apply Q1 through Q9 from § 2.1.
• Risk: low. Pure documentation.
• Depends on: PR-1 (so help is gone before we'd cross-link from it), PR-2 (so we're not referencing a now-removed agent like qa-tester).

Phase D — Strategic decisions (one PR each, owner-routed) Copy Section

These do NOT have a default recommendation in this document. Each lands as its own owner-approved PR.

PR-5 (optional) — refactor(agents): merge prometheus-strict triple into one composite (S2) — only if owner picks the composite option.

PR-6 (optional) — refactor(agents): promote team-executor to active (S3) — only if owner decides.

PR-7 (optional) — chore(catalog): drop legacy configure-* merged rows (S1) — only after ≥2 more releases.

PR-8 (optional) — refactor(skills): fold performance-goal into ultragoal --performance (S6) — only if owner decides.

Dependency graph Copy Section

PR-1 (chore: delete tombstones) ───┐
                                   ├──► PR-4 (docs: connectivity quick wins)
PR-2 (chore: delete merged agents)─┘
PR-3 (chore: resolve wiki anomaly) — independent, can land anywhere

PR-5..8 — owner-routed, no fixed sequence among themselves; can land after PR-4
         or independently if their scope doesn't overlap PR-4 edits.

Section 4 — Risk + verification per PR Copy Chapter

For each PR above, the minimum verification before landing:

Section 5 — What this roadmap deliberately does NOT do Copy Chapter

• It does not propose deleting the configure-{discord,telegram,slack,openclaw} merged manifest rows. Those are intentional upgrade-path absorbers. Removing them is a separate strategic decision (S1).
• It does not propose adding new skills. The owner explicitly asked for bloat triage + connectivity; new skills are out of scope.
• It does not propose touching src/agents/policy.ts or src/agents/native-config.ts beyond what is already covered by removing the merged/deprecated entries from AGENT_DEFINITIONS. Those files' logic is sound; only the data they operate on is shrinking.
• It does not propose rewriting any of the 7 STREAMLINE (optional) skills. Per bloat-audit.md, those are deferred until after the tombstone deletion lands so the diff stays small.
• It does not propose any change to ./prompts/explore-harness.md, ./prompts/sisyphus-lite.md, or ./prompts/team-orchestrator.md. They are intentionally non-installable per src/agents/policy.ts's NON_NATIVE_AGENT_PROMPT_ASSETS.

Section 6 — Quick reference Copy Chapter

Counts at a glance (drawn from bloat-audit.md § Summary):

• Skills to DEPRECATE: 16 → PR-1
• Agents to CONSOLIDATE: 10 → PR-2 (merged)
• Agents to DEPRECATE: 2 → PR-2 (deprecated)
• Skills with manifest anomaly: 1 (wiki) → PR-3
• Connectivity quick wins: 9 → PR-4
• Strategic decisions outstanding: 6 (S1–S6) → PR-5..8 (optional)

After PR-1 through PR-4 land, the surface is:

• ~30 skills (currently 50 catalog entries; 46 on-disk → 30 on-disk after tombstone deletion).
• ~21 agents (currently 33 in AGENT_DEFINITIONS → 21 after consolidation/deprecation).
• Zero on-disk skills missing from the manifest (anomaly A1 closed).
• Every active skill has at least one cross-skill link (or is intentionally below the cross-link layer).

That is the target shape this roadmap moves toward.

Generated for owner review. Re-run by regenerating notes/combined.json and recomputing the orphan analysis.

File: docs/audit/skills-agents-bloat-audit/inventory.md Copy Chapter

Inventory — skills + agents (omx)

Generated 2026-05-23. Data sources: src/catalog/manifest.json, src/agents/definitions.ts, git log -1 -- skills/<name>/, and rg -l --no-messages -F '<name>' skills/ src/ prompts/ templates/.

• Total skills: 50 (46 on disk + 4 merged-only in manifest).
• Total agents: 36 (33 in AGENT_DEFINITIONS + 3 non-installable prompt assets: explore-harness, sisyphus-lite, team-orchestrator).
• Catalog statuses (src/catalog/schema.ts): active | internal | alias | merged | deprecated.
• Shipped surface is plugins/oh-my-codex/skills/ (29 dirs). Anything in ./skills/ but not in ./plugins/oh-my-codex/skills/ is a catalog-only shadow (kept on disk to preserve the public/catalog contract while no longer being installed).

Conventions in the tables below:

• ref_count = number of files (outside the skill/agent's own directory and outside its own prompts/*.md) matching the literal name via rg -l -F. False positives are possible for short, English-word names (e.g. ask, plan, note, help, review, team). Treat these as upper bounds; structural references in src/catalog/*, templates/, and src/cli/* are the most load-bearing.
• shipped = directory exists under plugins/oh-my-codex/skills/.
• last_commit = %cs %s of the newest commit that touched the skill directory (git log -1 --format='%cs|%s' -- skills/<name>/). For agents, the relevant signal lives in src/agents/definitions.ts (single file) plus the agent's prompts/<name>.md; per-agent commit dates were not separately rolled up because the central definitions.ts aggregates them.

Skills Copy Chapter

Sorted alphabetically. All paths relative to repo root.

Skill cross-reference detail Copy Section

Selected breakdowns of skill → referencing files. Skills with ref_count ≤ 15 are fully expanded; high-ref skills are summarized as counts-by-kind to keep the table digestible.

Agents Copy Chapter

Sorted alphabetically. The 3 entries with status = NOT_IN_MANIFEST are non-installable prompt assets (see NON_NATIVE_AGENT_PROMPT_ASSETS in src/agents/policy.ts).

reasoningEffort, posture, modelClass, routingRole, tools come from src/agents/definitions.ts. Description is the one-line description field there.

Agent cross-reference detail Copy Section

Selected breakdowns of agent → referencing files. Agents with ref_count ≤ 15 are fully expanded; the rest are summarized.

Skill → agent reference matrix Copy Chapter

Rows = skills that mention agent names in their SKILL.md body. Columns = agents (only those mentioned by at least one skill). A cell is ● when the skill's SKILL.md textually contains the agent's bare name (rg -F).

This is the narrative coupling, not the runtime call graph. It tells you whether a skill's documentation orients the model toward a specific agent; it does NOT mean the skill executes that agent automatically.

Skills not appearing as a row above mention zero agent names verbatim (19 skills). That is itself a connectivity signal (covered in connectivity-roadmap.md).

Skills with zero agent mentions in their SKILL.md body:

• ask
• ask-claude
• ask-gemini
• build-fix
• cancel
• configure-notifications
• frontend-ui-ux
• help
• note
• omx-setup
• performance-goal
• ralph-init
• review
• security-review
• swarm
• trace
• visual-verdict
• web-clone
• worker

Catalog ↔ disk consistency Copy Chapter

• On disk but not in src/catalog/manifest.json (1): wiki
• In manifest but not on disk (4): configure-discord, configure-openclaw, configure-slack, configure-telegram
• On disk but not shipped via plugins/oh-my-codex/skills/ (17): ask-claude, ask-gemini, build-fix, deepsearch, ecomode, frontend-ui-ux, git-master, help, note, ralph-init, review, security-review, swarm, tdd, trace, visual-verdict, web-clone

These three lines are the most actionable consistency findings — see bloat-audit.md § Inventory anomalies for proposed fixes.

Generated for owner review. Do not edit by hand without re-running notes/audit-* data collection.

File: docs/audit/skills-agents-bloat-audit/README.md Copy Chapter

Skills + agents bloat audit (omx) — 2026-05-23

This directory contains a read-only audit of the ./skills/ and ./src/agents/ surfaces of oh-my-codex, produced in response to an owner verbal request for a "comprehensive bloat-audit + connectivity-improvement roadmap." Audit ran on branch chore/skills-agents-bloat-audit rooted on origin/dev.

How this audit was produced Copy Chapter

1. Enumerated all canonical skills via find ./skills -maxdepth 2 -name 'SKILL.md' (46 on disk).
2. Enumerated agents from src/agents/definitions.ts (AGENT_DEFINITIONS) plus the 3 non-installable prompt assets in src/agents/policy.ts (NON_NATIVE_AGENT_PROMPT_ASSETS) → 36 total.
3. Pulled authoritative status (active / internal / alias / merged / deprecated) from src/catalog/manifest.json (49 skill rows + 33 agent rows).
4. Per skill: file LOC, last-touched commit (git log -1 --format='%cs|%s' -- skills/<name>/), frontmatter description.
5. Per skill and per agent: reference count via rg -l --no-messages -F '<name>' skills/ src/ prompts/ templates/, excluding the entry's own directory and own prompts/<name>.md.
6. Per skill: which agent names appear textually in its SKILL.md body (narrative coupling matrix).
7. Per agent: which skill names appear textually in its prompts/<name>.md body.
8. Classified each entry deterministically per the rules in bloat-audit.md § header.

Raw intermediate data (per-skill metrics CSV, reference CSVs, the flattened catalog dump, and the combined JSON) was generated in a scratch notes/ directory during the audit; it is intentionally not committed (those files are reproducible from this repo at any commit by re-running the data collection described above).

Contents Copy Chapter

Top-line numbers Copy Chapter

From bloat-audit.md § Summary:

• Skills (50 catalog entries, 46 on disk):
  • 18 KEEP-AS-IS (incl. alias + internal)
  • 7 STREAMLINE (optional)
  • 4 CONSOLIDATE — already collapsed
  • 16 DEPRECATE (all already tombstoned to ~10 LOC)
  • 5 AMBIGUOUS — owner decision needed
• Agents (36 total, 33 in AGENT_DEFINITIONS):
  • 23 KEEP-AS-IS (incl. internal + non-installable asset)
  • 10 CONSOLIDATE (already-merged entries)
  • 2 DEPRECATE
  • 1 AMBIGUOUS — owner decision needed

After the suggested PR-1 + PR-2 land, the surface contracts to ~30 on-disk skills and ~21 agents. See connectivity-roadmap.md § 6 — Quick reference.

Important caveats Copy Chapter

• This audit is opinion + evidence, not a unilateral mandate. Every classification can be argued against the data. Owner reviews PR-by-PR; nothing is to be deleted in this PR.
• No files in ./skills/, ./src/agents/, ./prompts/, or any other production surface were modified. The committed delta is limited to this docs/audit/skills-agents-bloat-audit/ directory.
• Reference counts are upper bounds. Short, English-word names (ask, plan, team, note, review, help) inflate via false positives. The classifier weights structural references (catalog, templates, CLI surfaces) above prose mentions.
• Tests, benchmarks, and the full suite were NOT run. Per the audit's scope guardrails. The next PR (PR-1 in the roadmap) is where verification gets reattached.

Re-running this audit Copy Chapter

The data sources listed in § How this audit was produced are the entire input set. To re-run on a future commit:

1. Re-execute the 7 enumeration steps (1–7 above) against the new repo state.
2. Re-apply the classifier rules documented at the head of bloat-audit.md.
3. Diff the new inventory.md against the committed one to see what moved.

Because every classification is a deterministic function of catalog status + LOC + reference counts, the same inputs at a future commit will produce the same labels (modulo new entries appearing or old entries being deleted).

Next step Copy Chapter

Read bloat-audit.md for the per-entry triage, then connectivity-roadmap.md § 3 for the proposed PR sequence. The owner picks which PRs to authorize; this audit only proposes.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

File: docs/contracts/autoresearch-command-contract.md Copy Chapter

`omx autoresearch` parity contract

omx autoresearch is a thin supervisor that drives one Codex experiment session per iteration while OMX owns the durable keep/discard/reset loop.

CLI Copy Chapter

omx autoresearch <mission-dir> [codex-args...]
omx autoresearch --resume <run-id> [codex-args...]
omx autoresearch --help

• Fresh launch always creates a new run-tagged lane.
• --resume <run-id> loads .omx/logs/autoresearch/<run-id>/manifest.json.
• A second launch is rejected while repo-root .omx/state/autoresearch-state.json points at an active run.

Mission / sandbox contract Copy Chapter

<mission-dir> must be inside a git repo and contain mission.md plus sandbox.md.

sandbox.md YAML frontmatter must define:

• evaluator.command
• evaluator.format: json
• optional evaluator.keep_policy: score_improvement | pass_only

Evaluator stdout must be JSON with required boolean pass and optional numeric score.

Runtime model Copy Chapter

Fresh launch creates:

• branch autoresearch/<mission-slug>/<run-tag>
• worktree <repo>.omx-worktrees/autoresearch-<mission-slug>-<run-tag>
• repo-root run artifacts under .omx/logs/autoresearch/<run-id>/

Repo-root state responsibilities:

• .omx/state/autoresearch-state.json = active-run pointer/lock only
• .omx/logs/autoresearch/<run-id>/manifest.json = authoritative per-run state
• .omx/logs/autoresearch/<run-id>/candidate.json = candidate handoff from the just-finished Codex session
• .omx/logs/autoresearch/<run-id>/iteration-ledger.json = durable iteration history
• .omx/logs/autoresearch/<run-id>/latest-evaluator-result.json = latest evaluator output

Worktree-local state responsibilities:

• results.tsv
• optional evaluator logs such as run.log
• these runtime-generated files must be excluded via worktree-local .git/info/exclude

Candidate artifact Copy Chapter

The launched session must write repo-root candidate.json with:

• status: candidate | noop | abort | interrupted
• candidate_commit: string or null
• base_commit: string
• description: string
• notes: string[]
• created_at: ISO timestamp

Integrity rules:

• status=candidate requires a non-null candidate_commit
• candidate_commit must resolve in git and match the worktree HEAD commit on exit
• base_commit must resolve in git and match the supervisor-provided last_kept_commit

Supervisor behavior:

• candidate → run evaluator, classify keep/discard/ambiguous/error, update manifest/ledger/results, reset if discarded
• noop → log noop iteration and continue by default
• abort → stop run without reset
• interrupted → if dirty, stop for operator intervention; if clean, log interrupted/noop style outcome

Decision policy Copy Chapter

• Baseline row is always recorded.
• pass=false => discard.
• evaluator error/crash => discard.
• keep_policy=score_improvement => keep only when pass=true and score improves over last kept score; pass without comparable score is ambiguous and discarded.
• keep_policy=pass_only => any pass=true candidate is kept.
• Discard / ambiguous / error paths must reset to the last kept commit.

Resume Copy Chapter

--resume <run-id> must fail with actionable errors when:

• manifest is missing
• referenced worktree is missing
• worktree is dirty outside allowlisted runtime artifacts
• manifest is terminal

Successful resume continues from the last kept commit and existing results history.

Iteration handoff context Copy Chapter

Each launched worker session receives a supervisor-written instruction snapshot including:

• current iteration number
• baseline commit
• last kept commit
• last kept score when known
• previous iteration outcome
• bounded recent ledger summary
• keep policy

Verification targets Copy Chapter

Parity-aligned implementation should prove:

1. fresh launches create distinct run-tagged lanes
2. repo-root active-run lock rejects concurrent launches
3. candidate handoff artifact drives keep/discard/reset decisions
4. discarded candidates reset to last_kept_commit
5. --resume <run-id> reloads authoritative manifest/worktree state
6. README/help/contracts describe the thin-supervisor parity loop

File: docs/contracts/autoresearch-command-review.md Copy Chapter

`omx autoresearch` Full-Parity Review Notes

Date: 2026-03-14
Reviewer lane: worker-3

Scope reviewed Copy Chapter

Compared the implementation and operator-facing docs against:

• .omx/plans/prd-autoresearch-full-parity.md
• .omx/plans/test-spec-autoresearch-full-parity.md

Reviewed code and docs:

• src/cli/autoresearch.ts
• src/autoresearch/contracts.ts
• src/autoresearch/runtime.ts
• src/team/worktree.ts
• src/modes/base.ts
• README.md
• docs/contracts/autoresearch-command-contract.md
• focused autoresearch tests under src/**/__tests__

Current status Copy Chapter

Status: parity-critical behavior appears implemented and the previously noted shared help/test wording mismatch is now resolved.

The branch now matches the PRD/test-spec shape much more closely than the earlier scaffold review:

• omx autoresearch exposes both fresh launch and --resume <run-id> flows.
• the runtime owns a thin-supervisor loop boundary via repo-root candidate handoff + post-session evaluator decisions.
• repo-root active-run locking and authoritative per-run manifests are present.
• fresh launches create run-tagged autoresearch lanes instead of silently reusing one long-lived lane.
• docs/help/contracts describe keep/discard/reset semantics instead of the earlier v1 scaffold.

Verified evidence Copy Chapter

Build Copy Section

• npm run build → PASS

Focused tests Copy Section

• node --test dist/autoresearch/__tests__/runtime.test.js dist/cli/__tests__/autoresearch.test.js dist/cli/__tests__/index.test.js dist/cli/__tests__/nested-help-routing.test.js dist/team/__tests__/worktree.test.js dist/modes/__tests__/base-autoresearch-contract.test.js → PASS
• node --test dist/cli/__tests__/session-search-help.test.js → PASS

Code/doc alignment observed Copy Section

• CLI help documents fresh launch + --resume <run-id>: src/cli/autoresearch.ts
• top-level help advertises thin-supervisor parity semantics: src/cli/index.ts, src/compat/fixtures/help.stdout.txt
• README now explains baseline seeding, repo-root per-run artifacts, candidate handoff, keep/discard/reset, relaunch loop, and resume behavior: README.md
• contract doc now defines run-tagged lanes, repo-root authority split, candidate artifact schema, decision policy, and resume failure conditions: docs/contracts/autoresearch-command-contract.md
• runtime implements active-run lock, per-run manifest files, allowlisted runtime excludes, candidate parsing, evaluator-backed decisions, reset-to-last-kept behavior, and resume validation: src/autoresearch/runtime.ts
• worktree planning test locks run-tagged autoresearch branch/path naming: src/team/__tests__/worktree.test.ts

Parity checklist Copy Chapter

1. Thin-supervisor iteration model Copy Section

Pass.

• buildAutoresearchInstructions() tells the launched Codex session to perform exactly one experiment cycle and write the candidate artifact before exit.
• runAutoresearchLoop() relaunches Codex after processAutoresearchCandidate() unless the run aborts/errors.

2. Repo-root state authority Copy Section

Pass.

• repo-root active-run lock lives at .omx/state/autoresearch-state.json.
• per-run manifest, candidate, ledger, and latest evaluator files live under .omx/logs/autoresearch/<run-id>/.
• worktree-local runtime artifacts are limited to results.tsv and allowlisted logs.

3. Fresh-run semantics Copy Section

Pass.

• fresh launches compute a run tag and plan autoresearch/<mission-slug>/<run-tag> plus autoresearch-<mission-slug>-<run-tag>.
• focused worktree coverage now asserts run-tagged branch/path naming.

4. Resume contract Copy Section

Pass.

• CLI parses --resume <run-id>.
• runtime rejects missing manifest, missing worktree, dirty worktree, and terminal runs.

5. Keep/discard/reset decision policy Copy Section

Pass.

• baseline row is seeded.
• evaluator failure/error discards.
• pass_only keeps any pass.
• score_improvement requires comparable numeric scores and improvement; otherwise ambiguous/discard.
• discard paths reset to last_kept_commit.

6. Docs/help/contracts alignment Copy Section

Pass.

• README, command help, top-level help, fixture help text, and the contract doc now describe the parity loop rather than a one-shot bootstrap scaffold.
• Shared help/test wording now matches the thin-supervisor parity wording.

Remaining review notes / risks Copy Chapter

1. runAutoresearchLoop() currently reads the run id back from the manifest file via execFileSync('cat', ...) + JSON.parse(...) on each iteration. That works, but it is a slightly awkward implementation detail and could be simplified to avoid shelling out to cat.
2. Focused tests cover the main parity surfaces, but there is still room for broader runtime coverage around noop, abort, interrupted, and explicit pass_only policy branches if the lead wants even tighter semantic locking.
3. I verified focused parity coverage and build status, not the entire repository-wide test suite/lint suite.

Reviewer conclusion Copy Chapter

This lane no longer looks like the earlier v1 scaffold. The reviewed implementation and docs now appear largely consistent with the requested thin-supervisor autoresearch parity model; the previously noted shared top-level help/test wording mismatch is resolved; remaining follow-ups are optional cleanup/coverage improvements.

File: docs/contracts/autoresearch-ux-deep-interview-review.md Copy Chapter

`omx autoresearch` deep-interview UX review notes

Date: 2026-03-17
Reviewer lane: worker-3

Scope reviewed Copy Chapter

Compared the current implementation and operator-facing docs against:

• .omx/plans/prd-autoresearch-ux-deep-interview.md
• .omx/plans/test-spec-autoresearch-ux-deep-interview.md

Reviewed files:

• src/cli/autoresearch.ts
• src/cli/autoresearch-guided.ts
• src/cli/__tests__/autoresearch-guided.test.ts
• src/cli/__tests__/autoresearch.test.ts
• skills/deep-interview/SKILL.md
• README.md
• docs/contracts/autoresearch-command-contract.md
• in-progress contract-test delta from worker-2: src/hooks/__tests__/deep-interview-contract.test.ts

Current status Copy Chapter

Status: the PRD/test-spec behavior is not implemented on the reviewed branch yet.

Current code still reflects the older guided-init flow:

• omx autoresearch with no args enters guidedAutoresearchSetup() and immediately asks for a raw evaluator command.
• bare init still routes into that same guided path instead of an explicit novice compatibility bridge.
• there is no autoresearch-specific intake module, no canonical .omx/specs/deep-interview-autoresearch-{slug}.md artifact, and no confirm/refine launch gate.
• launch still happens immediately after guided setup returns.
• README/help/contract docs still describe the thin-supervisor runtime, but not the new novice deep-interview intake surface from this PRD.

Evidence observed Copy Chapter

Code-path findings Copy Section

• src/cli/autoresearch.ts
  • parseAutoresearchArgs() only recognizes no-arg guided mode, init, --resume, and <mission-dir>.
  • top-level --topic/--evaluator/--keep-policy/--slug seeded novice flags are not routed.
  • guided/init flows still call spawnAutoresearchTmux() immediately after mission creation.
• src/cli/autoresearch-guided.ts
  • guidedAutoresearchSetup() still prompts directly for Evaluator command.
  • no placeholder/readiness rejection exists beyond parseSandboxContract().
  • no draft artifact is written under .omx/specs/.
• skills/deep-interview/SKILL.md
  • the generic execution bridge exists, but the autoresearch specialization section required by the PRD is absent on this branch.

Test/doc alignment findings Copy Section

• src/cli/__tests__/autoresearch-guided.test.ts
  • covers mission/scaffold creation and flag parsing for the older init/guided flow only.
• src/cli/__tests__/autoresearch.test.ts
  • still asserts the older omx autoresearch init [--topic ...] help surface and non-interactive mission-dir is required failure.
• worker-2 has an in-progress test addition that correctly starts locking the expected deep-interview specialization text in src/hooks/__tests__/deep-interview-contract.test.ts.

PRD checklist assessment Copy Chapter

1. Vague-goal novice intake without raw evaluator knowledge Copy Section

Fail on current branch.
The first guided prompt still asks for a concrete evaluator shell command.

2. Autoresearch-specific deep-interview/refinement bridge Copy Section

Fail on current branch.
No autoresearch-specific refinement loop or seeded novice bridge exists.

3. Canonical draft artifact at `.omx/specs/deep-interview-autoresearch-{slug}.md` Copy Section

Fail on current branch.
No .omx/specs/ draft artifact is generated.

4. Explicit `refine further` vs `launch` confirmation boundary Copy Section

Fail on current branch.
Guided setup returns launch-ready mission data and tmux launch happens immediately.

5. Placeholder evaluator rejection before launch Copy Section

Fail on current branch.
There is no blocked-pattern gate for placeholder evaluator commands.

6. Top-level seeded novice flags (`--topic`, `--evaluator`, `--keep-policy`, `--slug`) Copy Section

Fail on current branch.
Those flags are not accepted at top level; only init parses them today.

7. Expert flows preserved (``, `init --flags`, `--resume`) Copy Section

Pass on current branch.
Existing expert/runtime flows remain intact.

8. Bare `omx autoresearch init` documented as novice alias Copy Section

Fail on current branch.
Bare init is routed into guided mode, but help/docs do not explain the compatibility semantics required by the PRD.

9. Non-interactive no-arg failure preserved Copy Section

Pass on current branch.
The TTY guard still rejects no-arg non-interactive invocation.

10. Regression coverage for interview/draft/confirm path Copy Section

Fail on current branch.
Those tests are not present yet.

Documentation follow-ups once implementation lands Copy Chapter

1. Update README.md with the new novice entry surfaces:
   • omx autoresearch as a deep-interview-style refinement flow
   • top-level seeded novice flags
   • explicit confirm-before-launch behavior
2. Update docs/contracts/autoresearch-command-contract.md to add:
   • canonical draft artifact path
   • launch-readiness placeholder rejection rules
   • confirm/refine bridge semantics
3. Extend skills/deep-interview/SKILL.md with the PRD-required Autoresearch specialization section and required artifact headings.
4. Keep help text explicit about the split between novice refinement mode and expert init --flags / <mission-dir> / --resume flows.

Reviewer conclusion Copy Chapter

This review lane can confirm the current branch preserves existing autoresearch runtime behavior, but it does not yet satisfy the deep-interview UX enhancement PRD. The most useful near-term review output is therefore this baseline gap assessment plus the documentation checklist above; once worker-1 lands the implementation, this file should be refreshed with a final pass/fail review and verification evidence.

File: docs/contracts/explicit-terminal-stop-model.md Copy Chapter

Explicit Terminal Stop Model Contract

Status: approved migration contract for runtime, hooks, MCP state, and prompt/documentation surfaces.

Purpose Copy Chapter

This document locks the canonical terminal stop vocabulary for active OMX workflows.
It exists so runtime code, native/fallback Stop handlers, MCP state, and user-facing handoff guidance all describe the same end-of-turn semantics.

Canonical terminal lifecycle outcomes Copy Chapter

These are the only canonical user-facing terminal lifecycle outcomes for the explicit stop model:

askuserQuestion and userinterlude are intentionally distinct:

• askuserQuestion is model-originated and should normally be backed by omx question or equivalent machine-readable question metadata.
• userinterlude is user-originated interruption/stop intent.

Legacy compatibility rules Copy Chapter

Legacy values may still appear in persisted state during migration, but they are compatibility inputs, not the public canonical vocabulary.

`cancelled` policy Copy Section

cancelled remains valid for legacy administrative state, teardown, or backward-compatible reads.
It is not a canonical user-facing terminal lifecycle outcome in the explicit stop model.
Docs, prompts, and runtime summaries should prefer one of:

• finished
• blocked
• failed
• userinterlude
• askuserQuestion

State / MCP precedence Copy Chapter

Terminal lifecycle metadata should be interpreted in this order:

1. a dedicated canonical lifecycle field such as lifecycle_outcome
2. legacy run_outcome compatibility data
3. fallback inference from current_phase, question metadata, and other persisted context

Notes:

• current_phase and lifecycle outcome are related but not identical. A workflow can keep legacy phase names while still exposing canonical lifecycle metadata.
• If both canonical lifecycle metadata and legacy run_outcome are present, the canonical lifecycle field wins.
• run_outcome should be treated as a compatibility read/write surface during migration, not as the long-term public contract.

Stop / watcher interpretation rules Copy Chapter

Stop readers, native hooks, and fallback watchers should prefer explicit lifecycle metadata over assistant prose heuristics.
During migration they should:

• honor canonical finished, blocked, failed, userinterlude, and askuserQuestion metadata first
• keep honoring legacy blocked_on_user as a suppress-continuation compatibility signal
• avoid treating optional assistant prose as the semantic owner of lifecycle state
• keep cancelled internal legacy-only when translating to user-facing lifecycle summaries

Active workflow terminal handoff contract Copy Chapter

When an active workflow produces a terminal user-facing message, the handoff should be explicit and structured.
The terminal summary should include:

1. Outcome — one explicit lifecycle label
2. Evidence — concrete verification output, failure evidence, or the missing dependency/question
3. Artifacts / state — changed files, saved artifacts, or recorded question identifiers when relevant
4. Handoff — the exact next owner or required answer, without optional permission-seeking phrasing

Forbidden terminal pattern Copy Section

Do not end active workflow terminal handoffs with optional follow-up softeners such as:

• If you want, I can ...
• If you'd like, I can ...
• Would you like me to continue?

Those phrases make the lifecycle state ambiguous. The terminal outcome should already explain whether the run finished, failed, blocked, entered user interlude, or is waiting on a required user question.

Non-goals Copy Chapter

This contract does not require every legacy internal phase name to be renamed immediately.
It does require every migrated surface to expose and prefer the canonical terminal lifecycle concepts above.