@geminix/gxpm 0.1.0

package/skills/gxpm-zoom-out/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gxpm-zoom-out
+description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code, stuck in implementation details, or need to understand how code fits into the bigger picture.
+---
+
+# Zoom Out
+
+Go up a layer of abstraction. Stop drowning in details and see the map.
+
+## 入口条件
+
+**何时触发**
+- 你在 implement 阶段陷入了实现细节，不确定当前修改是否符合架构设计。
+- 你面对一段不熟悉的代码，需要理解它如何融入更大的系统。
+- 用户说 "zoom out"、"bigger picture"、"how does this fit?"、"step back"。
+- 你连续阅读了多个文件但仍无法理解系统的组织方式。
+- 你在调试时迷失在调用链中，需要模块级别的地图。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需要具体代码调试定位根因 → `/gxpm-debug-issue`
+- 需要深度理解特定模块内部 → `/gxpm-explore-codebase`
+- 需要架构改进建议 → `/gxpm-architecture`
+- 需要术语对齐或计划验证 → `/gxpm-grill`
+
+## 可操作流程
+
+### 1. Ask for the map
+
+Request a high-level overview using the project's domain glossary vocabulary:
+
+> "Give me a map of all the relevant modules and callers. Use the domain glossary from CONTEXT.md."
+
+### 2. What to surface
+
+Provide a concise architectural briefing covering:
+
+- **Modules involved** — name and one-line responsibility for each relevant module
+- **Call graph** — who calls whom, data flow direction
+- **Domain concepts** — which CONTEXT.md terms are active in this area
+- **ADR relevance** — any architectural decisions that govern this code path
+- **Integration seams** — where this code meets external systems or other bounded contexts
+
+### 3. What NOT to do
+
+- Do not dump file listings or raw directory trees.
+- Do not read every file in the module — summarize from what you already know.
+- Do not descend into function-level detail unless specifically asked.
+- Do not suggest code changes — this is a viewing skill, not an editing skill.
+
+## 红旗清单 / 反模式
+
+- **STOP：不要变成文件浏览器。** Zoom-out 的目标是理解关系，不是枚举文件。
+- **STOP：不要建议重构。** 如果发现了架构问题，交给 `/gxpm-architecture`。
+- **STOP：不要在 zoom-out 后继续深挖。** 如果用户说 "zoom out"，不要立刻开始读下一个文件的每一行。
+- **危险信号：** 输出变成了目录列表 → 重新组织为模块关系图。
+- **危险信号：** 使用了与 CONTEXT.md 不一致的术语 → 纠正并引用 glossary。
+
+## 验证清单 / 出口条件
+
+- [ ] 提供了模块地图（不是文件列表）。
+- [ ] 使用了 CONTEXT.md 中的领域术语。
+- [ ] 说明了相关 ADR（如果有）。
+- [ ] 没有建议具体代码修改。
+- [ ] 用户能够基于这个地图做出下一步决策（继续实现、深入调试、或架构调整）。
+
+**失败时路由**
+- 需要具体代码调试 → `/gxpm-debug-issue`
+- 需要架构改进建议 → `/gxpm-architecture`
+- 需要术语对齐 → `/gxpm-grill`

