@geminix/gxpm 0.1.0

package/docs/research/superpowers-study.md

@@ -0,0 +1,209 @@
+# superpowers 工程实践研究报告
+
+> 研究日期：2026-05-02
+> 来源：obra/superpowers（本地路径 `/Users/x/Desktop/Project/github/superpowers`）
+> 研究目的：提取对 gxpm 有参考价值的工程实践，建立快速适配索引
+
+---
+
+## 一、项目定位
+
+**superpowers** 是由 Jesse Vincent 创建的多宿主代理能力编排框架（multi-harness agentic skills framework）。核心定位是：通过可组合的技能（skills）和引导式指令，为编码代理提供完整的软件开发方法论。
+
+它不是独立运行时，而是**依赖宿主平台原生机制**的 skill 编排层，支持 Claude Code、Codex CLI、Cursor、OpenCode、Gemini CLI、Copilot CLI 六大宿主。
+
+---
+
+## 二、架构与目录结构
+
+```
+superpowers/
+├── .claude-plugin/          # Claude Code 插件配置
+├── .codex-plugin/           # Codex CLI 插件配置
+├── .cursor-plugin/          # Cursor 插件配置
+├── .opencode/               # OpenCode 插件（JS 运行时）
+├── agents/                  # 预定义子代理模板
+├── commands/                # 已废弃的 legacy 命令入口
+├── docs/                    # 架构演进计划与自托管设计文档
+├── hooks/                   # SessionStart hook 注入系统
+│   ├── hooks.json           # Claude Code hook 配置
+│   ├── hooks-cursor.json    # Cursor hook 配置
+│   ├── run-hook.cmd         # 跨平台 polyglot wrapper
+│   └── session-start        # bash 引导脚本
+├── skills/                  # 核心技能库（14 个技能）
+│   ├── using-superpowers/   # 引导技能（bootstrap）
+│   ├── brainstorming/       # 设计前头脑风暴
+│   ├── writing-plans/       # 实现计划编写
+│   ├── subagent-driven-development/  # 子代理驱动开发
+│   ├── executing-plans/     # 计划执行（同会话）
+│   ├── dispatching-parallel-agents/  # 并行代理调度
+│   ├── test-driven-development/      # TDD 强制规范
+│   ├── systematic-debugging/         # 系统化调试
+│   ├── requesting-code-review/       # 代码审查请求
+│   ├── receiving-code-review/        # 代码审查响应
+│   ├── using-git-worktrees/          # Git worktree 隔离
+│   ├── finishing-a-development-branch/  # 分支收尾
+│   ├── verification-before-completion/  # 完成前验证
+│   └── writing-skills/      # 技能编写方法论
+├── scripts/                 # 维护脚本（版本同步、Codex 同步）
+├── tests/                   # 集成测试体系
+│   ├── claude-code/         # headless Claude Code 会话测试
+│   ├── skill-triggering/    # 技能自动触发测试
+│   ├── explicit-skill-requests/  # 显式技能请求测试
+│   ├── subagent-driven-dev/ # SDD 端到端测试
+│   ├── brainstorm-server/   # 零依赖头脑风暴服务测试
+│   └── opencode/            # OpenCode 插件测试
+├── .version-bump.json       # 声明式版本同步配置
+├── CLAUDE.md                # 面向代理的严格纪律手册（94% PR 拒绝率）
+├── package.json             # 仅含版本信息，零依赖
+└── README.md                # 用户文档
+```
+
+**关键架构决策**：
+- `skills/` 是 canonical 工作流面，`commands/` 仅作兼容保留
+- 所有 durable behavior 放在共享源，harness-specific 文件仅用于加载和适配
+- 零依赖设计哲学：package.json 无依赖，所有脚本用纯 bash 编写
+
+---
+
+## 三、核心功能模块
+
+| 模块 | 职责 | gxpm 映射参考 |
+|------|------|---------------|
+| **using-superpowers** | SessionStart hook 注入，建立指令优先级，强制技能检查规则 | `skills/gxpm/SKILL.md` — 引导技能 |
+| **工作流编排技能链** | 状态机式开发流程：brainstorming → worktree → plan → implement → review → verify | gxpm phase gate（triage→plan→dispatch→…→land） |
+| **subagent-driven-development** | 每个任务派发给新子代理，两阶段审查（spec compliance + code quality） | `gxpm-explore-codebase` / `gxpm-review-changes` 可借鉴 |
+| **多宿主适配层** | 6 个宿主平台的 manifest + hook 适配 | `hosts/claude.ts`、`hosts/codex.ts` — 适配层设计 |
+| **writing-skills** | 将 TDD 原则应用到流程文档：RED（压力测试）→ GREEN（最小 skill）→ REFACTOR（封堵漏洞） | `docs/governance/skill-authoring.md` |
+
+---
+
+## 四、技术栈
+
+- **零依赖**：package.json 无 runtime dependency
+- **纯 bash 脚本**：所有维护脚本用 bash 编写
+- **Markdown + YAML frontmatter**：所有 skill 逻辑用 Markdown 表达
+- **外部工具要求**：`jq`（版本脚本）、`rsync`（同步脚本）、`gh`（GitHub CLI）
+- **跨平台 hook**：polyglot `.cmd` wrapper 解决 Windows CMD 兼容
+
+---
+
+## 五、Skill/Plugin/Capability 机制
+
+### 5.1 Skill 格式规范
+
+```markdown
+---
+name: skill-name-with-hyphens
+description: Use when [specific triggering conditions and symptoms]
+---
+```
+
+- `name`：仅允许字母、数字、连字符
+- `description`：必须以 `"Use when..."` 开头，**只描述触发条件，绝不描述工作流程**
+- frontmatter 总计 ≤ 1024 字符
+- 引导技能 <150 词，高频技能 <200 词，其他 <500 词
+
+### 5.2 发现与加载
+
+依赖宿主平台原生机制：
+- Claude Code：`plugin.json` 的 `"skills": ["./skills/"]` 声明，自动扫描 `SKILL.md`
+- Codex：`skills` 字段指向 `./skills/` 目录
+- OpenCode：JS plugin 在运行时动态 `config.skills.paths.push(superpowersSkillsDir)`
+
+### 5.3 编排机制
+
+**自动触发**（核心模式）：skill 的 description 被设计为强制触发语句（如 "You MUST use this before any creative work..."）
+
+**显式调用**：用户直接请求 "use systematic-debugging"
+
+### 5.4 权限与纪律
+
+- **Instruction Priority**：用户明确指令 > Superpowers skills > 默认系统提示
+- **HARD-GATE**：`<HARD-GATE>...</HARD-GATE>` 声明不可逾越的边界
+- **Red Flags 表**：列出代理可能绕过规则的合理化思维，并一一驳斥
+- **Iron Law**："NO SKILL WITHOUT A FAILING TEST FIRST"
+
+---
+
+## 六、配置系统
+
+### 6.1 版本同步配置（`.version-bump.json`）
+
+声明式版本管理系统：
+```json
+{
+  "files": [
+    { "path": "package.json", "field": "version" },
+    { "path": ".claude-plugin/plugin.json", "field": "version" },
+    { "path": ".codex-plugin/plugin.json", "field": "version" }
+  ],
+  "audit": { "exclude": ["CHANGELOG.md", ...] }
+}
+```
+
+- `bump-version.sh --check`：检测版本漂移
+- `bump-version.sh --audit`：扫描仓库中未声明的旧版本字符串
+- 支持 nested field path
+
+### 6.2 多宿主配置扩展点
+
+每个宿主有独立 manifest 文件，但共享 `skills/` 和 `assets/`：
+- `.claude-plugin/plugin.json` — 基础元数据
+- `.codex-plugin/plugin.json` — 额外含 interface、defaultPrompt、brandColor
+- `.cursor-plugin/plugin.json` — 额外含 agents、commands、hooks 路径
+
+新增宿主 = 新增 manifest 目录 + 适配 hooks/session-start 中的输出格式分支。
+
+---
+
+## 七、对 gxpm 的借鉴价值
+
+### 7.1 可直接复用的模式 ✅
+
+| 模式 | superpowers 实践 | gxpm 应用点 |
+|------|------------------|-------------|
+| **Skill 描述设计原则** | Description = When to Use, NOT What the Skill Does | gxpm capability/skill 描述应只写触发条件，不写执行流程 |
+| **子代理两阶段审查** | Spec compliance review → Code quality review | `verify` phase 可先检查 artifact 合规性，再检查代码质量 |
+| **SessionStart Hook 注入** | 引导语注入首条消息，避免系统消息 token 膨胀 | `hosts/claude.ts`、`hosts/codex.ts` 的引导注入逻辑 |
+| **TDD 应用于流程文档** | RED（压力测试）→ GREEN（最小 skill）→ REFACTOR（封堵漏洞） | `gxpm-tdd` skill 和 skill authoring 流程建立 eval 体系 |
+| **多宿主版本同步** | `.version-bump.json` + `bump-version.sh` | 引入 drift detection 到 `bun run check` |
+| **严格治理文档** | CLAUDE.md 作为面向代理的纪律手册 | 强化 `AGENTS.md` 中关于 PR 质量的标准 |
+
+### 7.2 应避免的陷阱 ❌
+
+| 陷阱 | 原因 | gxpm 应对 |
+|------|------|-----------|
+| **无独立运行时** | 完全依赖宿主平台的 skill 发现机制 | gxpm 必须坚持 `.gxpm/` 本地状态、Linear 集成、phase gate 等运行时基础设施 |
+| **零依赖的测试代价** | 集成测试依赖外部 `claude` CLI 命令和 API key，CI 难以稳定运行 | 利用 `bun test` 建立可自动化的单元测试和模拟测试 |
+| **纯 Markdown 流程控制** | 决策树、循环、状态转换都写在 Markdown 中，依赖 LLM 遵循能力 | 坚持**代码优先**的流程控制（`core/gate.ts`、`core/dispatch.ts`） |
+
+---
+
+## 八、关键文件映射
+
+| superpowers 文件/模式 | gxpm 对应位置/建议 |
+|-----------------------|---------------------|
+| `skills/using-superpowers/SKILL.md` | `skills/gxpm/SKILL.md` — 引导技能 |
+| `skills/subagent-driven-development/` | `skills/gxpm-explore-codebase/` 可借鉴其两阶段 review |
+| `skills/writing-skills/SKILL.md` | `docs/governance/skill-authoring.md` + `skills/gxpm-planning/` |
+| `hooks/session-start` | `hosts/claude.ts`、`hosts/codex.ts` — 引导注入逻辑 |
+| `.version-bump.json` | 可引入到 `package.json` 或 `bun run check` |
+| `tests/skill-triggering/` | 应在 `test/` 下建立 skill eval 框架 |
+| `CLAUDE.md` 的 PR 治理 | 强化 `AGENTS.md` 中关于 PR 质量的标准 |
+
+---
+
+## 九、适配建议
+
+1. **Skill 触发优化**：学习 superpowers 的 "description 只写触发条件" 原则，确保 gxpm skills 的 description 精确、症状导向，避免代理只读 description 而不读完整 skill。
+2. **子代理审查分离**：在 `verify` phase 引入 spec compliance check（是否按要求实现）与 code quality review（实现是否优雅）的分离。
+3. **Host adapter 引导注入**：研究 `hooks/session-start` 的注入位置策略，按宿主优化引导语注入位置（系统消息 vs 首条用户消息）。
+4. **版本漂移检测**：引入 `.version-bump.json` 机制，管理 `hosts/`、`skills/`、插件 manifest 的版本同步。
+5. **Skill eval 框架**：参考 `tests/skill-triggering/` 和 `tests/explicit-skill-requests/`，为 gxpm skills 建立压力测试和触发测试。
+
+---
+
+## 十、一句话总结
+
+> superpowers 是**当前业界最成熟的代理技能框架之一**，其 skill 设计哲学、子代理编排模式、多宿主适配经验是 gxpm 的**工程实践上游参考**；但 gxpm 作为独立产品，必须坚持 state graph、capability runtime、本地 artifact 管理等运行时基础设施，避免退化为纯文档框架。

