oh-my-codex-cli 0.1.0

package/docs/ALIGNMENT.md

@@ -0,0 +1,40 @@
+# Alignment Status: oh-my-codex vs oh-my-claudecode
+
+This document tracks what is aligned, what is partially aligned, and what cannot be aligned due to Codex architecture limits.
+
+## ✅ Aligned (Implemented)
+
+- **Skills system**: All workflows are in `.codex/skills/` and ready for Codex.
+- **Native multi-agent orchestration**: Core skills use `spawn_agent`/`send_input`/`wait` patterns.
+- **MCP configuration**: `omcodex setup` writes Codex MCP config blocks (`omcodex_state`, `omcodex_memory`, `omcodex_trace`).
+- **Docs & entrypoints**: `README.md`, `docs/CODEX.md`, `AGENTS.md` are Codex-first.
+- **Event-driven notify extension**: `omcodex notify` provides additive plugin-style extensions.
+- **Role prompt install path**: `omcodex setup` installs prompt catalog into `.codex/prompts`.
+
+## ⚠️ Partially Aligned (Codex-Compatible Workarounds)
+
+- **Slash command UX**: Replaced by `$skill` or `skill:` invocation.
+- **MCP management UX**: Scripted config generation + Codex CLI MCP commands.
+
+## ❌ Not Alignable (Codex Architectural Limits)
+
+- **Claude Code plugin system** (`/plugin`, plugin cache, plugin lifecycle)
+- **Execution interception lifecycle** (PreToolUse/PostToolUse style interception)
+- **HUD statusline** (Claude Code-specific terminal integration)
+- **Native subagent spawning** (`Task(subagent_type=...)`)
+
+## ✅ Clarification
+
+- Codex supports event notifications via `notify`.
+- This can be extended with notify plugins, but it remains event-driven and cannot intercept tool execution.
+
+## Legacy/Claude-Only Areas
+
+These remain in the repo for reference but are not used by Codex:
+- `commands/` (Claude slash commands)
+- `docs/CLAUDE.md` and other Claude-oriented docs
+
+## Recommended Usage (Codex)
+
+- Use **skills**: `$autopilot`, `$ralph`, `$ultraqa`, or `autopilot:`
+- Enable MCP with `scripts/generate-codex-mcp-config.sh`

package/docs/CODEX.md

