@geminix/gxpm 0.1.0

package/skills/gxpm-architecture/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gxpm-architecture
+description: Find deepening opportunities in a codebase using domain language and ADRs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+## 入口条件
+
+Load this skill when you see:
+- User asks to "improve architecture", "refactor", "make this more testable", or "reduce coupling".
+- A diagnosis surfaces an architectural root cause (tight coupling, shallow modules, missing seams).
+- A new module is introduced during `self-review` and its depth is questionable.
+- The codebase has grown and `CONTEXT.md` terms no longer map cleanly to file structure.
+
+### 核心术语
+
+Use these terms exactly in every suggestion:
+
+- **Module** — anything with an interface and an implementation (function, class, package, slice).
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where an interface lives; a place behaviour can be altered without editing in place.
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+
+Key principles:
+
+- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.**
+- **One adapter = hypothetical seam. Two adapters = real seam.**
+
+## 可操作流程
+
+### 1. Explore
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then explore the codebase organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
+- **Dependencies** — classify into [references/DEEPENING.md](references/DEEPENING.md) categories so the testing strategy is clear
+
+**Use CONTEXT.md vocabulary for the domain.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR.
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline:
+- **Naming a deepened module after a concept not in CONTEXT.md?** Add the term to `CONTEXT.md`.
+- **Sharpening a fuzzy term?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR so future architecture reviews don't re-suggest it.
+
+### 4. Interface design (optional)
+
+If the user wants to explore alternative interfaces for the chosen candidate, load [references/INTERFACE-DESIGN.md](references/INTERFACE-DESIGN.md) and run the parallel sub-agent pattern.
+
+### gxpm 集成
+
+- Run `/architecture` once every few days, or after `/diagnose` surfaces an architectural root cause.
+- During `self-review`, apply the deletion test to new modules introduced in the PR.
+- After `land`, if architecture recommendations were deferred, create a follow-up issue via `gxpm issue create --auto-id`.
+
+## 红旗清单 / 反模式
+
+Do NOT use architecture deepening when:
+
+- The user wants a purely cosmetic rename. Use `gxpm-refactor-safely` instead.
+- The code is already deep, well-tested, and stable. If the deletion test shows the module earns its keep, leave it alone.
+- The change is urgent and tactical (hotfix, security patch). Architecture work is strategic; defer it.
+- You have not read `CONTEXT.md` and the relevant ADRs. Surfacing friction without domain vocabulary produces shallow advice.
+
+**Counter-examples:** Proposing full seam extraction for a simple rename is wrong — architecture skill is for structural depth, not naming preferences. Suggesting to split a module that passes the deletion test because it "looks large" is wrong — size is not depth.
+
+## 验证清单 / 出口条件
+
+- [ ] 已阅读 `CONTEXT.md` 和相关 ADR
+- [ ] 已用删除测试（deletion test）排查候选模块
+- [ ] deepening opportunities 已按 Files / Problem / Solution / Benefits / Dependencies 结构化呈现
+- [ ] 用户使用 `CONTEXT.md` 术语确认候选方案
+- [ ] 如需接口设计，已运行并行 sub-agent 模式并给出有主见的推荐
+- [ ] 如需更新 `CONTEXT.md` 或新增 ADR，已 inline 完成

package/skills/gxpm-architecture/references/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](../SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem, SQLite for a real DB). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/skills/gxpm-architecture/references/INTERFACE-DESIGN.md

