@geminix/gxpm 0.1.0

package/skills/gxpm-explore-codebase/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gxpm-explore-codebase
+description: Navigate and understand codebase structure using the knowledge graph. Use when user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase.
+---
+
+## gxpm-explore-codebase
+
+### 入口条件
+
+**Skill boundary:**
+- If you are debugging a **specific bug or error**, load `/gxpm-debug-issue` or `/gxpm-diagnose` instead.
+- If you are **refactoring** code you do not yet understand, load this skill first, then `/gxpm-refactor-safely`.
+
+Use available code intelligence tools (e.g., GitNexus MCP, grep, ReadFile) to explore and understand the codebase.
+
+### 可操作流程
+
+1. Run `list_repos` to discover indexed repositories.
+2. Run `query` with natural language to find execution flows and symbols.
+3. Use `context` on a specific symbol for 360-degree view (callers, callees, references).
+4. Use `impact` before making changes to analyze blast radius.
+5. Use `route_map` and `shape_check` to understand API consumption patterns.
+
+> **Tips**
+> - Start broad (repo list, architecture) then narrow down to specific areas.
+> - Use `cypher` for complex structural queries against the knowledge graph.
+> - Use `detect_changes` to map git diffs to affected execution flows.
+
+### 红旗清单 / 反模式
+
+- ALWAYS start with the narrowest query possible, then expand.
+- Use compact output modes when available. Only escalate to full dumps when necessary.
+
+### 验证清单 / 出口条件
+
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.

package/skills/gxpm-explore-codebase/scripts/summarize-communities.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * Summarize GitNexus community data into a compact markdown table.
+ * Reads JSON from stdin (e.g., list_communities output) and writes markdown to stdout.
+ *
+ * Usage:
+ *   cat communities.json | bun run summarize-communities.ts
+ */
+
+interface Community {
+  name?: string;
+  size?: number;
+  cohesion?: number;
+  dominantLanguage?: string;
+}
+
+const chunks: Buffer[] = [];
+for await (const chunk of Bun.stdin.stream()) {
+  chunks.push(Buffer.from(chunk));
+}
+
+const json = Buffer.concat(chunks).toString("utf8").trim();
+
+if (!json) {
+  console.error("No input received. Pipe JSON to stdin.");
+  process.exit(1);
+}
+
+try {
+  const data = JSON.parse(json) as { communities?: Community[] };
+  const communities = data.communities ?? [];
+
+  if (communities.length === 0) {
+    console.log("No communities found.");
+    process.exit(0);
+  }
+
+  console.log("| Community | Size | Cohesion | Language |");
+  console.log("|-----------|------|----------|----------|");
+
+  for (const community of communities) {
+    const name = community.name ?? "unnamed";
+    const size = community.size ?? 0;
+    const cohesion = community.cohesion != null ? community.cohesion.toFixed(2) : "n/a";
+    const language = community.dominantLanguage ?? "mixed";
+    console.log(`| ${name} | ${size} | ${cohesion} | ${language} |`);
+  }
+} catch (error) {
+  console.error("Failed to parse JSON:", error);
+  process.exit(1);
+}