@@ -0,0 +1,133 @@
+# oh-my-codex for Codex CLI
+
+This repo adapts the oh-my-claudecode workflows to **OpenAI Codex CLI** by packaging them as **Codex skills**.
+
+## Install
+
+### Option A: Global (recommended)
+```bash
+./scripts/install-codex.sh
+```
+
+Force overwrite:
+```bash
+./scripts/install-codex-force.sh
+```
+
+Incremental (skip existing files):
+```bash
+./scripts/install-codex-incremental.sh
+```
+
+### Option B: Repo-local
+```bash
+cp -R .agent/skills /path/to/your/repo/.codex/
+```
+
+Codex will automatically load skills from both locations.
+
+Note: The installer prefers `.agent/skills` when present, and falls back to `.codex/skills`.
+
+## Enable Codex Plan Mode (0.9+)
+
+Codex supports native plan mode when you enable collaboration modes in `config.toml`:
+```
+[features]
+collaboration_modes = true
+```
+
+Use our script to set it automatically:
+```bash
+./scripts/generate-codex-mcp-config.sh --enable-collab
+```
+
+## MCP Setup (Codex)
+
+Codex loads MCP servers from `~/.codex/config.toml` or a repo-local config.
+
+Generate a starter config with common servers:
+```bash
+./scripts/generate-codex-mcp-config.sh
+```
+
+To write a repo-local config:
+```bash
+./scripts/generate-codex-mcp-config.sh --project
+```
+
+You can also manage MCP servers via the Codex CLI (recommended):
+```bash
+codex mcp add
+codex mcp list
+```
+
+## Supported vs Unsupported Features
+
+### Supported
+- Execution modes: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline, ecomode
+- Planning, review, QA, research, and code-quality workflows
+- Skill learning and local skill management
+
+### Not Supported (Codex limitations)
+- Claude Code marketplace plugin install
+- Claude Code-style execution interception lifecycle (pre/post tool interception)
+- Claude Code-specific CLI commands
+- Claude Code plugin cache locations
+
+Codex does support event notifications via `notify`. In this project, all extensibility is event-driven notify dispatch, not execution interception.
+
+## Notify Extension Workflow
+
+```bash
+omcodex notify init
+omcodex notify status
+omcodex notify validate
+OMX_NOTIFY_PLUGINS=1 omcodex notify test
+```
+
+Plugins are discovered from:
+
+- `.omcodex/notify/*.mjs` (primary)
+- `.omcodex/notify-plugins/*.mjs` (legacy compatibility)
+
+## Skills Directory
+
+Global:
+```
+~/.codex/skills/<skill-name>/SKILL.md
+```
+
+Repo:
+```
+<repo>/.agent/skills/<skill-name>/SKILL.md
+```
+
+## Prompts Directory
+
+Global:
+```
+~/.codex/prompts/<prompt-name>.md
+```
+
+Repo:
+```
+<repo>/.codex/prompts/<prompt-name>.md
+```
+
+## Alignment Status
+
+See `docs/ALIGNMENT.md` for a full checklist of what matches oh-my-claudecode and what cannot be aligned in Codex.
+
+## Troubleshooting
+
+If a skill doesn’t seem to activate:
+1. Confirm `~/.codex/skills/<skill>/SKILL.md` exists.
+2. Try explicit invocation: `$skill-name ...`
+3. Make sure your Codex session is running in a repo with `.codex/skills` (if using repo-local install).
+
+## New Productivity Commands
+
+- Route task to best-fit skills:
+  - `omcodex route "fix auth lint + tests"`
+- Start team state with auto phase advancement:
+  - `omcodex team start "ship oauth login" --auto`

package/docs/NOTIFY.md

@@ -0,0 +1,81 @@
+# Notify Extension (Custom Plugins)
+
+`oh-my-codex` supports additive notify plugins under `.omcodex/notify/*.mjs`.
+
+## Quick Start
+
+```bash
+omcodex notify init
+omcodex notify status
+omcodex notify validate
+OMX_NOTIFY_PLUGINS=1 omcodex notify test
+```
+
+Primary plugin directory:
+
+- `.omcodex/notify/`
+
+Legacy compatibility directory:
+
+- `.omcodex/notify-plugins/`
+
+## Enablement Model
+
+Plugins are disabled by default.
+
+Enable dispatch explicitly:
+
+```bash
+export OMX_NOTIFY_PLUGINS=1
+```
+
+Optional timeout tuning (default `1500ms`):
+
+```bash
+export OMX_NOTIFY_PLUGIN_TIMEOUT_MS=1500
+```
+
+## Supported Events
+
+- `turn-complete`
+- `session-start`
+- `session-end`
+- `session-idle`
+- `needs-input`
+- `pre-tool-use`
+- `post-tool-use`
+
+## Team Auto-Advance Integration
+
+When team state is started with auto mode:
+
+```bash
+omcodex team start "your task" --auto
+```
+
+notify events can advance team phases automatically:
+
+- `turn-complete`: `team-plan -> team-prd -> team-exec`, and can complete `team-verify`
+- `post-tool-use`: can move `team-exec -> team-verify`
+- failure-like messages in notify context can trigger `team-fix`
+
+## Plugin Contract
+
+Each plugin must export:
+
+```js
+export async function onNotifyEvent(event, sdk) {
+  // handle event
+}
+```
+
+SDK surface includes:
+
+- `sdk.log.info|warn|error(...)`
+- `sdk.state.read|write|delete(...)`
+
+## Logs
+
+Dispatch and plugin logs are written to:
+
+- `.omcodex/logs/notify-YYYY-MM-DD.jsonl`

package/docs/SKILL_GOVERNANCE.md

