Files

T

araharah-executor 506ff68976 chore(01-design-tokens-rams-foundation-01): commit design baseline — Rams docs, mockups, agent skills

- Root Rams design docs (DESIGN.md, IDEAS.md) and GSD install-fix notes (GSD_FIX.md, gsd-fix.sh)
- Four Telemetry Rams mockup screens + telemetry_rams/DESIGN.md (canonical token frontmatter)
- .agents/ project skills (design-taste-frontend) + skills-lock.json
- .gitignore: node_modules/dist/env secrets/OS junk; .planning stays local-only; Zone.Identifier scrubbed (9 files deleted)

2026-10-22 07:33:04 +08:00

3.5 KiB

Raw Blame History

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/755 files intact, 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

which gsd-opencode also resolved to a Windows npm shim (/mnt/c/Users/.../npm/gsd-opencode) 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.
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.json 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)

3.5 KiB Raw Blame History