package/skills/gxpm-feedback/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: gxpm-feedback
+description: Create feedback issues in the gxpm source repository when the agent discovers problems or improvement opportunities during gxpm workflow execution. Use when the agent notices a gxpm bug, process flaw, skill deficiency, or has a suggestion for the gxpm tool itself.
+---
+
+# gxpm Feedback
+
+Create structured feedback issues in the gxpm source repository so that problems and improvements are tracked, triaged, and eventually resolved.
+
+## 入口条件
+
+**何时触发**
+- 代理在执行 gxpm 流程时发现 gxpm **自身**的 bug 或缺陷。
+- 代理发现 gxpm 流程、阶段门控、或 skill 设计存在可改进之处。
+- 代理遇到 gxpm CLI 报错、意外行为、或边界情况未处理。
+- 代理认为某个 skill 的指令存在歧义、遗漏、或反模式未覆盖。
+- 代理发现文档（CANON.md、AGENTS.md、CONTEXT.md、governance docs）与代码实现不一致。
+
+**前置条件**
+- `feedback.gxpmSourceRoot` 已配置（指向 gxpm 源码仓库的绝对路径）。
+- 代理已识别问题的具体表现和影响范围。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需要调试定位根因 → `/gxpm-debug-issue`
+- 需要提交代码修复 → `/gxpm-implementer`
+- 需要架构讨论 → `/gxpm-grill`
+- 只是对当前业务 issue 有疑问 → 在当前 skill 内解决，不要创建 feedback issue
+
+## 可操作流程
+
+### 1. 判断是否应该创建反馈 issue
+
+在以下情况**不要**创建 feedback issue：
+- 问题是当前业务项目的代码问题，不是 gxpm 工具本身的问题。
+- 问题只是代理对 gxpm 流程不熟悉（先查文档，确认确实是缺陷再反馈）。
+- 问题是暂时性的网络/环境故障，不可复现。
+
+### 2. 选择反馈分类
+
+| 分类 | 说明 | 对应 issueType |
+|---|---|---|
+| `bug` | gxpm CLI 崩溃、状态机异常、artifact 丢失、同步失败等 | `meta` |
+| `enhancement` | 新功能请求、现有功能扩展 | `feature` |
+| `process` | 流程改进、阶段门控调整、skill 结构优化 | `meta` |
+| `documentation` | 文档与代码不一致、文档缺失、术语模糊 | `meta` |
+
+默认 issueType 为 `meta`（轻量级 rigor）。如果是较大的功能请求，用 `feature`。
+
+### 3. 收集反馈内容
+
+在创建 issue 前，收集以下信息：
+
+1. **What** — 具体发现了什么问题或有什么建议（一句话概括）。
+2. **Context** — 在哪个阶段、执行什么命令、使用什么 skill 时发现的。
+3. **Reproduction** — 如果是 bug，提供复现步骤或相关日志片段。
+4. **Impact** — 这个问题对 gxpm 流程的影响程度（阻塞 / 困扰 / 轻微）。
+5. **Suggestion** — 建议的修复方向或改进方案（可选但推荐）。
+
+### 4. 创建反馈 issue
+
+使用 CLI 命令：
+
+```bash
+gxpm feedback create --auto-id \
+  --title "<一句话标题>" \
+  --description "<详细描述>" \
+  --type meta
+```
+
+参数说明：
+- `--auto-id`：自动分配下一个可用 ID（推荐）。
+- `--title`：简洁的问题/建议标题（50 字以内）。
+- `--description`：包含 What / Context / Reproduction / Impact / Suggestion 的完整描述。
+- `--type`：`meta`（默认，流程/文档/小缺陷）、`feature`（功能请求）、`spike`（需要调研）。
+
+命令执行后，会返回创建的 issue ID 和在 gxpm 源码目录中的 statePath。
+
+### 5. 记录溯源信息（可选但推荐）
+
+如果当前正在处理某个业务 issue，在业务 issue 的 memory 或 evidence 中记录：
+
+```markdown
+## Feedback Created
+- 反馈 issue: `<gxpm-source-issue-id>`
+- 原因: <简要说明>
+- 创建时间: <ISO 时间>
+```
+
+这有助于后续审计时理解为什么当时创建了反馈。
+
+## 红旗清单 / 反模式
+
+- **STOP：把业务 bug 当成 gxpm bug。** 如果问题是当前项目代码导致的，修复业务代码，不要创建 gxpm feedback issue。
+- **STOP：空标题或空描述。** 没有上下文的 feedback issue 对维护者毫无价值；必须包含 Context 和 Impact。
+- **STOP：重复反馈。** 创建前先检查 gxpm 源码目录 `.gxpm/issues/` 中是否已有相似标题或描述的 issue。
+- **STOP：在 feedback issue 中讨论业务实现。** Feedback issue 只讨论 gxpm 工具本身。
+- **危险信号：** "这个问题很小，不值得记录。" → 小问题的积累会腐蚀流程纪律。只要确认是 gxpm 的缺陷，就应该记录。
+- **危险信号：** "我现在就顺便修了。" → 如果代理在执行业务 issue 时顺手修 gxpm，会导致业务范围蔓延。创建 feedback issue，让修复走独立的 gxpm 流程。
+
+## 验证清单 / 出口条件
+
+- [ ] 确认问题是 gxpm 工具本身的问题，不是业务项目的问题。
+- [ ] 已检查是否存在重复反馈。
+- [ ] 反馈包含完整的 What / Context / Impact（Reproduction 和 Suggestion 视情况）。
+- [ ] 已成功执行 `gxpm feedback create` 并拿到 issue ID。
+- [ ] （可选）在当前业务 issue 的 memory 中记录了反馈溯源。
+- [ ] feedback issue 已自动进入 `triage` 阶段，等待 gxpm 维护者分类。
+
+**失败时路由**
+- `feedback.gxpmSourceRoot` 未配置 → 提示用户配置：`gxpm config set feedback.gxpmSourceRoot </absolute/path>`
+- 不确定是 gxpm bug 还是业务 bug → `/gxpm-debug-issue` 先定位根因
+- 反馈内容需要架构讨论 → `/gxpm-grill`
+
+## 常见说辞表
+
+| 用户/代理 utterance | 推荐回应 |
+|---|---|
+| "gxpm 又报错了，是不是 bug？" | "先确认报错是 gxpm CLI/流程导致的，还是当前项目代码导致的。如果是 gxpm 本身的问题，收集 Context 和 Reproduction，然后创建 feedback issue。" |
+| "这个 skill 的指令好像有问题。" | "具体哪里有问题？是指令歧义、边界未覆盖、还是与代码实现不一致？确认后创建 feedback issue，附上建议的修改方向。" |
+| "我觉得 gxpm 应该增加某某功能。" | "这是个 enhancement 建议。用 `gxpm feedback create --type feature --title ... --description ...` 记录，描述中要包含使用场景和预期行为。" |
+| "这个问题太小了，不值得记录。" | "小问题不记录会积累成流程债务。只要确认是 gxpm 缺陷，就值得一个 feedback issue。" |
+| "我在跑业务 issue，顺便把 gxpm 这个 bug 修了吧。" | "不要范围蔓延。创建 feedback issue 记录它，让修复走独立的 gxpm 流程，保证业务 issue 的聚焦。" |

