aha-codex-omx

What This Mode Activates

Agent-facing, brain-led capability orchestration for Codex CLI with oh-my-codex (OMX) installed. This skill enables the agent to discover, select, combine, and reselect available capability surfaces (native runtime, enhancement layer, skill, MCP, command, subagent, worktree) to build the lowest-sufficient task-lifecycle capability route for the task.

For non-trivial work, keep the current Codex session as the decision maker and final integrator: own the goal, constraints, decomposition, permission checks, integration, acceptance, verification, and final answer. Run a delegation-first scan before equivalent inline work. Prefer bounded Codex native subagents and available OMX lanes when they provide better evidence or context economy; do not delegate merely to create fan-out.

Pre-Check

Run detection at three levels. Do not collapse a partial failure into a full fallback — only re-orchestrate the specific surface that is unavailable.

1. L1 Binary installed: Verify OMX binary is installed: omx --version
2. L2 CLI surface available: Verify core OMX CLI commands work: omx list, omx exec --help. If L2 passes, the agent may use OMX skill enumeration, exec delegation, and sparkshell throughout the session.
3. L3 Interactive bridge available: Verify tmux-attached interactive bridge if the task needs omx question or team/question orchestration. Check whether a tmux session is attached. If L3 fails, skip omx question and team bridge features, but continue using L2 CLI surfaces.
4. Confirm runtime family: Codex (not OpenCode, not oh-my-openagent (OMO))
5. Wrong-runtime guard: If you are in OpenCode with OMO, use aha-opencode-omo instead. This skill is for Codex+OMX only.
6. Fallback rule: If L1 fails (OMX binary not installed), proceed with native Codex capabilities and state the limitation transparently. If L1 passes but L2 or L3 fail, do not fall back to native Codex — only skip the specific unavailable OMX surface and continue using available OMX CLI surfaces.

Capability Discovery

Run discovery on every orchestration pass. Capability surfaces change across sessions, projects, versions, and permission modes.

1. Primary tools: detect native subagent roles plus omx list and only the OMX feature surfaces needed for this task. Do not treat a binary or one feature as proof that all roles, models, or interactive bridges are available.
2. Delegation-first scan: mandatory for non-trivial work before equivalent inline work; identify bounded units suitable for OMX/native subagents, background lanes, review lanes, or QA lanes; delegate suitable units, but keep urgent blockers, tightly coupled integration, secret/session boundaries, and write-conflict risks in the primary session; if no unit is delegated, state the concrete reason when it affects collaboration shape or evidence
3. Secondary scan: check for configured MCPs, available commands, validators, and native subagent surfaces
4. Permission envelope: determine read-only vs write, external-write, network, approval policy, and destructive-action limits

Codex Delegation Map

Resolve these roles from the current runtime before dispatch; use the closest available role or keep the documented exception inline. Do not hardcode model names: the runtime resolves the model for the selected role.

OMX team, review, QA, or persistent modes are optional feature-level lanes; detect the specific feature before use. The primary session remains the only final integrator. Refer to the shared v1.1 delegation contract for return evidence, direct-work exceptions, and tool-composition limits.

See ./references/capability-orchestration.md for the 7-field discovery schema.

If discovery fails, transparently disclose, fall back to built-in reference knowledge, mark it as possibly outdated, and request current capability information only when needed. Do not overclaim actual availability.

Do NOT Use This Mode For

• Trivial single-step edits or read-only Q&A where native Codex is sufficient
• Tasks that require explicit operator confirmation at every step
• Cases where delegation would expose secrets/session material, create unbounded write conflicts, or add coordination cost without improving outcome evidence
• Environments where OMX is not installed and cannot be installed

Rollback / Deactivation

To deactivate: stop using OMX-specific capabilities and re-orchestrate to native Codex. No persistent state is maintained by this skill. Partial deactivation is valid: if only the interactive bridge is unavailable, deactivate bridge features only and keep using OMX CLI surfaces.

Reference

• Read ./references/capability-orchestration.md before applying orchestration logic. It is the source of truth for orchestration steps, transparency, re-orchestration, out-of-session, cost awareness, and the 7-field discovery schema.

Source & Upgrade

• Repository: https://github.com/its-How/aha-orch
• Note: This skill is part of the aha-orch multi-skill repository (contains aha-codex-omx, aha-opencode-omo, aha-orch-xx, aha-claudecode-omc).
• Upgrade: Run git pull in the aha-orch repo, or re-run npx skills add its-how/aha-orch to get the latest version.
• Uninstall: Delete the skill directory (e.g., aha-codex-omx/) from your skills path.