@geminix/gxpm 0.1.0

package/skills/gxpm-hygiene/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gxpm-hygiene
+description: Pre-commit hygiene and atomic commit discipline. Use before every commit, or when preparing changes for self-review or ship.
+---
+
+# gxpm-hygiene
+
+## 入口条件
+
+在以下场景触发本 skill：
+
+- 每次提交前
+- 准备变更进行自审（`self-review`）时
+- 准备进入 `ship` 阶段、整理 PR 时
+
+**Skill 边界**：本 skill 聚焦 **git 层纪律**（即将提交的内容本身），不验证代码是否可编译或通过测试。编译与测试验证是 `gxpm-build`（开发中）和 `gxpm-verify`（`local-verify` 关卡）的职责。在 hygiene 中重复运行那些检查会造成冗余循环并模糊责任边界。
+
+在 gxpm 工作流中：
+- `implement` 阶段每次提交前都运行本检查清单
+- `self-review` 阶段必须确认所有提交都遵循了本纪律
+- `ship` 阶段将本检查清单作为 PR 准备的一部分
+
+## 可操作流程
+
+按以下顺序执行预提交检查：
+
+```bash
+# 1. Review what you're about to commit
+git diff --staged
+
+# 2. Secret leak scan (manual review)
+git diff --staged --name-only | xargs grep -l "\.env" 2>/dev/null || true
+# Also review diff for high-entropy strings that look like keys/tokens
+
+# 3. Confirm atomicity — one logical change
+git diff --staged --stat
+```
+
+**为什么这里不运行 `bun run check` / `bun test` / `bun run build`？**
+These are the responsibility of `gxpm-build` (during development) and `gxpm-verify` (at the `local-verify` gate). Running them in hygiene creates redundant cycles and blurs accountability.
+
+### 原子提交规则
+
+- **One logical change per commit.** Do not mix refactoring, features, and unrelated cleanups.
+- **Generated files:** If `.tmpl` was modified, `bun run gen:skill-docs` must run first.
+- **Issue reference:** Commit message must include `GXPM-N` reference.
+- **Worktree discipline:** Main checkout stays on `main`. Feature work happens in dedicated worktrees.
+
+## 红旗清单 / 反模式
+
+- Committing with `--no-verify` to bypass checks
+- Build or tests failing at commit time
+- Missing `GXPM-N` reference in commit message
+- One commit mixing refactor + feature + cleanup
+- Uncommitted generated files after modifying templates
+- Committing secrets or `.env` files
+- Running the same check twice without code changes in between
+
+## 验证清单 / 出口条件
+
+提交前必须确认：
+
+- [ ] 已审查 `git diff --staged` 中的全部变更
+- [ ] 已扫描潜在密钥/令牌泄漏和高熵字符串
+- [ ] 本次提交只包含一个逻辑变更（原子性）
+- [ ] 如修改了 `.tmpl`，已重新生成关联文件
+- [ ] Commit message 包含 `GXPM-N` 引用
+- [ ] 未使用 `--no-verify` 绕过检查
+- [ ] 未提交 `.env` 或密钥文件