package/docs/roadmap/initial-roadmap.md

@@ -0,0 +1,53 @@
+# gxpm 初始路线图
+
+## V0：替代型核心合同
+
+- 定义 `.gxpm/issues/<issue-id>/` 状态、产物和 evidence store。
+- 写出 gxpm 原生 phase guide 最小集合。
+- 建立 PMC/gstack replacement map。
+- 写出 capability runtime interface 文档。
+- 让 `skills/gxpm/SKILL.md` 能指导代理按 gxpm state graph 路由。
+
+## V0.1：Issue Runtime
+
+- Linear issue 读取、同步、写回策略。
+- 本地 state 优先级和冲突补偿。
+- checkpoint helper。
+- issue index 与 resume packet。
+- PMC `.omc/pm` 迁移/import 策略。
+
+## V0.2：Execution 与 Verification Runtime
+
+- local-verify/ac-check/verify/qa artifact schema。
+- worker dispatch、worktree、claim、handoff。
+- review/self-review/adversarial review contract。
+- QA evidence bundle：截图、console、network、route、commit。
+
+## V0.3：Browser Runtime
+
+- gstack browse daemon 能力重构为 gxpm browser runtime。
+- token、state file、tab/ref、console/network/screenshot 证据模型。
+- browser QA 与 issue phase 的统一写回。
+
+## V0.4：Release Runtime
+
+- PR body、changelog、version、branch hygiene。
+- ship、pr-check、land 的统一 release policy。
+- merge/deploy handoff gate。
+
+## V1：gxpm skill runtime
+
+- 模板生成 `SKILL.md`。
+- host abstraction：Codex、Claude、OpenClaw/其他 agent。
+- context recovery、timeline、learn。
+- 配置系统和 team init。
+- gstack skill preamble 能力重构为 gxpm preflight/runtime。
+
+## 长期方向
+
+- 项目级 dashboard。
+- 多 issue dependency graph。
+- 自动 overlap/directional scan。
+- 验证 profile 与风险级别自适应。
+- 跨工具/跨 agent 的统一 artifact viewer。
+- PMC/gstack 迁移命令与弃用计划。

