oh-my-codex 0.7.5 → 0.8.0

package/README.vi.md

@@ -1,10 +1,59 @@
-# oh-my-codex (OMX) README tiếng Việt
+# oh-my-codex (OMX)
 
-> Tài liệu đầy đủ bằng tiếng Anh: [English README](./README.md).
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>Codex của bạn không đơn độc.</em>
+</p>
 
-OMX là lớp điều phối đa tác nhân cho OpenAI Codex CLI.
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-## Bắt đầu nhanh
+> **[Website](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[Documentation](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI Reference](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[Workflows](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+Lớp điều phối đa tác nhân cho [OpenAI Codex CLI](https://github.com/openai/codex).
+
+## Ngôn ngữ
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese)](./README.zh.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX biến Codex từ một tác nhân phiên đơn thành một hệ thống phối hợp với:
+- Role prompts (`/prompts:name`) cho các tác nhân chuyên biệt
+- Workflow skills (`$name`) cho các chế độ thực thi lặp lại
+- Điều phối đội ngũ trong tmux (`omx team`, `$team`)
+- Trạng thái bền vững và bộ nhớ qua máy chủ MCP
+
+## Tại sao chọn OMX
+
+Codex CLI mạnh mẽ cho các tác vụ trực tiếp. OMX thêm cấu trúc cho công việc lớn hơn:
+- Phân tách và thực thi theo giai đoạn (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- Trạng thái vòng đời chế độ bền vững (`.omx/state/`)
+- Bề mặt bộ nhớ và sổ ghi chú cho phiên làm việc dài
+- Điều khiển vận hành cho khởi chạy, xác minh và hủy bỏ
+
+OMX là một tiện ích bổ sung, không phải fork. Nó sử dụng các điểm mở rộng gốc của Codex.
+
+## Yêu cầu hệ thống
+
+- macOS hoặc Linux (Windows qua WSL2)
+- Node.js >= 20
+- Codex CLI đã cài đặt (`npm install -g @openai/codex`)
+- Xác thực Codex đã cấu hình
+
+## Bắt đầu nhanh (3 phút)
 
 ```bash
 npm install -g oh-my-codex
@@ -12,25 +61,254 @@ omx setup
 omx doctor
 ```
 
-## Tính năng chính
+Cấu hình khởi chạy khuyến nghị cho môi trường tin cậy:
 
-- Chạy tác nhân chuyên biệt với role prompt (`/prompts:name`)
-- Tự động hóa workflow lặp lại bằng skill (`$name`)
-- Điều phối đội ngũ trong tmux (`omx team`, `$team`)
-- Lưu trạng thái + bộ nhớ lâu dài qua MCP servers
+```bash
+omx --xhigh --madmax
+```
+
+## Mới trong v0.5.0
+
+- **Thiết lập nhận biết phạm vi** qua `omx setup --scope user|project` cho các chế độ cài đặt linh hoạt.
+- **Định tuyến Spark worker** qua `--spark` / `--madmax-spark` — worker của đội có thể sử dụng `gpt-5.3-codex-spark` mà không ép buộc model lãnh đạo.
+- **Hợp nhất danh mục** — loại bỏ các prompt không dùng nữa (`deep-executor`, `scientist`) và 9 skill không dùng nữa để có bề mặt gọn hơn.
+- **Mức độ chi tiết thông báo** cho kiểm soát chi tiết đầu ra CCNotifier.
+
+## Phiên đầu tiên
 
-## Lệnh thường dùng
+Trong Codex:
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+Từ terminal:
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## Mô hình cốt lõi
+
+OMX cài đặt và kết nối các lớp sau:
+
+```text
+User
+  -> Codex CLI
+    -> AGENTS.md (bộ não điều phối)
+    -> ~/.codex/prompts/*.md (danh mục prompt tác nhân)
+    -> ~/.agents/skills/*/SKILL.md (danh mục skill)
+    -> ~/.codex/config.toml (tính năng, thông báo, MCP)
+    -> .omx/ (trạng thái runtime, bộ nhớ, kế hoạch, nhật ký)
+```
+
+## Các lệnh chính
+
+```bash
+omx                # Khởi chạy Codex (+ HUD trong tmux khi có sẵn)
+omx setup          # Cài đặt prompt/skill/config theo phạm vi + dự án AGENTS.md/.omx
+omx doctor         # Chẩn đoán cài đặt/runtime
+omx doctor --team  # Chẩn đoán Team/swarm
+omx team ...       # Khởi động/trạng thái/tiếp tục/tắt worker tmux của đội
+omx status         # Hiển thị các chế độ đang hoạt động
+omx cancel         # Hủy các chế độ thực thi đang hoạt động
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...  # init|status|validate|test
+omx hooks ...      # init|status|validate|test (quy trình mở rộng plugin)
+omx hud ...        # --watch|--json|--preset
+omx help
+```
+
+## Mở rộng Hooks (Bề mặt bổ sung)
+
+OMX hiện bao gồm `omx hooks` cho scaffolding và xác thực plugin.
+
+- `omx tmux-hook` vẫn được hỗ trợ và không thay đổi.
+- `omx hooks` là bổ sung và không thay thế quy trình tmux-hook.
+- Tệp plugin nằm tại `.omx/hooks/*.mjs`.
+- Plugin tắt theo mặc định; kích hoạt bằng `OMX_HOOK_PLUGINS=1`.
+
+Xem `docs/hooks-extension.md` cho quy trình mở rộng đầy đủ và mô hình sự kiện.
+
+## Cờ khởi chạy
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # chỉ dành cho setup
+```
+
+`--madmax` ánh xạ đến Codex `--dangerously-bypass-approvals-and-sandbox`.
+Chỉ sử dụng trong môi trường sandbox tin cậy hoặc bên ngoài.
+
+### Chính sách workingDirectory MCP (tăng cường tùy chọn)
+
+Theo mặc định, các công cụ MCP state/memory/trace chấp nhận `workingDirectory` do người gọi cung cấp.
+Để hạn chế điều này, đặt danh sách gốc được phép:
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+Khi được đặt, các giá trị `workingDirectory` ngoài các gốc này sẽ bị từ chối.
+
+## Kiểm soát Prompt Codex-First
+
+Theo mặc định, OMX tiêm:
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+Điều này thêm hướng dẫn `AGENTS.md` của dự án vào lệnh khởi chạy Codex.
+Mở rộng hành vi Codex, nhưng không thay thế/bỏ qua các chính sách hệ thống cốt lõi của Codex.
+
+Điều khiển:
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # tắt tiêm AGENTS.md
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## Chế độ đội
+
+Sử dụng chế độ đội cho công việc lớn được hưởng lợi từ worker song song.
+
+Vòng đời:
+
+```text
+start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
+```
+
+Các lệnh vận hành:
 
 ```bash
-omx
-omx setup
-omx doctor
 omx team <args>
-omx status
-omx cancel
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
+```
+
+Quy tắc quan trọng: không tắt khi các tác vụ vẫn đang ở trạng thái `in_progress` trừ khi đang hủy bỏ.
+
+### Chính sách dọn dẹp Ralph
+
+Khi đội chạy trong chế độ ralph (`omx team ralph ...`), việc dọn dẹp khi tắt
+áp dụng chính sách chuyên dụng khác với đường dẫn thông thường:
+
+| Hành vi | Đội thông thường | Đội Ralph |
+|---|---|---|
+| Tắt cưỡng bức khi lỗi | Ném `shutdown_gate_blocked` | Bỏ qua cổng, ghi nhật ký sự kiện `ralph_cleanup_policy` |
+| Xóa nhánh tự động | Xóa nhánh worktree khi rollback | Giữ lại nhánh (`skipBranchDeletion`) |
+| Ghi nhật ký hoàn thành | Sự kiện `shutdown_gate` tiêu chuẩn | Sự kiện `ralph_cleanup_summary` bổ sung với phân tích tác vụ |
+
+Chính sách Ralph được phát hiện tự động từ trạng thái chế độ đội (`linked_ralph`) hoặc
+có thể được truyền rõ ràng qua `omx team shutdown <name> --ralph`.
+
+Chọn Worker CLI cho worker của đội:
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # mặc định; sử dụng claude khi worker --model chứa "claude"
+OMX_TEAM_WORKER_CLI=codex   # ép buộc worker Codex CLI
+OMX_TEAM_WORKER_CLI=claude  # ép buộc worker Claude CLI
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # hỗn hợp CLI theo worker (độ dài=1 hoặc số worker)
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # tùy chọn: tắt fallback thích ứng queue->resend
 ```
 
-## Tìm hiểu thêm
+Lưu ý:
+- Tham số khởi chạy worker vẫn được chia sẻ qua `OMX_TEAM_WORKER_LAUNCH_ARGS`.
+- `OMX_TEAM_WORKER_CLI_MAP` ghi đè `OMX_TEAM_WORKER_CLI` cho lựa chọn theo worker.
+- Gửi trigger sử dụng thử lại thích ứng theo mặc định (queue/submit, sau đó fallback an toàn clear-line+resend khi cần).
+- Trong chế độ Claude worker, OMX khởi chạy worker dưới dạng `claude` thuần túy (không có tham số khởi chạy thêm) và bỏ qua các ghi đè rõ ràng `--model` / `--config` / `--effort` để Claude sử dụng `settings.json` mặc định.
+
+## `omx setup` ghi những gì
+
+- `.omx/setup-scope.json` (phạm vi cài đặt được lưu trữ)
+- Cài đặt phụ thuộc phạm vi:
+  - `user`: `~/.codex/prompts/`, `~/.agents/skills/`, `~/.codex/config.toml`, `~/.omx/agents/`
+  - `project`: `./.codex/prompts/`, `./.agents/skills/`, `./.codex/config.toml`, `./.omx/agents/`
+- Hành vi khởi chạy: nếu phạm vi được lưu trữ là `project`, khởi chạy `omx` tự động sử dụng `CODEX_HOME=./.codex` (trừ khi `CODEX_HOME` đã được đặt).
+- `AGENTS.md` hiện có được giữ nguyên theo mặc định. Trong các lần chạy TTY tương tác, setup hỏi trước khi ghi đè; `--force` ghi đè không hỏi (kiểm tra an toàn phiên hoạt động vẫn áp dụng).
+- Cập nhật `config.toml` (cho cả hai phạm vi):
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - Mục máy chủ MCP (`omx_state`, `omx_memory`, `omx_code_intel`, `omx_trace`)
+  - `[tui] status_line`
+- `AGENTS.md` của dự án
+- Thư mục `.omx/` runtime và cấu hình HUD
+
+## Tác nhân và skill
+
+- Prompt: `prompts/*.md` (cài vào `~/.codex/prompts/` cho `user`, `./.codex/prompts/` cho `project`)
+- Skill: `skills/*/SKILL.md` (cài vào `~/.agents/skills/` cho `user`, `./.agents/skills/` cho `project`)
+
+Ví dụ:
+- Tác nhân: `architect`, `planner`, `executor`, `debugger`, `verifier`, `security-reviewer`
+- Skill: `autopilot`, `plan`, `team`, `ralph`, `ultrawork`, `cancel`
+
+## Cấu trúc dự án
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## Phát triển
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run build
+npm test
+```
+
+## Tài liệu
+
+- **[Tài liệu đầy đủ](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — Hướng dẫn hoàn chỉnh
+- **[Tham chiếu CLI](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — Tất cả lệnh `omx`, cờ và công cụ
+- **[Hướng dẫn thông báo](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Cài đặt Discord, Telegram, Slack và webhook
+- **[Quy trình công việc khuyến nghị](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — Chuỗi skill đã thử nghiệm thực chiến cho các tác vụ phổ biến
+- **[Ghi chú phát hành](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — Tính năng mới trong mỗi phiên bản
+
+## Ghi chú
+
+- Nhật ký thay đổi đầy đủ: `CHANGELOG.md`
+- Hướng dẫn di chuyển (sau v0.4.4 mainline): `docs/migration-mainline-post-v0.4.4.md`
+- Ghi chú về độ bao phủ và tương đương: `COVERAGE.md`
+- Quy trình mở rộng hook: `docs/hooks-extension.md`
+- Chi tiết cài đặt và đóng góp: `CONTRIBUTING.md`
+
+## Lời cảm ơn
+
+Lấy cảm hứng từ [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), được điều chỉnh cho Codex CLI.
+
+## Giấy phép
 
-- Tài liệu chính: [README.md](./README.md)
-- Website: https://yeachan-heo.github.io/oh-my-codex-website/
+MIT

package/README.zh.md

@@ -1,10 +1,59 @@
-# oh-my-codex (OMX) — 简体中文
+# oh-my-codex (OMX)
 
-> 英文原版 README： [README.md](./README.md)
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>你的 codex 并不孤单。</em>
+</p>
 
-`oh-my-codex (OMX)` 是 [OpenAI Codex CLI](https://github.com/openai/codex) 的多智能体编排层。
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-## 快速开始
+> **[Website](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[Documentation](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI Reference](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[Workflows](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+[OpenAI Codex CLI](https://github.com/openai/codex) 的多智能体编排层。
+
+## 语言
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese)](./README.zh.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX 将 Codex 从单会话代理转变为协调系统：
+- 用于专业代理的 role prompts (`/prompts:name`)
+- 用于可重复执行模式的 workflow skills (`$name`)
+- 在 tmux 中的团队编排 (`omx team`, `$team`)
+- 通过 MCP 服务器实现持久状态和记忆
+
+## 为什么选择 OMX
+
+Codex CLI 擅长处理直接任务。OMX 为更大规模的工作添加结构：
+- 分解和分阶段执行 (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- 持久化的模式生命周期状态 (`.omx/state/`)
+- 长时间会话的记忆和记事本表面
+- 用于启动、验证和取消的操作控制
+
+OMX 是一个插件，而非 fork。它使用 Codex 的原生扩展点。
+
+## 系统要求
+
+- macOS 或 Linux（Windows 通过 WSL2）
+- Node.js >= 20
+- 已安装 Codex CLI (`npm install -g @openai/codex`)
+- 已配置 Codex 身份验证
+
+## 快速开始（3 分钟）
 
 ```bash
 npm install -g oh-my-codex
@@ -12,28 +61,254 @@ omx setup
 omx doctor
 ```
 
-推荐启动参数：
+推荐的可信环境启动配置：
 
 ```bash
 omx --xhigh --madmax
 ```
 
-## OMX 提供的能力
+## v0.5.0 新功能
 
-- 角色提示词（`/prompts:name`）
-- 工作流技能（`$name`）
-- 基于 tmux 的团队编排（`omx team`, `$team`）
-- 基于 `.omx/` 的状态与记忆持久化
+- 通过 `omx setup --scope user|project` 实现**作用域感知设置** — 灵活的安装模式。
+- 通过 `--spark` / `--madmax-spark` 实现 **Spark worker 路由** — 团队 worker 可以使用 `gpt-5.3-codex-spark` 而无需强制使用领导者模型。
+- **目录整合** — 移除已弃用的 prompt（`deep-executor`、`scientist`）和 9 个已弃用的 skill，使表面更精简。
+- **通知详细级别** — 对 CCNotifier 输出的精细控制。
 
-## 常用命令
+## 首次会话
+
+在 Codex 内部：
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+从终端：
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## 核心模型
+
+OMX 安装并连接以下层：
+
+```text
+User
+  -> Codex CLI
+    -> AGENTS.md (编排大脑)
+    -> ~/.codex/prompts/*.md (代理 prompt 目录)
+    -> ~/.agents/skills/*/SKILL.md (skill 目录)
+    -> ~/.codex/config.toml (功能、通知、MCP)
+    -> .omx/ (运行时状态、记忆、计划、日志)
+```
+
+## 主要命令
+
+```bash
+omx                # 启动 Codex（在 tmux 中附带 HUD）
+omx setup          # 按作用域安装 prompt/skill/config + 项目 AGENTS.md/.omx
+omx doctor         # 安装/运行时诊断
+omx doctor --team  # Team/swarm 诊断
+omx team ...       # 启动/状态/恢复/关闭 tmux 团队 worker
+omx status         # 显示活动模式
+omx cancel         # 取消活动执行模式
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...  # init|status|validate|test
+omx hooks ...      # init|status|validate|test（插件扩展工作流）
+omx hud ...        # --watch|--json|--preset
+omx help
+```
+
+## Hooks 扩展（附加表面）
+
+OMX 现在包含用于插件脚手架和验证的 `omx hooks`。
+
+- `omx tmux-hook` 继续支持且未更改。
+- `omx hooks` 是附加的，不会替代 tmux-hook 工作流。
+- 插件文件位于 `.omx/hooks/*.mjs`。
+- 插件默认关闭；使用 `OMX_HOOK_PLUGINS=1` 启用。
+
+完整的扩展工作流和事件模型请参阅 `docs/hooks-extension.md`。
+
+## 启动标志
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # 仅用于 setup
+```
+
+`--madmax` 映射到 Codex `--dangerously-bypass-approvals-and-sandbox`。
+仅在可信/外部沙箱环境中使用。
+
+### MCP workingDirectory 策略（可选加固）
+
+默认情况下，MCP state/memory/trace 工具接受调用方提供的 `workingDirectory`。
+要限制此行为，请设置允许的根目录列表：
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+设置后，超出这些根目录的 `workingDirectory` 值将被拒绝。
+
+## Codex-First Prompt 控制
+
+默认情况下，OMX 注入：
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+这将项目 `AGENTS.md` 指导添加到 Codex 启动指令中。
+扩展 Codex 行为，但不会替换/绕过 Codex 核心系统策略。
+
+控制：
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # 禁用 AGENTS.md 注入
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## 团队模式
+
+对于受益于并行 worker 的大规模工作，使用团队模式。
+
+生命周期：
+
+```text
+start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
+```
+
+操作命令：
 
 ```bash
-omx
-omx setup
-omx doctor
 omx team <args>
-omx status
-omx cancel
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
 ```
 
-更多细节请参考英文文档 [README.md](./README.md)。
+重要规则：除非中止，否则不要在任务仍处于 `in_progress` 状态时关闭。
+
+### Ralph 清理策略
+
+当团队在 ralph 模式下运行时（`omx team ralph ...`），关闭清理
+应用与常规路径不同的专用策略：
+
+| 行为 | 普通团队 | Ralph 团队 |
+|---|---|---|
+| 失败时强制关闭 | 抛出 `shutdown_gate_blocked` | 绕过闸门，记录 `ralph_cleanup_policy` 事件 |
+| 自动分支删除 | 回滚时删除 worktree 分支 | 保留分支 (`skipBranchDeletion`) |
+| 完成日志 | 标准 `shutdown_gate` 事件 | 附带任务分解的 `ralph_cleanup_summary` 事件 |
+
+Ralph 策略从团队模式状态（`linked_ralph`）自动检测，或
+可通过 `omx team shutdown <name> --ralph` 显式传递。
+
+团队 worker 的 Worker CLI 选择：
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # 默认；当 worker --model 包含 "claude" 时使用 claude
+OMX_TEAM_WORKER_CLI=codex   # 强制 Codex CLI worker
+OMX_TEAM_WORKER_CLI=claude  # 强制 Claude CLI worker
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # 每个 worker 的 CLI 混合（长度=1 或 worker 数量）
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # 可选：禁用自适应 queue->resend 回退
+```
+
+注意：
+- Worker 启动参数仍通过 `OMX_TEAM_WORKER_LAUNCH_ARGS` 共享。
+- `OMX_TEAM_WORKER_CLI_MAP` 覆盖 `OMX_TEAM_WORKER_CLI` 以实现每个 worker 的选择。
+- 触发器提交默认使用自适应重试（queue/submit，需要时使用安全的 clear-line+resend 回退）。
+- 在 Claude worker 模式下，OMX 以普通 `claude` 启动 worker（无额外启动参数），并忽略显式的 `--model` / `--config` / `--effort` 覆盖，使 Claude 使用默认 `settings.json`。
+
+## `omx setup` 写入的内容
+
+- `.omx/setup-scope.json`（持久化的设置作用域）
+- 依赖作用域的安装：
+  - `user`：`~/.codex/prompts/`、`~/.agents/skills/`、`~/.codex/config.toml`、`~/.omx/agents/`
+  - `project`：`./.codex/prompts/`、`./.agents/skills/`、`./.codex/config.toml`、`./.omx/agents/`
+- 启动行为：如果持久化的作用域是 `project`，`omx` 启动时自动使用 `CODEX_HOME=./.codex`（除非 `CODEX_HOME` 已设置）。
+- 现有 `AGENTS.md` 默认保留。在交互式 TTY 运行中，setup 会在覆盖前询问；`--force` 无需询问直接覆盖（活动会话安全检查仍然适用）。
+- `config.toml` 更新（两种作用域均适用）：
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - MCP 服务器条目（`omx_state`、`omx_memory`、`omx_code_intel`、`omx_trace`）
+  - `[tui] status_line`
+- 项目 `AGENTS.md`
+- `.omx/` 运行时目录和 HUD 配置
+
+## 代理和技能
+
+- Prompt：`prompts/*.md`（`user` 安装到 `~/.codex/prompts/`，`project` 安装到 `./.codex/prompts/`）
+- Skill：`skills/*/SKILL.md`（`user` 安装到 `~/.agents/skills/`，`project` 安装到 `./.agents/skills/`）
+
+示例：
+- 代理：`architect`、`planner`、`executor`、`debugger`、`verifier`、`security-reviewer`
+- 技能：`autopilot`、`plan`、`team`、`ralph`、`ultrawork`、`cancel`
+
+## 项目结构
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## 开发
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run build
+npm test
+```
+
+## 文档
+
+- **[完整文档](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — 完整指南
+- **[CLI 参考](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — 所有 `omx` 命令、标志和工具
+- **[通知指南](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Discord、Telegram、Slack 和 webhook 设置
+- **[推荐工作流](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — 用于常见任务的经过实战检验的 skill 链
+- **[发行说明](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — 每个版本的新功能
+
+## 备注
+
+- 完整变更日志：`CHANGELOG.md`
+- 迁移指南（v0.4.4 后的 mainline）：`docs/migration-mainline-post-v0.4.4.md`
+- 覆盖率和对等说明：`COVERAGE.md`
+- Hook 扩展工作流：`docs/hooks-extension.md`
+- 设置和贡献详情：`CONTRIBUTING.md`
+
+## 致谢
+
+受 [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) 启发，为 Codex CLI 适配。
+
+## 许可证
+
+MIT

package/dist/catalog/__tests__/generator.test.js

@@ -32,6 +32,8 @@ describe('catalog reader/contract', () => {
         assert.ok(contract.aliases.some((a) => a.name === 'swarm' && a.canonical === 'team'));
         assert.ok(contract.internalHidden.includes('worker'));
         assert.ok(contract.coreSkills.includes('autopilot'));
+        assert.ok(contract.skills.some((s) => s.name === 'ask-claude' && s.status === 'active'));
+        assert.ok(contract.skills.some((s) => s.name === 'ask-gemini' && s.status === 'active'));
     });
     it('template manifest can be synced from source manifest', async () => {
         const sourceRaw = await readFile(join(process.cwd(), 'src', 'catalog', 'manifest.json'), 'utf8');

package/dist/catalog/__tests__/generator.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"generator.test.js","sourceRoot":"","sources":["../../../src/catalog/__tests__/generator.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generator.test.js","sourceRoot":"","sources":["../../../src/catalog/__tests__/generator.test.ts"],"names":[],"mappings":"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"}