package/skills/gxpm-grill/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: gxpm-grill
+description: Grilling session that challenges plans against the domain model and sharpens terminology. Use when user wants to stress-test a plan, align on requirements, challenge assumptions, or make architecture decisions.
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# Grill
+
+Interview the user relentlessly about every aspect of a plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+## 入口条件
+
+**何时触发**
+- 用户 utterances: "grill me", "let's align", "challenge this plan", "does this make sense?"
+- Plan 或 design 存在未解决的依赖、未定义术语或隐含假设。
+- Issue 从 `triage` 移动到 `plan` 时没有书面的 `acceptance-contract`。
+- 出现术语漂移：用户用多个不同名称描述同一概念。
+
+**前置条件**
+- 有 plan、design、issue 或概念需要澄清。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 用户要求 quick code snippet 或 one-line fix → 直接实现，不 grill
+- 需求已完全明确，有 acceptance criteria，无歧义 → 不 grill，直接进入 plan/implement
+- 用户明确说 "just do it" 或 "no need to discuss" → 不 grill
+- 时间压力极大且错误成本低于讨论成本 → 不 grill
+- 需要代码调试 → `/gxpm-debug-issue`
+- 需要产出实现计划 → `/gxpm-planning`
+- 需要 issue 分类 → `/gxpm-triage`
+
+## 可操作流程
+
+### 1. Ask one question at a time
+
+Wait for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead.
+
+### 2. Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately:
+
+> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### 3. Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term:
+
+> "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### 4. Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about boundaries between concepts.
+
+### 5. Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it:
+
+> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+
+## 红旗清单 / 反模式
+
+- **STOP：不要对 clear one-line fix 进行 grilling。** User says "Add a login button to the header." → 直接实现。Grill 仅当 login flow 涉及 CONTEXT.md 中没有的新领域概念。
+- **STOP：不要对 fully specified、无歧义的需求 grilling。** 浪费用户时间。
+- **STOP：不要跳过 grilling 直接 coding（当涉及新领域概念时）。** User says "Let's build a real-time sync system." → 必须先 grill：WebSockets, SSE, polling, CRDTs？哪种一致性模型？失败模式是什么？
+- **STOP：不要 batch 文档更新。** 决策结晶时立即内联更新文档，不要攒到后面。
+- **危险信号：**  grilling 过程中 issue 范围不断扩大 → 停止，要求用户先拆分 issue 再继续。
+- **危险信号：** 同一概念出现多个名称而用户不认为它们是同义词 → 强制选择一个并写入 CONTEXT.md。
+
+## 验证清单 / 出口条件
+
+- [ ] 每个设计分支的依赖已逐层解决。
+- [ ] 术语已统一并记录到 `CONTEXT.md`。
+- [ ] `triage → plan` 阶段：`acceptance-contract` 已更新并书面化。
+- [ ] `plan` 阶段：`implementation-plan` 已更新，关键实现决策已解决。
+- [ ]  grilling 过程中创建的 ADR 已记录到 issue artifact history（通过 `gxpm artifact write`）。
+- [ ] 用户和代理对 plan 达成 shared understanding。
+
+**失败时路由**
+-  grilling 后仍无法做架构决策 → `/gxpm-architecture`
+-  issue 需要重新分类 → `/gxpm-triage`
+-  需要进一步代码调研 → `/gxpm-explore-codebase`
+
+## 常见说辞表
+
+| 用户 utterance | 推荐回应 |
+|----------------|----------|
+| "grill me" / "challenge this plan" | "好。我们从最不确定的假设开始。请确认 [关键假设1] 是否成立？如果变化，会影响哪些决策？" |
+| "let's align" | "我先梳理当前计划中未解决的依赖项和未定义术语，然后逐一确认。" |
+| "does this make sense?" | "我先检查计划与领域模型的一致性，然后指出冲突或缺失的约束。" |
+| "Add a login button to the header."（清晰请求） | "这个请求很清晰，直接实现。如果 login flow 涉及新领域概念，我再 grill。" |
+| "Let's build a real-time sync system."（模糊宏大） | "'Real-time' 涵盖 WebSockets、SSE、polling、CRDTs。我们先对齐：选哪种？一致性模型？失败模式？" |
+
+## Documentation side effects
+
+As decisions crystallise, update project documentation inline. Do not batch these up — capture them as they happen.
+
+### Update CONTEXT.md
+
+When a term is resolved, update `CONTEXT.md` right there. Use this format:
+
+```markdown
+## Language
+
+**Issue tracker**:
+The tool that hosts a repo's issues — GitHub Issues, Linear, a local markdown convention, or similar.
+_Avoid_: backlog manager, backlog backend, issue host
+
+**Issue**:
+A single tracked unit of work inside an **Issue tracker**.
+_Avoid_: ticket
+
+## Relationships
+
+- An **Issue tracker** holds many **Issues**
+- An **Issue** carries one **Triage role** at a time
+
+## Flagged ambiguities
+
+- "backlog" was previously used to mean both the *tool* and the *body of work* — resolved.
+```
+
+Create `CONTEXT.md` lazily — only when you have the first term to write. Do not couple it to implementation details; only include terms meaningful to domain experts.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If any of the three is missing, skip the ADR. Write ADRs under `docs/adr/` using this format:
+
+```markdown
+# ADR-000N: Title
+
+## Status
+
+Accepted
+
+## Context
+
+What is the forcing function? What constraints exist?
+
+## Decision
+
+What are we doing?
+
+## Consequences
+
+What becomes easier? What becomes harder?
+```
+
+
+## gxpm integration
+
+- Before leaving `triage`, use grilling to clarify issue scope and write the `acceptance-contract`.
+- During `plan`, use grilling to resolve implementation decisions and write the `implementation-plan`.
+- Record any ADR created during grilling in the issue's artifact history via `gxpm artifact write`.

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