package/docs/solutions/README.md

@@ -0,0 +1,45 @@
+# docs/solutions/
+
+最佳实践、故障恢复手册与工程决策记录的存放目录。
+
+## 命名规范
+
+采用描述性命名，建议包含组件或场景前缀：
+
+- `component-name-recovery.md` — 故障恢复手册
+- `pattern-name-practice.md` — 最佳实践
+- `decision-name-adr.md` — 架构决策记录
+
+## Frontmatter 标准
+
+每份文档必须以 YAML frontmatter 开头：
+
+```yaml
+---
+title: "文档标题"
+category: "recovery | practice | decision | playbook"
+date: "YYYY-MM-DD"
+severity: "critical | high | medium | low | info"
+component: "组件名或 *"
+tags: ["tag1", "tag2"]
+---
+```
+
+### 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 文档标题，简洁明确 |
+| `category` | 文档类型：recovery（恢复）、practice（实践）、decision（决策）、playbook（手册） |
+| `date` | 创建或最后更新日期 |
+| `severity` | 问题严重程度或重要性 |
+| `component` | 相关组件名，跨组件用 `*` |
+| `tags` | 便于检索的标签数组 |
+
+## 内容约定
+
+- 场景描述（Context）
+- 症状或触发条件（Symptoms / Triggers）
+- 解决步骤（Resolution Steps），编号列表
+- 预防措施（Prevention）
+- 相关链接（References）

