@geminix/gxpm 0.1.0

package/skills/gxpm-tdd/testing-anti-patterns.tmpl

@@ -0,0 +1,304 @@
+---
+name: testing-anti-patterns
+description: Reference for 5 common testing anti-patterns and their gate functions. Load when writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
+---
+
+# Testing Anti-Patterns
+
+**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
+
+## Overview
+
+Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
+
+**Core principle:** Test what the code does, not what the mocks do.
+
+**Following strict TDD prevents these anti-patterns.**
+
+## The Iron Laws
+
+```
+1. NEVER test mock behavior
+2. NEVER add test-only methods to production classes
+3. NEVER mock without understanding dependencies
+```
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+**The violation:**
+```typescript
+// ❌ BAD: Testing that the mock exists
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why this is wrong:**
+- You're verifying the mock works, not that the component works
+- Test passes when mock is present, fails when it's not
+- Tells you nothing about real behavior
+
+**your human partner's correction:** "Are we testing the behavior of a mock?"
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test real component or don't mock it
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// OR if sidebar must be mocked for isolation:
+// Don't assert on the mock - test Page's behavior with sidebar present
+```
+
+### Gate Function
+
+```
+BEFORE asserting on any mock element:
+  Ask: "Am I testing real component behavior or just mock existence?"
+
+  IF testing mock existence:
+    STOP - Delete the assertion or unmock the component
+
+  Test real behavior instead
+```
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**The violation:**
+```typescript
+// ❌ BAD: destroy() only used in tests
+class Session {
+  async destroy() {  // Looks like production API!
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
+  }
+}
+
+// In tests
+afterEach(() => session.destroy());
+```
+
+**Why this is wrong:**
+- Production class polluted with test-only code
+- Dangerous if accidentally called in production
+- Violates YAGNI and separation of concerns
+- Confuses object lifecycle with entity lifecycle
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test utilities handle test cleanup
+// Session has no destroy() - it's stateless in production
+
+// In test-utils/
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// In tests
+afterEach(() => cleanupSession(session));
+```
+
+### Gate Function
+
+```
+BEFORE adding any method to production class:
+  Ask: "Is this only used by tests?"
+
+  IF yes:
+    STOP - Don't add it
+    Put it in test utilities instead
+
+  Ask: "Does this class own this resource's lifecycle?"
+
+  IF no:
+    STOP - Wrong class for this method
+```
+
+## Anti-Pattern 3: Mocking Without Understanding
+
+**The violation:**
+```typescript
+// ❌ BAD: Mock breaks test logic
+test('detects duplicate server', () => {
+  // Mock prevents config write that test depends on!
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // Should throw - but won't!
+});
+```
+
+**Why this is wrong:**
+- Mocked method had side effect test depended on (writing config)
+- Over-mocking to "be safe" breaks actual behavior
+- Test passes for wrong reason or fails mysteriously
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mock at correct level
+test('detects duplicate server', () => {
+  // Mock the slow part, preserve behavior test needs
+  vi.mock('MCPServerManager'); // Just mock slow server startup
+
+  await addServer(config);  // Config written
+  await addServer(config);  // Duplicate detected ✓
+});
+```
+
+### Gate Function
+
+```
+BEFORE mocking any method:
+  STOP - Don't mock yet
+
+  1. Ask: "What side effects does the real method have?"
+  2. Ask: "Does this test depend on any of those side effects?"
+  3. Ask: "Do I fully understand what this test needs?"
+
+  IF depends on side effects:
+    Mock at lower level (the actual slow/external operation)
+    OR use test doubles that preserve necessary behavior
+    NOT the high-level method the test depends on
+
+  IF unsure what test depends on:
+    Run test with real implementation FIRST
+    Observe what actually needs to happen
+    THEN add minimal mocking at the right level
+
+  Red flags:
+    - "I'll mock this to be safe"
+    - "This might be slow, better mock it"
+    - Mocking without understanding the dependency chain
+```
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**The violation:**
+```typescript
+// ❌ BAD: Partial mock - only fields you think you need
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // Missing: metadata that downstream code uses
+};
+
+// Later: breaks when code accesses response.metadata.requestId
+```
+
+**Why this is wrong:**
+- **Partial mocks hide structural assumptions** - You only mocked fields you know about
+- **Downstream code may depend on fields you didn't include** - Silent failures
+- **Tests pass but integration fails** - Mock incomplete, real API complete
+- **False confidence** - Test proves nothing about real behavior
+
+**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mirror real API completeness
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // All fields real API returns
+};
+```
+
+### Gate Function
+
+```
+BEFORE creating mock responses:
+  Check: "What fields does the real API response contain?"
+
+  Actions:
+    1. Examine actual API response from docs/examples
+    2. Include ALL fields system might consume downstream
+    3. Verify mock matches real response schema completely
+
+  Critical:
+    If you're creating a mock, you must understand the ENTIRE structure
+    Partial mocks fail silently when code depends on omitted fields
+
+  If uncertain: Include all documented fields
+```
+
+## Anti-Pattern 5: Integration Tests as Afterthought
+
+**The violation:**
+```
+✅ Implementation complete
+❌ No tests written
+"Ready for testing"
+```
+
+**Why this is wrong:**
+- Testing is part of implementation, not optional follow-up
+- TDD would have caught this
+- Can't claim complete without tests
+
+**The fix:**
+```
+TDD cycle:
+1. Write failing test
+2. Implement to pass
+3. Refactor
+4. THEN claim complete
+```
+
+## When Mocks Become Too Complex
+
+**Warning signs:**
+- Mock setup longer than test logic
+- Mocking everything to make test pass
+- Mocks missing methods real components have
+- Test breaks when mock changes
+
+**your human partner's question:** "Do we need to be using a mock here?"
+
+**Consider:** Integration tests with real components often simpler than complex mocks
+
+## TDD Prevents These Anti-Patterns
+
+**Why TDD helps:**
+1. **Write test first** → Forces you to think about what you're actually testing
+2. **Watch it fail** → Confirms test tests real behavior, not mocks
+3. **Minimal implementation** → No test-only methods creep in
+4. **Real dependencies** → You see what the test actually needs before mocking
+
+**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
+
+## Quick Reference
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Assert on mock elements | Test real component or unmock it |
+| Test-only methods in production | Move to test utilities |
+| Mock without understanding | Understand dependencies first, mock minimally |
+| Incomplete mocks | Mirror real API completely |
+| Tests as afterthought | TDD - tests first |
+| Over-complex mocks | Consider integration tests |
+
+## Red Flags
+
+- Assertion checks for `*-mock` test IDs
+- Methods only called in test files
+- Mock setup is >50% of test
+- Test fails when you remove mock
+- Can't explain why mock is needed
+- Mocking "just to be safe"
+
+## The Bottom Line
+
+**Mocks are tools to isolate, not things to test.**
+
+If TDD reveals you're testing mock behavior, you've gone wrong.
+
+Fix: Test real behavior or question why you're mocking at all.

package/skills/gxpm-triage/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: gxpm-triage
+description: Triage issues through a state machine of triage roles. Use when user wants to create an issue, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
+---
+
+# Triage
+
+Move issues through a small state machine of triage roles.
+
+## 入口条件
+
+**何时触发**
+- 用户想创建 issue。
+- 用户要求 review incoming bugs 或 feature requests。
+- 用户需要 prepare issues for an AFK agent。
+- 用户需要 manage issue workflow（查看待分类、待处理的内容）。
+- 从 `plan` 回退或新信息到达时，需要重新评估 issue 状态。
+
+**前置条件**
+- Issue body 或 bug report 已存在；或用户已提供足够信息创建新 issue。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需求/范围需要深入对齐 → `/gxpm-grill`
+- 需要代码调试定位根因 → `/gxpm-debug-issue`
+- 需要产出实现计划或 PRD → `/gxpm-planning`
+- 需要自动驾驶全流程 → `/gxpm-autopilot`
+
+## 可操作流程
+
+### 角色定义
+
+Two **category** roles:
+- `bug` — something is broken
+- `enhancement` — new feature or improvement
+
+Five **state** roles:
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter for more information
+- `ready-for-agent` — fully specified, ready for an AFK agent
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Every triaged issue should carry exactly one category role and one state role.
+
+### 1. Show what needs attention
+
+Query the issue tracker and present three buckets, oldest first:
+
+1. **Unlabeled** — never triaged.
+2. **`needs-triage`** — evaluation in progress.
+3. **`needs-info` with reporter activity since last triage notes** — needs re-evaluation.
+
+Show counts and a one-line summary per issue.
+
+### 2. Triage a specific issue
+
+1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse prior triage notes. Explore the codebase. Read `.gxpm/out-of-scope/` (if exists) and surface any prior rejection that resembles this issue.
+
+2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary.
+
+3. **Reproduce (bugs only).** Before grilling, attempt reproduction. Report what happened — successful repro, failed repro, or insufficient detail (a strong `needs-info` signal).
+
+4. **Grill (if needed).** If the issue needs fleshing out, run `/gxpm-grill`.
+
+5. **Apply the outcome:**
+   - **No exceptions:** category + state must both be assigned. Never leave an issue with only one dimension filled.
+   - `ready-for-agent` — write an agent brief.
+   - `ready-for-human` — same structure as agent brief, but note why it can't be delegated.
+   - `needs-info` — post triage notes.
+   - `wontfix` (bug) — polite explanation, then close.
+   - `wontfix` (enhancement) — write to `.gxpm/out-of-scope/`, link from comment, then close.
+
+#### Agent brief format
+
+```markdown
+> *This was generated by AI during triage.*
+
+## What to build
+Concise description.
+
+## Acceptance criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Key constraints
+- Constraint 1
+- Constraint 2
+
+## Relevant code areas
+- File/path 1
+- File/path 2
+```
+
+#### Needs-info template
+
+```markdown
+> *This was generated by AI during triage.*
+
+## Triage Notes
+
+**What we've established so far:**
+- point 1
+- point 2
+
+**What we still need from you (@reporter):**
+- question 1
+- question 2
+```
+
+### gxpm integration
+
+- gxpm's `triage` phase initializes the `acceptance-contract` artifact.
+- During triage, if the issue is a bug, the `acceptance-contract` must include a `reproduction` field:
+  - Test command that reproduces the bug, OR
+  - Steps to reproduce, OR
+  - "Could not reproduce — insufficient detail"
+- The `acceptance-contract` should include a `triageRole` field:
+  - `needs-info` / `ready-for-agent` / `ready-for-human` / `wontfix`
+- Use `gxpm issue create --auto-id` for new issues; use `gxpm issue transition` to move through phases.
+- Out-of-scope knowledge lives under `.gxpm/out-of-scope/<topic>.md`.
+
+## 红旗清单 / 反模式
+
+- **STOP：没有 reproduction，就没有 `ready-for-agent`。** A bug without a reproduction attempt or clear "could not reproduce — insufficient detail" note must NOT be marked `ready-for-agent`.
+- **STOP：范围蔓延。** If the issue grows beyond its original description during triage, stop and ask the user to split it before assigning a state role.
+- **STOP：冲突的 triage roles。** If an issue carries more than one category role or more than one state role, reset to `needs-triage` and fix immediately.
+- **STOP：绕过 `needs-info`。** Never guess a category or state when information is insufficient. Default to `needs-info`.
+- **STOP：绝不只分配一个维度。** category + state 必须同时分配；禁止只填其一。
+- **危险信号：** "The bug is obvious, no need to reproduce." → Obvious bugs are the most dangerous to skip. Reproduction validates assumptions and provides the acceptance-contract entry.
+- **危险信号：** "The reporter is trusted, mark it ready-for-agent." → **No exceptions.** Every bug needs reproduction or a clear `needs-info` path, regardless of who reported it.
+- **危险信号：** "I'll just add both category roles to be safe." → Exactly one category role. Adding both destroys the state machine and makes routing impossible.
+- **危险信号：** "The user seems impatient, I'll skip grilling." → Skipping grilling when scope is unclear produces `ready-for-agent` issues that fail at `ac-check`.
+
+**Foundational Principle:** Violating the letter of the rules is violating the spirit of the rules. The triage state machine exists to protect downstream phases from garbage-in-garbage-out. Every shortcut at triage becomes a blocker at `implement`, `local-verify`, or `land`. Discipline here is kindness to the future agent.
+
+## 验证清单 / 出口条件
+
+- [ ] 每个 issue 恰好一个 category role 和一个 state role。
+- [ ] Bug 必须有 reproduction（test command / steps / "Could not reproduce — insufficient detail"）。
+- [ ] `acceptance-contract` artifact 已初始化，含 `triageRole` 字段。
+- [ ] `ready-for-agent` 已输出 agent brief（What to build / Acceptance criteria / Key constraints / Relevant code areas）。
+- [ ] `ready-for-human` 已说明为什么不能委托给 agent。
+- [ ] `needs-info` 已输出 triage notes（已建立的事实 + 仍需 reporter 提供的信息）。
+- [ ] `wontfix` (bug) 已有 polite explanation 并关闭。
+- [ ] `wontfix` (enhancement) 已写入 `.gxpm/out-of-scope/` 并关闭。
+
+**失败时路由**
+- Scope 不清或术语漂移 → `/gxpm-grill`
+- 需要代码定位或根因分析 → `/gxpm-debug-issue`
+- 已 ready-for-agent 需要实现计划 → `/gxpm-planning`
+
+## 常见说辞表
+
+| 用户 utterance / 借口 | 推荐回应 |
+|-----------------------|----------|
+| "这个 bug 很明显，不用复现。" | "明显的 bug 跳过复现最危险。复现能验证假设，也是验收契约的入口。请先尝试复现。" |
+| "报告者很可信，直接 ready-for-agent 吧。" | "没有例外。每个 bug 都需要复现或清晰的 needs-info 路径，无论谁报告的。" |
+| "我把两个 category 都加上以防万一。" | "只能选一个 category role。选两个会破坏状态机，导致路由失败。请根据问题本质选一个。" |
+| "用户好像很急，我就不 grill 了。" | "scope 不清时跳过 grilling，会导致 ready-for-agent 的 issue 在 ac-check 阶段失败。建议先用 /gxpm-grill 对齐。" |
+| "帮我看看有哪些 issue 需要处理。" | 展示 Unlabeled / needs-triage / needs-info with reporter activity 三个 bucket。 |

package/skills/gxpm-verify/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: gxpm-verify
+description: Local verification pipeline execution and evidence collection. Use when transitioning from implement to local-verify, or when running the full verification suite for an issue.
+---
+
+# gxpm-verify
+
+## 入口条件
+
+在以下场景触发本 skill：
+
+- `implement` 阶段完成，即将过渡到 `local-verify`
+- 需要为某个 issue 运行完整验证套件
+- 需要收集验证证据以推进工作流
+
+`local-verify` artifact 不完整时禁止进入 `ac-check`。
+
+## 可操作流程
+
+### 验证流水线
+
+按成本升序执行。**遇到第一个失败即停止。**
+
+```
+Step 1: git diff --check          (free — whitespace violations)
+Step 2: bun run check             (fast — static analysis + typecheck)
+Step 3: bun test                  (medium — unit + integration tests)
+Step 4: bun run build             (medium — compilation verification)
+```
+
+只运行与变更相关的步骤：
+- Pure test changes: Steps 1–3 are sufficient.
+- Build config or type changes: All 4 steps required.
+- Documentation only: Step 1 only.
+
+### 证据收集
+
+每步完成后记录：
+
+```json
+{
+  "verificationSteps": [
+    {
+      "step": "git-diff-check",
+      "command": "git diff --check",
+      "exitCode": 0,
+      "durationMs": 120,
+      "summary": "no whitespace errors"
+    },
+    {
+      "step": "typecheck",
+      "command": "bun run check",
+      "exitCode": 0,
+      "durationMs": 1200,
+      "summary": "42 files checked, 0 errors"
+    },
+    {
+      "step": "test",
+      "command": "bun test",
+      "exitCode": 0,
+      "durationMs": 4500,
+      "summary": "156 passed, 0 failed"
+    },
+    {
+      "step": "build",
+      "command": "bun run build",
+      "exitCode": 0,
+      "durationMs": 2800,
+      "summary": "build succeeded"
+    }
+  ]
+}
+```
+
+### 失败时的 Skill 路由
+
+某一步失败时，加载对应 skill 修复，禁止盲目修复：
+
+| Failed step | Root cause likely | Load this skill |
+|-------------|-------------------|-----------------|
+| `git diff --check` | Whitespace / trailing space | Fix directly, re-run from Step 1 |
+| `bun run check` | Type error, syntax error, lint violation | `/gxpm-build` |
+| `bun test` | Test failure, regression, missing coverage | `/gxpm-tdd` |
+| `bun run build` | Build script error, dependency issue | `/gxpm-build` |
+
+**Do not fix blindly.** Load the relevant skill, follow its discipline, then re-run the full pipeline from Step 1.
+
+## 红旗清单 / 反模式
+
+- **No skips.** Every relevant step must execute and pass.
+- **Evidence before transition.** `local-verify` artifact is incomplete without `verificationSteps`.
+- **Re-run discipline:** Only re-run a step if the code has changed since the last run. Re-running on unchanged code adds no information.
+
+## 验证清单 / 出口条件
+
+完成 `local-verify` 必须满足：
+
+- [ ] 所有相关步骤均已执行且通过（exit code 0）
+- [ ] `local-verify` artifact 包含完整的 `verificationSteps` 数组
+- [ ] 每步记录包含：step 名称、command、exitCode、durationMs、summary
+- [ ] 如某步失败，已加载对应 skill 修复并重新运行完整流水线
+- [ ] 代码自上次运行后如有变更，已重新执行全部相关步骤
+
+在 gxpm 工作流中：
+- 在 `implement → local-verify` 过渡时加载本 skill
+- `local-verify` artifact 必须包含 `verificationSteps` 后才能推进到 `ac-check`
+- 任何步骤失败，修复后必须从 Step 1 重新运行完整流水线

package/skills/gxpm-write-skill/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: gxpm-write-skill
+description: Create new gxpm skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Write a Skill
+
+Create new agent skills that follow gxpm conventions.
+
+## 入口条件
+
+**何时触发**
+- 用户说 "create a skill"、"write a skill"、"new skill"。
+- 需要为 gxpm 生态添加新能力。
+- 需要审核或改进现有 skill 的结构。
+
+**Skill 边界**
+- 需要 skill 质量评估 → `/gxpm-eval`
+- 需要更新 skills-lock → `/maintain-hygiene-skills-lock`
+
+## 可操作流程
+
+### 1. Gather requirements
+
+Ask the user:
+
+- What task/domain does the skill cover?
+- What specific use cases should it handle?
+- Does it need executable scripts or just instructions?
+- Any reference materials to include?
+
+### 2. Draft the skill
+
+Create:
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── references/        # Detailed docs (if needed)
+│   └── topic.md
+└── scripts/           # Utility scripts (if needed)
+    └── helper.ts
+```
+
+### 3. SKILL.md structure
+
+```md
+---
+name: skill-name
+description: Brief description. Use when [specific triggers].
+---
+
+# Skill Name
+
+## 入口条件
+
+**何时触发**
+- ...
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- ...
+
+## 可操作流程
+
+[Step-by-step processes]
+
+## 红旗清单 / 反模式
+
+- **STOP：...**
+
+## 验证清单 / 出口条件
+
+- [ ] ...
+
+**失败时路由**
+- ...
+```
+
+### Description rules
+
+The description is **the only thing your agent sees** when deciding which skill to load.
+
+- Max 1024 chars
+- Third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good:**
+```
+Move issues through a state machine of triage roles. Use when user wants to create, review, or route issues.
+```
+
+**Bad:**
+```
+Helps with issues.
+```
+
+### When to split files
+
+Split into `references/` when:
+
+- SKILL.md exceeds 120 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+### When to add scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+## 红旗清单 / 反模式
+
+- **STOP：description 超过 1024 字符。** Agent 的上下文有限，过长的 description 降低匹配精度。
+- **STOP：没有 "Use when" 触发句。** Agent 无法判断何时加载该 skill。
+- **STOP：SKILL.md 超过 200 行还不拆分。** 使用 `references/` 子文件做渐进式披露。
+- **STOP：缺少红旗清单或验证清单。** 每个 gxpm skill 必须包含这四个核心 section。
+
+## 验证清单 / 出口条件
+
+- [ ] Description ≤ 1024 chars，包含 "Use when..." 触发句。
+- [ ] SKILL.md 包含：入口条件、可操作流程、红旗清单、验证清单。
+- [ ] 如超过 120 行，已拆分为 `references/` 子文件。
+- [ ] 术语与 `CONTEXT.md` 一致。
+- [ ] 运行 `bun run check` 通过（skills-lock hash 已更新）。
+
+**失败时路由**
+- Skill 质量评估 → `/gxpm-eval`
+- 需要更新 skills-lock → `/maintain-hygiene-skills-lock`