@@ -0,0 +1,72 @@
+# Skill Governance
+
+This document defines the governance baseline for skills in this repository.
+
+## Objectives
+
+1. Keep skill instructions executable in current Codex CLI behavior.
+2. Prevent legacy command drift from Claude-era syntax.
+3. Track technical debt explicitly when migration cannot be completed in one pass.
+
+## Governance Layers
+
+1. Admission: Require valid `SKILL.md` frontmatter (`name`, `description`) and clear trigger semantics.
+2. Execution safety: Block instructions that imply unavailable runtime features.
+3. Quality gates: Enforce pre-merge checks through repository scripts.
+4. Change control: Track exceptions in a reviewed allowlist.
+5. Continuous cleanup: Burn down allowlisted debt skill-by-skill.
+
+## Automated Checks
+
+Run:
+
+```bash
+npm run governance:skills
+npm run governance:skills:llm
+npm run eval:skills
+```
+
+The checker currently enforces:
+
+- Blockers:
+  - Legacy slash invocation (`Run: /verify`)
+  - Plugin-specific runtime command (`cc --plugin-dir`)
+  - Legacy task API syntax (`Task(...)` with agent/task parameters)
+- Controlled debt:
+  - `Task(subagent_type=...)` references are allowed only when explicitly listed in `.governance/skill-lint.allowlist`
+  - Slash command references are allowed only for files explicitly listed in `.governance/skill-lint.allowlist`
+
+## LLM Governance Gate
+
+`npm run governance:skills:llm` runs a second-pass governance audit:
+
+- `--mode=auto` (default): uses OpenAI audit when `OPENAI_API_KEY` is set, otherwise uses heuristic fallback
+- Flags high-severity blockers for non-Codex runtime instructions and execution ambiguity
+- Writes report to `.omcodex/reports/skill-llm-governance-latest.json`
+- Supports controlled debt via `.governance/skill-llm.allowlist` (`<rule_id>:<skill_name>`)
+
+## Skill Eval Harness
+
+`npm run eval:skills` scores each skill document for execution quality:
+
+- Frontmatter completeness
+- Invocation clarity
+- Workflow structure
+- Codex compatibility checks
+
+Reports are written to:
+
+- `.omcodex/reports/skill-eval-latest.json`
+- `.omcodex/reports/skill-eval-latest.md`
+
+## Debt Policy
+
+- New debt is blocked by default.
+- Existing debt is recorded in `.governance/skill-lint.allowlist`.
+- Removing debt entries must happen in the same change that migrates the corresponding skill.
+
+## Migration Priority
+
+1. Remove runtime-invalid instructions (blockers).
+2. Replace pseudo-subagent API usage with Codex-compatible role protocols.
+3. Remove stale plugin-only wording when equivalent Codex-native guidance exists.

package/docs/SKILL_GOVERNANCE_FRAMEWORK.md