package/docs/solutions/artifact-nesting-recovery.md

@@ -0,0 +1,58 @@
+---
+title: "artifact write 嵌套 payload 的修复"
+category: "recovery"
+date: "2026-05-04"
+severity: "low"
+component: "gxpm-cli"
+tags: ["artifact", "cli", "json"]
+---
+
+# artifact write 嵌套 payload 的修复
+
+## 场景
+
+使用 `gxpm artifact write` 直接传入包含 `payload` 字段的 JSON 时，CLI 可能将整个 JSON 包装为新的 `payload`，导致双重嵌套。
+
+## 症状
+
+读取 artifact 时看到结构：
+```json
+{
+  "payload": {
+    "payload": {
+      "criteria": [...]
+    }
+  }
+}
+```
+
+## 解决步骤
+
+1. **确认嵌套层级**
+   ```bash
+   ./bin/gxpm artifact read <issue-id> <artifact-type>
+   ```
+
+2. **重写 artifact（只传 payload 内容）**
+   ```bash
+   ./bin/gxpm artifact write <issue-id> <artifact-type> --json '{
+     "criteria": [...],
+     "status": "ready"
+   }'
+   ```
+   注意：不传外层的 `schemaVersion`、`issueId`、`type` 等字段，CLI 会自动填充。
+
+3. **验证修复**
+   ```bash
+   ./bin/gxpm artifact read <issue-id> <artifact-type> | jq '.payload'
+   ```
+
+## 预防措施
+
+- 使用 `artifact write` 时只提供业务数据（criteria、steps 等）
+- 不要手动构造完整的 artifact envelope
+- 不确定时先用 `artifact read` 查看当前结构
+
+## 相关
+
+- `core/artifacts.ts` — artifact 序列化逻辑