@@ -0,0 +1,77 @@
+---
+name: gxpm-grill
+description: Grilling session that challenges plans against the domain model and sharpens terminology. Use when user wants to stress-test a plan, align on requirements, challenge assumptions, or make architecture decisions.
+---
+
+# Grill
+
+Interview the user relentlessly about every aspect of a plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+## 入口条件
+
+**何时触发**
+- 用户 utterances: "grill me", "let's align", "challenge this plan", "does this make sense?"
+- Plan 或 design 存在未解决的依赖、未定义术语或隐含假设。
+- Issue 从 `triage` 移动到 `plan` 时没有书面的 `acceptance-contract`。
+- 出现术语漂移：用户用多个不同名称描述同一概念。
+
+**前置条件**
+- 有 plan、design、issue 或概念需要澄清。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 用户要求 quick code snippet 或 one-line fix → 直接实现，不 grill
+- 需求已完全明确，有 acceptance criteria，无歧义 → 不 grill，直接进入 plan/implement
+- 用户明确说 "just do it" 或 "no need to discuss" → 不 grill
+- 时间压力极大且错误成本低于讨论成本 → 不 grill
+- 需要代码调试 → `/gxpm-debug-issue`
+- 需要产出实现计划 → `/gxpm-planning`
+- 需要 issue 分类 → `/gxpm-triage`
+
+## 可操作流程
+
+{{REFERENCE:process}}
+
+## 红旗清单 / 反模式
+
+- **STOP：不要对 clear one-line fix 进行 grilling。** User says "Add a login button to the header." → 直接实现。Grill 仅当 login flow 涉及 CONTEXT.md 中没有的新领域概念。
+- **STOP：不要对 fully specified、无歧义的需求 grilling。** 浪费用户时间。
+- **STOP：不要跳过 grilling 直接 coding（当涉及新领域概念时）。** User says "Let's build a real-time sync system." → 必须先 grill：WebSockets, SSE, polling, CRDTs？哪种一致性模型？失败模式是什么？
+- **STOP：不要 batch 文档更新。** 决策结晶时立即内联更新文档，不要攒到后面。
+- **危险信号：**  grilling 过程中 issue 范围不断扩大 → 停止，要求用户先拆分 issue 再继续。
+- **危险信号：** 同一概念出现多个名称而用户不认为它们是同义词 → 强制选择一个并写入 CONTEXT.md。
+
+## 验证清单 / 出口条件
+
+- [ ] 每个设计分支的依赖已逐层解决。
+- [ ] 术语已统一并记录到 `CONTEXT.md`。
+- [ ] `triage → plan` 阶段：`acceptance-contract` 已更新并书面化。
+- [ ] `plan` 阶段：`implementation-plan` 已更新，关键实现决策已解决。
+- [ ]  grilling 过程中创建的 ADR 已记录到 issue artifact history（通过 `gxpm artifact write`）。
+- [ ] 用户和代理对 plan 达成 shared understanding。
+
+**失败时路由**
+-  grilling 后仍无法做架构决策 → `/gxpm-architecture`
+-  issue 需要重新分类 → `/gxpm-triage`
+-  需要进一步代码调研 → `/gxpm-explore-codebase`
+
+## 常见说辞表
+
+| 用户 utterance | 推荐回应 |
+|----------------|----------|
+| "grill me" / "challenge this plan" | "好。我们从最不确定的假设开始。请确认 [关键假设1] 是否成立？如果变化，会影响哪些决策？" |
+| "let's align" | "我先梳理当前计划中未解决的依赖项和未定义术语，然后逐一确认。" |
+| "does this make sense?" | "我先检查计划与领域模型的一致性，然后指出冲突或缺失的约束。" |
+| "Add a login button to the header."（清晰请求） | "这个请求很清晰，直接实现。如果 login flow 涉及新领域概念，我再 grill。" |
+| "Let's build a real-time sync system."（模糊宏大） | "'Real-time' 涵盖 WebSockets、SSE、polling、CRDTs。我们先对齐：选哪种？一致性模型？失败模式？" |
+
+## Documentation side effects
+
+As decisions crystallise, update project documentation inline. Do not batch these up — capture them as they happen.
+
+{{REFERENCE:documentation-templates}}
+
+## gxpm integration
+
+- Before leaving `triage`, use grilling to clarify issue scope and write the `acceptance-contract`.
+- During `plan`, use grilling to resolve implementation decisions and write the `implementation-plan`.
+- Record any ADR created during grilling in the issue's artifact history via `gxpm artifact write`.