package/skills/maintain-hygiene-skills-lock/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: maintain-hygiene-skills-lock
+description: 维护 skills-lock.json 完整性锁。在新增、修改或删除 skill 时更新锁文件。
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->
+
+# maintain-hygiene-skills-lock
+
+## 入口条件
+
+- `skills/` 目录发生变更（新增、修改、删除 skill）
+- `skills-lock.json` 与当前 skill 内容不一致
+- `bun run check` 报 `skills-lock: hash mismatch` 或 `not listed`
+
+## 可操作流程
+
+### 1. 重新计算哈希
+
+运行以下脚本重新生成 `skills-lock.json`：
+
+```bash
+python3 -c "
+import json, hashlib
+from pathlib import Path
+lock = {'version': 1, 'skills': {}}
+for d in sorted(Path('skills').iterdir()):
+    p = d / 'SKILL.md'
+    if p.exists():
+        lock['skills'][d.name] = hashlib.sha256(p.read_bytes()).hexdigest()
+print(json.dumps(lock, indent=2, ensure_ascii=False))
+"
+```
+
+### 2. 写入 skills-lock.json
+
+将输出写入 `skills-lock.json`。
+
+### 3. 验证
+
+运行 `bun run check` 确认 `skills-lock` 校验通过。
+
+## 红旗清单 / 反模式
+
+- **不要**手动编辑 `skills-lock.json` 中的哈希值；始终通过脚本重新生成
+- 删除 skill 时必须同步删除 `skills-lock.json` 中的对应条目
+- 新增 skill 必须立即加入 `skills-lock.json` 并提交
+- `SKILL.md` 是生成产物时，以 `.tmpl` 为真值计算哈希（如技能使用模板生成）
+
+## 验证清单 / 出口条件
+
+- [ ] `bun run check` 通过
+- [ ] `skills-lock.json` 中所有 skill 的哈希与实际文件一致
+- [ ] 没有未列入 `skills-lock.json` 的 skill
+- [ ] 没有已删除但仍在 `skills-lock.json` 中的 skill

package/skills/maintain-hygiene-skills-lock/SKILL.md.tmpl

@@ -0,0 +1,53 @@
+---
+name: maintain-hygiene-skills-lock
+description: 维护 skills-lock.json 完整性锁。在新增、修改或删除 skill 时更新锁文件。
+---
+
+# maintain-hygiene-skills-lock
+
+## 入口条件
+
+- `skills/` 目录发生变更（新增、修改、删除 skill）
+- `skills-lock.json` 与当前 skill 内容不一致
+- `bun run check` 报 `skills-lock: hash mismatch` 或 `not listed`
+
+## 可操作流程
+
+### 1. 重新计算哈希
+
+运行以下脚本重新生成 `skills-lock.json`：
+
+```bash
+python3 -c "
+import json, hashlib
+from pathlib import Path
+lock = {'version': 1, 'skills': {}}
+for d in sorted(Path('skills').iterdir()):
+    p = d / 'SKILL.md'
+    if p.exists():
+        lock['skills'][d.name] = hashlib.sha256(p.read_bytes()).hexdigest()
+print(json.dumps(lock, indent=2, ensure_ascii=False))
+"
+```
+
+### 2. 写入 skills-lock.json
+
+将输出写入 `skills-lock.json`。
+
+### 3. 验证
+
+运行 `bun run check` 确认 `skills-lock` 校验通过。
+
+## 红旗清单 / 反模式
+
+- **不要**手动编辑 `skills-lock.json` 中的哈希值；始终通过脚本重新生成
+- 删除 skill 时必须同步删除 `skills-lock.json` 中的对应条目
+- 新增 skill 必须立即加入 `skills-lock.json` 并提交
+- `SKILL.md` 是生成产物时，以 `.tmpl` 为真值计算哈希（如技能使用模板生成）
+
+## 验证清单 / 出口条件
+
+- [ ] `bun run check` 通过
+- [ ] `skills-lock.json` 中所有 skill 的哈希与实际文件一致
+- [ ] 没有未列入 `skills-lock.json` 的 skill
+- [ ] 没有已删除但仍在 `skills-lock.json` 中的 skill

package/templates/constitution-template.md