package/docs/solutions/session-context-restore-practice.md

@@ -0,0 +1,67 @@
+---
+title: "新会话通过 docs/ 恢复工程上下文"
+category: "practice"
+date: "2026-05-04"
+severity: "high"
+component: "*"
+tags: ["context", "session", "onboarding", "docs"]
+---
+
+# 新会话通过 docs/ 恢复工程上下文
+
+## 场景
+
+新 AI 会话启动时，chat 记忆为空，需要快速恢复项目的关键工程决策、约束和最佳实践。
+
+## 推荐步骤
+
+1. **读取架构概览**
+   ```bash
+   cat docs/architecture/gxpm-replacement-architecture.md
+   cat docs/architecture/gxpm-v0-contract.md
+   ```
+
+2. **查阅治理契约**
+   ```bash
+   cat docs/governance/development-contract.md
+   cat docs/governance/skill-authoring.md
+   ```
+
+3. **扫描解决方案库**
+   ```bash
+   ls docs/solutions/
+   # 按需读取相关恢复手册
+   ```
+
+4. **确认 host 规范**
+   ```bash
+   cat docs/specs/$(detect_host).md
+   ```
+
+5. **检查当前 issue 状态**
+   ```bash
+   ./bin/gxpm issue list
+   ./bin/gxpm issue next GXPM-N
+   ```
+
+## 优先级
+
+| 优先级 | 文档 | 目的 |
+|--------|------|------|
+| P0 | `AGENTS.md` | 项目级代理契约 |
+| P0 | `CONTEXT.md` | 共享语言/术语表 |
+| P1 | `docs/governance/development-contract.md` | 开发流程与约束 |
+| P1 | `docs/solutions/` | 工程决策与故障恢复 |
+| P2 | `docs/specs/` | Host 平台适配要求 |
+| P2 | `docs/architecture/` | 系统设计参考 |
+
+## 维护责任
+
+- 每次重大工程决策后，同步更新 `docs/solutions/`
+- 每次 host 适配变更后，同步更新 `docs/specs/`
+- 每月审查一次 `docs/` 目录，归档过时内容
+
+## 相关
+
+- `docs/governance/template-authoring.md`
+- `docs/research/pmc-gstack-skill-study.md`

package/docs/solutions/workflow/version-drift-recovery.md

