golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(2): clarify installer is required for cross-runtime compatibility (#144)

Browse Source 
* docs(readme): add cross-runtime compatibility note for installer requirement

Source files in agents/ and commands/ are Claude Code-format frontmatter.
The installer (bin/install.js:5208 convertClaudeToOpencodeFrontmatter) is
the mandatory conversion layer for non-Claude-Code runtimes. Manually
copying source files to ~/.config/opencode/agents (or equivalent) bypasses
conversion and produces schema validation errors.

README lines 37, 165, 273 all claim OpenCode as a first-class runtime
without flagging the installer as mandatory. This adds an explicit note
immediately after the Getting Started section (README.md line ~175).

Refs #2

* docs(user-guide): add manual install / no-Node.js setup section for non-Claude runtimes

Users without Node.js (Windows + OpenCode being the most common case per
issue #2) cannot run the installer and may attempt to copy agents/ source
files directly. This section documents what manual conversion is required
for OpenCode (remove tools:, convert color: to hex), references the
installer function at bin/install.js:5208, links to the OpenCode schema
docs, and covers the Docker/WSL alternative.

USER-GUIDE.md insertion after line 1258 (after the Codex/non-Claude
runtime section, before Installing for Cline).

Refs #2

* ci: retrigger checks after transient git-auth runner failure

The original run for this PR had a single CI job fail with:
"fatal: could not read Username for 'https://github.com': terminal prompts disabled"
That is a hosted-runner infrastructure flake — no code defect. The run
cannot be retried via gh CLI (too old). This empty commit kicks a fresh
full CI cycle.
This commit is contained in:
Tom Boucher
2026-05-23 15:50:20 -04:00
committed by GitHub
parent 89886d90b4
commit c439890e26
2 changed files with 46 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/USER-GUIDE.md
View File

@@ -1257,6 +1257,44 @@ GSD will resolve each agent's tier (`opus`/`sonnet`/`haiku`) to the Codex-native
See the [Configuration Reference](CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli-kilo) for the full explanation.
### Manual install / no-Node.js setup
If you cannot run the GSD installer (e.g., Windows machine without Node.js or npm), you cannot use the source files in `agents/` directly. The source files are in Claude Code's native frontmatter format; each supported runtime requires a different shape. Copying them as-is into another runtime's config directory will produce schema validation errors.
> The installer function responsible for OpenCode conversion is `convertClaudeToOpencodeFrontmatter` at `bin/install.js:5208`. It is the canonical reference for what must be transformed.
#### OpenCode — required transformations
OpenCode validates agent frontmatter against its own schema ([opencode.ai/docs/agents](https://opencode.ai/docs/agents)). The GSD source format is incompatible in two ways:
| Field | GSD source format | OpenCode-valid format | Action |
|---|---|---|---|
| `tools:` | `Read, Bash, Grep` (comma-string) | Not a frontmatter field in OpenCode | Remove the `tools:` line entirely |
| `color:` | Plain CSS color name (e.g., `steelblue`) | Hex (`#4682b4`) or semantic name from OpenCode's fixed set | Convert to hex or remove |
The minimum viable manual transformation for a single agent file:
1. Open the `.md` file from `agents/` in a text editor.
2. Remove any `tools:` line from the YAML frontmatter block.
3. Change `color:` to a hex value, or remove it.
4. Save the file into `~/.config/opencode/agents/<agent-name>.md`.
All other frontmatter fields (`description:`, `system:`, `model:`) are accepted by OpenCode without modification.
#### Alternative: use a machine with Node.js to run the installer
If you have access to any machine with Node.js — including WSL, a Linux VM, a CI runner, or a Docker container — you can run:
```bash
npx @opengsd/get-shit-done-redux@latest --opencode --global
```
This produces a correctly converted `~/.config/opencode/agents/` directory. Copy that directory to your Windows machine.
#### Other runtimes
The same principle applies to all non-Claude-Code runtimes. Each runtime has its own schema, and the installer handles each conversion. If you are manually installing for a runtime not covered above, review the relevant installer converter in `bin/install.js` (search for `convert*Frontmatter`) for the exact field transformations needed.
### Installing for Cline
Cline uses a rules-based integration — GSD installs as `.clinerules` rather than slash commands.