package/skills/gxpm-grill/references/documentation-templates.md

@@ -0,0 +1,56 @@
+### Update CONTEXT.md
+
+When a term is resolved, update `CONTEXT.md` right there. Use this format:
+
+```markdown
+## Language
+
+**Issue tracker**:
+The tool that hosts a repo's issues — GitHub Issues, Linear, a local markdown convention, or similar.
+_Avoid_: backlog manager, backlog backend, issue host
+
+**Issue**:
+A single tracked unit of work inside an **Issue tracker**.
+_Avoid_: ticket
+
+## Relationships
+
+- An **Issue tracker** holds many **Issues**
+- An **Issue** carries one **Triage role** at a time
+
+## Flagged ambiguities
+
+- "backlog" was previously used to mean both the *tool* and the *body of work* — resolved.
+```
+
+Create `CONTEXT.md` lazily — only when you have the first term to write. Do not couple it to implementation details; only include terms meaningful to domain experts.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If any of the three is missing, skip the ADR. Write ADRs under `docs/adr/` using this format:
+
+```markdown
+# ADR-000N: Title
+
+## Status
+
+Accepted
+
+## Context
+
+What is the forcing function? What constraints exist?
+
+## Decision
+
+What are we doing?
+
+## Consequences
+
+What becomes easier? What becomes harder?
+```

