@geminix/gxpm 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (299) hide show
  1. package/AGENTS.md +148 -0
  2. package/CANON.md +53 -0
  3. package/CLAUDE.md +60 -0
  4. package/CONTEXT.md +49 -0
  5. package/DEBUG.md +59 -0
  6. package/ISSUE_CONTEXT.md +25 -0
  7. package/README.md +143 -0
  8. package/VERSION +1 -0
  9. package/agents/cleanup-auditor/cleanup-auditor.md +56 -0
  10. package/agents/grill-master.md +26 -0
  11. package/agents/implementer.md +32 -0
  12. package/agents/review-army/accessibility-reviewer.md +54 -0
  13. package/agents/review-army/code-quality-reviewer.md +54 -0
  14. package/agents/review-army/security-reviewer.md +56 -0
  15. package/agents/review-army/spec-compliance-reviewer.md +51 -0
  16. package/agents/review-army/test-reviewer.md +55 -0
  17. package/agents/reviewer.md +59 -0
  18. package/agents/ship-audit-army/docs-auditor.md +53 -0
  19. package/agents/ship-audit-army/performance-auditor.md +52 -0
  20. package/agents/ship-audit-army/security-auditor.md +52 -0
  21. package/agents/specifier.md +55 -0
  22. package/agents/triage-officer.md +27 -0
  23. package/bin/gxpm +17 -0
  24. package/bin/gxpm-browser +17 -0
  25. package/bin/gxpm-config +15 -0
  26. package/bin/gxpm-eval +13 -0
  27. package/bin/gxpm-global-discover +15 -0
  28. package/bin/gxpm-init +38 -0
  29. package/bin/gxpm-investigate +194 -0
  30. package/bin/gxpm-uninstall +15 -0
  31. package/bin/gxpm-update-check +165 -0
  32. package/commands/build.md +40 -0
  33. package/commands/help.md +53 -0
  34. package/commands/plan.md +34 -0
  35. package/commands/refine.md +46 -0
  36. package/commands/review.md +34 -0
  37. package/commands/ship.md +37 -0
  38. package/core/ac-check.ts +20 -0
  39. package/core/agent-runtime.ts +363 -0
  40. package/core/artifact-validator.ts +151 -0
  41. package/core/artifacts.ts +313 -0
  42. package/core/autopilot.ts +250 -0
  43. package/core/capabilities.ts +779 -0
  44. package/core/checkpoint.ts +370 -0
  45. package/core/cleanup.ts +32 -0
  46. package/core/command-probe.ts +82 -0
  47. package/core/config.ts +533 -0
  48. package/core/contracts/behavior-spec.schema.ts +38 -0
  49. package/core/contracts/converter.ts +61 -0
  50. package/core/contracts/host.ts +43 -0
  51. package/core/converters/converter.ts +93 -0
  52. package/core/converters/index.ts +8 -0
  53. package/core/converters/managed-artifact.ts +119 -0
  54. package/core/converters/parser.ts +159 -0
  55. package/core/converters/template-renderer.ts +35 -0
  56. package/core/converters/writer.ts +61 -0
  57. package/core/dag-executor.ts +426 -0
  58. package/core/dag-loader.ts +292 -0
  59. package/core/dag-schemas.ts +150 -0
  60. package/core/dispatch.ts +125 -0
  61. package/core/evidence.ts +148 -0
  62. package/core/gate.ts +269 -0
  63. package/core/hook-engine.ts +566 -0
  64. package/core/host-probe.ts +64 -0
  65. package/core/implement.ts +16 -0
  66. package/core/isolation-errors.ts +174 -0
  67. package/core/isolation-resolver.ts +921 -0
  68. package/core/issue-context.ts +381 -0
  69. package/core/issue-readiness.ts +457 -0
  70. package/core/issue-sync.ts +427 -0
  71. package/core/issues.ts +132 -0
  72. package/core/land.ts +108 -0
  73. package/core/orchestrator.ts +54 -0
  74. package/core/phase-artifact.ts +32 -0
  75. package/core/phase-gates.ts +130 -0
  76. package/core/phase-rewind.ts +94 -0
  77. package/core/plan-lint.ts +61 -0
  78. package/core/plan.ts +77 -0
  79. package/core/port-allocation.ts +50 -0
  80. package/core/pr-check.ts +15 -0
  81. package/core/preset-system/preset-resolver.ts +221 -0
  82. package/core/project-init-status.ts +127 -0
  83. package/core/qa.ts +15 -0
  84. package/core/resilience.ts +165 -0
  85. package/core/runs.ts +288 -0
  86. package/core/safe-path.test.ts +80 -0
  87. package/core/safe-path.ts +60 -0
  88. package/core/sdd-gate.test.ts +98 -0
  89. package/core/sdd-gate.ts +134 -0
  90. package/core/self-review.ts +62 -0
  91. package/core/session.ts +70 -0
  92. package/core/ship.ts +86 -0
  93. package/core/specify.ts +173 -0
  94. package/core/state.ts +1002 -0
  95. package/core/template-engine.ts +152 -0
  96. package/core/template-resolver.test.ts +70 -0
  97. package/core/template-resolver.ts +156 -0
  98. package/core/triage.ts +26 -0
  99. package/core/verify.ts +15 -0
  100. package/core/wiki-native.ts +2423 -0
  101. package/core/wiki.ts +27 -0
  102. package/core/workflow-event-emitter.ts +163 -0
  103. package/core/workflows/engine.ts +273 -0
  104. package/core/workflows/expressions.ts +76 -0
  105. package/core/workflows/index.ts +38 -0
  106. package/core/workflows/steps/command.ts +43 -0
  107. package/core/workflows/steps/gate.ts +47 -0
  108. package/core/workflows/steps/gxpm.ts +44 -0
  109. package/core/workflows/steps/linear.ts +31 -0
  110. package/core/workflows/steps/shell.ts +65 -0
  111. package/core/workflows/types.ts +62 -0
  112. package/core/workspace-runtime.ts +227 -0
  113. package/core/worktree-init-steps.ts +647 -0
  114. package/core/worktree-init.ts +330 -0
  115. package/core/worktree-owner.ts +143 -0
  116. package/docs/GXPM_VERIFY.md +98 -0
  117. package/docs/INSTALL_FOR_AGENTS.md +113 -0
  118. package/docs/README.md +57 -0
  119. package/docs/adr/adr-005-multi-platform-skill-converter.md +72 -0
  120. package/docs/agents/domain.md +30 -0
  121. package/docs/agents/issue-tracker.md +30 -0
  122. package/docs/agents/triage-labels.md +32 -0
  123. package/docs/architecture/gxpm-architecture-diagram.md +265 -0
  124. package/docs/architecture/gxpm-current-architecture.md +175 -0
  125. package/docs/architecture/gxpm-current-flow.md +278 -0
  126. package/docs/architecture/gxpm-replacement-architecture.md +211 -0
  127. package/docs/architecture/gxpm-target-architecture.md +449 -0
  128. package/docs/architecture/gxpm-v0-contract.md +311 -0
  129. package/docs/architecture/layered-workflow-boundaries.md +193 -0
  130. package/docs/architecture/preset-system.md +126 -0
  131. package/docs/architecture/scaffold-northstar.md +23 -0
  132. package/docs/brainstorms/2026-05-14-bdd-then-tdd-design.md +320 -0
  133. package/docs/brainstorms/README.md +22 -0
  134. package/docs/brainstorms/docs-knowledge-system-requirements.md +29 -0
  135. package/docs/governance/beta-skill-promotion.md +39 -0
  136. package/docs/governance/development-contract.md +144 -0
  137. package/docs/governance/gherkin-style.md +90 -0
  138. package/docs/governance/host-adapter.md +56 -0
  139. package/docs/governance/skill-authoring.md +87 -0
  140. package/docs/governance/skill-testing.md +356 -0
  141. package/docs/governance/template-authoring.md +53 -0
  142. package/docs/migrations/v0.2.md +51 -0
  143. package/docs/plans/README.md +23 -0
  144. package/docs/plans/bdd-then-tdd-plan.md +1767 -0
  145. package/docs/plans/docs-knowledge-system-plan.md +31 -0
  146. package/docs/plans/spec-kit-sdd-adoption-plan.md +305 -0
  147. package/docs/research/agents-md-best-practices.md +207 -0
  148. package/docs/research/archon-study.md +351 -0
  149. package/docs/research/claude-hooks-study.md +440 -0
  150. package/docs/research/codex-hooks-study.md +624 -0
  151. package/docs/research/everything-claude-code-study.md +252 -0
  152. package/docs/research/from-skills-to-layered-workflow.md +322 -0
  153. package/docs/research/gsd-study.md +69 -0
  154. package/docs/research/kimi-hooks-study.md +274 -0
  155. package/docs/research/mattpocock-skills-comparison.md +429 -0
  156. package/docs/research/mattpocock-skills-study.md +275 -0
  157. package/docs/research/oh-my-codex-study.md +279 -0
  158. package/docs/research/perplexity-agent-skills-design.md +168 -0
  159. package/docs/research/pmc-gstack-skill-study.md +122 -0
  160. package/docs/research/spec-kit-study.md +224 -0
  161. package/docs/research/superpowers-study.md +209 -0
  162. package/docs/roadmap/initial-roadmap.md +53 -0
  163. package/docs/solutions/README.md +45 -0
  164. package/docs/solutions/artifact-nesting-recovery.md +58 -0
  165. package/docs/solutions/session-context-restore-practice.md +67 -0
  166. package/docs/solutions/workflow/version-drift-recovery.md +49 -0
  167. package/docs/solutions/worktree-gate-recovery.md +62 -0
  168. package/docs/specs/README.md +28 -0
  169. package/docs/specs/claude.md +45 -0
  170. package/docs/specs/codex.md +44 -0
  171. package/docs/specs/cursor.md +44 -0
  172. package/hosts/adapters/claude.ts +29 -0
  173. package/hosts/adapters/codex.ts +27 -0
  174. package/hosts/adapters/cursor.ts +27 -0
  175. package/hosts/adapters/kimi.ts +27 -0
  176. package/hosts/claude.ts +23 -0
  177. package/hosts/codex.ts +26 -0
  178. package/hosts/cursor.ts +19 -0
  179. package/hosts/index.ts +33 -0
  180. package/hosts/registry.test.ts +52 -0
  181. package/hosts/registry.ts +57 -0
  182. package/hosts/schema.ts +58 -0
  183. package/package.json +52 -0
  184. package/scripts/browser.ts +185 -0
  185. package/scripts/cleanup.ts +142 -0
  186. package/scripts/commands/artifact.ts +115 -0
  187. package/scripts/commands/autopilot.ts +143 -0
  188. package/scripts/commands/capability.ts +57 -0
  189. package/scripts/commands/config.ts +69 -0
  190. package/scripts/commands/dag.ts +126 -0
  191. package/scripts/commands/feedback.ts +123 -0
  192. package/scripts/commands/gate.ts +291 -0
  193. package/scripts/commands/helpers.ts +126 -0
  194. package/scripts/commands/hook.ts +66 -0
  195. package/scripts/commands/init.ts +515 -0
  196. package/scripts/commands/issue.ts +825 -0
  197. package/scripts/commands/phase.ts +61 -0
  198. package/scripts/commands/preset.ts +159 -0
  199. package/scripts/commands/runtime.ts +199 -0
  200. package/scripts/commands/specify.ts +71 -0
  201. package/scripts/commands/upgrade.ts +243 -0
  202. package/scripts/commands/verify.ts +183 -0
  203. package/scripts/commands/wiki.ts +242 -0
  204. package/scripts/commands/workflow.ts +131 -0
  205. package/scripts/dev-skill.ts +55 -0
  206. package/scripts/discover-skills.ts +116 -0
  207. package/scripts/doctor.ts +410 -0
  208. package/scripts/dogfood-check.ts +125 -0
  209. package/scripts/eval-functional.ts +218 -0
  210. package/scripts/eval.ts +246 -0
  211. package/scripts/gen-skill-docs.ts +201 -0
  212. package/scripts/global-discover.ts +217 -0
  213. package/scripts/governance-check.ts +75 -0
  214. package/scripts/gxpm-check.ts +12 -0
  215. package/scripts/gxpm.ts +216 -0
  216. package/scripts/host-config.ts +62 -0
  217. package/scripts/install-claude-hooks.ts +138 -0
  218. package/scripts/install-codex-hooks.ts +271 -0
  219. package/scripts/install-hooks.ts +128 -0
  220. package/scripts/install-kimi-hooks.ts +92 -0
  221. package/scripts/install-skill.ts +184 -0
  222. package/scripts/phase-artifact-commands.ts +100 -0
  223. package/scripts/post-land-sync.ts +46 -0
  224. package/scripts/scaffold-check.ts +85 -0
  225. package/scripts/skill-naming-check.ts +78 -0
  226. package/scripts/skill-structure-check.ts +157 -0
  227. package/scripts/skills-lock-check.ts +60 -0
  228. package/scripts/sync-markdown-artifacts.ts +172 -0
  229. package/scripts/uninstall.ts +162 -0
  230. package/scripts/version.ts +47 -0
  231. package/scripts/wait-pr-ready.ts +407 -0
  232. package/skills/gxpm/SKILL.md +485 -0
  233. package/skills/gxpm/SKILL.md.tmpl +422 -0
  234. package/skills/gxpm/references/CANON.md +53 -0
  235. package/skills/gxpm/references/key-rules.md +130 -0
  236. package/skills/gxpm-architecture/SKILL.md +106 -0
  237. package/skills/gxpm-architecture/references/DEEPENING.md +37 -0
  238. package/skills/gxpm-architecture/references/INTERFACE-DESIGN.md +44 -0
  239. package/skills/gxpm-autopilot/SKILL.md +116 -0
  240. package/skills/gxpm-autopilot/SKILL.md.tmpl +107 -0
  241. package/skills/gxpm-browser/SKILL.md +105 -0
  242. package/skills/gxpm-browser/SKILL.md.tmpl +41 -0
  243. package/skills/gxpm-browser/references/commands.md +43 -0
  244. package/skills/gxpm-browser/references/evidence-path.md +20 -0
  245. package/skills/gxpm-build/SKILL.md +78 -0
  246. package/skills/gxpm-cleanup/SKILL.md +76 -0
  247. package/skills/gxpm-debug-issue/SKILL.md +39 -0
  248. package/skills/gxpm-diagnose/SKILL.md +220 -0
  249. package/skills/gxpm-diagnose/SKILL.md.tmpl +31 -0
  250. package/skills/gxpm-diagnose/references/feedback-loop.md +34 -0
  251. package/skills/gxpm-diagnose/references/feedback-loops.md +43 -0
  252. package/skills/gxpm-diagnose/references/phases.md +60 -0
  253. package/skills/gxpm-eval/SKILL.md +78 -0
  254. package/skills/gxpm-explore-codebase/SKILL.md +36 -0
  255. package/skills/gxpm-explore-codebase/scripts/summarize-communities.ts +51 -0
  256. package/skills/gxpm-feedback/SKILL.md +122 -0
  257. package/skills/gxpm-grill/SKILL.md +159 -0
  258. package/skills/gxpm-grill/SKILL.md.tmpl +77 -0
  259. package/skills/gxpm-grill/references/documentation-templates.md +56 -0
  260. package/skills/gxpm-grill/references/process.md +25 -0
  261. package/skills/gxpm-handoff/SKILL.md +112 -0
  262. package/skills/gxpm-hygiene/SKILL.md +69 -0
  263. package/skills/gxpm-implementer/SKILL.md +142 -0
  264. package/skills/gxpm-implementer/SKILL.md.tmpl +141 -0
  265. package/skills/gxpm-linear/SKILL.md +282 -0
  266. package/skills/gxpm-linear/SKILL.md.tmpl +86 -0
  267. package/skills/gxpm-linear/references/commands.md +75 -0
  268. package/skills/gxpm-linear/references/workflows.md +120 -0
  269. package/skills/gxpm-planning/SKILL.md +134 -0
  270. package/skills/gxpm-prototype/SKILL.md +64 -0
  271. package/skills/gxpm-refactor-safely/SKILL.md +62 -0
  272. package/skills/gxpm-review-army/SKILL.md +117 -0
  273. package/skills/gxpm-review-changes/SKILL.md +36 -0
  274. package/skills/gxpm-setup/SKILL.md +101 -0
  275. package/skills/gxpm-specifier/SKILL.md +135 -0
  276. package/skills/gxpm-tdd/SKILL.md +187 -0
  277. package/skills/gxpm-tdd/references/interface-design.md +23 -0
  278. package/skills/gxpm-tdd/references/mocking.md +27 -0
  279. package/skills/gxpm-tdd/references/red-green-refactor.md +61 -0
  280. package/skills/gxpm-tdd/references/troubleshooting.md +28 -0
  281. package/skills/gxpm-tdd/references/workflow.md +50 -0
  282. package/skills/gxpm-tdd/testing-anti-patterns.tmpl +304 -0
  283. package/skills/gxpm-triage/SKILL.md +160 -0
  284. package/skills/gxpm-verify/SKILL.md +107 -0
  285. package/skills/gxpm-write-skill/SKILL.md +131 -0
  286. package/skills/gxpm-zoom-out/SKILL.md +69 -0
  287. package/skills/maintain-hygiene-skills-lock/SKILL.md +54 -0
  288. package/skills/maintain-hygiene-skills-lock/SKILL.md.tmpl +53 -0
  289. package/templates/constitution-template.md +63 -0
  290. package/templates/hooks/gxpm-commit-msg +16 -0
  291. package/templates/hooks/gxpm-post-checkout +19 -0
  292. package/templates/hooks/gxpm-post-commit +7 -0
  293. package/templates/hooks/gxpm-post-merge +29 -0
  294. package/templates/hooks/gxpm-pre-commit +39 -0
  295. package/templates/hooks/gxpm-pre-push +33 -0
  296. package/templates/plan-template.md.tmpl +46 -0
  297. package/templates/spec-template.md.tmpl +63 -0
  298. package/templates/specify-stub.tmpl +22 -0
  299. package/templates/tasks-template.md.tmpl +32 -0