package/skills/gxpm-implementer/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: gxpm-implementer
+description: Subagent implementer behavior template enforcing four-dimension self-review. Use when dispatching a task to an implementer subagent, or when a subagent needs structured self-review and reporting rules.
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent through gxpm's dispatch phase.
+
+## 入口条件
+
+在以下场景使用本模板：
+
+- 通过 gxpm 的 dispatch 阶段派遣 implementer subagent
+- Subagent 需要结构化自审和报告规则
+
+派遣前填充以下 Task Header：
+
+```
+You are implementing Task N: [task name]
+
+## Task Description
+
+[FULL TEXT of task from implementation plan - paste it here]
+
+## Context
+
+[Scene-setting: where this fits, dependencies, architectural context]
+```
+
+### 开始前确认
+
+If you have questions about:
+- The requirements or acceptance criteria
+- The approach or implementation strategy
+- Dependencies or assumptions
+- Anything unclear in the task description
+
+**Ask them now.** Raise any concerns before starting work.
+
+## 可操作流程
+
+### 你的职责
+
+Once you're clear on requirements:
+1. Implement exactly what the task specifies
+2. Write tests (following TDD if task says to)
+3. Verify implementation works:
+   - Load `/gxpm-build` to verify compilation and type checking
+   - Load `/gxpm-verify` to run the full verification pipeline and collect evidence
+4. Commit your work (load `/gxpm-hygiene` for pre-commit checklist)
+5. Self-review (see 验证清单 / 出口条件)
+6. Report back
+
+Work from: [directory]
+
+**While you work:** If you encounter something unexpected or unclear, **ask questions**.
+It's always OK to pause and clarify. Don't guess or make assumptions.
+
+### 代码组织原则
+
+You reason best about code you can hold in context at once, and your edits are more
+reliable when files are focused. Keep this in mind:
+- Follow the file structure defined in the plan
+- Each file should have one clear responsibility with a well-defined interface
+- If a file you're creating is growing beyond the plan's intent, stop and report
+  it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
+- If an existing file you're modifying is already large or tangled, work carefully
+  and note it as a concern in your report
+- In existing codebases, follow established patterns. Improve code you're touching
+  the way a good developer would, but don't restructure things outside your task.
+
+### 升级流程
+
+It is always OK to stop and say "this is too hard for me." Bad work is worse than
+no work. You will not be penalized for escalating.
+
+**STOP and escalate when:**
+- The task requires architectural decisions with multiple valid approaches
+- You need to understand code beyond what was provided and can't find clarity
+- You feel uncertain about whether your approach is correct
+- The task involves restructuring existing code in ways the plan didn't anticipate
+- You've been reading file after file trying to understand the system without progress
+
+**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
+specifically what you're stuck on, what you've tried, and what kind of help you need.
+The controller can provide more context, re-dispatch with a more capable model,
+or break the task into smaller pieces.
+
+## 红旗清单 / 反模式
+
+- **不要擅自拆分文件。** 如果文件超出计划预期，报告 DONE_WITH_CONCERNS 而非自行拆分。
+- **不要修改任务范围外的代码结构。** 遵循现有模式，只改进你正在接触的代码。
+- **不要猜测需求。** 遇到不清楚的地方必须暂停并提问，不能假设。
+- **不要忽视警告信号。** 连续阅读文件仍无法理解系统时应立即升级（BLOCKED/NEEDS_CONTEXT），而不是硬推。
+- **不要在需要架构决策时独断。** 存在多个有效方案时必须上报。
+
+## 验证清单 / 出口条件
+
+报告前必须完成四维自审：
+
+**Completeness:**
+- Did I fully implement everything in the spec?
+- Did I miss any requirements?
+- Are there edge cases I didn't handle?
+
+**Quality:**
+- Is this my best work?
+- Are names clear and accurate (match what things do, not how they work)?
+- Is the code clean and maintainable?
+
+**Discipline:**
+- Did I avoid overbuilding (YAGNI)?
+- Did I only build what was requested?
+- Did I follow existing patterns in the codebase?
+
+**Testing:**
+- Do tests actually verify behavior (not just mock behavior)?
+- Did I follow TDD if required?
+- Are tests comprehensive?
+
+**Verification:**
+- Did I run `/gxpm-build` and confirm compilation passes?
+- Did I run `/gxpm-verify` and collect evidence for all steps?
+- Did I run `/gxpm-hygiene` before committing?
+
+If you find issues during self-review, fix them now before reporting.
+
+### 报告格式
+
+When done, report:
+- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+- What you implemented (or what you attempted, if blocked)
+- What you tested and test results
+- Files changed
+- Self-review findings (if any)
+- Any issues or concerns
+
+Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
+Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
+information that wasn't provided. Never silently produce work you're unsure about.

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