@@ -0,0 +1,49 @@
+# Version Drift Recovery
+
+## Problem
+
+`bun run check` reports that `package.json` version does not match the `VERSION` file.
+
+## Root Causes
+
+- Manual edit of one file but not the other
+- Merge conflict resolution that left mismatched versions
+- Automated tooling that bumped only `package.json`
+
+## Recovery Steps
+
+1. Read both versions:
+   ```bash
+   cat VERSION
+   node -p "require('./package.json').version"
+   ```
+
+2. Decide the canonical version:
+   - If releasing: update both files to the desired version
+   - If the `VERSION` file is the source of truth: sync `package.json` to match
+   - If `package.json` is the source of truth: sync `VERSION` to match
+
+3. Apply the fix:
+   ```bash
+   # Option A: VERSION is canonical
+   npm version $(cat VERSION) --no-git-tag-version
+   
+   # Option B: package.json is canonical
+   node -p "require('./package.json').version" > VERSION
+   ```
+
+4. Verify:
+   ```bash
+   bun run check
+   ```
+
+5. Commit the change with a `GXPM-N` reference:
+   ```bash
+   git add VERSION package.json
+   git commit -m "chore(GXPM-N): sync version drift"
+   ```
+
+## Prevention
+
+- Always run `bun run check` before committing
+- The check runs automatically via `gxpm gate` in pre-commit hooks

package/docs/solutions/worktree-gate-recovery.md

@@ -0,0 +1,62 @@
+---
+title: "Worktree Gate 触发后的恢复步骤"
+category: "recovery"
+date: "2026-05-04"
+severity: "medium"
+component: "gxpm-cli"
+tags: ["git", "worktree", "hook", "gate"]
+---
+
+# Worktree Gate 触发后的恢复步骤
+
+## 场景
+
+在 canonical main checkout 上尝试创建 feature branch 时，gxpm 的 pre-checkout hook 阻止操作并提示：
+
+```
+[gxpm gate branch-policy] main-worktree-non-main: canonical main checkout must stay on main
+```
+
+## 症状
+
+- `git checkout -b feature-branch` 失败
+- 错误信息要求使用 dedicated git worktree
+
+## 解决步骤
+
+1. **切回 main 分支**
+   ```bash
+   git checkout main
+   ```
+
+2. **删除已创建的 feature branch（如有）**
+   ```bash
+   git branch -D feature-branch
+   ```
+
+3. **创建 git worktree**
+   ```bash
+   git worktree add /path/to/worktrees/feature-branch-name -b feature-branch-name
+   ```
+
+4. **进入 worktree 目录开始工作**
+   ```bash
+   cd /path/to/worktrees/feature-branch-name
+   ```
+
+5. **如需临时绕过 gate**
+   ```bash
+   GXPM_GATE_DISABLE=1 git checkout -b feature-branch
+   ```
+   > 仅用于紧急修复，不推荐常规使用。
+
+## 预防措施
+
+- 进入 implement 阶段前，先检查 `git status -sb`
+- 3+ 个来源不明文件时，默认走独立 worktree
+- 牢记：`git worktree add` 之后必须 `cd` 进新 worktree 才能动代码
+
+## 相关
+
+- `docs/governance/development-contract.md`
+- `hosts/claude.ts` — worktree enforcement 逻辑

package/docs/specs/README.md

@@ -0,0 +1,28 @@
+# docs/specs/
+
+Host 平台规范镜像的存放目录。
+
+## 目的
+
+将各 AI host 平台（Claude、Codex、Cursor 等）的规范、约束和适配要求以结构化文档形式沉淀，确保新会话可快速恢复 host 上下文，减少跨平台行为漂移。
+
+## 命名规范
+
+采用平台名称命名：
+
+- `claude.md` — Claude Code / Claude Desktop 规范
+- `codex.md` — OpenAI Codex CLI 规范
+- `cursor.md` — Cursor IDE 规范
+- `kimi.md` — Kimi Code CLI 规范（如适用）
+
+## 内容约定
+
+- 平台标识与版本范围
+- 支持的上下文长度与格式
+- 工具调用约定（MCP、hooks、skills）
+- 已知限制与 workaround
+- 与 gxpm 的集成点
+
+## 同步策略
+
+specs/ 文档应与 `hosts/` 代码目录保持同步。当 host adapter 发生变更时，需同步更新对应 spec 文档。

package/docs/specs/claude.md