package/bin/gxpm-init ADDED
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ SOURCE="${BASH_SOURCE[0]}"
5
+ while [ -L "$SOURCE" ]; do
6
+ TARGET="$(readlink "$SOURCE")"
7
+ if [[ "$TARGET" = /* ]]; then
8
+ SOURCE="$TARGET"
9
+ else
10
+ SOURCE="$(cd -P "$(dirname "$SOURCE")" && pwd)/$TARGET"
11
+ fi
12
+ done
13
+ ROOT="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
14
+
15
+ case "${1:-}" in
16
+ --install-hooks)
17
+ shift
18
+ exec bun run "$ROOT/scripts/install-hooks.ts" "$@"
19
+ ;;
20
+ --install-skill)
21
+ shift
22
+ exec bun run "$ROOT/scripts/install-skill.ts" "$@"
23
+ ;;
24
+ --install-codex-hooks)
25
+ shift
26
+ exec bun run "$ROOT/scripts/install-codex-hooks.ts" "$@"
27
+ ;;
28
+ --install)
29
+ shift
30
+ # Combo: install skill globally to all hosts AND install hooks to a target repo.
31
+ # Usage: gxpm-init --install [--target <repo>]
32
+ bun run "$ROOT/scripts/install-skill.ts" --host all
33
+ exec bun run "$ROOT/scripts/install-hooks.ts" "$@"
34
+ ;;
35
+ *)
36
+ exec bun run "$ROOT/scripts/gen-skill-docs.ts" "$@"
37
+ ;;
38
+ esac
@@ -0,0 +1,194 @@
1
+ #!/usr/bin/env bun
2
+ import {
3
+ evidenceFilename,
4
+ prepareIssueEvidencePath,
5
+ writeIssueEvidenceJson,
6
+ } from "../core/evidence";
7
+ import { readIssueState } from "../core/state";
8
+
9
+ interface InvestigationArtifact {
10
+ schemaVersion: 1;
11
+ ts: string;
12
+ surface_id: string;
13
+ status: "running" | "complete" | "failed";
14
+ url: string | null;
15
+ viewport: { width: number; height: number } | null;
16
+ isMobile: boolean | null;
17
+ snapshot_text: string;
18
+ console_lines: string[];
19
+ errors: string[];
20
+ screenshot_path: string | null;
21
+ label?: string;
22
+ actions: Array<{
23
+ name: string;
24
+ command: string[];
25
+ exitCode: number;
26
+ ok: boolean;
27
+ stdout?: string;
28
+ stderr?: string;
29
+ }>;
30
+ failure?: { message: string };
31
+ }
32
+
33
+ const args = Bun.argv.slice(2);
34
+ const issueId = args[0];
35
+ const usage = "Usage: gxpm-investigate <issue-id> [--label <text>]";
36
+
37
+ if (args.includes("--help") || args.includes("-h")) {
38
+ console.log(usage);
39
+ process.exit(0);
40
+ }
41
+
42
+ if (!issueId) {
43
+ fail(usage);
44
+ }
45
+
46
+ const labelIndex = args.indexOf("--label");
47
+ const label = labelIndex >= 0 ? args[labelIndex + 1] : undefined;
48
+ if (labelIndex >= 0 && !label) {
49
+ fail("Missing value for --label");
50
+ }
51
+
52
+ const surfaceId = process.env.CMUX_SURFACE_ID;
53
+ if (!surfaceId) {
54
+ fail("CMUX_SURFACE_ID is required; run this from a cmux surface-aware session.");
55
+ }
56
+
57
+ if (!Bun.which("cmux")) {
58
+ fail("cmux CLI was not found in PATH.");
59
+ }
60
+
61
+ const root = process.env.GXPM_ROOT ?? process.cwd();
62
+ try {
63
+ readIssueState({ root, issueId });
64
+ } catch (error) {
65
+ fail(error instanceof Error ? error.message : String(error));
66
+ }
67
+
68
+ const startedAt = new Date();
69
+ const ts = startedAt.toISOString();
70
+ const artifactFilename = evidenceFilename("investigation", "json", startedAt);
71
+ const investigation = prepareIssueEvidencePath({
72
+ root,
73
+ issueId,
74
+ kind: "investigations",
75
+ filename: artifactFilename,
76
+ });
77
+ const screenshot = prepareIssueEvidencePath({
78
+ root,
79
+ issueId,
80
+ kind: "screenshots",
81
+ filename: evidenceFilename("investigation", "png", startedAt),
82
+ });
83
+ const screenshotRelPath = screenshot.path;
84
+ const screenshotPath = screenshot.absolutePath;
85
+
86
+ const artifact: InvestigationArtifact = {
87
+ schemaVersion: 1,
88
+ ts,
89
+ surface_id: surfaceId,
90
+ status: "running",
91
+ url: null,
92
+ viewport: null,
93
+ isMobile: null,
94
+ snapshot_text: "",
95
+ console_lines: [],
96
+ errors: [],
97
+ screenshot_path: null,
98
+ label,
99
+ actions: [],
100
+ };
101
+
102
+ function persist() {
103
+ writeIssueEvidenceJson({
104
+ root,
105
+ issueId,
106
+ kind: "investigations",
107
+ filename: artifactFilename,
108
+ payload: artifact,
109
+ });
110
+ }
111
+
112
+ function runCmux(name: string, commandArgs: string[]) {
113
+ const command = ["cmux", "browser", surfaceId!, ...commandArgs];
114
+ const result = Bun.spawnSync({
115
+ cmd: command,
116
+ stdout: "pipe",
117
+ stderr: "pipe",
118
+ });
119
+ const stdout = result.stdout.toString().trimEnd();
120
+ const stderr = result.stderr.toString().trimEnd();
121
+ const action = {
122
+ name,
123
+ command,
124
+ exitCode: result.exitCode,
125
+ ok: result.exitCode === 0,
126
+ stdout: stdout || undefined,
127
+ stderr: stderr || undefined,
128
+ };
129
+ artifact.actions.push(action);
130
+ if (result.exitCode !== 0) {
131
+ throw new Error(`${name} failed: ${command.slice(1).join(" ")}\n${stderr || stdout}`);
132
+ }
133
+ return stdout;
134
+ }
135
+
136
+ function lines(text: string) {
137
+ return text.split(/\r?\n/).map((line) => line.trimEnd()).filter(Boolean);
138
+ }
139
+
140
+ function applyContext(text: string) {
141
+ try {
142
+ const context = JSON.parse(text) as {
143
+ url?: string;
144
+ viewport?: { width?: number; height?: number };
145
+ isMobile?: boolean;
146
+ };
147
+ if (context.url) artifact.url = context.url;
148
+ if (typeof context.viewport?.width === "number" && typeof context.viewport?.height === "number") {
149
+ artifact.viewport = { width: context.viewport.width, height: context.viewport.height };
150
+ }
151
+ if (typeof context.isMobile === "boolean") {
152
+ artifact.isMobile = context.isMobile;
153
+ }
154
+ } catch {
155
+ // Keep get-url as the source of truth when eval output is not JSON.
156
+ }
157
+ }
158
+
159
+ try {
160
+ persist();
161
+ artifact.url = runCmux("get-url", ["get-url"]).trim() || null;
162
+ persist();
163
+
164
+ const contextScript =
165
+ "JSON.stringify({url: location.href, viewport: {width: window.innerWidth, height: window.innerHeight}, isMobile: window.matchMedia('(max-width: 767px)').matches})";
166
+ applyContext(runCmux("viewport-context", ["eval", "--script", contextScript]));
167
+ persist();
168
+
169
+ artifact.snapshot_text = runCmux("snapshot", ["snapshot", "--compact"]);
170
+ persist();
171
+
172
+ runCmux("screenshot", ["screenshot", "--out", screenshotPath]);
173
+ artifact.screenshot_path = screenshotRelPath;
174
+ persist();
175
+
176
+ artifact.console_lines = lines(runCmux("console", ["console", "list"]));
177
+ persist();
178
+
179
+ artifact.errors = lines(runCmux("errors", ["errors", "list"]));
180
+ artifact.status = "complete";
181
+ persist();
182
+ console.log(`wrote ${investigation.absolutePath}`);
183
+ } catch (error) {
184
+ artifact.status = "failed";
185
+ artifact.failure = { message: error instanceof Error ? error.message : String(error) };
186
+ persist();
187
+ console.error(artifact.failure.message);
188
+ process.exit(1);
189
+ }
190
+
191
+ function fail(message: string): never {
192
+ console.error(message);
193
+ process.exit(1);
194
+ }
@@ -0,0 +1,15 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ SOURCE="${BASH_SOURCE[0]}"
5
+ while [ -L "$SOURCE" ]; do
6
+ TARGET="$(readlink "$SOURCE")"
7
+ if [[ "$TARGET" = /* ]]; then
8
+ SOURCE="$TARGET"
9
+ else
10
+ SOURCE="$(cd -P "$(dirname "$SOURCE")" && pwd)/$TARGET"
11
+ fi
12
+ done
13
+ ROOT="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
14
+
15
+ exec bun run "$ROOT/scripts/uninstall.ts" "$@"
@@ -0,0 +1,165 @@
1
+ #!/usr/bin/env bash
2
+ # gxpm-update-check — periodic remote VERSION check.
3
+ #
4
+ # Output (one line, or nothing):
5
+ # JUST_UPGRADED <old> <new>
6
+ # UPGRADE_AVAILABLE <old> <new>
7
+ # (nothing)
8
+ #
9
+ # Env overrides:
10
+ # GXPM_DIR — override gxpm install root
11
+ # GXPM_REMOTE_URL — override remote VERSION URL
12
+ # GXPM_STATE_DIR — override ~/.gxpm state directory
13
+ set -euo pipefail
14
+
15
+ if [ -z "${GXPM_DIR:-}" ]; then
16
+ SOURCE="${BASH_SOURCE[0]}"
17
+ while [ -L "$SOURCE" ]; do
18
+ TARGET="$(readlink "$SOURCE")"
19
+ if [[ "$TARGET" = /* ]]; then
20
+ SOURCE="$TARGET"
21
+ else
22
+ SOURCE="$(cd -P "$(dirname "$SOURCE")" && pwd)/$TARGET"
23
+ fi
24
+ done
25
+ GXPM_DIR="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
26
+ fi
27
+ STATE_DIR="${GXPM_STATE_DIR:-$HOME/.gxpm}"
28
+ CACHE_FILE="$STATE_DIR/last-update-check"
29
+ MARKER_FILE="$STATE_DIR/just-upgraded-from"
30
+ SNOOZE_FILE="$STATE_DIR/update-snoozed"
31
+ VERSION_FILE="$GXPM_DIR/VERSION"
32
+ REMOTE_URL="${GXPM_REMOTE_URL:-https://raw.githubusercontent.com/laozhong86/gxpm/main/VERSION}"
33
+
34
+ FORCE=0
35
+ if [ "${1:-}" = "--force" ]; then
36
+ FORCE=1
37
+ rm -f "$CACHE_FILE"
38
+ rm -f "$SNOOZE_FILE"
39
+ fi
40
+
41
+ CONFIG_VALUE="$("$GXPM_DIR/bin/gxpm" config get update_check --raw 2>/dev/null || true)"
42
+ if [ "$CONFIG_VALUE" = "false" ]; then
43
+ exit 0
44
+ fi
45
+
46
+ check_snooze() {
47
+ local remote_ver="$1"
48
+ if [ ! -f "$SNOOZE_FILE" ]; then
49
+ return 1
50
+ fi
51
+
52
+ local snoozed_ver snoozed_level snoozed_epoch
53
+ snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
54
+ snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
55
+ snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
56
+
57
+ if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
58
+ return 1
59
+ fi
60
+ case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
61
+ case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
62
+
63
+ if [ "$snoozed_ver" != "$remote_ver" ]; then
64
+ return 1
65
+ fi
66
+
67
+ local duration
68
+ case "$snoozed_level" in
69
+ 1) duration=86400 ;;
70
+ 2) duration=172800 ;;
71
+ *) duration=604800 ;;
72
+ esac
73
+
74
+ local now expires
75
+ now="$(date +%s)"
76
+ expires=$((snoozed_epoch + duration))
77
+ if [ "$now" -lt "$expires" ]; then
78
+ return 0
79
+ fi
80
+
81
+ return 1
82
+ }
83
+
84
+ fetch_remote_version() {
85
+ case "$REMOTE_URL" in
86
+ file://*)
87
+ cat "${REMOTE_URL#file://}" 2>/dev/null || true
88
+ ;;
89
+ /*|./*|../*)
90
+ cat "$REMOTE_URL" 2>/dev/null || true
91
+ ;;
92
+ *)
93
+ curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true
94
+ ;;
95
+ esac
96
+ }
97
+
98
+ LOCAL=""
99
+ if [ -f "$VERSION_FILE" ]; then
100
+ LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
101
+ fi
102
+ if [ -z "$LOCAL" ]; then
103
+ exit 0
104
+ fi
105
+
106
+ if [ -f "$MARKER_FILE" ]; then
107
+ OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
108
+ rm -f "$MARKER_FILE"
109
+ rm -f "$SNOOZE_FILE"
110
+ if [ -n "$OLD" ]; then
111
+ echo "JUST_UPGRADED $OLD $LOCAL"
112
+ fi
113
+ fi
114
+
115
+ if [ "$FORCE" -eq 0 ] && [ -f "$CACHE_FILE" ]; then
116
+ CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
117
+ case "$CACHED" in
118
+ UP_TO_DATE*) CACHE_TTL=60 ;;
119
+ UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
120
+ *) CACHE_TTL=0 ;;
121
+ esac
122
+
123
+ STALE=$(find "$CACHE_FILE" -mmin +"$CACHE_TTL" 2>/dev/null || true)
124
+ if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
125
+ case "$CACHED" in
126
+ UP_TO_DATE*)
127
+ CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
128
+ if [ "$CACHED_VER" = "$LOCAL" ]; then
129
+ exit 0
130
+ fi
131
+ ;;
132
+ UPGRADE_AVAILABLE*)
133
+ CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
134
+ if [ "$CACHED_OLD" = "$LOCAL" ]; then
135
+ CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
136
+ if check_snooze "$CACHED_NEW"; then
137
+ exit 0
138
+ fi
139
+ echo "$CACHED"
140
+ exit 0
141
+ fi
142
+ ;;
143
+ esac
144
+ fi
145
+ fi
146
+
147
+ mkdir -p "$STATE_DIR"
148
+ REMOTE="$(fetch_remote_version | tr -d '[:space:]')"
149
+
150
+ if ! echo "$REMOTE" | grep -qE '^[0-9]+(\.[0-9]+)+$'; then
151
+ echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
152
+ exit 0
153
+ fi
154
+
155
+ if [ "$LOCAL" = "$REMOTE" ]; then
156
+ echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
157
+ exit 0
158
+ fi
159
+
160
+ echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$CACHE_FILE"
161
+ if check_snooze "$REMOTE"; then
162
+ exit 0
163
+ fi
164
+
165
+ echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"
@@ -0,0 +1,40 @@
1
+ ---
2
+ description: 增量实现与决策记录入口 — 映射 gxpm dispatch → implement → local-verify
3
+ ---
4
+
5
+ # Command: /build
6
+
7
+ ## 对应 gxpm Phase
8
+ `dispatch` → `implement` → `local-verify` → `ac-check`
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `.gxpm/issues/<id>/artifacts/dispatch-handoff.json` — 派发交接单
13
+ 3. `skills/gxpm-implementer/SKILL.md` — 实现者行为模板
14
+ 4. `skills/gxpm-tdd/SKILL.md` — TDD 方法论(如适用)
15
+ 5. `docs/governance/development-contract.md` — 开发规范
16
+
17
+ ## 调用 Skill
18
+ - `gxpm-implementer` — 增量实现与四维自审
19
+ - `gxpm-tdd` — 红-绿-重构循环
20
+ - `gxpm-build` — 编译与类型检查
21
+ - `gxpm-debug-issue` — 调试(失败时)
22
+ - `gxpm-refactor-safely` — 安全重构(需要时)
23
+
24
+ ## 产出 Artifact
25
+ - 代码变更(commit 到 feature branch)
26
+ - `local-verify` — 本地验证结果
27
+ - `acceptance-check` — AC 符合性检查
28
+ - (需要决策时)`adr/<num>.md` — 架构决策记录
29
+
30
+ ## 通过条件
31
+ - [ ] 已 `cd` 进 worktree 再编辑
32
+ - [ ] `bun test` 通过(或记录基线失败证据)
33
+ - [ ] `bun run check` 通过
34
+ - [ ] `gxpm issue transition <id> local-verify`
35
+ - [ ] `gxpm issue transition <id> ac-check`
36
+
37
+ ## 注意事项
38
+ - 每次 commit 只表达一个逻辑变化,message 必须含 `GXPM-N` 引用
39
+ - 进入 implement 前 `git status -sb` 检查未追踪文件
40
+ - 失败时进入 debug 回路,不硬推
@@ -0,0 +1,53 @@
1
+ ---
2
+ description: 能力发现入口 — 列出可用命令与技能
3
+ ---
4
+
5
+ # Command: /help
6
+
7
+ ## Goal
8
+ 帮助用户和 Agent 发现 gxpm 当前可用的命令、技能和文档入口。
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `AGENTS.md` — 项目约束入口
13
+ 3. `skills/gxpm/SKILL.md` — 核心 skill 索引
14
+ 4. `skills-index.json` — 技能发现索引(如存在)
15
+
16
+ ## 输出
17
+
18
+ ### 核心命令
19
+ | 命令 | 对应 gxpm Phase | 作用 |
20
+ |------|----------------|------|
21
+ | `/refine` | triage → plan | 需求收敛与事实扫描 |
22
+ | `/plan` | plan → dispatch | 任务拓扑与执行计划 |
23
+ | `/build` | dispatch → implement | 增量实现与决策记录 |
24
+ | `/review` | ac-check → self-review → ship | 多角色质量审查 |
25
+ | `/ship` | ship → land | 发布、导出与文档同步 |
26
+
27
+ ### 常用 CLI
28
+ ```bash
29
+ gxpm issue create --auto-id [--type meta]
30
+ gxpm issue status <id>
31
+ gxpm issue next <id>
32
+ gxpm issue transition <id> <phase>
33
+ gxpm phase rewind <id> --to <phase> --reason "..."
34
+ gxpm artifact write <id> <type> --json '...'
35
+ bun test
36
+ bun run check
37
+ bun run gen:skill-docs
38
+ ```
39
+
40
+ ### 核心 Skill
41
+ - `gxpm-triage` — 分类与范围收敛
42
+ - `gxpm-planning` — 任务拓扑与计划
43
+ - `gxpm-implementer` — 增量实现与自审
44
+ - `gxpm-review-changes` — 代码审查
45
+ - `gxpm-verify` — 验证管道
46
+ - `gxpm-debug-issue` — 调试
47
+ - `gxpm-refactor-safely` — 安全重构
48
+
49
+ ### 渐进文档
50
+ - 全局纪律 → `CANON.md`
51
+ - 开发规范 → `docs/governance/development-contract.md`
52
+ - Skill 写法 → `docs/governance/template-authoring.md`
53
+ - 架构 → `docs/architecture/`
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: 任务拓扑与执行计划门 — 映射 gxpm plan → dispatch
3
+ ---
4
+
5
+ # Command: /plan
6
+
7
+ ## 对应 gxpm Phase
8
+ `plan` → `dispatch`
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `.gxpm/issues/<id>/artifacts/acceptance-contract.json` — 已批准的规格
13
+ 3. `skills/gxpm-planning/SKILL.md` — 规划方法论
14
+ 4. `docs/governance/development-contract.md` — 开发与提交规范
15
+
16
+ ## 调用 Skill
17
+ - `gxpm-planning` — 任务分解与拓扑排序
18
+ - `gxpm-tdd` — 测试策略(如适用)
19
+ - `gxpm-grill` — 计划压力测试(可选)
20
+
21
+ ## 产出 Artifact
22
+ - `implementation-plan` — 更新后的详细执行计划
23
+ - `dispatch-handoff` — 工作项、依赖、风险、验证计划
24
+ - (大型/并行任务)`plans/*.md` — 子计划
25
+
26
+ ## 通过条件
27
+ - [ ] `implementation-plan` 存在且 `status=ready`
28
+ - [ ] `dispatch-handoff` 已写入
29
+ - [ ] 如有 3+ 来源不明文件,`worktreeDecision` 已确认
30
+ - [ ] `gxpm issue transition <id> dispatch`
31
+
32
+ ## 注意事项
33
+ - 只有 `Parallel Execution Matrix` 证明 `parallel_safe` 时才允许并行
34
+ - 不确定下一步时查 `gxpm issue next <id>`
@@ -0,0 +1,46 @@
1
+ ---
2
+ description: 需求收敛与事实扫描入口 — 映射 gxpm triage → plan
3
+ ---
4
+
5
+ # Command: /refine
6
+
7
+ ## 对应 gxpm Phase
8
+ `triage` → `plan`
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `CONTEXT.md` — 术语表
13
+ 3. `docs/architecture/gxpm-v0-contract.md` — 阶段与产物定义
14
+ 4. `skills/gxpm-triage/SKILL.md` — 分类方法论
15
+ 5. `skills/gxpm-planning/SKILL.md` — 规划方法论
16
+
17
+ ## 调用 Skill
18
+ - `gxpm-triage` — 范围收敛、需求澄清
19
+ - `gxpm-planning` — 任务拓扑与执行计划
20
+ - `gxpm-grill` — 压力测试计划(可选)
21
+
22
+ ## 产出 Artifact
23
+ - `acceptance-contract` — 范围、成功标准、非目标
24
+ - `implementation-plan` — 步骤、验收标准、风险
25
+ - (可选)`01-spec.md` — 人类可读规格摘要
26
+
27
+ ## 产物链(Markdown)
28
+ JSON artifact 会自动同步到 `.gxpm/issues/<id>/docs/`:
29
+ ```
30
+ docs/
31
+ ├── 01-spec.md ← acceptance-contract
32
+ ├── 03-plan.md ← implementation-plan
33
+ ├── 04-review.md ← self-review
34
+ └── 05-ship.md ← ship-readiness / pr-check / verify-findings / qa-findings
35
+ ```
36
+ 同步命令:`bun run sync:markdown <issue-id>`
37
+
38
+ ## 通过条件
39
+ - [ ] issue 已创建(`gxpm issue create --auto-id [--type meta]`)
40
+ - [ ] `acceptance-contract` 已写入
41
+ - [ ] `implementation-plan` 已写入且 `constitutionCheck` 通过
42
+ - [ ] `gxpm issue transition <id> plan`
43
+
44
+ ## 注意事项
45
+ - 新的非平凡任务必须先走需求确认;用户说“直接做”时可跳过
46
+ - meta tracker、retro、长期观察日志必须用 `--type meta`
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: 多角色质量审查门 — 映射 gxpm ac-check → self-review → ship
3
+ ---
4
+
5
+ # Command: /review
6
+
7
+ ## 对应 gxpm Phase
8
+ `ac-check` → `self-review` → `ship`
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `.gxpm/issues/<id>/artifacts/acceptance-check.json` — AC 检查结果
13
+ 3. `skills/gxpm-review-changes/SKILL.md` — 代码审查方法论
14
+ 4. `skills/gxpm-hygiene/SKILL.md` — 提交卫生检查
15
+
16
+ ## 调用 Skill
17
+ - `gxpm-review-changes` — 结构化代码审查
18
+ - `gxpm-hygiene` — 提交卫生与原子提交纪律
19
+ - `gxpm-verify` — 本地验证管道执行
20
+
21
+ ## 产出 Artifact
22
+ - `self-review` — 审查结果(blocking / important / suggestion 分级)
23
+ - `ship-readiness` — 发布就绪检查
24
+
25
+ ## 通过条件
26
+ - [ ] blocking 问题全部解决(不能靠口头承诺跳过)
27
+ - [ ] `bun test`、`bun run check`、`git diff --check` 通过
28
+ - [ ] `self-review` artifact 已写入
29
+ - [ ] `gxpm issue transition <id> ship`
30
+
31
+ ## 注意事项
32
+ - blocking 回 `/build`;批准后进入发布
33
+ - 不把 generated `SKILL.md` 冲突用“接受某一边”解决
34
+ - 新增 host、skill、生成规则时同步补测试或检查入口
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: 发布、导出与文档同步门 — 映射 gxpm ship → pr-check → verify → qa → land
3
+ ---
4
+
5
+ # Command: /ship
6
+
7
+ ## 对应 gxpm Phase
8
+ `ship` → `pr-check` → `verify` → `qa` → `land`
9
+
10
+ ## 读取文档
11
+ 1. `CANON.md` — 全局纪律
12
+ 2. `.gxpm/issues/<id>/artifacts/ship-readiness.json` — 发布就绪状态
13
+ 3. `skills/gxpm-verify/SKILL.md` — 验证管道
14
+ 4. `docs/governance/development-contract.md` — 提交与发布规范
15
+
16
+ ## 调用 Skill
17
+ - `gxpm-verify` — 完整验证管道执行与证据收集
18
+ - `gxpm-hygiene` — 最终提交卫生检查
19
+
20
+ ## 产出 Artifact
21
+ - `pr-check` — PR 就绪状态
22
+ - `verify-findings` — 验证结果
23
+ - `qa-findings` — QA 结果(含 `retainWorktreeReason` 如需保留)
24
+ - `land-findings` — 落地报告
25
+ - (可选)`06-canary-report.md`、`07-deploy-report.md`
26
+
27
+ ## 通过条件
28
+ - [ ] PR 创建且 checks 通过
29
+ - [ ] `verify-findings` 已写入
30
+ - [ ] `qa-findings` 已写入
31
+ - [ ] merge 后 post-merge hook 自动 transition `qa → land`
32
+ - [ ] `land` 后默认运行 `gxpm cleanup land <id> --execute`
33
+
34
+ ## 注意事项
35
+ - destructive cleanup、发布、合并、远端写操作前确认
36
+ - 若保留 worktree,必须在 `land-findings` 写 `retainWorktreeReason`
37
+ - 完成 land 后标记 Linear issue 为 Done
@@ -0,0 +1,20 @@
1
+ import { createPhaseArtifactInitializer } from "./phase-artifact";
2
+
3
+ export const initializeAcceptanceCheck = createPhaseArtifactInitializer({
4
+ artifactType: "acceptance-check",
5
+ label: "Acceptance check",
6
+ payload: {
7
+ adversarialFindings: [],
8
+ criteria: [],
9
+ findings: [],
10
+ localVerifyArtifact: "local-verify",
11
+ specCompliance: {
12
+ missingRequirements: [],
13
+ planCoverage: 0,
14
+ unplannedChanges: [],
15
+ },
16
+ status: "draft",
17
+ summary: "",
18
+ },
19
+ requiredPhase: "local-verify",
20
+ });