@geminix/gxpm 0.1.0

package/docs/research/mattpocock-skills-study.md

@@ -0,0 +1,275 @@
+# mattpocock-skills 工程实践研究报告
+
+> 研究日期：2026-05-02
+> 来源：mattpocock/skills（本地路径 `/Users/x/Desktop/Project/github/mattpocock-skills`）
+> 研究目的：提取对 gxpm 有参考价值的工程实践，建立快速适配索引
+> 关联文档：`docs/research/mattpocock-skills-comparison.md`（已有对标分析）
+
+---
+
+## 一、项目定位
+
+**mattpocock-skills** 是一个**纯 Markdown + Shell 的技能仓库**，无 package.json，不依赖 Node.js 运行时。所有技能都是面向 Claude Code 的 prompt 指令集合，通过 `.claude-plugin/plugin.json` 声明可被 Claude CLI 发现。
+
+核心定位：面向软件交付生命周期的**工作流技能集合**，按 issue tracker 驱动的工程流程组织（需求对齐 → 计划产出 → 任务拆解 → 问题流转 → 开发实施 → 故障排查）。
+
+---
+
+## 二、架构与目录结构
+
+```
+mattpocock-skills/
+├── README.md              # 技能总览 + 使用哲学
+├── CONTEXT.md             # 领域词汇表（issue tracker, triage role 等）
+├── CLAUDE.md              # 仓库内部治理规则
+├── docs/adr/              # 架构决策记录（仅 1 条 ADR）
+├── .claude-plugin/
+│   └── plugin.json        # 暴露给 Claude CLI 的技能清单（12 个技能）
+├── scripts/
+│   ├── list-skills.sh     # 枚举所有 SKILL.md
+│   └── link-skills.sh     # 将技能软链到 ~/.claude/skills
+├── skills/
+│   ├── engineering/       # 9 个日常工程技能
+│   ├── productivity/      # 3 个通用工作流技能
+│   ├── misc/              # 4 个低频工具
+│   ├── personal/          # 2 个个人专用（不在 README/plugin 中曝光）
+│   └── deprecated/        # 4 个已弃用技能
+└── .out-of-scope/         # 反需求知识库（3 个拒绝项记录）
+```
+
+**关键治理规则（`CLAUDE.md`）**：
+- `engineering/`、`productivity/`、`misc/` 中的技能必须在根级 `README.md` 和 `plugin.json` 中登记
+- `personal/` 和 `deprecated/` **严禁**出现在 README/plugin 中
+- 每个 bucket 目录有自己的 `README.md`，列出该 bucket 内所有技能的一行描述
+
+---
+
+## 三、核心功能模块
+
+项目按**软件交付生命周期**组织技能，职责边界极其清晰：
+
+| 阶段 | 技能 | 职责 |
+|------|------|------|
+| **初始化** | `setup-matt-pocock-skills` | 种子配置：issue tracker 类型、triage label 映射、domain doc 布局 |
+| **需求对齐** | `grill-me` / `grill-with-docs` | 通过"拷问式访谈"消解需求歧义；`grill-with-docs` 额外维护 `CONTEXT.md` 和 ADR |
+| **计划产出** | `to-prd` | 将对话上下文合成为 PRD，发布到 issue tracker |
+| **任务拆解** | `to-issues` | 将 PRD/计划拆分为 tracer-bullet 垂直切片（Vertical Slices） |
+| **问题流转** | `triage` | 状态机驱动的 issue 分类：5 个 state role + 2 个 category role |
+| **开发实施** | `tdd` | 红-绿-重构循环，强制"一个测试 → 一个实现"的垂直切片 |
+| **故障排查** | `diagnose` | 6 阶段诊断法：构建反馈循环 → 复现 → 假设 → 探测 → 修复 → 事后分析 |
+| **架构治理** | `improve-codebase-architecture` | 基于 `CONTEXT.md` + ADR 持续发现"深度模块"重构机会 |
+| **代码理解** | `zoom-out` | 轻量提示：要求 Agent 使用领域词汇给出高层模块地图 |
+
+**设计哲学**：每个技能只做一件事，技能之间通过**文档真值（`CONTEXT.md`、ADR、配置）**间接协作，而非直接调用。
+
+---
+
+## 四、技术栈
+
+- **纯 Markdown**：所有 skill 逻辑用 Markdown 表达
+- **YAML frontmatter**：skill 元数据（name、description、disable-model-invocation）
+- **Shell 脚本**：辅助工具（list-skills.sh、link-skills.sh）
+- **无 package.json**：零 Node.js 依赖
+- **无 CI/CD**：无自动化测试基础设施
+
+---
+
+## 五、Skill 结构定义
+
+### 5.1 文件结构规范
+
+```
+skill-name/
+├── SKILL.md           # 主指令（必需）
+├── REFERENCE.md       # 详细参考（可选，当 SKILL.md 超过 100 行时拆分）
+├── EXAMPLES.md        # 用例示例（可选）
+├── AGENT-BRIEF.md     # 专用模板（如 triage）
+├── OUT-OF-SCOPE.md    # 知识库规范（如 triage）
+├── CONTEXT-FORMAT.md  # 上下文格式规范（如 grill-with-docs）
+└── scripts/           # 确定性工具脚本（可选）
+    └── helper.sh
+```
+
+### 5.2 Frontmatter 规范
+
+```yaml
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+disable-model-invocation: true   # 可选，仅作为提示，不调用模型
+---
+```
+
+### 5.3 Description 字段契约
+
+- **硬限制**：≤ 1024 字符
+- **视角**：第三人称
+- **格式**：第一句讲能力，第二句以 `"Use when..."` 给出触发条件
+- **重要性**：`description` 是 Agent 选择加载哪个 skill 的**唯一信息源**
+
+### 5.4 内容组织原则
+
+| 原则 | 说明 |
+|------|------|
+| **Progressive Disclosure** | SKILL.md 保持精简（目标 <100 行），高级内容拆分到 REFERENCE.md |
+| **确定性脚本外置** | 验证、格式化等确定性操作写为脚本，节省 token 并提升可靠性 |
+| **具体示例优先** | 禁止空泛描述，必须包含 Good/Bad 对比示例 |
+| **无时效信息** | 禁止包含版本号、时间等易过期内容 |
+
+### 5.5 对比 gxpm 现状
+
+gxpm 的 skill 结构（`skills/gxpm-*/SKILL.md`）已经高度遵循此模式，且增加了 `.tmpl` 源文件 + `gen:skill-docs` 生成管道，这是 mattpocock-skills 所没有的**工程化增强**。
+
+---
+
+## 六、Skill 的测试与验证机制
+
+### 6.1 现状：无自动化测试基础设施
+
+mattpocock-skills **没有**测试目录、没有 CI 配置、没有自动化验证管道。Skill 的质量保障依赖：
+
+1. **Review Checklist**（`write-a-skill/SKILL.md` 末尾）：
+   - Description 包含触发条件（"Use when..."）
+   - SKILL.md < 100 行
+   - 无时效敏感信息
+   - 术语一致
+   - 包含具体示例
+   - 引用仅一层深度
+
+2. **Deprecated 目录作为迭代证据**：弃用技能不删除，移入 `deprecated/`，保留历史决策痕迹。
+
+3. **使用反馈驱动**：通过 newsletter 和实际工程使用发现问题。
+
+### 6.2 诊断技能的"反馈循环"哲学
+
+虽然 skill 本身无测试，但 `diagnose` skill 将**"构建快速反馈循环"**提升为调试的第一性原理：
+
+> "If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause... If you don't have one, no amount of staring at code will save you."
+
+`tdd` skill 同样将测试视为**行为契约**而非实现验证。
+
+---
+
+## 七、配置系统与扩展点
+
+### 7.1 核心设计：Per-Repo 配置种子
+
+`setup-matt-pocock-skills` 是一个**prompt-driven 的配置生成器**（非确定性脚本），产出以下真值文件：
+
+```
+docs/agents/
+├── issue-tracker.md     # GitHub / GitLab / Local / Other
+├── triage-labels.md     # 5 个 canonical role → 实际 label 字符串映射
+└── domain.md            # 单上下文 vs 多上下文布局规则
+```
+
+并在 `AGENTS.md` 或 `CLAUDE.md` 中注入 `## Agent skills` 块。
+
+### 7.2 硬依赖 vs 软依赖分离（ADR-0001）
+
+| 类型 | 技能 | 策略 |
+|------|------|------|
+| **Hard dependency** | `to-issues`, `to-prd`, `triage` | 必须显式提示：*"run `/setup-matt-pocock-skills` if not"*。没有配置则输出错误。 |
+| **Soft dependency** | `diagnose`, `tdd`, `improve-codebase-architecture`, `zoom-out` | 模糊引用"domain glossary"和"ADRs"。无配置时优雅降级，输出只是不够精准。 |
+
+**设计意图**：避免在不需要的地方 cargo-cult 配置指针，保持软依赖技能的 token 轻量。
+
+### 7.3 Issue Tracker 抽象
+
+支持四级后端：
+- **GitHub**（`gh` CLI）
+- **GitLab**（`glab` CLI）
+- **Local markdown**（`.scratch/<feature>/`）
+- **Other**（自由文本，由用户自行描述工作流）
+
+### 7.4 领域文档布局
+
+- **Single-context**：根级 `CONTEXT.md` + `docs/adr/`
+- **Multi-context**：根级 `CONTEXT-MAP.md` 指向多个子上下文（如 monorepo）
+
+### 7.5 反需求知识库：`.out-of-scope/`
+
+- 一概念一文件（kebab-case 命名）
+- 格式：决策、理由、先例请求列表
+- 在 `triage` 阶段自动匹配，避免重复讨论已拒绝的特性
+- 仅用于 enhancement 的 `wontfix`，不用于 bug
+
+### 7.6 Agent Brief 模板
+
+当 issue 进入 `ready-for-agent` 时，`triage` 要求发布结构化评论：
+- **Durability over precision**：只描述接口/行为/类型，不引用文件路径或行号
+- **Behavioral, not procedural**：描述"系统应该做什么"，而非"如何修改"
+- **Explicit scope boundaries**：明确列出 Out of scope
+
+---
+
+## 八、对 gxpm 的借鉴价值
+
+### 8.1 可直接复用的模式 ✅
+
+| 模式 | 来源文件 | gxpm 应用建议 |
+|------|----------|---------------|
+| **硬/软依赖分离** | `docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md` | `gxpm-init` 应明确区分哪些技能/phase 必须预配置，哪些可优雅降级 |
+| **Agent Brief 契约** | `skills/engineering/triage/AGENT-BRIEF.md` | `dispatch` phase 产出的 artifact 可直接采用：行为描述 + 关键接口 + 验收标准 + 范围边界，禁止文件路径/行号 |
+| **`.out-of-scope/` 反需求库** | `skills/engineering/triage/OUT-OF-SCOPE.md` | gxpm 已有 `.gxpm/out-of-scope/`（目前为空），可采纳"一概念一文件 + 先例请求列表 + triage 自动匹配"的完整规范 |
+| **垂直切片（Tracer Bullet）** | `skills/engineering/to-issues/SKILL.md` | `gxpm-planning` skill 拆解 issue 时已使用 vertical slice，可进一步引入 HITL vs AFK 分类和显式依赖图 |
+| **诊断反馈循环优先** | `skills/engineering/diagnose/SKILL.md` | `gxpm-diagnose` skill 可将 Phase 1（构建反馈循环）作为核心框架 |
+| **Disable-model-invocation 轻量技能** | `skills/engineering/zoom-out/SKILL.md` | 对于纯提示类技能（如 `gxpm-grill` 的某些模式），可加 `disable-model-invocation: true` |
+| **Issue tracker CLI 抽象** | `skills/engineering/setup-matt-pocock-skills/issue-tracker-*.md` | gxpm 的 Linear/GitHub 集成不应硬编码 CLI，而应通过配置抽象，支持"本地 markdown"作为 fallback |
+
+### 8.2 应避免的陷阱 ❌
+
+| 陷阱 | mattpocock-skills 现状 | gxpm 应如何超越 |
+|------|------------------------|-----------------|
+| **无自动化验证** | Skill 质量仅靠人工 review checklist 保障 | gxpm 应为 skill 建立**自动化 lint/检查**（如 `bun run check`）、甚至 eval 测试 |
+| **无类型安全** | 纯 Markdown frontmatter，无 schema 校验 | gxpm 使用 TypeScript 运行时，skill 元数据应通过 Zod 等 schema 校验 |
+| **版本与迁移缺失** | 弃用技能仅移入 `deprecated/` 目录，无迁移指南 | 应建立 skill 版本契约和 deprecation 策略（如 `DEPRECATED.md` + 自动迁移提示） |
+| **配置重复提示** | 每个硬依赖技能都重复同样的 setup 提示语 | 可通过 host hook 或 capability runtime 在 session 启动时统一注入配置状态 |
+| **无状态机持久化** | triage 状态依赖 issue tracker label，无本地状态图 | gxpm 的核心优势正是**统一 state graph**（`.gxpm/issues/<id>/`），应继续强化 |
+| **Plugin.json 静态注册** | `.claude-plugin/plugin.json` 是静态清单 | gxpm 的 skill 注册应支持动态发现（`discover-skills`），与 host adapter 解耦 |
+
+---
+
+## 九、关键差异提醒
+
+mattpocock-skills 是**Claude Code 的纯 prompt skill 集合**，没有自己的运行时、状态图或 capability 系统。gxpm 是**独立产品**，具备：
+- TypeScript 运行时 + state graph
+- `.gxpm/` 本地真值目录
+- Capability runtime + browser evidence
+- Review/ship governance
+
+因此，gxpm 不应模仿其"无测试、无类型"的轻量模式，而应**吸收其 workflow 设计、文档治理和 skill 结构规范**，同时在工程化、自动化验证和状态持久化上建立更高标准。
+
+---
+
+## 十、关键文件映射
+
+| mattpocock-skills 文件/模式 | gxpm 对应位置/建议 |
+|----------------------------|---------------------|
+| `CONTEXT.md` | 已存在，继续作为领域词汇单一真相源 |
+| `docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md` | `docs/architecture/` 下记录 gxpm 的硬/软依赖决策 |
+| `skills/engineering/triage/AGENT-BRIEF.md` | `core/dispatch.ts` + artifact 模板 |
+| `skills/engineering/triage/OUT-OF-SCOPE.md` | `.gxpm/out-of-scope/` 规范化 |
+| `skills/engineering/to-issues/SKILL.md` | `skills/gxpm-planning/SKILL.md` |
+| `skills/engineering/diagnose/SKILL.md` | `skills/gxpm-diagnose/SKILL.md` |
+| `skills/engineering/tdd/SKILL.md` | `skills/gxpm-tdd/SKILL.md` |
+| `skills/engineering/write-a-skill/SKILL.md` | `docs/governance/skill-authoring.md` |
+| `.out-of-scope/` | `.gxpm/out-of-scope/` 待填充 |
+| `deprecated/` | 未来 skill 淘汰机制参考 |
+
+---
+
+## 十一、适配建议
+
+1. **硬/软依赖分离**：在 `gxpm-init` 和 `AGENTS.md` 中明确标记哪些能力是 hard dependency（必须 setup 后才能使用，如 issue tracker 配置），哪些是 soft dependency（无配置时优雅降级，如 `gxpm-diagnose`）。
+2. **Agent Brief 模板**：`dispatch` phase 产出的 artifact 采用 Agent Brief 格式——只描述接口/行为/类型，不引用文件路径或行号，明确 scope boundaries。
+3. **`.out-of-scope/` 规范化**：将 `.gxpm/out-of-scope/` 从空目录升级为"一概念一文件"的反需求知识库，在 `gxpm-triage` 中自动匹配，避免重复讨论已拒绝的特性。
+4. **Skill 自动化验证**：为 gxpm skills 建立自动化 lint（description 长度、frontmatter 完整性、术语一致性）和 eval 测试框架，超越 mattpocock-skills 的人工 review checklist。
+5. **Issue Tracker 抽象**：当前 gxpm 硬绑定 Linear，应参考 mattpocock-skills 的抽象层设计，支持本地 markdown fallback（`.gxpm/issues/<id>/` 本身就是本地真值，可作为独立后端）。
+6. **垂直切片强化**：`gxpm-planning` skill 在拆解 issue 时，引入 tracer-bullet 垂直切片 + HITL vs AFK 分类 + 显式依赖图。
+
+---
+
+## 十二、一句话总结
+
+> mattpocock-skills 是 gxpm 在**工作流设计、领域文档治理、skill 契约规范**方面的优秀上游参考。gxpm 已大量吸收其术语和结构（`CONTEXT.md`、triage role、vertical slice），下一步应重点补齐其短板：**skill 自动化验证、类型安全 schema、状态机持久化、以及硬/软依赖的 runtime 级管理**。