@@ -0,0 +1,63 @@
+# gxpm Specification-Driven Development Constitution
+
+> Adapted from Spec Kit's Nine Articles of Development.
+> These constraints are enforced as Phase -1 Gates before plan phase advancement.
+
+## Nine Articles
+
+### 1. Capability-First
+Every feature must first exist as a capability contract in `core/capabilities.ts` before implementation.
+- Declare input/output, mutation scope, idempotency, failure modes, and evidence metadata.
+- No code without a declared capability slice.
+
+### 2. CLI Interface Mandate
+All capabilities must expose a CLI surface (stdin/stdout, JSON-compatible).
+- Commands are the primary integration point, not internal APIs.
+- `gxpm capability list/show` remains read-only; execution is a separate concern.
+
+### 3. Test-First Imperative
+Strict red-green-refactor for all non-trivial changes.
+- Write the test before the implementation.
+- `bun test` is the fast gate; it must pass before any phase transition.
+
+### 4. Composition over Inheritance
+Prefer composing small, focused modules over deep inheritance hierarchies.
+- `StepBase`, `HostAdapter`, and `PresetResolver` are interfaces, not base classes.
+- Mixins and inheritance are last resorts.
+
+### 5. Explicit over Implicit
+No magic, no hidden conventions, no global state mutations.
+- All side effects must be declared in capability contracts.
+- Configuration is explicit: `config.json` > env > default.
+
+### 6. Fail Fast, Fail Loud
+Errors must surface immediately with actionable context.
+- No silent swallowing of exceptions.
+- Validation happens at the boundary (config, artifact, command input).
+
+### 7. Simplicity Gate
+A feature must justify its complexity. When in doubt, delete.
+- Max 3 modules per feature slice unless proven otherwise.
+- Preset system MVP: Override + Preset + Core only; Extension and hooks deferred.
+
+### 8. Anti-Abstraction
+Use framework/language features directly. Avoid wrapper upon wrapper.
+- `yaml` library directly, not a custom YAML parser.
+- `execSync` directly, not a "command runner abstraction layer".
+
+### 9. Integration-First Testing
+Prefer real environments over mocks for integration surfaces.
+- Browser tests use real Playwright, not stubbed.
+- Linear integration tests hit real API in sandbox mode.
+- Unit tests mock; integration tests verify.
+
+## Phase -1 Gates
+
+Before advancing from `triage` to `plan`, confirm:
+
+- [ ] **Capability declared?** — `core/capabilities.ts` has the slice.
+- [ ] **Test strategy defined?** — Implementation plan includes test approach.
+- [ ] **Simplicity justified?** — Feature complexity is minimal viable.
+- [ ] **Integration path clear?** — Real environment testing is planned, not deferred indefinitely.
+
+These gates are optional for spike/investigation issues (type=spike), mandatory for feature delivery (default type).

package/templates/hooks/gxpm-commit-msg

@@ -0,0 +1,16 @@
+#!/bin/bash
+# gxpm commit-msg hook. $1 is the path to .git/COMMIT_EDITMSG
+set -e
+
+if ! command -v gxpm >/dev/null 2>&1; then
+  exit 0
+fi
+
+current_branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
+issue_id=$(printf '%s' "$current_branch" | grep -oEi '(gxg|gxpm)-[0-9]+' | head -1 | tr 'a-z' 'A-Z')
+
+if [ -n "$issue_id" ] && [ -f ".gxpm/issues/${issue_id}/state.json" ]; then
+  exec gxpm gate commit-msg "$1" --issue "$issue_id"
+fi
+
+exit 0

package/templates/hooks/gxpm-post-checkout

@@ -0,0 +1,19 @@
+#!/bin/bash
+# gxpm post-checkout hook
+# Git runs this after checkout/switch. It cannot prevent the switch, but it
+# fails loudly when the canonical checkout is no longer on main.
+set -e
+
+if [ -x "./bin/gxpm" ]; then
+  GXPM_BIN="./bin/gxpm"
+elif command -v gxpm >/dev/null 2>&1; then
+  GXPM_BIN="$(command -v gxpm)"
+else
+  exit 0
+fi
+
+"$GXPM_BIN" gate branch-policy
+
+# gxpm wiki is an optional human-facing documentation surface. Keep branch
+# switching focused on policy enforcement; humans can refresh docs explicitly
+# with `gxpm wiki update` when they want an up-to-date wiki.

package/templates/hooks/gxpm-post-commit

@@ -0,0 +1,7 @@
+#!/bin/bash
+# gxpm post-commit hook
+# Reserved for future post-commit policy. Wiki refresh is manual because the
+# gxpm wiki is an optional human-facing documentation surface.
+set +e
+
+exit 0

package/templates/hooks/gxpm-post-merge

