cc3ee301a7
* fix(#2544): stage the CommonJS marker in GSD-owned dirs, not the config root installSharedHooksBundle wrote `{"type":"commonjs"}` over <configRoot>/package.json unconditionally — no existence check, no merge, no backup — on every install and every /gsd-update re-install. On the 11 affected runtimes that file is often user-owned; on OpenCode and Kilo it is the documented place to declare local-plugin npm dependencies, so a user's name/type/dependencies/scripts were destroyed on each run. The uninstall path already read the file and unlinked it only on an exact content match. That asymmetry was the defect: the discipline existed in the codebase, it just was not applied on the write side. Move the marker into the directories GSD creates and fills with its own .js files — hooks/ (all shared-hooks runtimes, incl. Kimi's own root) and the nativePlugin dir (plugins/ for OpenCode+Kilo, extensions/ for pi) — and stop writing the config root entirely. New src/commonjs-marker.cts owns the marker string plus one ownership predicate (absent / gsd-owned / foreign, fail-closed on an unreadable file) shared by ensureCommonJsMarker and removeCommonJsMarker, so install and uninstall cannot drift apart again. Nothing else depended on the config-root marker: package identity is baked at build time (#378/#498) and version resolution prefers gsd-core/VERSION and already tolerates a missing root package.json (#1383) — Codex has installed without one all along. A package.json in plugins/ or extensions/ is inert to plugin discovery, which globs *.{ts,js} only (see installer-migration 006). Uninstall retires the pre-fix config-root marker, so upgrading users are cleaned up on removal, and still never touches a file it did not write. * fix(#2544): point the changeset fragment at the filed PR The fragment's `pr:` field is only knowable after `gh pr create` returns. * fix(#2544): register commonjs-marker.cjs in the tsc-generated ESLint ignore set bin/lib/commonjs-marker.cjs is tsc output (src/commonjs-marker.cts is the linted source), so it belongs in the ADR-457 ignore list like its siblings. Clears the lint-tests no-var failure and the repo-invariants "linted xor ignored" migration-state test. * fix(#2544): pin the kimi CommonJS marker to hooks/, not the ~/.kimi root The UPGRADE 1 test still asserted the pre-#2544 marker location (~/.kimi/package.json). The marker now lives inside ~/.kimi/hooks — the directory GSD itself creates — matching the updated golden-install-parity and install-tree fixtures. Also asserts the root marker is NOT written. * fix(#2544): make the CommonJS marker write path non-fatal Review round 2, Major 3 + Minor 1 + the stagedHooks nit. ensureCommonJsMarker rethrew any non-EEXIST write error and neither call site caught it, so EACCES on a read-only hooks/, EROFS, or ENOSPC aborted the whole install with a raw stack trace. Every other marker interaction in the module is best-effort — removeCommonJsMarker swallows unlink failures, classifyMarker swallows read failures — and this was the write path, i.e. the one most likely to fail on a locked-down config dir. It now returns a new 'failed' outcome and both call sites warn and continue. Sibling found while sweeping for the same defect class: fs.mkdirSync sat OUTSIDE the try block, so an unwritable parent threw past the guard entirely. Creating the directory is the same environmental hazard as writing into it, so it moved inside. Also in this file: - The hooks marker is now gated on `stagedHooks && hooksOk`, not stagedHooks alone. stagedHooks is computed from the SOURCE listing before the copy loop, so it stays true when the copies land but verifyInstalled() then fails — marking a hooks/ GSD did not successfully populate claims an ownership the install did not earn. - The uninstall rmdir of the native plugin dir is gated on GSD having actually removed something from it. Hoisting it out of the adapter-exists guard (so the marker-only case could prune) had silently widened it into deleting a user-created but empty plugins/ or extensions/ dir — the same "don't touch territory GSD didn't fill" principle this issue is about, inverted. - Kimi's pre-#2544 marker at its native hook root (~/.kimi) is retired at the same call site that writes its replacement. That path is outside kimi's configDir, so installer-migration 007 structurally cannot reach it. * fix(#2544): retire the stale config-root marker via installer-migration 007 Review round 2, Major 1 — the PR's headline claim was false for existing installs. Upgraders kept BOTH markers: the new one under hooks/ and the stale {"type":"commonjs"} at the config root, so their config root stayed pinned to CommonJS and their dependency manifest stayed gone until they uninstalled. The migration is unusual in one way, and it is the part worth reviewing: the config-root marker was never recorded in gsd-file-manifest.json (writeManifest records hooks/, agents/, commands/, scripts/ and the native plugin, never a root package.json), so classifyArtifact answers 'unknown' for it and the planner's own guard downgrades a remove-managed on an 'unknown' classification to preserve-user. 007 therefore supplies the "purpose-built detector for an old GSD-owned shape" that docs/installer-migrations.md#remove-managed sanctions — exact content match, the same predicate removeCommonJsMarker has always used — and declares the resulting classification on the action. A package.json with any other content is left untouched, and there is deliberately no backup-and-remove branch: a non-matching file here is not a patched GSD artifact, it is somebody else's file. Scope is all runtimes. The `runtimes` field is OMITTED rather than `[]`: validateStringArray requires the field to be non-empty WHEN PRESENT, while the runtime filter treats an empty array as "all" — so `runtimes: []` throws at plan time and the migration never runs. The metadata test pins this. Kimi is a deliberate carve-out, named in the migration's own header: its marker lived at ~/.kimi, outside kimi's configDir, and migration relPaths are structurally confined to configDir. It is retired by the installer instead. Registration: shipped-migrations table, .gitignore for the emitted .cjs, the EXPECTED_CHECKSUMS baseline, and the ESLint ignore set. That last one is not copied from migration 006 by rote — 006 needs no entry because it imports nothing, while 007 imports node builtins, so tsc emits its __importDefault helper and the `var` in it trips no-var. This is the same lint gate that made round 1 red. * test(#2544): fault-injection and multi-runtime marker coverage Review round 2, Major 2 + Minors 4 and 5. Major 2 — CONTRIBUTING.md:514-531 is mandatory for install/uninstall flows and the suite had no fs monkeypatching at all. Every branch now covered is one whose doc comment claims it as the module's safety posture: - classifyMarker non-ENOENT lstat error -> 'foreign' (the fail-closed rule), with an ENOENT control alongside it so the test discriminates rather than just asserting one side - classifyMarker readFileSync throw -> 'foreign' (present-but-unreadable never downgrades to the permissive answer) — the fixture's bytes are exactly GSD's marker, so the test fails if the code ever answers on content it could not read - a DIRECTORY at the marker path (CONTRIBUTING:521; the symlink case was already covered with a real symlink, the directory case needs no injection at all) - the ensureCommonJsMarker TOCTOU EEXIST branch — the entire reason for flag:'wx' - the new 'failed' outcome, for both writeFileSync (EACCES/EROFS/ENOSPC) and the mkdirSync that used to sit outside the guard - removeCommonJsMarker unlink throw -> false These save and restore fs methods in `finally` rather than using chmod 0o000, which does not fault under root and would pass vacuously in root Docker and CI. Minor 4 — uninstall was driven for opencode only. pi's extensions/ and both kimi locations now have behavioral coverage, install and uninstall, each paired with a user-authored-file case proving GSD leaves it alone. Minor 5 — the stagedHooks gate had no assertion behind its stated reason. A pre-existing, GSD-untouched hooks/ directory is now driven through a runtime that declares skipSharedHooksInstall and asserted to stay marker-free, with its user content intact. Also regression-tests the uninstall rmdir gate from the previous commit: an empty plugin dir GSD removed nothing from must survive. * docs(#2544): correct stale marker prose, register the module, document the trade-off Review round 2, Minors 2, 3 and 6. Minor 2 — six files asserted the installed ROOT ships the synthetic marker. None was load-bearing (all three walk-up consumers are VERSION-first with try/catch and the marker never carried a `version`), but ADR-457:52 is the rationale for keeping a generated module, so a future reader would mis-derive the constraint from it. Each site is corrected to what is now true: the installed tree carries no package.json with a .name at all, because the only ones GSD stages are {"type":"commonjs"} markers and they now live in GSD's own directories. Two of the six needed more than a location swap. hooks/gsd-check-update-worker.js and the platform-gate test both described `require('../package.json').name` resolving to undefined; post-#2544 that require does not resolve at all, so the history is kept accurate and the present-tense claim corrected rather than just moved. And src/runtime-artifact-conversion.cts described the no-root-package.json case as Codex-only — it is now every runtime, which strengthens that comment's own argument for lazy resolution. The generated .cjs sibling needs no edit: it is gitignored build output, not a tracked file. Minor 3 — src/commonjs-marker.cts had no CONTEXT.md entry, unlike every peer module, and CONTEXT.md is the #2 co-change partner of bin/install.js. Added, including the fail-closed posture and the never-throws contract. Minor 6 — the plugins//extensions/ marker shadows the config root for all .js siblings, so an OpenCode/Kilo user's ESM plugin/*.js stays broken. That is exactly what #2544's Fix section prescribed and it is disclosed in the PR body, but the PR body is not documentation. It now lives in the OpenCode section of docs/how-to/install-on-your-runtime.md, stated as a real constraint rather than a pure improvement, with the .ts mitigation and a fallback for ESM plugins. * test(#2544): attribute the CommonJS marker in the emitted-provenance rules The differential emitted-attribution gate (#2723, landed on `next` after this branch was cut) went red on the macOS shards once this PR rebased onto it. Two distinct causes, both real gaps rather than noise: 1. `plugins/package.json` and `extensions/package.json` matched NO rule — the `native-plugin` rule covers `*.{js,cjs,mjs}` only, so the marker read as an unattributed emitted family. 2. `hooks/package.json` fell through to `hooks-built`, which attributes an emitted `hooks/<X>` to a repo source `hooks/<X>`. There is no `hooks/package.json` in the repo, so it resolved to a nonexistent path. Cause 2 is exactly the failure already documented three lines above it for Copilot's `gsd-session.json` — "a code literal, not a built script" — so the fix follows that precedent rather than inventing one: `package.json` is excluded from `hooks-built` the same way, and a dedicated `commonjs-marker` rule attributes the family across all four roots it can appear in (both hooks roots plus `plugins`/`extensions`) to the sources that actually emit it. Deliberately a RULE, not an entry in tests/emitted-drift-ack.json. An ack is for a one-off ripple and goes stale by design — the gate fails a stale ack precisely so it cannot pre-clear the next change on that path. These markers are a permanent part of the emitted tree from #2544 onward, so they need standing attribution. Verified by reproducing the CI failure locally with GSD_EMITTED_BASE: 3 provenance errors + 12 unattributed paths before, 35/35 green after. * fix(#2544): route the #2717 hooks-surface marker helpers through commonjs-marker #2717 landed a second copy of ensureCommonJsMarker/removeCommonJsMarkerIfGsdOwned in src/runtime-hooks-surface.cts for the runtimes that stage .js hooks via dedicated paths (cursor/windsurf/codex). That copy had drifted from this PR's module on the two properties that matter: - ownership probe: `fs.existsSync` FOLLOWS symlinks and reports false for a DANGLING one, so a dangling package.json symlink classified as absent and the write went straight through it. Demonstrated: against the pre-fix copy, ensureCommonJsMarker() on a hooks/ dir holding a dangling package.json symlink returns true and creates {"type":"commonjs"} OUTSIDE that directory. - create: a plain writeFileSync leaves the classify->write window open, where commonjs-marker creates with flag:'wx' (O_EXCL). Both helpers now delegate to src/commonjs-marker.cts, which is what this PR's own docstring already claimed was the single place these rules are enforced. Exported signatures are unchanged (still boolean), so bin/install.js and the #2717 tests are unaffected. The new subtest is the only coverage that fails if the duplicate is ever reintroduced — the two implementations agree on every non-adversarial input, so the existing suites pass against both. * test(#2544): pin the stagedHooks gate on zcode, not windsurf The Minor-5 coverage picked windsurf because hostBehaviors.skipSharedHooksInstall kept it out of the shared hooks bundle, so GSD staged nothing into hooks/ and the marker was correctly absent. #2717 changed that premise: cursor/windsurf/codex now stage their .js hooks via dedicated paths and get the marker beside those scripts. Measured on this tree, windsurf stages 2 .js hooks and receives a marker — so the assertion was pinning behaviour that is now wrong, not the gate it was written for. ZCode is the durable choice: per #1821 it has hooksSurface:'none' AND no plugin surface to spawn hooks, so GSD stages no .js there by either route (measured: 0 staged, no marker). The property under test is unchanged — a user-created hooks/ directory GSD never fills stays marker-free. * test(#2544): use the shared cleanup helper in the migration test Addresses the review's Major 1. The suppression's stated reason — "no helpers import available" — was not correct: tests/helpers.cjs exports cleanup, and the other test file added in this same PR imports it (tests/commonjs-marker.test.cjs). The local reimplementation dropped two protections that are live on this repo's windows-latest lane: the CWD guard (Windows cannot remove a directory that is the current working directory) and the 20 x 250ms retry budget that absorbs the deferred-scan handle Windows Defender holds on newly-written files. Local function and suppression both removed; local/no-raw-rmsync-in-tests now passes without one. * test(#2544): expect hooks/package.json for the #2717 runtimes The fresh-install contract table predates #2717, which stages cursor/windsurf/ codex .js hooks via dedicated paths and writes the CommonJS marker beside them. All three therefore now receive hooks/package.json legitimately. Measured on this tree: codex stages 3 .js hooks, cursor 6, windsurf 2 — each with the marker; cline/copilot/trae/zcode stage none and get none, so their contracts are unchanged. * fix(#2544): gate the #2717 marker writes on having staged something The three dedicated marker writers #2717 added ran unconditionally. Each one mkdirs hooks/ up front and stages its scripts conditionally on the source existing, so with an absent or empty hook source they created a directory, filled it with nothing, and marked it as GSD's anyway. That is the same write-into-someone-else's-territory this issue is about, and installSharedHooksBundle already guards the identical case with `stagedHooks`. The dedicated paths now carry the matching gate: - cursor / windsurf: `installedScripts.size > 0` - codex: a new `codexStagedHooks` flag. The enclosing guard only proves that hooks/dist EXISTS; it says nothing about whether any CODEX_HOOKS_TO_COPY entry landed. Covered for cursor and windsurf by driving each writer against a src tree whose hooks/ dir is empty. The codex leg is defensive and deliberately uncovered: its trigger state needs a package tree where hooks/dist exists but holds none of the allowlist, which is not constructible from a real checkout. * test(#2544): scope the commonjs-marker sources per root The rule declared one flat source list for every marker root, so `extensions/package.json` was attributed to runtime-hooks-surface.cts (which never writes there) and `.kimi/hooks/package.json` to install-engine.cts. That is not merely untidy. emitted-diff.cjs accepts the FIRST satisfied source, so a flat list containing bin/install.js let any change anywhere in that 13k-line file authorise marker drift for every root — the blanket escape hatch this file's own agents-verbatim comment refuses for exactly the same reason. Sources are now derived per root from ctx.rel. Note the rule ctx is `{ rel, runtime }` and carries no `root`, so keying on ctx.root would have sent every path down one branch silently. * test(#2544): state precisely what the zcode assertion pins The comment claimed the test pinned installSharedHooksBundle's `stagedHooks` gate. It does not, and neither did the windsurf version it replaced: zcode declares skipSharedHooksInstall, so the outer guard skips that helper entirely and the gate is never evaluated. The test passes on the runtime exclusion. What it does pin — the outcome a pre-existing, GSD-untouched hooks/ stays marker-free — is still worth having, and is what the review asked for. The two `staging zero hook scripts` tests are the ones that pin a real staged-nothing gate. Comment corrected rather than left implying coverage that is not there. --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
32 KiB
How to install GSD Core on your runtime
Install GSD Core (@opengsd/gsd-core) into the AI coding runtime you use every day. This guide gives you the standard installer path for each supported runtime, then covers the manual path for machines without Node.js.
What you need: Node.js 18+ and npm (or npx). If you do not have Node.js, jump to Installing without Node.js.
Why the installer is required
GSD Core ships agent and command files in Claude Code's native frontmatter format. Each supported runtime expects a different schema, directory layout, and command-invocation syntax. The installer performs the necessary transformations — for example, converting tool lists and colour values for OpenCode and writing TOML agent entries for Codex.
Do not copy files from agents/ or commands/ directly. Doing so bypasses the transformations and produces schema-validation errors or missing commands.
Standard install
Run the installer from any directory. It prompts for your runtime and whether to install globally (all projects) or locally (this project only).
npx @opengsd/gsd-core@latest
That is the only command you need for a fresh install or to re-run the installer after switching runtimes.
Per-runtime instructions
Claude Code
npx @opengsd/gsd-core@latest --claude --global
Skills land in ~/.claude/. Commands appear as /gsd-* slash commands in your next Claude Code session. Restart Claude Code to pick them up.
Override the install directory:
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
Hook coverage
GSD registers the following Claude Code hook events automatically on install:
| Event | Hook | Purpose |
|---|---|---|
SessionStart |
gsd-check-update.js, gsd-session-state.sh |
Update check, session orientation |
PostToolUse |
gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh |
Context monitoring, read-time scan, phase boundary detection |
PreToolUse |
gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh |
Prompt guard, read-before-edit, workflow + worktree safety, commit validation |
SubagentStop |
gsd-context-monitor.js |
Context headroom tracking after subagent completion |
Stop |
gsd-context-monitor.js |
Context headroom tracking before model stop |
PreCompact |
gsd-context-monitor.js |
Context awareness before conversation compaction |
FileChanged (matcher: config.json) |
gsd-config-reload.js |
Hot-reloads .planning/config.json context mid-session when you edit your GSD config — no session restart required |
The FileChanged hook is always-on and a no-op when .planning/config.json does not exist in the project. Editing that file while a session is running injects an additionalContext summary of the new configuration so the agent picks up model overrides, workflow toggles, and hook settings immediately.
Claude Code — native plugin install
GSD Core ships a .claude-plugin/plugin.json manifest, which enables installation and lifecycle management through the Claude Code plugin system. This path is additive — the npm installer above remains fully supported, and the two approaches differ in namespace and lifecycle only.
Install paths
Option A — marketplace or git install (once listed):
claude plugin install gsd-core
Option B — zero-friction skills-dir load: Claude Code automatically discovers any directory under ~/.claude/skills/ that contains a .claude-plugin/plugin.json as a plugin. To use gsd-core this way, place (or symlink) the gsd-core package directory there:
# Example: place the package under ~/.claude/skills/gsd-core/
# Claude Code loads it as gsd-core@skills-dir on the next session start.
# No explicit install step required.
Command namespace
Plugin commands are namespaced as /gsd-core:<command> — for example, /gsd-core:plan-phase. This is distinct from the classic npm/file-copy installer, which exposes commands as /gsd:<command>. Use whichever namespace corresponds to your install method.
Lifecycle
claude plugin enable gsd-core
claude plugin disable gsd-core
claude plugin update gsd-core
Hooks
The plugin wires gsd-core's always-on guard and update hooks automatically via hooks/hooks.json. No manual hook registration is required.
Prerequisites
The gsd-tools binary (installed as part of the @opengsd/gsd-core npm package) must be available on your PATH for gsd commands to execute their backing logic. The plugin delivers the command, agent, and hook surface; the npm package delivers the runtime CLI.
Node.js (node) must also be available on your PATH. The plugin's always-on guard hooks (wired in hooks/hooks.json) are invoked as node "${CLAUDE_PLUGIN_ROOT}/hooks/<script>". Some Claude Code distributions ship as a standalone binary and do not expose a node executable on PATH; in those environments the plugin's hooks will not run. Verify with node --version before relying on the plugin hooks.
Runtime build (self-healing). The runtime CLI's compiled modules under gsd-core/bin/lib/*.cjs are build artifacts (ADR-457): they are compiled from src/*.cts by npm run build:lib and shipped prebuilt in the npm tarball. A plugin-marketplace or git-clone install materializes the repository tree directly and never runs that build step, so those files are initially absent. The CLI heals this automatically: the first gsd-tools invocation detects the missing output and compiles it once (using the bundled typescript devDependency), then proceeds normally. You may see a one-time gsd: runtime library not built — compiling once… notice on stderr; subsequent commands are unaffected. If auto-build cannot run (for example node_modules was pruned to production-only and typescript is unavailable), the CLI prints an actionable message telling you to run npm install && npm run build:lib in the plugin directory.
Claude plugin marketplace discovery (ZCODE and compatible runtimes)
GSD Core also ships a .claude-plugin/marketplace.json marketplace manifest (sibling to plugin.json). Runtimes that implement the Claude plugin marketplace contract — such as ZCODE — can discover and install GSD Core from a custom marketplace source without a manual clone:
- In your runtime's plugin UI, add a custom marketplace source pointing at
open-gsd/gsd-core(GitHubowner/repoform). - GSD Core appears in the catalog and can be installed directly from the UI.
This path is additive and changes nothing about the Claude Code plugin install above (.claude-plugin/plugin.json is unchanged). The marketplace entry's source is ./, so it reuses plugin.json's commands / skills / hooks mapping. The catalog version tracks package.json (it lives at plugins[0].version and is stamped by the release version-sync), so the version you see in the marketplace matches the npm release.
OpenCode
npx @opengsd/gsd-core@latest --opencode --global
The installer writes four surfaces under ~/.config/opencode/ (XDG) or ~/.opencode/: flat slash commands in commands/ (plural — the directory OpenCode discovers slash commands from, #2329), file-based subagents in agents/, on-demand skills in skills/<name>/SKILL.md, and a native plugin in plugins/gsd-core.js. It converts agent frontmatter to OpenCode's schema — removing the tools: field and converting colour values to hex — and emits each skill with spec-compliant frontmatter (name matching the skill directory plus a description). Skills are loaded on demand via OpenCode's native skill tool; commands remain invokable as /gsd-*. See Installing without Node.js — OpenCode transformations if you need to understand what changes.
GSD safety hooks on OpenCode. OpenCode does not register lifecycle hooks the way Claude Code does (its hooksSurface is none), so GSD's prompt-injection guard, read-before-edit guard, injection scanner, and context monitor would otherwise be inert. The bundled plugin (plugins/gsd-core.js) closes that gap: OpenCode auto-discovers plugins/*.{ts,js} files under its config directory at startup and the adapter bridges OpenCode's event bus (tool.execute.before/after, session.created, file.edited) onto GSD's existing hook scripts, spawning them as subprocesses. No opencode.json entry is needed — the plugin is loaded by directory auto-discovery (the config plugin array is for npm packages only). A blocking hook aborts the tool call; an advisory hook surfaces its message without blocking.
Your plugin directory is pinned to CommonJS (accepted trade-off, #2544). GSD's adapter is a CommonJS .js file, and Node decides a .js file's module type by walking up for the nearest package.json. So the installer writes a minimal {"type":"commonjs"} marker into the plugin directory itself — plugins/package.json on OpenCode and Kilo, extensions/package.json on pi. It is written only when GSD actually stages its adapter there, it never overwrites a package.json GSD did not write, and uninstall removes only its own.
The trade-off: that marker shadows your config root for every .js file in that directory, not just GSD's. If you author your own plugins as ESM .js and rely on a "type": "module" at the config root, they will stop resolving as ESM. This is deliberate — it is strictly narrower than the pre-#2544 behavior, which wrote the marker over <configRoot>/package.json itself and destroyed whatever was there — but it is a real constraint rather than a pure improvement, which is why it is stated here.
Mitigation: author your own plugins as .ts. OpenCode and Kilo compile plugin TypeScript with Bun, and a package.json type field does not affect .ts resolution — so a .ts plugin is unaffected by the marker. Failing that, keep ESM plugins outside the auto-discovered directory and load them as npm packages via the config plugin array.
Override the install directory:
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
Kilo
npx @opengsd/gsd-core@latest --kilo --global
The installer writes the same three surfaces under ~/.config/kilo/ (XDG) or ~/.kilo/ as for OpenCode — flat commands in command/, subagents in agents/, and skills in skills/<name>/SKILL.md — since Kilo derives from OpenCode and shares its config schema and skill layout.
Override the install directory:
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
Codex
npx @opengsd/gsd-core@latest --codex --global
Skills land in ~/.codex/skills/gsd-*/SKILL.md. Agents are written as standalone ~/.codex/agents/gsd-*.toml files, which Codex auto-discovers — that is the sole registration source for each role; config.toml only carries the shared [agents] dispatch-tuning scalar (max_depth), not a per-role table (#2406). Restart Codex (or run codex --reload) after install.
Minimum supported version: Codex CLI 0.130.0. Earlier versions had additional skill-root scanning that can produce duplicate listings.
Hook coverage
GSD registers the following Codex hook events automatically on install (requires Codex CLI 0.137.0+ for the stable hook-event schema):
| Event | Hook | Purpose |
|---|---|---|
SessionStart |
gsd-check-update.js |
Update check at session open; Windows installs also emit a commandWindows field pointing to the .cmd shim so Codex picks the correct executor on Windows without requiring per-OS config regeneration |
SubagentStart |
gsd-context-monitor.js |
Inject context / GSD_AGENT_NAME awareness at subagent open |
Stop |
gsd-context-monitor.js |
Context headroom tracking before model stop |
PostToolUse |
gsd-context-monitor.js |
Mirror the context-monitor coverage available in Claude Code |
All registered hooks are managed by GSD and are removed cleanly on --uninstall.
Kimi CLI
Support boundary — legacy
kimi-clivs Kimi Code. This integration targets the legacy/Pythonkimi-clicustom-agent contract. Thekimi --agent-file <configRoot>/agents/gsd.yamllaunch shown below is accepted bykimi-cli. The newer npm Kimi Code (@moonshot-ai/kimi-code, e.g.0.11.0) does not accept--agent-file; it discovers skills through fixed skill roots and--skills-dir. The generated/skill:gsd-*skills work in both, but the custom-agent (--agent-file) surface is specific to legacykimi-cli. For Kimi Code, point it at the installed skills root with--skills-dir <configRoot>/skillsinstead of using--agent-file.
npx @opengsd/gsd-core@latest --kimi --global
Skills land in Kimi's first existing generic user skills root:
~/.config/agents/skills/gsd-*/SKILL.mdwhen~/.config/agents/skillsalready exists, or when neither generic root exists yet~/.agents/skills/gsd-*/SKILL.mdwhen~/.agents/skillsalready exists and~/.config/agents/skillsdoes not
Start a new Kimi CLI session after install, then invoke GSD skills with /skill:gsd-*, for example:
/skill:gsd-new-project
The installer also writes the GSD custom agent definition to the same selected config root: <configRoot>/agents/gsd.yaml with its prompt at <configRoot>/agents/gsd.md; subagents land under <configRoot>/agents/subagents/gsd-*.yaml and <configRoot>/agents/subagents/gsd-*.md.
Kimi custom agents do not auto-activate just because the files exist. Launch Kimi with the generated agent file when you want the GSD agent surface:
kimi --agent-file ~/.config/agents/agents/gsd.yaml
If your machine already uses ~/.agents/skills and does not have ~/.config/agents/skills, GSD installs there instead and the launch command becomes:
kimi --agent-file ~/.agents/agents/gsd.yaml
Kimi also discovers user skills from the brand-specific ~/.kimi-code directory. If your Kimi setup is already centered on ~/.kimi-code, install there explicitly:
npx @opengsd/gsd-core@latest --kimi --global --config-dir ~/.kimi-code
Then launch the generated agent from that directory:
kimi --agent-file ~/.kimi-code/agents/gsd.yaml
For brand-specific scripted installs, use:
KIMI_CONFIG_DIR=~/.kimi-code npx @opengsd/gsd-core@latest --kimi --global
Avoid arbitrary KIMI_CONFIG_DIR roots unless your Kimi configuration also adds the matching skills/ directory to Kimi's extra skill directories. GSD can write files there, but Kimi will not auto-discover skills outside its documented generic and brand-specific roots without that Kimi-side configuration.
--kimi --local is intentionally deferred and guarded in v1; use the global install path above for Kimi CLI.
Hook coverage
GSD wires its lifecycle hooks into Kimi's native [[hooks]] array in config.toml — by default ~/.kimi/config.toml (overridable via Kimi's own KIMI_SHARE_DIR environment variable, a directory deliberately separate from the ~/.config/agents skills root above). Kimi CLI's hooks system is documented as Beta. GSD's entries are wrapped in # GSD Hooks BEGIN/# GSD Hooks END marker comments, so reinstalling only ever rewrites GSD's own block and never touches hand-written [[hooks]] entries around it.
| Event | Hook | Purpose |
|---|---|---|
SessionStart |
gsd-check-update.js, gsd-session-state.sh |
Update check and session-state bootstrap at session open |
PreToolUse |
gsd-prompt-guard.js, gsd-read-guard.js, gsd-worktree-path-guard.js, gsd-workflow-guard.js, gsd-validate-commit.sh |
Prompt-injection guard, read-before-edit guidance, worktree path safety, workflow guard, and commit validation before tool calls |
PostToolUse |
gsd-context-monitor.js, gsd-phase-boundary.sh, gsd-read-injection-scanner.js, gsd-graphify-update.sh |
Context window tracking, phase-boundary detection, read-time injection scanning, and graph updates after tool calls |
Stop |
gsd-context-monitor.js |
Context headroom tracking before the model stops |
PreCompact |
gsd-context-monitor.js |
Context headroom tracking before compaction |
SubagentStart |
gsd-context-monitor.js |
Inject context / GSD_AGENT_NAME awareness at subagent open |
SubagentStop |
gsd-context-monitor.js |
Context headroom tracking at subagent stop |
All registered hooks are managed by GSD and are removed cleanly on --uninstall.
GitHub Copilot
npx @opengsd/gsd-core@latest --copilot --global
Skills land in ~/.copilot/. GSD installs as agent .md files and repository instruction files.
GSD also wires Copilot's lifecycle hooks and instruction files:
AGENTS.md(local installs) — written at the repository root, which GitHub Copilot CLI reads as primary instructions, alongsidecopilot-instructions.md.- Lifecycle hook — a
sessionStarthook config is written to.github/hooks/gsd-session.json(local) or~/.copilot/hooks/gsd-session.json(global). It is a self-contained inlinecommandhook (no separate hook script to install), so it can never reference a missing script. The hook is advisory-only: at session start it surfaces whether the project has a.planning/workflow.
Both are removed (and any user-authored content preserved) on --uninstall.
Override the install directory:
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
Cursor
npx @opengsd/gsd-core@latest --cursor --global
Artifacts land in ~/.cursor/. GSD installs slash commands (~/.cursor/commands/gsd-*.md), skills (~/.cursor/skills/gsd-*/SKILL.md), agents, and rule references. Each GSD action appears once in Cursor's / menu: the command surface is the single / entry point, and the skills are installed with user-invocable: false so they stay model-invocable background knowledge without duplicating the / entries.
Override the install directory:
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
Windsurf / Devin Desktop
Windsurf has rebranded to Devin Desktop. Both runtime names are accepted — use either --windsurf or --devin-desktop.
npx @opengsd/gsd-core@latest --windsurf --global
# or equivalently:
npx @opengsd/gsd-core@latest --devin-desktop --global
Use a workspace install for Windsurf slash commands. Workspace installs write /gsd-* commands as Windsurf workflow files under .windsurf/workflows/. Windsurf discovers those .md workflow files in Cascade and exposes them through the / menu. Global-scope Windsurf workflow installation is intentionally a no-op for now because global workflow locations are outside GSD's normal user-owned runtime config directory.
Override the install directory:
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
Cline
GSD gives Cline both skills (≥ v3.48.0) and the .clinerules/ directory integration — no custom slash commands are registered.
# Global install (all projects — skills + rules directory)
npx @opengsd/gsd-core@latest --cline --global
# Local install (this project only — rules directory only)
npx @opengsd/gsd-core@latest --cline --local
GSD writes the .clinerules/ directory form:
.clinerules/gsd.md— the GSD rule file. Cline loads every.md/.txtfile in the.clinerules/directory automatically; no custom slash commands are registered..clinerules/hooks/PreToolUse— a lifecycle hook (Cline v3.36+). It is an executable script that receives the tool-call context as JSON on stdin and returns a JSON decision (cancel/errorMessage/contextModification). The GSD hook guards.planning/artifacts from direct edits and otherwise allows the operation; it fails open, so a hook error never blocks you. Cline runs hooks on macOS and Linux only.
Global install additionally:
- Emits each GSD command as
~/.cline/skills/<name>/SKILL.md. Cline ≥ v3.48.0 loads skills from~/.cline/skills/automatically — no configuration needed. - Merges GSD instructions into
~/.agents/AGENTS.md, the cross-tool global instruction file Cline reads. The block is marker-delimited, so your ownAGENTS.mdcontent (and other tools' entries) is preserved, and--uninstallstrips only the GSD block.
Local install writes the .clinerules/ directory into the current project only. No skills
directory is created for local scope.
Cline's global hook directory (
~/Documents/Cline/Rules/Hooks/) is not yet populated by the installer — project-scope hooks (.clinerules/hooks/) and the globalAGENTS.mdinstruction target cover the common cases.
CodeBuddy
npx @opengsd/gsd-core@latest --codebuddy --global
GSD installs four surfaces. Slash command definitions land in ~/.codebuddy/commands/gsd-*.md and appear as /gsd-help, /gsd-phase, /gsd-ship, etc. in the / menu. Subagents land in ~/.codebuddy/agents/gsd-*.md. Skills land in ~/.codebuddy/skills/gsd-*/SKILL.md — emitted with user-invocable: false so they stay out of the / menu (the commands surface is the sole / entry point) and remain available for model invocation. CodeBuddy hooks are written to settings.json. No mcp.json is written: GSD ships no MCP server.
Hook coverage
GSD registers the following events automatically on install (Claude hook event dialect):
| Event | Hook | Purpose |
|---|---|---|
SessionStart |
gsd-check-update.js, gsd-session-state.sh |
Update check, session orientation |
PreToolUse |
gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh |
Prompt guard, read-before-edit, workflow + worktree safety, commit validation |
PostToolUse |
gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh |
Context monitoring, read-time scan, phase boundary detection |
SubagentStop |
gsd-context-monitor.js |
Context headroom tracking after subagent completion |
SubagentStart |
gsd-context-monitor.js |
Context headroom tracking at subagent start |
Stop |
gsd-context-monitor.js |
Context headroom tracking before model stop |
PreCompact |
gsd-context-monitor.js |
Context awareness before conversation compaction |
CodeBuddy's own background sub-agent dispatch (run_in_background: true) is a caller-side invocation parameter, not something GSD's installed agent files control — there is no frontmatter field to set on GSD's agent artifacts to request it.
Qwen Code
Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
npx @opengsd/gsd-core@latest --qwen --global
Skills land in ~/.qwen/skills/gsd-*/SKILL.md.
GSD's main-loop skills are emitted with Qwen's optional numeric priority frontmatter field so the most-used workflows surface first in the /skills TUI list. Higher values sort earlier (per Qwen's skills spec), so core commands such as /skills for new-project (100), plan-phase (90), and execute-phase (85) appear above utility skills, which are left unset (default 0). This affects only the /skills list order — slash-command completion and /help remain alphabetical.
Subagents land in ~/.qwen/agents/gsd-*.md as native Qwen subagents, converted to Qwen's own name:/description:/tools: (YAML block list) frontmatter schema rather than Claude Code's.
Override the install directory:
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
Hook coverage
Qwen Code supports 15 hook events. GSD registers the following events automatically on install:
| Event | Hook | Purpose |
|---|---|---|
SessionStart |
gsd-check-update.js, gsd-session-state.sh |
Update check, session orientation |
PostToolUse |
gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh |
Context monitoring, read-time scan, phase boundary detection |
PreToolUse |
gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh |
Prompt guard, read-before-edit, workflow + worktree safety, commit validation |
SubagentStop |
gsd-context-monitor.js |
Context headroom tracking after subagent completion |
SubagentStart |
gsd-context-monitor.js |
Context headroom tracking at subagent start |
Stop |
gsd-context-monitor.js |
Context headroom tracking before model stop |
PreCompact |
gsd-context-monitor.js |
Context awareness before conversation compaction |
Augment Code
npx @opengsd/gsd-core@latest --augment --global
Skills land in ~/.augment/skills/ and slash command definitions land in ~/.augment/commands/. GSD installs skills, agents, and commands (/gsd-phase, /gsd-ship, etc.). GSD's managed lifecycle hooks are registered into Augment's own settings.json hooks block (Claude hook event dialect, covering session-start, tool-use, and phase-boundary events) — no statusline ownership. #2097 also registers the GSD companion MCP server under settings.json's mcpServers.gsd (see Connect a host to the GSD MCP server).
Antigravity
npx @opengsd/gsd-core@latest --antigravity --global
The installer auto-detects the Antigravity config directory (~/.gemini/antigravity, ~/.gemini/antigravity-ide, or ~/.gemini/antigravity-cli). Uses Gemini-compatible settings policy.
Override the install directory:
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
Trae
npx @opengsd/gsd-core@latest --trae --global
Skills land in ~/.trae/. GSD installs skills, agents, and rule references.
ZCode
npx @opengsd/gsd-core@latest --zcode --global
ZCode is Z.ai's desktop Agentic Development Environment for the GLM-5.2 model. GSD installs skills (nested SKILL.md bundles), slash commands, and subagents under ~/.zcode/:
- Skills →
~/.zcode/skills/gsd-<name>/SKILL.md(invoke with$gsd-<name>in chat) - Commands →
~/.zcode/commands/gsd-<name>.md(invoke with/gsd-<name>) - Subagents →
~/.zcode/agents/gsd-<name>.md
ZCode's skill format is identical to Claude Code's, so no runtime-specific converter is required — GSD lands as a pure declarative descriptor with no hardcoded installer branches. ZCode also natively imports skills and MCP config from ~/.claude; if you install GSD for both Claude and ZCode, you may see duplicate GSD skills inside ZCode, which is expected. To connect ZCode's MCP servers to GSD's companion server, see how to connect the GSD MCP server.
GSD's hook-automation and native-MCP-registration integrations are not yet wired for ZCode — both are blocked on ZCode not yet publishing the on-disk config format for its plugin Hook component or the settings filename/schema for its MCP store. See the ## zcode section of the host-integration capability matrix for the cited source URLs.
pi
npx @opengsd/gsd-core@latest --pi --global
pi is a bun-runtime programmatic CLI whose extensions implement pi's own ExtensionAPI (registerCommand/registerTool/registerProvider/pi.on) rather than a settings-file or slash-markdown surface. GSD ships a single native-extension file:
- Extension →
~/.pi/agent/extensions/gsd.js(global) or.pi/extensions/gsd.js(local)
The .js suffix is load-bearing: pi auto-discovers extensions by scanning that directory and keeping only names ending in .ts or .js, and it skips anything else silently — no error, no log line. GSD shipped the file as gsd.cjs through 1.7.0, which pi therefore never loaded, so /gsd never appeared (#2470). Upgrading removes the stale gsd.cjs; if you had added a manual extensions entry in ~/.pi/agent/settings.json as a workaround, you can drop it.
The extension registers a /gsd command and a gsd_invoke tool that dispatch GSD commands via a bounded subprocess call to gsd-core/bin/gsd-tools.cjs (no fully-populated in-process command-routing hub exists — see the matrix's Stage 2 note). This is a plugin-only install: pi has no shared-settings hook surface (hooksSurface: none) and, unlike Claude/OpenCode/Kilo, no host-read markdown surface at all — pi's /gsd command is registered programmatically by the extension, not discovered from files, so GSD installs the extension plus its universal gsd-core/ engine payload and the shared hooks//hooks/lib/ bundle (spawned by the extension itself, not by any config-file hook bus), and does not write any commands/, agents/, or skills/ directory for pi. The extension bridges GSD's session_start/before_agent_start/session_before_compact/tool_call lifecycle events to those staged hooks/ scripts as bounded, fail-open subprocesses, and steers pi's active model (modelMode: active) to a tier-resolved bare anthropic id via pi.on('before_provider_request', ...). See the ## pi section of the host-integration capability matrix for the negotiated axes and citations.
Local vs global install
All examples above use --global, which installs GSD once for your user account. To scope an install to a single project, replace --global with --local:
npx @opengsd/gsd-core@latest --claude --local
A local install writes into the .claude/ directory at your project root. Local install settings take precedence over global ones when both exist.
Installing prerelease editions (Next / Nightly / Insiders / Preview)
Prerelease editions of runtimes (Windsurf Next / Devin Desktop Next, Cursor Nightly, VS Code Insiders, Codex preview channels, etc.) read from a sibling config directory. Set the matching *_CONFIG_DIR env var before running the installer:
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
Select the corresponding stable runtime in the installer prompt. GSD does not enumerate prerelease editions as separate named runtimes — they are best-effort via this env-var mechanism and are not separately tested in release CI.
Installing without Node.js
If you cannot run npx (for example, on a Windows machine without Node.js), you have two options.
Option A — Use a machine that has Node.js. Any machine with Node.js will do: WSL, a Linux VM, a CI runner, or a Docker container. Run the installer there, then copy the output directory to your target machine. For OpenCode:
npx @opengsd/gsd-core@latest --opencode --global
# Then copy ~/.config/opencode/agents/ to the Windows machine
Option B — Manually transform the source files. The agent source files live in agents/ in the GSD Core repository and are in Claude Code's native frontmatter format. Each runtime expects a different shape. For the exact field transformations per runtime, see Manual install / no-Node.js setup in the User Guide, which covers the OpenCode transformations in full detail and points to the installer's convert*Frontmatter functions for other runtimes.
After install
Restart your runtime to pick up new commands and agents. Then start a new project or onboard an existing repo:
/gsd-new-project # greenfield project
/gsd-onboard # existing codebase
If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
"… is not on your PATH" after install
If the installer's global bin directory is not on your PATH, it prints a one-time warning with a copy-paste command for your shell. The suggestion list covers zsh, bash, and fish (plus PowerShell, cmd.exe, and Git Bash on Windows). For fish, run the line it prints:
fish_add_path '/path/to/global/bin'
If the directory is already on your PATH but the installer still warns, open a new fish session (exec fish) to pick up the change.