package/docs/research/oh-my-codex-study.md

@@ -0,0 +1,279 @@
+# oh-my-codex 工程实践研究报告
+
+> 研究日期：2026-05-02
+> 来源：Yeachan-Heo/oh-my-codex（本地路径 `/Users/x/Desktop/Project/github/oh-my-codex`）
+> 研究目的：提取对 gxpm 有参考价值的工程实践，建立快速适配索引
+
+---
+
+## 一、项目定位
+
+**oh-my-codex（OMX）** 是一个基于 OpenAI Codex CLI 的**工作流编排层**，不自建执行引擎，而是通过 hooks、skills、state 管理和 tmux 运行时来增强 Codex 的默认体验。
+
+核心定位："better task routing + better workflow + better runtime"。OMX 在 Codex CLI 之上构建了一个完整的代理项目管理工作流，包含需求澄清、计划生成、团队并行执行、持久化完成循环等阶段。
+
+---
+
+## 二、架构与目录结构
+
+```
+oh-my-codex/
+├── src/
+│   ├── cli/          # CLI 命令入口（omx.ts → index.ts）
+│   ├── config/       # 配置解析：Codex hooks、模型路由、MCP registry
+│   ├── hooks/        # 生命周期钩子：keyword-detector、session、agents-overlay
+│   ├── modes/        # 工作流模式基类：startMode/updateMode/cancelMode
+│   ├── state/        # 状态机：workflow-transition、skill-active、reconcile
+│   ├── runtime/      # 执行循环：run-loop、run-outcome、terminal-lifecycle
+│   ├── team/         # 团队并行运行时：orchestrator、tmux-session、worktree、state
+│   ├── ralph/        # 持久化完成循环：persistence、contract
+│   ├── pipeline/     # 流水线阶段
+│   ├── mcp/          # MCP 服务器实现（state-server、trace-server）
+│   ├── agents/       # 原生代理配置生成
+│   ├── hud/          # Heads-up display 状态
+│   └── utils/        # 路径解析、AGENTS.md 工具
+├── skills/           # SKILL.md 技能定义（ralph、team、autopilot、deep-interview 等）
+├── prompts/          # 角色提示词（analyst、architect、executor 等 30+ 角色）
+├── templates/        # 模型指令模板
+├── plugins/          # Codex 官方插件打包（含 marketplace.json）
+├── crates/           # Rust 子 crate（runtime-core、explore、mux、sparkshell）
+└── docs/             # 详尽文档（contracts、reference、release-notes、状态模型）
+```
+
+**关键架构决策**：
+- **双层状态存储**：`.omx/state/<mode>-state.json`（权威）+ `skill-active-state.json`（兼容/可见层）
+- **Session 作用域优先**：session-scoped state > current session > root scope fallback
+- **混合语言运行时**：TS 负责编排与 CLI，Rust 负责高性能探索和 runtime 桥接
+- **Codex 插件 + 原生 Hooks 双轨**：既有 `.codex/hooks.json` 原生 hook，也有 OMX plugin hooks
+
+---
+
+## 三、核心功能模块
+
+| 模块 | 职责 | gxpm 映射参考 |
+|------|------|---------------|
+| **cli/omx.ts** | CLI 入口，处理 `main(argv)` | `bin/gxpm` 系列脚本 |
+| **config/** | 解析 `.omx-config.json`、Codex `config.toml`、模型路由 | `core/config.ts` |
+| **hooks/** | `UserPromptSubmit` 关键词检测、`SessionStart` 上下文注入、`Stop` 续行判断 | `.githooks/` 和 host adapter |
+| **modes/base.ts** | 统一模式生命周期：start → update → cancel | gxpm phase gate |
+| **state/** | 工作流过渡决策、协调同步 | gxpm issue state graph |
+| **runtime/** | 通用执行循环、结果分类 | gxpm implement/execute loop |
+| **team/** | tmux 多窗格并行工作器、任务分解、worktree 隔离 | gxpm（未来）并行执行层 |
+| **ralph/** | 持久化完成循环：进度台账、PRD 迁移、视觉校验门 | gxpm implement → verify → land |
+| **mcp/** | 暴露 `omx_state.*` 工具给 Codex/MCP 客户端 | gxpm capability runtime |
+| **agents/** | 原生 Codex Agent TOML 生成（30+ 角色定义） | gxpm skills/hosts |
+
+---
+
+## 四、技术栈
+
+- **Node.js 20+ + TypeScript**：主运行时与编排
+- **Rust**：辅助运行时（`omx-explore`、`omx-mux`、`omx-runtime-core`、`omx-sparkshell`）
+- **Cargo**：构建 Native 代理/探索 harness
+- **tmux**：macOS/Linux 团队并行执行的基础设施
+- **MCP (Model Context Protocol)**：状态读写、wiki、trace 等服务器能力
+
+---
+
+## 五、Codex CLI 工作流设计
+
+### 5.1 Native Hook 映射矩阵
+
+| Codex Hook | OMX 处理 | 状态 |
+|-----------|---------|------|
+| `SessionStart` | 刷新 session bookkeeping、注入 wiki 上下文、恢复开发者上下文 | native |
+| `UserPromptSubmit` | 关键词检测（`$ralph`/`$team`/`$ralplan`）、状态种子、triage 路由 | native |
+| `PreToolUse` (Bash) | `rm -rf` 警告、内联 `git commit` 拦截、文档刷新警告 | native-partial |
+| `PostToolUse` (Bash) | 命令失败/权限错误指引、MCP 传输死亡检测 | native-partial |
+| `Stop` | Ralph/Team/Autopilot 续行判断、auto-nudge、生命周期元数据 | native-partial |
+
+**关键设计**：`.codex/hooks.json` 是**共享所有权文件** —— OMX 只刷新自己管理的 wrapper 条目，保留用户自定义 hook。`omx uninstall` 也只移除 OMX 管理的部分。
+
+### 5.2 标准工作流（Canonical Workflow）
+
+```
+$deep-interview → $ralplan → ($team | $ralph)
+```
+
+- **deep-interview**：澄清需求、边界、非目标
+- **ralplan**：生成并审批实现计划
+- **team**：tmux 并行执行（适合大任务）
+- **ralph**：持久化单所有者完成循环（适合需要保证完成的场景）
+
+### 5.3 关键词检测与状态种子
+
+`src/hooks/keyword-detector.ts` 是工作流路由的核心：
+- 检测 `$skill` 关键词并排序
+- 记录 `skill-active-state.json`
+- 对 `$ralph` 只做**状态种子**，不启动 CLI 进程
+- 多关键词支持：`$ralplan $team $ralph` 会延迟执行技能，保留 planning 为当前主模式
+
+### 5.4 插件 Hooks 扩展点
+
+- 用户可在 `.omx/hooks/*.mjs` 编写插件
+- 暴露事件：`session-start`、`keyword-detector`、`pre-tool-use`、`post-tool-use`、`stop`、`session-end`、`turn-complete`、`session-idle`
+- SDK 提供：`sdk.state.read/write`（插件命名空间隔离）、`sdk.tmux.sendKeys`、`sdk.log.info/warn/error`
+
+---
+
+## 六、配置系统与扩展点
+
+### 6.1 三层配置来源
+
+1. **Shell 环境变量**（最高优先级）：`OMX_DEFAULT_FRONTIER_MODEL`、`OMX_DEFAULT_STANDARD_MODEL`
+2. **`.omx-config.json`**：用户级（`~/.codex/`）或项目级（`./.codex/`）
+3. **Codex `config.toml`**：读取 root model、provider、model_providers
+
+### 6.2 模型路由解析链
+
+```
+mode-specific > models.default > OMX_DEFAULT_FRONTIER_MODEL > config.toml model > built-in default (gpt-5.5)
+```
+
+- 团队低复杂度 worker：`team_low_complexity` 别名支持三种 key 风格（snake/kebab/camel）
+- **显式规则**：禁止从模型名称子串推断 reasoning effort
+
+### 6.3 扩展点
+
+| 扩展点 | 机制 | 位置 |
+|--------|------|------|
+| **Skills** | SKILL.md + frontmatter | `skills/`（项目级）或 `~/.codex/skills/`（用户级） |
+| **Prompts** | Markdown 角色定义 | `prompts/` |
+| **Native Agents** | TOML 生成 | `.codex/agents/` |
+| **Plugin Hooks** | ES Module 导出 `onHookEvent` | `.omx/hooks/*.mjs` |
+| **MCP Servers** | 通过 `.mcp.json` / `config.toml` 注册 | `config/mcp-registry.ts` |
+| **Wiki** | Markdown-first、搜索优先 | `.omx/wiki/` |
+
+### 6.4 AGENTS.md 合并策略
+
+- `omx setup --merge-agents` 在现有 `AGENTS.md` 中插入 OMX 生成区块
+- 使用 `<!-- OMX:AGENTS:START -->` / `<!-- OMX:AGENTS:END -->` 标记
+- 非交互式 setup 默认跳过已有 `AGENTS.md`（避免覆盖用户定制）
+
+---
+
+## 七、Agent 执行循环与状态管理
+
+### 7.1 状态模型（Explicit Terminal Stop Model）
+
+生命周期结果：`finished` / `blocked` / `failed` / `userinterlude` / `askuserQuestion`
+
+**读取优先级**：
+1. `lifecycle_outcome`（规范生命周期元数据）
+2. 遗留 `run_outcome`
+3. 从 `current_phase` 推断
+
+### 7.2 工作流过渡规则（Workflow Transition）
+
+`src/state/workflow-transition.ts` 实现了严格的状态机：
+
+| 源模式 | 目标模式 | 结果 |
+|--------|---------|------|
+| deep-interview | ralplan | auto-complete 源模式 |
+| ralplan | team / ralph / autopilot | auto-complete 源模式 |
+| team | ralph | overlap（共存） |
+| ralph | team | overlap（共存） |
+| execution → planning | — | **deny**（禁止回滚） |
+
+**关键不变量**：
+- 执行类模式回滚到规划类模式永远不允许自动完成
+- 未在白名单中的过渡默认拒绝
+- native-hook 输出是展示层，不是独立决策引擎
+
+### 7.3 通用执行循环（Run Loop）
+
+`src/runtime/run-loop.ts` 提供 `runUntilTerminal(step, options)`：
+- 每次迭代返回 `{ outcome, state }`
+- 结果分类：`progress` / `continue`（非终端） vs `finish` / `blocked_on_user` / `failed` / `cancelled`（终端）
+- 支持 `maxIterations` 和 `onIteration` 回调
+- 标准化别名映射：`done` → `finish`, `error` → `failed`, `abort` → `cancelled`
+
+### 7.4 Team 并行运行时
+
+**阶段管道**：`team-plan` → `team-prd` → `team-exec` → `team-verify` → `team-fix`（循环）→ `complete`/`failed`
+
+**基础设施**：
+- **tmux**：leader 窗格 + worker 窗格分割
+- **worktree**：每个 worker 可运行在独立 git worktree（`--worktree`）
+- **Mailbox**：`.omx/state/team/<team>/mailbox/leader-fixed.json` 进行 leader-worker 通信
+- **Dispatch Request**：任务分派状态机（pending → notified → delivered → integrated）
+- **Worker CLI 多态**：支持 Codex 或 Claude CLI 作为 worker（`OMX_TEAM_WORKER_CLI`）
+
+### 7.5 Ralph 持久化循环
+
+- **Context Snapshot**：`.omx/context/{task-slug}-{timestamp}.md` 强制 grounding
+- **Progress Ledger**：`.omx/state/ralph-progress.json` 记录迭代、视觉反馈
+- **PRD 模式**：`--prd` 先初始化产品需求文档
+- **完成门控**：
+  1. 零 pending TODO
+  2. 新鲜测试/构建通过
+  3. Architect 验证（STANDARD tier 起）
+  4. AI-slop-cleaner 清理
+  5. 回归重验证
+
+---
+
+## 八、对 gxpm 的借鉴价值
+
+### 8.1 可直接复用的模式 ✅
+
+| # | 模式 | 具体借鉴方式 |
+|---|------|-------------|
+| 1 | **显式终端停止模型** | gxpm phase gate 可引入 `lifecycle_outcome` 规范层，替代单一 `phase` 推断 |
+| 2 | **工作流过渡白名单** | gxpm issue 的 phase 推进可引入 `evaluateWorkflowTransition`，防止非法回滚 |
+| 3 | **Session 作用域状态隔离** | gxpm 的 `.gxpm/issues/<id>/` 可进一步引入 `session-scoped state` 优先于 `root scope` |
+| 4 | **共享所有权配置** | `.codex/hooks.json` 的共享所有权设计可直接用于 gxpm 的 `.githooks/` |
+| 5 | **AGENTS.md 合并标记** | `<!-- OMX:AGENTS:START/END -->` 的区块合并策略比全文件覆盖更安全 |
+| 6 | **模型路由解析链** | gxpm host adapter 可引入 `mode-specific > default > env > built-in` 的模型选择链 |
+| 7 | **Context Snapshot 强制门控** | Ralph 的 context snapshot 可移植到 gxpm 的 `dispatch→implement` 阶段 |
+| 8 | **Run Loop 抽象** | `runUntilTerminal(step)` 的通用循环可封装为 gxpm capability runtime 的基础执行原语 |
+| 9 | **MCP 状态服务器** | `omx_state.*` MCP 工具将状态读写暴露给 agent，gxpm 可将 artifact 读写封装为 MCP tools |
+| 10 | **Skill frontmatter 元数据** | `--- name: ralph description: ... ---` 的标准化 SKILL.md 头部可被 gxpm skills 采用 |
+
+### 8.2 应避免的陷阱 ❌
+
+| # | 陷阱 | 原因 | gxpm 应对建议 |
+|---|------|------|---------------|
+| 1 | **过度依赖 tmux** | 强绑定 tmux，Windows/WSL 体验降级、测试复杂 | 优先考虑原生 subagent/MCP 并行，tmux 仅作为可选后端 |
+| 2 | **双层状态同步风险** | `mode-state.json` + `skill-active-state.json` 多次导致 "ghost state" | 坚持**单一真相源**（`.gxpm/issues/<id>/`），若需兼容层则引入显式协调 helper |
+| 3 | **Hooks fallback 矩阵过复杂** | native/native-partial/runtime-fallback/not-supported-yet 四级，调试困难 | 优先走**原生 host adapter 扩展点**，减少 fallback 层 |
+| 4 | **Rust/TS 混合构建复杂度** | 需要 Cargo + Node 双构建链，测试和发布流程重 | gxpm 当前纯 TS/Bun 是优势，Rust 引入需有明确性能诉求 |
+| 5 | **进程级 worker 过重** | 每个 worker 是完整 Codex/Claude CLI 进程，启动慢、资源消耗大 | 使用**轻量级 task delegation** 而非完整进程复制 |
+| 6 | **Setup 副作用过多** | `omx setup` 修改多处位置，回滚复杂 | `gxpm-init` 应更模块化，支持 dry-run 和 scope 选择 |
+| 7 | **Prompt 路由的隐性状态** | `keyword-detector` + `triage-heuristic` 在 prompt submit 时注入路由上下文 | gxpm 应让**issue id 显式驱动路由**，避免隐式分类干扰 |
+
+---
+
+## 九、关键文件映射
+
+| OMX 文件路径 | 内容 | gxpm 对应 |
+|-------------|------|-----------|
+| `docs/STATE_MODEL.md` | 状态权威、过渡规则、审计字段 | `docs/architecture/gxpm-v0-contract.md` |
+| `docs/codex-native-hooks.md` | 原生 hook 映射矩阵 | `docs/governance/host-adapter.md` |
+| `docs/hooks-extension.md` | 插件扩展点、SDK 接口 | `hosts/codex.ts` 扩展设计 |
+| `src/state/workflow-transition.ts` | 工作流过渡决策引擎 | `core/gate.ts` |
+| `src/modes/base.ts` | 统一模式生命周期 | `core/dispatch.ts` |
+| `src/runtime/run-loop.ts` | 通用终端执行循环 | capability runtime 执行原语 |
+| `src/team/orchestrator.ts` | Team 阶段管道 | 未来并行执行层参考 |
+| `src/team/runtime.ts` | Team tmux 运行时、worktree、mailbox | `core/worktree.ts`（如存在） |
+| `src/config/models.ts` | 模型路由解析链 | `hosts/` 模型选择逻辑 |
+| `src/hooks/keyword-detector.ts` | 关键词检测与状态种子 | `core/command-probe.ts` |
+| `skills/ralph/SKILL.md` | 持久化完成循环的完整契约 | `skills/gxpm/` 系列 |
+| `skills/team/SKILL.md` | 团队并行执行的完整契约 | 未来并行执行层参考 |
+
+---
+
+## 十、适配建议
+
+1. **生命周期模型规范化**：在 gxpm 的 phase gate 中引入 `lifecycle_outcome` 规范层（`finished`/`blocked`/`failed`/`cancelled`），替代单一的 `phase` 字符串推断，增强跨会话恢复能力。
+2. **工作流过渡规则**：引入 `evaluateWorkflowTransition` 白名单机制，明确允许和禁止的 phase 转换（如 `qa→implement` 禁止自动完成）。
+3. **AGENTS.md 合并策略**：`gxpm-init` 采用标记式合并（`<!-- GXPM:AGENTS:START/END -->`），避免覆盖用户已有定制。
+4. **模型路由链**：host adapter 引入 `mode-specific > default > env > built-in` 的模型选择链，支持 per-skill/per-phase 模型降级。
+5. **MCP 状态暴露**：将 `.gxpm/issues/<id>/` 的 artifact 读写封装为 MCP tools（如 `gxpm_state.read`、`gxpm_state.write`），实现 agent 自托管状态。
+6. **Context Snapshot**：在 `dispatch→implement` 阶段要求 agent 完成上下文快照（`.gxpm/issues/<id>/context-snapshot.md`），强制 grounding。
+
+---
+
+## 十一、一句话总结
+
+> oh-my-codex 在**工作流过渡规则、显式生命周期模型、配置分层解析、共享所有权 hook、AGENTS.md 合并策略**方面提供了非常成熟的参考实现，建议 gxpm 在 capability runtime 和 phase gate 设计中重点吸收；同时，OMX 作为 Codex wrapper 的某些复杂兼容层（双层状态、tmux 进程级并行）在 gxpm 的独立产品定位下可以简化或避免。