@@ -0,0 +1,182 @@
+# Skill Governance Framework (Cross-Project)
+
+This framework is designed for repositories like `oh-my-codex` and `oh-my-antigravity` that maintain skill packs for AI-assisted development.
+
+## 1. Governance Goals
+
+1. Keep every skill executable in the current runtime (no stale syntax, no unavailable APIs).
+2. Keep quality stable as skill count grows (consistent structure, clear boundaries, testable instructions).
+3. Keep maintenance cost under control (ownership, debt tracking, measurable cleanup velocity).
+4. Keep user trust high (safe defaults, explicit risk controls, predictable behavior).
+
+## 2. Scope and Object Model
+
+Governance applies to:
+- Skill definitions (`SKILL.md` and supporting assets)
+- Installation/distribution scripts
+- Governance scripts, allowlists, and policy docs
+
+Skill classes:
+- Core skills: high-frequency, cross-project foundation (planning, review, verify, tdd)
+- Domain skills: project/platform specific (for example editor, electron, workflow)
+- Experimental skills: incubating, low-trust, fast iteration
+- Deprecated skills: retained only for migration windows
+
+## 3. Skill Contract (Minimum Standard)
+
+Every skill must satisfy:
+1. Metadata contract: `name`, `description`, explicit trigger guidance.
+2. Runtime contract: examples runnable in target CLI/runtime only.
+3. Boundary contract: clear "when to use / when not to use".
+4. Dependency contract: external tools/paths declared.
+5. Output contract: expected output format and completion criteria.
+
+## 4. Lifecycle and Gates
+
+### 4.1 Lifecycle
+
+1. Proposal: problem statement + overlap check.
+2. Draft: create skill with contract sections.
+3. Validation: governance checks + dry-run examples.
+4. Release: installable and documented.
+5. Observe: usage, failures, confusion signals.
+6. Evolve or retire: merge, split, deprecate, archive.
+
+### 4.2 Quality Gates
+
+Required pre-merge gates:
+1. `npm run governance:skills` passes.
+2. No new allowlist debt unless explicitly approved.
+3. Backward-compatibility note for renamed/retired skills.
+4. At least one runnable invocation example per skill.
+
+Recommended gates:
+1. Duplicate-intent detection (same trigger intent across multiple skills).
+2. Link integrity check (paths/scripts in skill docs).
+3. Install smoke test (`install-codex*.sh` equivalent for target project).
+
+## 5. Debt and Compatibility Strategy
+
+Debt types:
+- Syntax debt: legacy command/task syntax no longer supported.
+- Semantic debt: unclear role boundaries and overlapping responsibilities.
+- Tooling debt: references to unavailable plugins/commands.
+
+Policy:
+1. New debt blocked by default.
+2. Legacy debt recorded in allowlist with owner and target removal date.
+3. Removing debt and allowlist entries happens in the same change.
+4. High-risk debt (runtime-invalid instructions) is P0 and must be removed first.
+
+## 6. Topology and Duplication Control
+
+Use a 4-layer topology to avoid skill sprawl:
+1. Foundation layer: universal skills (plan/review/verify/tdd).
+2. Domain layer: project-specific capabilities.
+3. Orchestration layer: sequencing/composition (pipeline/swarm-like skills).
+4. Governance layer: quality, checks, migration, release.
+
+De-dup rules:
+1. One canonical skill per intent.
+2. Variants become playbooks inside canonical skill, not separate top-level skills.
+3. Keep aliases only during migration windows; set sunset date.
+
+## 7. Ownership Model (RACI)
+
+- Maintainer (A): final decision on merge/retire.
+- Skill owner (R): authoring, bugfixes, compatibility.
+- Reviewer (R/C): quality and risk review.
+- Consumers (C): feedback on usability and ambiguity.
+
+Each skill should declare:
+- Owner
+- Last reviewed date
+- Maturity (`core`, `domain`, `experimental`, `deprecated`)
+
+## 8. Metrics and SLOs
+
+Track monthly:
+1. Governance pass rate (`governance:skills` success in PRs).
+2. Debt burndown (allowlist entries net change).
+3. Duplication ratio (skills mapped to same intent cluster).
+4. Time-to-fix for broken skills.
+5. Deprecation lead time and completion rate.
+
+Suggested SLOs:
+- P0 governance breakage fixed within 24h.
+- No net-new unresolved allowlist debt for 2 consecutive cycles.
+- Duplicate-intent skills reduced cycle over cycle.
+
+## 9. Release and Change Management
+
+For every skill-facing release:
+1. Changelog section: added/changed/deprecated/removed skills.
+2. Migration notes: old -> new invocation mapping.
+3. Install verification: local and global install checks.
+4. Rollback path: previous known-good tag.
+
+## 10. Cross-Project Federation (Codex + Antigravity)
+
+Recommended model:
+1. Shared governance baseline:
+   - `docs/SKILL_GOVERNANCE_FRAMEWORK.md` (this file)
+   - same governance checker philosophy
+2. Project overlays:
+   - `docs/SKILL_GOVERNANCE.<project>.md` for project-specific exceptions
+3. Shared taxonomy:
+   - same maturity labels and lifecycle states
+4. Shared migration language:
+   - consistent deprecation and replacement templates
+
+## 11. Implementation Blueprint (Practical)
+
+For each project repository:
+1. Add governance docs:
+   - `docs/SKILL_GOVERNANCE.md` (project policy)
+   - `docs/SKILL_GOVERNANCE_FRAMEWORK.md` (shared framework)
+2. Add governance machinery:
+   - checker script (`scripts/check-skill-governance.sh`)
+   - allowlist (`.governance/skill-lint.allowlist`)
+   - package script (`governance:skills`)
+3. Add CI gate:
+   - run governance check on PRs touching skills.
+4. Add ownership metadata policy:
+   - owner + maturity + last-reviewed required in each skill.
+
+## 12. 30/60/90 Day Rollout Plan
+
+### Day 0-30
+
+1. Establish baseline checker and debt inventory.
+2. Freeze net-new debt.
+3. Classify all skills by maturity and owner.
+
+### Day 31-60
+
+1. Merge duplicate-intent skills into canonical tracks.
+2. Convert aliases to deprecation shims.
+3. Introduce monthly governance report.
+
+### Day 61-90
+
+1. Remove expired deprecated skills.
+2. Normalize cross-project taxonomy and templates.
+3. Enforce SLO-based review cadence.
+
+## 13. Definition of Done (Governance)
+
+A repository is considered "governed" when:
+1. Governance checks are mandatory and passing.
+2. Debt is explicit, owned, and burning down.
+3. Every active skill has a clear owner and maturity.
+4. Duplicate-intent skills are consolidated.
+5. Release notes include skill migration guidance.
+
+## 14. Quick Import Checklist for `oh-my-antigravity`
+
+1. Copy this file to `docs/SKILL_GOVERNANCE_FRAMEWORK.md`.
+2. Create `docs/SKILL_GOVERNANCE.md` with antigravity-specific runtime blockers.
+3. Port governance checker + allowlist + npm script.
+4. Run baseline scan and generate debt register.
+5. Start with P0 blockers, then duplicate-intent consolidation.
+