@@ -0,0 +1,29 @@
+#!/bin/bash
+# gxpm post-merge hook (runs after `git merge` or `git pull` completes)
+set -e
+
+if ! command -v gxpm >/dev/null 2>&1; then
+  exit 0
+fi
+
+# When a feature branch merges into develop, the post-merge runs ON the
+# branch that received the merge (usually develop). Use the merged branch
+# name from MERGE_MSG when available.
+issue_id=""
+if [ -f .git/MERGE_MSG ]; then
+  issue_id=$(grep -oEi '(gxg|gxpm)-[0-9]+' .git/MERGE_MSG | head -1 | tr 'a-z' 'A-Z' || true)
+fi
+
+if [ -n "$issue_id" ] && [ -f ".gxpm/issues/${issue_id}/state.json" ]; then
+  gxpm gate post-merge "$issue_id" || true
+  if current_sha=$(git rev-parse HEAD 2>/dev/null); then
+    log_dir="${GXPM_HOME:-$HOME/.gxpm}"
+    mkdir -p "$log_dir" 2>/dev/null || true
+    log_file="$log_dir/post-merge-error.log"
+    if ! gxpm gate post-merge-reconcile "$issue_id" --sha "$current_sha" 2>>"$log_file"; then
+      printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "post-merge-reconcile failed for $issue_id $current_sha" >>"$log_file" 2>/dev/null || true
+    fi
+  fi
+fi
+
+exit 0

package/templates/hooks/gxpm-pre-commit