@@ -0,0 +1,45 @@
+# Claude Host 规范镜像
+
+## 平台标识
+
+- **名称**: Claude Code / Claude Desktop
+- **上下文长度**: ~200K tokens（Claude 3.5 Sonnet）
+- **工具支持**: MCP、Skills、Projects
+
+## 上下文格式
+
+- 优先使用 `CLAUDE.md` 作为项目级契约文件
+- 支持 `.claude/skills/` 目录下的 SKILL.md 技能系统
+- 支持 frontmatter 元数据解析
+
+## 工具调用约定
+
+- **MCP**: 通过 `.mcp.json` 或 `CLAUDE.md` 中的 `mcpServers` 字段配置
+- **Skills**: 自动发现 `.claude/skills/*/SKILL.md`，按 scope（Project > User > Extra > Built-in）优先级解析
+- **Projects**: 支持项目级知识库，与 gxpm 的 `.gxpm/` 本地状态互补
+
+## 已知限制
+
+- 无法直接读取 `.gxpm/issues/` 的 JSON 状态文件，需要通过 gxpm CLI 查询
+- 不原生支持 Codex 的 `hooks.json` 机制
+- Skills 冲突时按 scope 优先级覆盖，不合并
+
+## gxpm 集成点
+
+- `hosts/claude.ts` — Claude 宿主适配器
+- `skills/gxpm/` — gxpm 核心 skill
+- SessionStart hook 注入 gxpm 能力提醒
+- UserPromptSubmit hook 在命中 GXPM-N 时注入 issue 上下文
+
+## 工作流差异
+
+| 阶段 | Claude 行为 |
+|------|-------------|
+| 启动 | 加载 CLAUDE.md + Skills + MCP |
+| 用户提示 | UserPromptSubmit hook 可注入 issue 上下文 |
+| 工具调用 | 直接调用 MCP tools，无额外沙箱 |
+| 文件编辑 | 使用 Edit/Write 工具，受 `/freeze` 约束 |
+
+## 同步策略
+
+当 `hosts/claude.ts` 发生变更时，同步更新本文档。

package/docs/specs/codex.md

@@ -0,0 +1,44 @@
+# Codex Host 规范镜像
+
+## 平台标识
+
+- **名称**: OpenAI Codex CLI
+- **上下文长度**: ~128K tokens（GPT-4o）
+- **工具支持**: MCP、Hooks、Plugins
+
+## 上下文格式
+
+- 优先使用 `AGENTS.md` 作为项目级契约文件
+- 支持 `.codex/` 目录下的 `hooks.json` 和 `config.toml`
+- 支持 `CLAUDE.md` 作为共享契约（与 Claude 兼容）
+
+## 工具调用约定
+
+- **MCP**: 通过 `.codex/config.toml` 或 `.mcp.json` 配置
+- **Hooks**: `hooks.json` 定义事件钩子（SessionStart、UserPromptSubmit 等）
+- **Plugins**: `plugin.json` 定义插件元数据
+
+## 已知限制
+
+- `apply_patch` 和写文件命令以 cwd 为路径根，worktree 切换后必须 `cd` 到新目录
+- `update_plan` 仅用于阶段内细分任务，**不要与 gxpm phase 平行**
+- 不原生支持 Claude 的 Skills 系统
+
+## gxpm 集成点
+
+- `hosts/codex.ts` — Codex 宿主适配器
+- `.codex/hooks/` — gxpm 注入的 hook 脚本
+- `githooks/gxpm-*` — 与 Codex 协同的 git hooks
+
+## 工作流差异
+
+| 阶段 | Codex 行为 |
+|------|------------|
+| 启动 | 加载 AGENTS.md + hooks + MCP |
+| 用户提示 | UserPromptSubmit hook 注入 issue 上下文 |
+| 文件编辑 | `apply_patch` / 写文件，需确认 cwd |
+| 计划更新 | `update_plan` 仅限子任务，不替代 gxpm phase |
+
+## 同步策略
+
+当 `hosts/codex.ts` 或 `.codex/hooks/` 发生变更时，同步更新本文档。