package/docs/SKILL_GOVERNANCE_FRAMEWORK.zh.md

@@ -0,0 +1,170 @@
+# Skill 治理框架（跨项目版）
+
+本框架用于 `oh-my-codex`、`oh-my-antigravity` 这类维护 Skill 体系的仓库，目标是“可执行、可演进、可度量”。
+
+## 1. 治理目标
+
+1. 保证 Skill 在当前运行时可执行（不含过期语法和不可用能力）。
+2. 保证规模增长后质量稳定（结构一致、边界清晰、可验证）。
+3. 控制维护成本（明确 owner、债务可见、持续清理）。
+4. 维持用户信任（默认安全、行为可预测、变更可迁移）。
+
+## 2. 治理对象与分类
+
+治理对象：
+- Skill 定义（`SKILL.md` + 配套资产）
+- 安装/分发脚本
+- 治理脚本、allowlist、治理文档
+
+Skill 分类：
+- `core`：高频基础能力（plan/review/verify/tdd）
+- `domain`：项目或平台专属能力
+- `experimental`：试验态能力
+- `deprecated`：迁移窗口保留能力
+
+## 3. Skill 最小契约
+
+每个 Skill 必须满足：
+1. 元数据契约：`name`、`description`、触发条件。
+2. 运行时契约：示例可在目标 CLI/运行时直接执行。
+3. 边界契约：明确“何时使用/何时不使用”。
+4. 依赖契约：外部工具、路径、前置条件可见。
+5. 输出契约：输出格式、完成标准明确。
+
+## 4. 生命周期与门禁
+
+生命周期：
+1. Proposal：问题定义 + 重复能力检查。
+2. Draft：按契约编写 Skill。
+3. Validation：治理检查 + 示例演练。
+4. Release：可安装、可文档化。
+5. Observe：收集使用与失败信号。
+6. Evolve/Retire：合并、拆分、废弃、归档。
+
+必过门禁（PR 前）：
+1. `npm run governance:skills` 通过。
+2. 不允许新增未审批债务。
+3. 重命名/下线必须给出迁移说明。
+4. 每个 Skill 至少一个可运行调用示例。
+
+推荐门禁：
+1. 重复意图检测（多 Skill 覆盖同一意图）。
+2. 文档链接/路径有效性检查。
+3. 安装冒烟验证（本地与全局安装）。
+
+## 5. 债务治理策略
+
+债务类型：
+- 语法债：旧命令/旧 API 语法
+- 语义债：边界不清、职责重叠
+- 工具债：引用不可用插件/命令
+
+治理规则：
+1. 新债务默认禁止。
+2. 存量债务进入 allowlist，必须有 owner 与清理目标时间。
+3. 清理代码与移除 allowlist 条目同一次提交完成。
+4. 运行时无效指令属于 P0，优先清除。
+
+## 6. 拓扑与去重
+
+采用四层拓扑：
+1. Foundation：通用基础层
+2. Domain：业务/平台层
+3. Orchestration：编排层
+4. Governance：治理层
+
+去重规则：
+1. 一个意图只保留一个 canonical skill。
+2. 变体写入 canonical skill 的 playbook，不新增顶层重复 skill。
+3. 别名仅用于迁移窗口，必须有 sunset 日期。
+
+## 7. 角色与责任（RACI）
+
+- Maintainer（A）：合并/下线最终责任
+- Skill Owner（R）：内容维护与兼容性
+- Reviewer（R/C）：质量与风险评审
+- Consumer（C）：可用性反馈
+
+每个 Skill 建议声明：
+- Owner
+- Last reviewed
+- Maturity（`core/domain/experimental/deprecated`）
+
+## 8. 指标与 SLO
+
+月度指标：
+1. 治理通过率（`governance:skills`）
+2. 债务净变化（allowlist burndown）
+3. 重复率（同意图多 skill）
+4. 失效 skill 修复时长
+5. 废弃迁移完成率
+
+建议 SLO：
+- P0 治理故障 24 小时内修复
+- 连续两个周期无净新增未解决债务
+- 重复意图技能数持续下降
+
+## 9. 发布与变更管理
+
+每次 Skill 相关发布必须包含：
+1. Changelog：新增/变更/废弃/移除
+2. 迁移说明：旧调用 -> 新调用映射
+3. 安装验证：本地与全局
+4. 回滚路径：可回退到上一个稳定 tag
+
+## 10. Codex 与 Antigravity 的联邦治理
+
+建议模型：
+1. 共享基线：统一使用本框架文档
+2. 项目叠加：各自维护 `docs/SKILL_GOVERNANCE.md`
+3. 共享分类法：统一 maturity 和生命周期状态
+4. 共享迁移语言：统一废弃与替代模板
+
+## 11. 落地蓝图（每个仓库都做）
+
+1. 文档：
+   - `docs/SKILL_GOVERNANCE_FRAMEWORK.md`
+   - `docs/SKILL_GOVERNANCE.md`
+2. 机制：
+   - `scripts/check-skill-governance.sh`
+   - `.governance/skill-lint.allowlist`
+   - `package.json` 中 `governance:skills`
+3. CI：
+   - 触达 skill 变更的 PR 必跑治理检查
+4. 元数据：
+   - owner + maturity + last-reviewed 策略
+
+## 12. 30/60/90 推进计划
+
+0-30 天：
+1. 建立基线检查与债务清单
+2. 冻结净新增债务
+3. 给全部 skill 标注 owner 与 maturity
+
+31-60 天：
+1. 合并重复意图 skill
+2. 别名降级为迁移 shim
+3. 形成月度治理报告
+
+61-90 天：
+1. 移除过期 deprecated skills
+2. 对齐跨仓库分类与模板
+3. 执行 SLO 驱动评审节奏
+
+## 13. 治理完成定义（DoD）
+
+满足以下条件即视为进入“受治理状态”：
+1. 治理检查强制且稳定通过
+2. 债务显式、有人负责、持续下降
+3. 每个活跃 skill 都有 owner 与 maturity
+4. 重复意图已完成收敛
+5. 发布说明包含迁移指引
+
+## 14. 导入 oh-my-antigravity 快速清单
+
+1. 复制本文件到 `docs/SKILL_GOVERNANCE_FRAMEWORK.md`。
+2. 编写 `docs/SKILL_GOVERNANCE.md`（填入 antigravity 运行时 blocker）。
+3. 迁移治理脚本 + allowlist + npm 命令。
+4. 跑基线扫描并建立债务台账。
+5. 按“P0 blocker -> 重复收敛”顺序执行。
+