Arah2/GSD_FIX.md

GSD_FIX.md — Notes on repairing the GSD-OpenCode install

Date: 2026-10-21 Package: gsd-opencode v1.38.5 (installed via npx gsd-opencode → global scope, ~/.config/opencode/)

Symptoms

Inside OpenCode, none of the /gsd-* commands were available, and gsd-sdk appeared broken/missing.

Root causes (two separate issues)

1. Slash commands were registered under the wrong names — /gsd/gsd-*, not /gsd-*

The v1.38.5 distribution manager installs the 88 GSD command files into a nested subdirectory:

~/.config/opencode/commands/gsd/gsd-plan-phase.md
~/.config/opencode/commands/gsd/gsd-execute-phase.md
...

This layout predates OpenCode V2's command discovery rules. In V2, nested paths become namespaced slash commands (documented at https://opencode.ai/v2/docs/commands/):

• commands/gsd/gsd-execute-phase.md → /gsd/gsd-execute-phase (what OpenCode registered)
• instead of /gsd-execute-phase (what the GSD README documents and users expect)

Verified against the running service via opencode api get /api/command: every command was registered as gsd/gsd-*, so typing /gsd-* found nothing — they "seemed" missing even though the files were all present (the installer's gsd-opencode check reported 755/843 files verified — 755 passing out of the 843-file manifest — which is exactly why the health check did not catch this).

Fix: flattened the command files:

mv ~/.config/opencode/commands/gsd/*.md ~/.config/opencode/commands/
rmdir ~/.config/opencode/commands/gsd

OpenCode hot-reloads command files, so the /gsd-* names registered immediately (confirmed via the /api/command endpoint — 88 flat gsd-* commands, zero gsd/gsd-* entries).

2. gsd-sdk was a dangling symlink into the ephemeral npx cache

Running the installer via npx gsd-opencode leaves the "global" binaries pointing into ~/.npm/_npx/*.*/node_modules/.bin/, which npx may garbage-collect at any time:

~/.local/bin/gsd-sdk -> ~/.npm/_npx/2ada84fac427087c/node_modules/.bin/gsd-sdk   # fragile

Every GSD command/agent shells out to gsd-sdk query …; when the npx cache is pruned, all of those calls die silently.

Fix: installed a pinned global copy and re-pointed the shim:

npm install -g gsd-opencode
ln -sf ~/.nvm/versions/node/v24.18.0/bin/gsd-sdk ~/.local/bin/gsd-sdk

Verified with gsd-sdk query state.load (succeeds) and gsd-sdk --version.

Side notes

• At the time of this repair, which gsd-opencode also resolved to a Windows npm shim (under /mnt/c/Users/.../npm/) on the WSL PATH, from a previous install on the Windows side. Harmless but confusing; the Linux binaries under ~/.nvm/.../bin now take precedence for gsd-sdk. That shim has since been removed and is no longer on the current PATH.
• The installer's own health checker (gsd-opencode check) still expects the old nested commands/gsd/ layout and will report the 88 flattened files as "missing" — this is a false positive caused by the checker not knowing about OpenCode V2's namespacing rules. The files are fine where OpenCode can find them.
• After changing GSD model profiles, note the package requires a full OpenCode restart (agent→model mappings come from opencode.jsonc and are read at startup).

Current state

Item	Status
/gsd-* slash commands	✅ 88 registered flat at ~/.config/opencode/commands/
gsd-sdk CLI	✅ stable symlink to global npm install (~/.nvm/.../bin/gsd-sdk)
Agents / skills / rules / sdk files	✅ untouched, integrity verified
gsd-opencode check	⚠️ reports false "missing files" (stale checker, see above)