@@ -0,0 +1,44 @@
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](../SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](../SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/skills/gxpm-autopilot/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: gxpm-autopilot
+description: 开启 gxpm 自动驾驶模式。使用 Autopilot Grant 持久化用户授权，让代理在授权 profile 内自主完成 issue delivery。
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+## Host Preamble
+
+Target host: OpenAI Codex CLI.
+
+```bash
+GXPM_ROOT="${GXPM_ROOT:-$PWD}"
+GXPM_STATE_DIR="${GXPM_STATE_DIR:-$GXPM_ROOT/.gxpm}"
+export GXPM_ROOT GXPM_STATE_DIR
+```
+
+# gxpm Autopilot
+
+## 入口条件
+
+**何时触发**
+- 用户明确要求"自动驾驶模式"。
+- 用户选择 autopilot command prompt。
+- 用户授权代理不再逐步确认而完成整个 gxpm 工作流。
+- 用户说"全程交给你"、"不需要确认"等类似 utterance。
+
+**前置条件**
+- 需要 issue（已有 issue ID，或通过 `--auto-id` 新建）。
+- 用户已明确授权代理自主行动。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- Hard stop 出现且需要专项分析时 → `/gxpm-diagnose`、 `/gxpm-debug-issue`、 `/gxpm-grill`
+- 仅需要单阶段操作（如只写 plan 或只 review） → 使用对应专项 skill，不启动 autopilot
+- 用户未明确授权 → 不加载此 skill，按常规逐步确认推进
+
+## 可操作流程
+
+### 启动
+
+若用户已给出 issue：
+
+```bash
+gxpm autopilot start <issue-id> --profile full-delivery --prompt "<user prompt>"
+gxpm issue status <issue-id>
+gxpm issue next <issue-id>
+```
+
+若用户只给任务，没有 issue：
+
+```bash
+gxpm autopilot start --auto-id --profile full-delivery --prompt "<user prompt>"
+gxpm issue list
+```
+
+随后按 `gxpm issue next <issue-id>` 推进。不要停在"我可以继续"的确认话术里。
+
+### 授权边界
+
+`full-delivery` 授权以下动作：
+
+- 创建/推进 issue phases
+- 写入和更新 gxpm artifacts
+- 创建或使用 worktree
+- 修改代码和文档
+- 运行本地验证、lint、测试、浏览器 QA
+- 创建 commit、push branch、创建或更新 PR
+- 在验证通过后 merge/land
+- land 后执行 cleanup
+
+### 核心原则
+
+Autopilot 的核心不是跳过治理，而是把用户授权落到 `autopilot-grant` artifact。active grant 允许代理在 profile 范围内自主规划、实施、验证、开 PR、merge/land 和清理；phase gate、artifact、验证证据仍然必须完整保留。
+
+### 命令
+
+```bash
+gxpm autopilot status <issue-id>
+gxpm autopilot list
+gxpm autopilot stop <issue-id> --reason "<reason>"
+```
+
+## 红旗清单 / 反模式
+
+- **STOP：用户明确停止或撤销授权。** 立即停止，写入阻塞原因到当前阶段 artifact。
+- **STOP：需要密钥、账号登录、付费外部 API 或用户私密输入。** 先写入阻塞原因，停止自动驾驶。
+- **STOP：涉及生产数据、破坏性迁移或无法自动回滚的操作。** 必须 human-in-the-loop。
+- **STOP：merge conflict、验证失败或安全/权限边界无法自主解决。** 停止并记录。
+- **STOP：当前 repo 明确规则与 Autopilot Grant 冲突。** 遵守 repo 规则，停止自动驾驶。
+- **STOP：在 allowed actions 内反复询问用户确认。** active grant 的含义就是无需反复确认；只在 hard stop 时停止。
+- **STOP：不要将 autopilot 视为跳过阶段门。** phase gate、artifact、验证证据仍然必须完整保留。
+- **STOP：`stop_hook_active` 已经为 true 时不再重复阻止。** 避免无限循环。
+- **危险信号：** 用户未授权不可逆操作却试图 merge/land → 拒绝并请求显式授权。
+
+## 验证清单 / 出口条件
+
+- [ ] `autopilot-grant` artifact 已持久化（含 issue、profile、prompt）。
+- [ ] `gxpm issue status` 和 `gxpm issue next` 已执行。
+- [ ] 各阶段 artifact、phase gate、验证证据完整保留（与 manual 模式一致）。
+- [ ] Hard stop 时阻塞原因已写入当前阶段 artifact。
+- [ ] 到达 terminal phase（land + cleanup 完成）或用户停止/撤销时正常结束。
+- [ ] `gxpm autopilot stop` 已调用并记录 reason。
+
+**失败时路由**
+- 调试/验证失败 → `/gxpm-diagnose` 或 `/gxpm-debug-issue`
+- 需求/架构决策受阻 → `/gxpm-grill`
+- 代码审查问题 → `/gxpm-review-changes`
+- 安全/权限问题 → 停止 autopilot，等待 human-in-the-loop
+
+## 常见说辞表
+
+| 用户 utterance | 推荐回应 |
+|----------------|----------|
+| "全程交给你，不用确认。" | 启动 `gxpm autopilot start --auto-id --profile full-delivery --prompt "..."`，然后按 `gxpm issue next` 推进。 |
+| "帮我自动驾驶 GXPM-42。" | 启动 `gxpm autopilot start GXPM-42 --profile full-delivery --prompt "..."`，然后按 `gxpm issue next` 推进。 |
+| "可以停了。" / "暂停 autopilot" | `gxpm autopilot stop <issue-id> --reason "User requested pause"`，报告当前阶段和已产出 artifact。 |
+| "autopilot 到哪了？" | `gxpm autopilot status <issue-id>`，结合 `gxpm issue status` 汇报当前阶段和 next 推荐。 |

package/skills/gxpm-autopilot/SKILL.md.tmpl

@@ -0,0 +1,107 @@
+---
+name: gxpm-autopilot
+description: 开启 gxpm 自动驾驶模式。使用 Autopilot Grant 持久化用户授权，让代理在授权 profile 内自主完成 issue delivery。
+---
+
+{{PREAMBLE}}
+
+# gxpm Autopilot
+
+## 入口条件
+
+**何时触发**
+- 用户明确要求"自动驾驶模式"。
+- 用户选择 autopilot command prompt。
+- 用户授权代理不再逐步确认而完成整个 gxpm 工作流。
+- 用户说"全程交给你"、"不需要确认"等类似 utterance。
+
+**前置条件**
+- 需要 issue（已有 issue ID，或通过 `--auto-id` 新建）。
+- 用户已明确授权代理自主行动。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- Hard stop 出现且需要专项分析时 → `/gxpm-diagnose`、 `/gxpm-debug-issue`、 `/gxpm-grill`
+- 仅需要单阶段操作（如只写 plan 或只 review） → 使用对应专项 skill，不启动 autopilot
+- 用户未明确授权 → 不加载此 skill，按常规逐步确认推进
+
+## 可操作流程
+
+### 启动
+
+若用户已给出 issue：
+
+```bash
+gxpm autopilot start <issue-id> --profile full-delivery --prompt "<user prompt>"
+gxpm issue status <issue-id>
+gxpm issue next <issue-id>
+```
+
+若用户只给任务，没有 issue：
+
+```bash
+gxpm autopilot start --auto-id --profile full-delivery --prompt "<user prompt>"
+gxpm issue list
+```
+
+随后按 `gxpm issue next <issue-id>` 推进。不要停在"我可以继续"的确认话术里。
+
+### 授权边界
+
+`full-delivery` 授权以下动作：
+
+- 创建/推进 issue phases
+- 写入和更新 gxpm artifacts
+- 创建或使用 worktree
+- 修改代码和文档
+- 运行本地验证、lint、测试、浏览器 QA
+- 创建 commit、push branch、创建或更新 PR
+- 在验证通过后 merge/land
+- land 后执行 cleanup
+
+### 核心原则
+
+Autopilot 的核心不是跳过治理，而是把用户授权落到 `autopilot-grant` artifact。active grant 允许代理在 profile 范围内自主规划、实施、验证、开 PR、merge/land 和清理；phase gate、artifact、验证证据仍然必须完整保留。
+
+### 命令
+
+```bash
+gxpm autopilot status <issue-id>
+gxpm autopilot list
+gxpm autopilot stop <issue-id> --reason "<reason>"
+```
+
+## 红旗清单 / 反模式
+
+- **STOP：用户明确停止或撤销授权。** 立即停止，写入阻塞原因到当前阶段 artifact。
+- **STOP：需要密钥、账号登录、付费外部 API 或用户私密输入。** 先写入阻塞原因，停止自动驾驶。
+- **STOP：涉及生产数据、破坏性迁移或无法自动回滚的操作。** 必须 human-in-the-loop。
+- **STOP：merge conflict、验证失败或安全/权限边界无法自主解决。** 停止并记录。
+- **STOP：当前 repo 明确规则与 Autopilot Grant 冲突。** 遵守 repo 规则，停止自动驾驶。
+- **STOP：在 allowed actions 内反复询问用户确认。** active grant 的含义就是无需反复确认；只在 hard stop 时停止。
+- **STOP：不要将 autopilot 视为跳过阶段门。** phase gate、artifact、验证证据仍然必须完整保留。
+- **STOP：`stop_hook_active` 已经为 true 时不再重复阻止。** 避免无限循环。
+- **危险信号：** 用户未授权不可逆操作却试图 merge/land → 拒绝并请求显式授权。
+
+## 验证清单 / 出口条件
+
+- [ ] `autopilot-grant` artifact 已持久化（含 issue、profile、prompt）。
+- [ ] `gxpm issue status` 和 `gxpm issue next` 已执行。
+- [ ] 各阶段 artifact、phase gate、验证证据完整保留（与 manual 模式一致）。
+- [ ] Hard stop 时阻塞原因已写入当前阶段 artifact。
+- [ ] 到达 terminal phase（land + cleanup 完成）或用户停止/撤销时正常结束。
+- [ ] `gxpm autopilot stop` 已调用并记录 reason。
+
+**失败时路由**
+- 调试/验证失败 → `/gxpm-diagnose` 或 `/gxpm-debug-issue`
+- 需求/架构决策受阻 → `/gxpm-grill`
+- 代码审查问题 → `/gxpm-review-changes`
+- 安全/权限问题 → 停止 autopilot，等待 human-in-the-loop
+
+## 常见说辞表
+
+| 用户 utterance | 推荐回应 |
+|----------------|----------|
+| "全程交给你，不用确认。" | 启动 `gxpm autopilot start --auto-id --profile full-delivery --prompt "..."`，然后按 `gxpm issue next` 推进。 |
+| "帮我自动驾驶 GXPM-42。" | 启动 `gxpm autopilot start GXPM-42 --profile full-delivery --prompt "..."`，然后按 `gxpm issue next` 推进。 |
+| "可以停了。" / "暂停 autopilot" | `gxpm autopilot stop <issue-id> --reason "User requested pause"`，报告当前阶段和已产出 artifact。 |
+| "autopilot 到哪了？" | `gxpm autopilot status <issue-id>`，结合 `gxpm issue status` 汇报当前阶段和 next 推荐。 |

package/skills/gxpm-browser/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: gxpm-browser
+description: Headless browser automation for QA evidence capture. Use when user asks to test a web page, take a screenshot, verify an element, fill a form, or capture browser evidence for an issue.
+status: stable
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# gxpm-browser
+
+Minimal headless browser CLI built on Playwright. Designed for gxpm evidence
+capture and QA automation, not general web scraping.
+
+## 入口条件
+
+- User asks to "test the site", "open in browser", "take a screenshot"
+- QA phase needs browser/runtime proof
+- Verify-gate requires visual evidence
+- User describes a bug that needs reproduction with screenshot
+
+## 可操作流程
+
+## Commands
+
+### Navigate and inspect
+
+```bash
+gxpm-browser navigate <url> [--json]
+```
+
+Returns page title and final URL after `networkidle`.
+
+### Screenshot evidence
+
+```bash
+gxpm-browser screenshot <url> [--out <path>] [--full-page] [--json]
+```
+
+Default output: `/tmp/gxpm-browser-<ts>.png`.
+If run inside a repo with an active issue, pass `--issueid <id>` to write to
+`.gxpm/issues/<id>/evidence/browser/` automatically.
+
+### Assert element text
+
+```bash
+gxpm-browser assert <url> --selector <css> --text <expected> [--json]
+```
+
+Exits 1 if the first matching element does not contain the expected text.
+Use this for pass/fail QA gates.
+
+### Interact
+
+```bash
+gxpm-browser click <url> --selector <css> [--json]
+gxpm-browser type <url> --selector <css> --text <value> [--json]
+```
+
+### Headed mode for debugging
+
+```bash
+gxpm-browser screenshot <url> --no-headless
+```
+
+Opens a visible Chrome window. Use sparingly; default is headless.
+
+
+## Evidence path
+
+When `--issueid` is provided, screenshots are written to:
+
+```
+.gxpm/issues/<issue-id>/evidence/browser/screenshot-<ts>.png
+```
+
+Link them in `qa-findings` or `verify-findings` artifacts:
+
+```bash
+gxpm artifact write <issue-id> qa-findings --json '{"evidence":["browser/screenshot-12345.png"]}'
+```
+
+## Limitations
+
+- Uses Chromium/Chrome via Playwright. Requires Chrome or `playwright install chromium`.
+- No persistent session state between commands (each command launches a fresh browser).
+- No network interception or request mocking; use `agent-browser` for advanced automation.
+- cmux browser session investigation is a separate path (see main gxpm skill).
+
+
+## 红旗清单 / 反模式
+
+- **禁止用于通用网页抓取** — 本 skill 仅限 gxpm 证据捕获与 QA 自动化
+- 不要在没有明确 QA 需求或证据要求时随意截图
+- 不要在 verify-gate 未要求时产生冗余的浏览器证据
+
+## 验证清单 / 出口条件
+
+- [ ] 浏览器操作成功执行（页面加载、元素验证、截图等）
+- [ ] 证据文件保存到正确路径并可在后续 QA 环节引用
+- [ ] 截图/记录与 issue 中描述的 bug 或验收标准对应
+- [ ] 相关证据已归档或链接到 verify-gate 交付物
+
+## Read Next
+
+- `docs/governance/development-contract.md`
+- Main `/gxpm` skill for QA phase gate details

package/skills/gxpm-browser/SKILL.md.tmpl

@@ -0,0 +1,41 @@
+---
+name: gxpm-browser
+description: Headless browser automation for QA evidence capture. Use when user asks to test a web page, take a screenshot, verify an element, fill a form, or capture browser evidence for an issue.
+status: stable
+---
+
+# gxpm-browser
+
+Minimal headless browser CLI built on Playwright. Designed for gxpm evidence
+capture and QA automation, not general web scraping.
+
+## 入口条件
+
+- User asks to "test the site", "open in browser", "take a screenshot"
+- QA phase needs browser/runtime proof
+- Verify-gate requires visual evidence
+- User describes a bug that needs reproduction with screenshot
+
+## 可操作流程
+
+{{REFERENCE:commands}}
+
+{{REFERENCE:evidence-path}}
+
+## 红旗清单 / 反模式
+
+- **禁止用于通用网页抓取** — 本 skill 仅限 gxpm 证据捕获与 QA 自动化
+- 不要在没有明确 QA 需求或证据要求时随意截图
+- 不要在 verify-gate 未要求时产生冗余的浏览器证据
+
+## 验证清单 / 出口条件
+
+- [ ] 浏览器操作成功执行（页面加载、元素验证、截图等）
+- [ ] 证据文件保存到正确路径并可在后续 QA 环节引用
+- [ ] 截图/记录与 issue 中描述的 bug 或验收标准对应
+- [ ] 相关证据已归档或链接到 verify-gate 交付物
+
+## Read Next
+
+- `docs/governance/development-contract.md`
+- Main `/gxpm` skill for QA phase gate details

package/skills/gxpm-browser/references/commands.md

@@ -0,0 +1,43 @@
+## Commands
+
+### Navigate and inspect
+
+```bash
+gxpm-browser navigate <url> [--json]
+```
+
+Returns page title and final URL after `networkidle`.
+
+### Screenshot evidence
+
+```bash
+gxpm-browser screenshot <url> [--out <path>] [--full-page] [--json]
+```
+
+Default output: `/tmp/gxpm-browser-<ts>.png`.
+If run inside a repo with an active issue, pass `--issueid <id>` to write to
+`.gxpm/issues/<id>/evidence/browser/` automatically.
+
+### Assert element text
+
+```bash
+gxpm-browser assert <url> --selector <css> --text <expected> [--json]
+```
+
+Exits 1 if the first matching element does not contain the expected text.
+Use this for pass/fail QA gates.
+
+### Interact
+
+```bash
+gxpm-browser click <url> --selector <css> [--json]
+gxpm-browser type <url> --selector <css> --text <value> [--json]
+```
+
+### Headed mode for debugging
+
+```bash
+gxpm-browser screenshot <url> --no-headless
+```
+
+Opens a visible Chrome window. Use sparingly; default is headless.

package/skills/gxpm-browser/references/evidence-path.md

@@ -0,0 +1,20 @@
+## Evidence path
+
+When `--issueid` is provided, screenshots are written to:
+
+```
+.gxpm/issues/<issue-id>/evidence/browser/screenshot-<ts>.png
+```
+
+Link them in `qa-findings` or `verify-findings` artifacts:
+
+```bash
+gxpm artifact write <issue-id> qa-findings --json '{"evidence":["browser/screenshot-12345.png"]}'
+```
+
+## Limitations
+
+- Uses Chromium/Chrome via Playwright. Requires Chrome or `playwright install chromium`.
+- No persistent session state between commands (each command launches a fresh browser).
+- No network interception or request mocking; use `agent-browser` for advanced automation.
+- cmux browser session investigation is a separate path (see main gxpm skill).