package/skills/gxpm-grill/references/process.md

@@ -0,0 +1,25 @@
+### 1. Ask one question at a time
+
+Wait for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead.
+
+### 2. Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately:
+
+> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### 3. Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term:
+
+> "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### 4. Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about boundaries between concepts.
+
+### 5. Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it:
+
+> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

package/skills/gxpm-handoff/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: gxpm-handoff
+description: Compact the current session into a handoff document so another agent can continue the work. Use when switching agents, ending a session, or passing work between implementer subagents.
+---
+
+# Handoff
+
+Write a handoff document summarising the current session so a fresh agent can continue the work without losing context.
+
+## 入口条件
+
+**何时触发**
+- 当前 session 即将结束，需要让下一个 session 接续工作。
+- dispatch 阶段需要将一个 implementer subagent 的工作传递给下一个 subagent。
+- 用户明确说 "handoff"、"summarise for next session"、"pass this to another agent"。
+- 一个 phase 完成，进入下一个 phase 且 agent 上下文可能重置时。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需要代码调试 → `/gxpm-diagnose`
+- 需要对齐需求 → `/gxpm-grill`
+- 需要运行验证流水线 → `/gxpm-verify`
+- 需要提交代码 → `/gxpm-hygiene`
+
+## 可操作流程
+
+### 1. Gather context
+
+Collect the essential state from the current session:
+
+- **Current phase** — what gxpm phase is the issue in?
+- **What was done** — files changed, tests written, decisions made
+- **What was NOT done** — explicit scope exclusions or deferred items
+- **Blockers** — anything that stopped progress or needs resolution
+- **Next steps** — what the next agent should do first
+- **Relevant artifacts** — paths to PRDs, plans, ADRs, test outputs, screenshots
+
+### 2. Write the handoff doc
+
+Save to a temporary path:
+
+```bash
+mktemp -t handoff-XXXXXX.md
+```
+
+Or append to the issue's artifact history:
+
+```bash
+gxpm artifact write <issue-id> handoff --stdin
+```
+
+### 3. Structure
+
+```markdown
+# Handoff: <issue-id> — <brief description>
+
+## Session summary
+- Host: <Claude/Codex/etc>
+- Date: <ISO date>
+- Phase: <current gxpm phase>
+
+## What was done
+- <item 1>
+- <item 2>
+
+## What remains
+- <item 1>
+- <item 2>
+
+## Blockers / concerns
+- <item 1>
+
+## Next steps (prioritised)
+1. <first thing the next agent should do>
+2. <second thing>
+
+## Key artifacts
+- Plan: <path or URL>
+- Spec: <path or URL>
+- Test results: <path or summary>
+- Screenshots / evidence: <paths>
+
+## Skills to load next
+- <e.g. /gxpm-tdd for remaining implementation>
+- <e.g. /gxpm-verify for running tests>
+```
+
+### 4. Do not duplicate
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+## 红旗清单 / 反模式
+
+- **STOP：不要复制粘贴整段代码。** 引用文件路径，不要内联代码块。
+- **STOP：不要遗漏阻塞物。** 如果工作被阻塞，必须明确说明阻塞原因和已尝试的解决方案。
+- **STOP：不要假设下一个 agent 知道上下文。** 即使是显而易见的状态，也要明确写出。
+- **危险信号：** Handoff 文档超过 200 行 → 过度详细，应拆分为 artifact 引用。
+- **危险信号：** 没有 "Next steps" 部分 → 下一个 agent 不知道从何开始。
+
+## 验证清单 / 出口条件
+
+- [ ] 当前 phase 和 issue 状态已明确记录。
+- [ ] 已完成工作和剩余工作已区分。
+- [ ] 任何阻塞物已记录，包括已尝试的解决方案。
+- [ ] 下一步已按优先级列出。
+- [ ] 已有 artifact 被引用而非复制。
+- [ ] 建议了下一个 agent 应加载的 skills。
+- [ ] 文档已保存到临时路径或 issue artifact。
+
+**失败时路由**
+- 阻塞物需要调试 → `/gxpm-diagnose`
+- 阻塞物是需求不清 → `/gxpm-grill`
+- 需要验证当前工作 → `/gxpm-verify`