@@ -0,0 +1,39 @@
+#!/bin/bash
+# gxpm pre-commit hook
+# Installed by `gxpm-init --install-hooks`. Reads `.gxpm/issues/<id>/state.json`
+# to enforce phase gate. No-op if no state file or no issue id in branch name.
+# Escape hatch: GXPM_GATE_DISABLE=1 git commit ...
+
+set -e
+
+if [ -x "./bin/gxpm" ]; then
+  GXPM_BIN="./bin/gxpm"
+elif command -v gxpm >/dev/null 2>&1; then
+  GXPM_BIN="$(command -v gxpm)"
+else
+  exit 0
+fi
+
+"$GXPM_BIN" gate branch-policy
+
+current_branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
+issue_id=$(printf '%s' "$current_branch" | grep -oEi '(gxg|gxpm)-[0-9]+' | head -1 | tr 'a-z' 'A-Z')
+
+if [ -z "$issue_id" ]; then
+  exit 0
+fi
+
+if [ ! -f ".gxpm/issues/${issue_id}/state.json" ]; then
+  exit 0
+fi
+
+staged_files=()
+while IFS= read -r -d '' staged_file; do
+  staged_files+=("$staged_file")
+done < <(git diff --cached --name-only --diff-filter=ACMR -z)
+
+if [ "${#staged_files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+exec "$GXPM_BIN" gate pre-commit "$issue_id" --staged "${staged_files[@]}"

package/templates/hooks/gxpm-pre-push

@@ -0,0 +1,33 @@
+#!/bin/bash
+# gxpm pre-push hook
+set -e
+
+if [ -x "./bin/gxpm" ]; then
+  GXPM_BIN="./bin/gxpm"
+elif command -v gxpm >/dev/null 2>&1; then
+  GXPM_BIN="$(command -v gxpm)"
+else
+  exit 0
+fi
+
+"$GXPM_BIN" gate branch-policy
+
+current_branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
+issue_id=$(printf '%s' "$current_branch" | grep -oEi '(gxg|gxpm)-[0-9]+' | head -1 | tr 'a-z' 'A-Z')
+
+if [ -n "$issue_id" ] && [ -f ".gxpm/issues/${issue_id}/state.json" ]; then
+  "$GXPM_BIN" gate pre-push "$issue_id"
+fi
+
+# Informational dogfood compliance check (non-blocking by default).
+# Reports issues that reached implement without going through specify
+# after SPECIFY_PHASE_CUTOFF. Set GXPM_DOGFOOD_STRICT=1 to enforce.
+if command -v bun >/dev/null 2>&1 && [ -f "scripts/dogfood-check.ts" ]; then
+  if [ "${GXPM_DOGFOOD_STRICT:-0}" = "1" ]; then
+    bun run scripts/dogfood-check.ts --strict || exit 1
+  else
+    bun run scripts/dogfood-check.ts || true
+  fi
+fi
+
+exit 0

package/templates/plan-template.md.tmpl

@@ -0,0 +1,46 @@
+---
+name: gxpm-plan
+description: Use when creating an implementation plan artifact. Breaks a spec into discrete, implementable tasks with verification steps.
+---
+
+# Plan: [Feature Name]
+
+## Summary
+
+[One-paragraph summary of the implementation approach]
+
+## Architecture Decisions
+
+| Decision | Rationale | Trade-offs |
+|----------|-----------|------------|
+| [Decision] | [Why] | [What we give up] |
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| [Risk] | High/Med/Low | High/Med/Low | [How we reduce it] |
+
+## Approach
+
+### Step 1: [Name]
+- **Files:** [which files will be touched]
+- **Details:** [what to do]
+- **Verification:** [how to confirm it works]
+
+### Step 2: [Name]
+- **Files:**
+- **Details:**
+- **Verification:**
+
+## Validation
+
+```bash
+# Commands to run after implementation
+bun test
+bun run check
+```
+
+## Non-Goals
+
+- [What is explicitly out of scope]

package/templates/spec-template.md.tmpl

@@ -0,0 +1,63 @@
+---
+name: gxpm-spec
+description: Use when creating a specification artifact for a new feature or significant change. Defines what we're building, why, and how we'll know it's done.
+---
+
+# Spec: [Feature Name]
+
+## Objective
+
+What are we building and why?
+
+- **What:** [One-sentence description]
+- **Why:** [Business or technical motivation]
+- **Who:** [Target users or consumers]
+
+## Tech Stack
+
+- Runtime: [e.g. TypeScript/Bun]
+- Key dependencies: [list]
+
+## Commands
+
+```bash
+# Primary command
+
+# Verification command
+```
+
+## Project Structure
+
+```
+[directory layout]
+```
+
+## Code Style
+
+[Conventions and patterns]
+
+## Testing Strategy
+
+- Framework: [e.g. bun:test]
+- Coverage target: [e.g. >80%]
+- Integration path: [real environment or mock]
+
+## Boundaries
+
+### Always
+- [Non-negotiable discipline]
+
+### Ask First
+- [Human-in-the-loop decisions]
+
+### Never
+- [Hard guardrails]
+
+## Success Criteria
+
+- [ ] [Measurable, testable criterion 1]
+- [ ] [Measurable, testable criterion 2]
+
+## Open Questions
+
+- [Question that needs resolution before implementation]

package/templates/specify-stub.tmpl

@@ -0,0 +1,22 @@
+// Feature: {{feature.title}}
+//
+//   As a {{feature.asA}}
+//   I want {{feature.iWant}}
+//   So that {{feature.soThat}}
+//
+{{#each scenarios}}
+// Scenario ({{this.id}}): {{this.name}}
+{{#each this.given}}
+//   {{#if @first}}Given{{else}}And{{/if}} {{this}}
+{{/each}}
+//   When {{this.when}}
+{{#each this.then}}
+//   {{#if @first}}Then{{else}}And{{/if}} {{this}}
+{{/each}}
+
+test("{{this.testName}}", () => {
+  // intentionally empty — awaiting user confirmation
+  // implement only after `gxpm specify confirm <issue-id>`
+});
+
+{{/each}}

package/templates/tasks-template.md.tmpl

@@ -0,0 +1,32 @@
+---
+name: gxpm-tasks
+description: Use when creating a task list artifact. Vertical slices that are independently grabbable and completable in a single focused session.
+---
+
+# Tasks: [Feature Name]
+
+## Task List
+
+- [ ] **Task 1:** [Description]
+  - **Acceptance:** [What must be true when done]
+  - **Verify:** [How to confirm]
+  - **Files:** [Which files will be touched]
+
+- [ ] **Task 2:** [Description]
+  - **Acceptance:**
+  - **Verify:**
+  - **Files:**
+
+## Dependency Graph
+
+```
+Task 1 ──→ Task 3
+Task 2 ──→ Task 3
+```
+
+## Verification Checklist
+
+- [ ] All tasks have explicit acceptance criteria
+- [ ] No task touches more than ~5 files
+- [ ] Tasks are ordered by dependency
+- [ ] Each task can be completed in one focused session