@@ -0,0 +1,141 @@
+---
+name: gxpm-implementer
+description: Subagent implementer behavior template enforcing four-dimension self-review. Use when dispatching a task to an implementer subagent, or when a subagent needs structured self-review and reporting rules.
+---
+
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent through gxpm's dispatch phase.
+
+## 入口条件
+
+在以下场景使用本模板：
+
+- 通过 gxpm 的 dispatch 阶段派遣 implementer subagent
+- Subagent 需要结构化自审和报告规则
+
+派遣前填充以下 Task Header：
+
+```
+You are implementing Task N: [task name]
+
+## Task Description
+
+[FULL TEXT of task from implementation plan - paste it here]
+
+## Context
+
+[Scene-setting: where this fits, dependencies, architectural context]
+```
+
+### 开始前确认
+
+If you have questions about:
+- The requirements or acceptance criteria
+- The approach or implementation strategy
+- Dependencies or assumptions
+- Anything unclear in the task description
+
+**Ask them now.** Raise any concerns before starting work.
+
+## 可操作流程
+
+### 你的职责
+
+Once you're clear on requirements:
+1. Implement exactly what the task specifies
+2. Write tests (following TDD if task says to)
+3. Verify implementation works:
+   - Load `/gxpm-build` to verify compilation and type checking
+   - Load `/gxpm-verify` to run the full verification pipeline and collect evidence
+4. Commit your work (load `/gxpm-hygiene` for pre-commit checklist)
+5. Self-review (see 验证清单 / 出口条件)
+6. Report back
+
+Work from: [directory]
+
+**While you work:** If you encounter something unexpected or unclear, **ask questions**.
+It's always OK to pause and clarify. Don't guess or make assumptions.
+
+### 代码组织原则
+
+You reason best about code you can hold in context at once, and your edits are more
+reliable when files are focused. Keep this in mind:
+- Follow the file structure defined in the plan
+- Each file should have one clear responsibility with a well-defined interface
+- If a file you're creating is growing beyond the plan's intent, stop and report
+  it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
+- If an existing file you're modifying is already large or tangled, work carefully
+  and note it as a concern in your report
+- In existing codebases, follow established patterns. Improve code you're touching
+  the way a good developer would, but don't restructure things outside your task.
+
+### 升级流程
+
+It is always OK to stop and say "this is too hard for me." Bad work is worse than
+no work. You will not be penalized for escalating.
+
+**STOP and escalate when:**
+- The task requires architectural decisions with multiple valid approaches
+- You need to understand code beyond what was provided and can't find clarity
+- You feel uncertain about whether your approach is correct
+- The task involves restructuring existing code in ways the plan didn't anticipate
+- You've been reading file after file trying to understand the system without progress
+
+**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
+specifically what you're stuck on, what you've tried, and what kind of help you need.
+The controller can provide more context, re-dispatch with a more capable model,
+or break the task into smaller pieces.
+
+## 红旗清单 / 反模式
+
+- **不要擅自拆分文件。** 如果文件超出计划预期，报告 DONE_WITH_CONCERNS 而非自行拆分。
+- **不要修改任务范围外的代码结构。** 遵循现有模式，只改进你正在接触的代码。
+- **不要猜测需求。** 遇到不清楚的地方必须暂停并提问，不能假设。
+- **不要忽视警告信号。** 连续阅读文件仍无法理解系统时应立即升级（BLOCKED/NEEDS_CONTEXT），而不是硬推。
+- **不要在需要架构决策时独断。** 存在多个有效方案时必须上报。
+
+## 验证清单 / 出口条件
+
+报告前必须完成四维自审：
+
+**Completeness:**
+- Did I fully implement everything in the spec?
+- Did I miss any requirements?
+- Are there edge cases I didn't handle?
+
+**Quality:**
+- Is this my best work?
+- Are names clear and accurate (match what things do, not how they work)?
+- Is the code clean and maintainable?
+
+**Discipline:**
+- Did I avoid overbuilding (YAGNI)?
+- Did I only build what was requested?
+- Did I follow existing patterns in the codebase?
+
+**Testing:**
+- Do tests actually verify behavior (not just mock behavior)?
+- Did I follow TDD if required?
+- Are tests comprehensive?
+
+**Verification:**
+- Did I run `/gxpm-build` and confirm compilation passes?
+- Did I run `/gxpm-verify` and collect evidence for all steps?
+- Did I run `/gxpm-hygiene` before committing?
+
+If you find issues during self-review, fix them now before reporting.
+
+### 报告格式
+
+When done, report:
+- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+- What you implemented (or what you attempted, if blocked)
+- What you tested and test results
+- Files changed
+- Self-review findings (if any)
+- Any issues or concerns
+
+Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
+Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
+information that wasn't provided. Never silently produce work you're unsure about.

package/skills/gxpm-linear/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: gxpm-linear
+description: Linear CLI integration for gxpm issue lifecycle management. Use when creating, updating, or querying Linear issues, syncing gxpm issues to Linear, or managing issue lifecycle via command line.
+status: stable
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# gxpm-linear
+
+Linear 协作前门，通过 CLI 与 issue tracker 交互。**不使用 MCP** — 所有操作走 `linear` 命令。
+
+## 入口条件
+
+- 需要创建/更新/查询 Linear issue
+- gxpm issue 需要同步到 Linear（`maybeSyncIssue` 的替代路径）
+- Sprint 规划、backlog 分类、批量操作
+- 需要读取 issue 评论获取上下文
+
+### 前置条件
+
+```bash
+# CLI 已安装在
+/opt/homebrew/bin/linear
+
+# 如不在 PATH
+export PATH="/opt/homebrew/bin:$PATH"
+```
+
+### 认证
+
+```bash
+linear auth login    # 首次使用或 token 过期
+linear config        # 查看默认 team/workspace
+```
+
+> **认证收敛**：gxpm 内置 issue-sync 直接调用 `linear` CLI，**不再单独配置 API key**。
+> 只需确保 `linear auth login` 已完成，gxpm 会自动复用其认证状态。
+> 旧配置 `sync.linearApiKey` 和 `GXPM_LINEAR_API_KEY` 已废弃，可安全移除。
+
+## 可操作流程
+
+## CLI Commands
+
+### Issue Commands
+
+| Task | Command |
+|------|---------|
+| List my issues | `linear issue list --team GXG --sort priority --json` |
+| List all issues | `linear issue list --team GXG --all --sort priority --json` |
+| Filter by state | `linear issue list --team GXG --state todo --sort priority -A --json` |
+| Filter by project | `linear issue list --team GXG --project "Name" --sort priority -A --json` |
+| Search by text | `linear issue list --team GXG --query "keyword" --sort priority -A --json` |
+| View issue | `linear issue view GXG-123 --json` |
+| View with children | `linear issue children GXG-123 --json` |
+| Create issue | `linear issue create -t "Title" --team GXG --priority 2 --label feature --json` |
+| Create with parent | `linear issue create -t "Sub-task" --team GXG --parent GXG-123 --json` |
+| Create with desc file | `cat desc.md \| linear issue create -t "Title" --team GXG --json` |
+| Update state | `linear issue update GXG-123 --state "In Progress" --json` |
+| Move (shorthand) | `linear issue move GXG-123 "In Progress"` |
+| Update title | `linear issue update GXG-123 -t "New Title" --json` |
+| Set priority | `linear issue priority GXG-123 2` |
+| Assign | `linear issue assign GXG-123 self` |
+| Set estimate | `linear issue estimate GXG-123 3` |
+| Add comment | `linear issue comment add GXG-123 --body "text" --json` |
+| Batch create | `linear issue create-batch --json < batch.json` |
+| Dry-run preview | `linear issue create -t "Title" --team GXG --dry-run --json` |
+
+### Comment Subcommands
+
+| Task | Command |
+|------|---------|
+| Add comment | `linear issue comment add GXG-123 --body "text" --json` |
+| Update comment | `linear issue comment update <commentId> --body "text"` |
+| List/Delete comments | Use `linear api` GraphQL queries/mutations |
+
+**Note**: `linear issue comment list` and `linear issue comment delete` were **removed** in CLI v3.2.0. Use `linear api` for comment reads and deletes.
+
+### Issue Relations
+
+| Task | Command |
+|------|---------|
+| List relations | `linear issue relation list GXG-123 --json` |
+| Add relation | `linear issue relation add GXG-123 blocked-by GXG-456 --json` |
+| Delete relation | `linear issue relation delete <relationId>` |
+
+### Other Commands
+
+| Task | Command |
+|------|---------|
+| List teams | `linear team list --json` |
+| Team members | `linear user list --json` |
+| Workflow states | `linear workflow-state list --json` |
+| Labels | `linear label list --json` |
+| Current cycle | `linear cycle current --json` |
+| Next cycle | `linear cycle next --json` |
+| List cycles | `linear cycle list --json` |
+| List projects | `linear project list --json` |
+| View project | `linear project view <slug> --json` |
+| Create project | `linear project create --name "Name" --json` |
+| List milestones | `linear milestone list --json` |
+| List initiatives | `linear initiative list --json` |
+| List documents | `linear document list --json` |
+| List users | `linear user list --json` |
+| Notifications | `linear notification list --json` |
+| GraphQL escape hatch | `linear api '{ issues { nodes { id title } } }'` |
+
+### Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Auth failure | Re-run `linear auth login` |
+| Rate limited | Batch operations, add delays |
+| "No team configured" | Add `--team GXG` or run `linear config` |
+| "Sort must be provided" | Add `--sort priority` to `issue list` |
+| CLI not found | Use full path `/Users/x/.nvm/versions/node/v25.8.0/bin/linear` |
+| Wrong workflow states | Query `linear workflow-state list --json` first |
+
+
+## Workflows
+
+### Full Context = View + Comments
+
+`linear issue view` 只返回标题、描述、状态和元数据。**评论是独立 API 调用。**
+
+**规则**：接手 issue 时必须运行：
+```bash
+linear issue view GXG-123 --json
+```
+Comments require a GraphQL query via `linear api` (CLI v3.2.0 removed `issue comment list`).
+
+评论中可能包含 scope 定义、设计决策、PoC 结果、review 反馈、跨 agent 交接上下文。仅在批量 list/triage 时可跳过评论阅读。
+
+### Creating an Issue
+
+1. 搜索重复：`linear issue list --team GXG --query "keyword" --all --sort priority --json`
+2. 检测当前 git branch：`git branch --show-current`
+3. 起草 issue（标题、描述、标签、项目、团队、负责人、优先级）
+4. 呈现给用户确认
+5. 执行：
+   ```bash
+   linear issue create \
+     -t "[Domain] Clear description" \
+     --team GXG \
+     --priority 2 \
+     --label feature --label backend \
+     --json
+   ```
+6. 报告 issue identifier 和链接
+
+### Implementing a Linear Issue
+
+1. 获取完整上下文（view + comments）
+2. 移到 Todo：`linear issue update GXG-123 --state "Todo" --json`
+3. 读取 acceptance criteria 和依赖
+4. 创建 feature branch（命名含 issue ID）
+5. TDD 实现
+6. 完成后移到 In Review：`linear issue update GXG-123 --state "In Review" --json`
+7. 添加 completion comment：
+   ```bash
+   BRANCH=$(git branch --show-current)
+   linear issue comment add GXG-123 --body "## Completion Summary
+   **Branch:** \`$BRANCH\`
+   **PR:** <pr-url-or-pending>
+   **Summary:** <what was done>" --json
+   ```
+
+### Bulk Operations
+
+3+ issue 的批量操作：
+1. 收集所有目标 issue
+2. 以表格呈现：Issue ID、Current State、Proposed Change、Reason
+3. 加 `--dry-run` 预览
+4. 等用户确认后执行
+5. 报告摘要：N succeeded, N failed
+
+### Sub-Issue Management
+
+子 issue 继承父 issue：
+- 相同 project 和 team
+- 相同标签（除非有理由覆盖）
+- 通过 parent 关系链接
+
+```bash
+# 创建子 issue
+linear issue create -t "Sub-task title" --team GXG --parent GXG-123 --json
+# 或给已有 issue 设置 parent
+linear issue update GXG-456 --parent GXG-123 --json
+```
+
+### Sprint Planning
+
+1. 收集当前状态：
+   ```bash
+   linear cycle current --json
+   linear cycle next --json
+   linear issue list --team GXG --state backlog --sort priority -A --json
+   linear user list --json
+   ```
+2. 分析：按优先级排序（P0 bugs > blockers > high-value features > tech debt）
+3. 以表格呈现计划：issue、priority、assignee、estimate、rationale
+4. 确认后批量分配到 cycle
+
+### Backlog Triage
+
+1. 拉取未分类项：
+   ```bash
+   linear issue list --team GXG --state triage --sort priority -A --json
+   linear issue list --team GXG --state backlog --sort priority -A --json
+   ```
+2. 对每个 issue 推荐：priority、labels、assignee、cycle placement
+3. 以表格呈现 triage 计划
+4. 确认后执行
+5. 标记 stale issue（3+ cycles 无活动）— 先提醒用户 review
+
+### Status Integrity
+
+- 永远不要硬编码 state 名称，先查：
+  ```bash
+  linear workflow-state list --json
+  ```
+- 关父 issue 前先查子 issue：
+  ```bash
+  linear issue children GXG-123 --json
+  ```
+- 任何子 issue 未 Done 都不能关父 issue
+
+### Label Taxonomy
+
+应用标签前先确认存在：
+```bash
+linear label list --json
+```
+
+| Category | Labels | Rule |
+|----------|--------|------|
+| **Type** | `feature`, `bug`, `chore`, `tech-debt`, `spike` | 恰好一个 |
+| **Domain** | `frontend`, `backend`, `infra`, `design`, `security`, `testing` | 1-2 个 |
+| **Workflow** | `blocked`, `in-review`, `needs-design`, `needs-split` | 按需 |
+
+
+### 常用全局参数
+
+| Flag | 说明 |
+|------|------|
+| `--json` | 机器可读输出（默认使用） |
+| `--text` | 人类可读输出 |
+| `--dry-run` | 预览不执行 |
+| `--team <KEY>` | 指定 team（如 `GXG`） |
+
+### 操作原则
+
+1. **Issue 是单一真相源** — 所有需求、bug、变更都先落地 Linear issue
+2. **创建前先查重** — `linear issue list --query "keyword"` 避免重复
+3. **写操作需确认** — 批量操作先呈现表格，等用户点头再执行
+4. **状态完整性** — 子 issue 全 Done 才能关父 issue
+
+### Tips
+
+- `--json` 优先于 `--text`，方便脚本解析
+- `issue list` 默认只显示分配给当前用户的，加 `-A` 看全部
+- `issue list` 必须加 `--sort`（`manual` 或 `priority`）
+- GraphQL escape hatch: `linear api '{ issues { nodes { id title } } }'`
+
+## 红旗清单 / 反模式
+
+- **不使用 MCP** — 所有操作走 `linear` 命令，禁止通过 MCP 操作 Linear
+- 禁止绕过查重直接创建 issue
+- 禁止未确认就执行批量写操作
+- 禁止在子 issue 未完成时关闭父 issue
+- 不要混用旧 API key 认证方式（`sync.linearApiKey`、`GXPM_LINEAR_API_KEY` 已废弃）
+
+## 验证清单 / 出口条件
+
+- [ ] issue 创建/更新/查询结果与预期一致
+- [ ] 同步后的 gxpm issue 与 Linear issue 状态一致
+- [ ] 批量操作已获用户确认
+- [ ] `--json` 输出可被脚本正确解析（如需要）
+
+## Read Next
+
+- `docs/governance/development-contract.md`
+- Main `/gxpm` skill for phase gate details