mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-20 15:13:47 +01:00
* Fix spaced-out terminal text on Windows: put a Latin monospace before the CJK fallbacks On Windows none of the Mac/Linux monospace fonts in the stack are installed, so the first font that resolves is Malgun Gothic (the Windows Korean UI font). xterm.js sizes its character cell from that font's advance width, and Malgun Gothic advances Latin glyphs in a full-width CJK cell — doubling every cell and rendering the whole terminal (and the sidepanel mono UI) as spaced-out text. Insert Consolas (present on every Windows install) and the Cascadia faces ahead of the CJK fonts in both the xterm fontFamily and the --font-mono CSS var. The CJK fonts stay last for actual CJK coverage. No bundled font, no user install needed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GKj8Nr8T4GvryTcWBJRMyC * fix(windows): every compiled binary answers --version before any side effect browse --version started a server and exited 1, pdf printed usage and exited 1, gstack-global-discover rejected the flag, and find-browse ran discovery. A launch probe for Smart App Control (#2595) needs one side-effect-free command that exits 0 on a healthy build, so browse, find-browse, make-pdf and gstack-global-discover now answer --version first (design already did). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(extension): pin Consolas ahead of the CJK fallbacks in both mono stacks (#2287) Regression test for @tomfluff's fix: the xterm fontFamily and --font-mono must list Consolas before Noto Sans Mono CJK KR and Malgun Gothic, or Windows renders the sidebar terminal double-width. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(cso): record each CSO build's outcome and stop arming the parent trap across the native publisher exec (#3071) scripts/build-cso.sh now writes bin/.gstack-cso-build-result: result, failed stage (build or publish), reason, this revision, the revision of the generation still installed, whether its launcher is usable, and the diagnostic log. An 'interrupted' entry is written before each stage so a killed run is visible. A failed publish that restores the old generation records it as still installed. Before exec'ing the native publisher, the parent re-checks the locker, clears its EXIT trap and enables execfail: the locked child's own trap owns the stage. On Git Bash an exec of a native program may not replace the shell, so the parent's trap could otherwise delete the stage under the running child (the vanishing files in #3071; root cause unproven). If the exec itself fails the parent cleans the stage and records it. The Windows build prefers PowerShell 7 (pwsh) over Windows PowerShell 5.1, which crashed outright on the reporter's machine. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(setup): an optional CSO build or publish failure no longer aborts setup (#3071) CSO was optional at probe time but fatal at build time: scripts/build.sh ran build-cso.sh under set -e before the browse server bundle and the completion stamp, and setup exited when the CSO artifact set was incomplete. A failed CSO step now prints 'CSO unavailable: the <stage> step failed' with its log (bin/.gstack-cso-build.log) and retry, and the build and setup finish. GSTACK_STRICT_BUILD=1 keeps it fatal; the free-tests, make-pdf-gate and windows-setup-e2e builds set it, so regressions still fail CI. setup's summary reads the build-result record instead of the pre-build availability flag: probe failures keep their prerequisite instruction; build and publish failures name the stage, the diagnostic and 'bun run build:cso && ./setup', and a restored earlier helper is reported as 'previous CSO kept: <revision>'. setup records probe failures in the same file. The Windows prerequisite probe prefers pwsh, and a probe that fails for any reason other than a missing toolchain or a compile error keeps its exit status and first output line (windows-toolchain-probe) instead of being labeled windows-msvc-toolchain. Reported and diagnosed by @dviolante. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(windows): detect Smart App Control-blocked binaries in setup and gstack-doctor (#2595, #2124) Smart App Control refuses the five unsigned binaries gstack compiles locally, and Git Bash reports it as 'Permission denied', so setup's [ -x ] gate passed and skills failed later. bin/gstack-launch-probe.sh runs each binary's side-effect-free --version and classifies it: native, blocked (spawn error, exit 126/127, or an application-control message), broken (launched, exited non-zero) or missing. It shows the raw first output line, since the exact Windows text is unverified. On Windows, setup names each blocked binary and the skills that need it, cites #2595, says which shell ran setup and whether WSL is installed, gives today's workarounds (WSL, or turning Smart App Control off), how to undo, and the new troubleshooting section. gstack-doctor's browse row now says 'blocked at launch' instead of passing, a binaries row covers the other four, and a cso row reads the build-result record. windows-setup-e2e builds with GSTACK_STRICT_BUILD=1, checks all five binaries answer --version, and adds two forced CSO failures: fatal under strict mode, and a completed setup that reports the failure and a doctor cso warning under GSTACK_STRICT_BUILD=0. No shim or launcher: it could not be called from PowerShell and would load the caller's project .env/bunfig. Signing is the follow-up in TODOS.md. Diagnosis credit: @knetics9000 (#2595, #2596), @smartjelic-sys (#2595), @pstilwell90 (#2124), @cko32002 (#2265), @salluexez (#2127). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: Windows Smart App Control known issue, optional CSO failures, doctor rows README's Windows section says /cso failures no longer stop setup (GSTACK_STRICT_BUILD=1 keeps them fatal), documents Smart App Control as a known issue with today's workarounds (WSL, or turning it off) and the Consolas fix. troubleshooting.md gains a Windows section for blocked binaries and an entry for CSO build/publish failures. TODOS.md replaces the Node CLI lane item with Windows code signing (needs a signing account), the #3071 root-cause follow-up and SAC text verification. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(setup): never write the CSO build record into a source checkout that needed no build Setup wrote bin/.gstack-cso-build-result for every probe-stage outcome, so a run that built nothing still changed the source checkout's bin/ (caught by setup-codex-scope's unchanged-source checks). A missing prerequisite now comes from the run's own probe, as before, and setup only removes a stale record alongside the removed helper. scripts/build-cso.sh remains the only writer. The doctor's cso row reports 'native helper not built' with no record. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(extension): move the Consolas font-stack check into sidebar-ux (#2287) The standalone file read extension sources without importing product code, which the test-of-test ratchet rejects; sidebar-ux already owns the sidepanel.css structural checks. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * v1.91.43.0 fix(windows): setup degrades instead of dying on a CSO failure, detects Smart App Control, Consolas terminal font Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(setup): every env-var runtime root carries the files its skills read as $GSTACK_ROOT/<path> (#1077 residue) Codex, Factory, Kiro, OpenCode, Cursor and Copilot runtime roots linked bin/, lib/ and the compiled tools but not the files the generated skills read on demand: the preamble's jargon list and question registry, the AskUserQuestion split and CJK docs, the DX Hall of Fame, the test-value bar, the review checklists and specialists, design-html's vendored pretext.js, VERSION and plan-design-review/SKILL.md. The reads failed silently on every non-Claude host. _link_runtime_dists now links the shared list for every root, and _copy_runtime_skill_refs copies the host-rendered office-hours and plan-design-review SKILL.md (the #2449 pattern) into each root. The per-root review loops it replaces had drifted (Cursor shipped two of four checklists, only OpenCode had specialists). hosts/define-host.ts mirrors the list in sharedRuntimeRoot(). test/runtime-root-assets.test.ts renders every host, builds each root with setup's own functions and checks every $GSTACK_ROOT literal on disk; it fails on the previous setup for all five roots. scripts/ship-measure.ts stays deferred (it needs the eval harness). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(build): an install renders skills only for the hosts installed from it (#1694) ./setup ran gen:skill-docs --host all inside the install, so a global Claude install at ~/.claude/skills/gstack carried 632 SKILL.md files (34.7 MB) where 56 are its own; Claude Code and Cursor-agent scan that tree, and Cursor-agent freezes above roughly 11 MB. setup now keeps an additive record of the hosts it installs from a checkout (.gstack-installed-hosts, owned by bin/gstack-host-renders.sh), seeded from installs that predate it: registry rows, install roots that resolve to the checkout, host skills that link into its renders, and legacy skill copies with no runtime root. scripts/build.sh renders claude plus the recorded hosts and prints which hosts and why. A checkout with no record (development) or GSTACK_RENDER_HOSTS=all renders every host. The Codex .agents/ render runs only when Codex is installed or recorded; bin/dev-setup records Codex because it serves the repo's .agents/. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(setup): prune skill renders for hosts a checkout does not serve, without losing a file (#1694) Every ./setup now removes the render dirs of hosts missing from the installed-hosts record, so an install that rendered every host (632 SKILL.md, 34.7 MB under ~/.claude/skills/gstack) converges on its own hosts. It runs per install, so two installs sharing one state root are both cleaned, and never touches a recorded host, so ./setup --host codex keeps a --host factory render. The rules follow bin/gstack-relink: a symlink into the checkout (STRONG) is removed; a file proven generated (WEAK: gen-skill-docs' banner, the generator's exact openai.yaml shape, byte identity with the checkout, or setup's runtime pointers naming it) is moved to $GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/; any other file, including a link outside the checkout or bin/dev-setup's link to the checkout itself, stays where it is. Only directories left empty are removed. setup prints each kept path and a per-host summary, and prune.log in the backup lists every path. A tree with nothing left to remove is silent, so reruns print nothing. gstack-upgrade/migrations/v1.91.50.0.sh records the hosts an existing install serves and runs the same prune; a checkout no install points at is left alone. The Hermes, OpenClaw and GBrain hints say to add the host to the record before rendering it by hand. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(build): name the installed-hosts record in the build's host line 'Rendering skills for: claude codex (recorded in <checkout>/.gstack-installed-hosts; GSTACK_RENDER_HOSTS=all renders every host)' instead of a nested parenthesis. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * v1.91.50.0 fix(install): skills only for the agents you installed, every runtime-root file their skills read (#1694, #1077) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(team-mode): copy bin/gstack-host-renders.sh into the setup fixture setup sources the new helper (#1694); team-mode's hand-picked fixture file list lacked it, so its two setup runs exited 1 ('gstack-host-renders.sh is missing'). Found by the final full free suite on 9b39cc6; product code is unchanged. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * chore(release): re-slot C2 to v1.91.61.0 (merge queue); migration renamed to match VERSION Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: Yotam <yotsurfing@gmail.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
407 lines
22 KiB
Markdown
407 lines
22 KiB
Markdown
# Adding a New Host to gstack
|
|
|
|
gstack uses a declarative host config system. Each supported AI coding agent
|
|
(Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes,
|
|
GBrain) is defined as a typed TypeScript config object built by the
|
|
`defineHost()` factory. Rendering a new host means creating one file and
|
|
re-exporting it: the generator, tests, and validation pick it up. Installing
|
|
it is not free: setup still has one install arm per installable host (see
|
|
"What setup changes on disk" below), so an installable host also needs a setup
|
|
arm, an entry in the install registry tier table, and a certification run
|
|
before it is labelled `full`.
|
|
|
|
## Install ownership rules
|
|
|
|
These rules hold for every host, every scope, and every upgrade path
|
|
(`./setup`, `./setup --refresh-registered`, `/gstack-upgrade`, the team-mode
|
|
auto-update). Each refusal names what was left alone, the rule that applied,
|
|
and the exact command to proceed.
|
|
|
|
1. **Project-local setup never silently replaces a global install.** Setup
|
|
run from a project-vendored copy, or from any checkout other than the one a
|
|
global install links to, leaves that global install alone and prints
|
|
`./setup --global` as the way to replace it on purpose. (Codex:
|
|
`setup:186-207`, #2879. Claude: the global `~/.claude/skills/gstack` link.)
|
|
2. **An explicit `--host X` never mutates another host.** `--host codex`
|
|
writes only Codex's skills directory and the checkout's own `.agents/`
|
|
render. It does not heal, register, or remove Claude Code hooks in
|
|
`settings.json`, and it does not touch the Claude gbrain render (#2347).
|
|
One deliberate exception: the one-time `/claude` → `/claude-code` rename
|
|
repair (`bin/gstack-migrate-claude-code`) renames gstack-owned entries in
|
|
every install that shares the checkout.
|
|
3. **Upgrades refresh exactly the registered installs.** Every install setup
|
|
activates is recorded in the install registry. Upgrades run
|
|
`./setup --refresh-registered`, which runs setup once per registered host
|
|
of that checkout (printing the source first) and nothing else. Installs
|
|
owned by another checkout, and project installs of another project, are
|
|
listed with the command that refreshes them there; they are never repointed
|
|
(#1925).
|
|
4. **User-owned files survive.** Setup, `gstack-relink`, and
|
|
`gstack-uninstall` delete or link over an entry only with proof that gstack
|
|
created it (the #2119 ownership gate); anything else is reported and left.
|
|
|
|
### The install registry
|
|
|
|
`$GSTACK_STATE_ROOT/installs.tsv` (mode 0600) is the one record of installs.
|
|
Only `bin/gstack-install-registry.sh` writes it, under a lock directory with an
|
|
atomic rename. Columns: host, scope (`global`/`project`), project, destination
|
|
(the skills directory the host discovers), install root, source realpath,
|
|
version, prefix setting, render, updated-at. A row publishes only after the
|
|
host arm finished activating. Rows whose install root is gone are dropped
|
|
(`gstack_install_registry_reconcile`) by every refresh and by
|
|
`gstack-uninstall`, so an upgrade never resurrects an uninstalled host.
|
|
|
|
`./setup --status` prints one row per install (host, tier, scope, result,
|
|
version, destination, source) without building or writing anything, plus any
|
|
pre-registry install it finds on disk, labelled `unregistered` with the
|
|
command that registers it. A Codex install captured by a project-vendored copy
|
|
(#2879) is reported with both choices instead of being repointed. The setup
|
|
summary, the `/gstack-upgrade` summary, and `--status` share one renderer
|
|
(`gstack_install_registry_render`).
|
|
|
|
### Migrations
|
|
|
|
`gstack-upgrade/migrations/v*.sh` are state-root migrations. Their marker is
|
|
`$GSTACK_STATE_ROOT/.last-setup-version` (read from `~/.gstack` once for
|
|
installs that predate the move). It advances only past migrations that
|
|
succeeded; a failed migration stops the sequence, prints a `failed` row with
|
|
the retry command, and runs again on the next `./setup`. Install and host
|
|
migrations are tracked per install by the registry row's version.
|
|
|
|
### What setup changes on disk
|
|
|
|
Inventory of every setup side effect, by phase (line numbers are approximate):
|
|
|
|
| Phase | Writes | Scope |
|
|
|---|---|---|
|
|
| Build | `browse/dist`, `design/dist`, `make-pdf/dist`, `bin/gstack-cso-*` in the source checkout | source |
|
|
| Hosts record | `.gstack-installed-hosts` in the source checkout: every host setup installed from it, additive (#1694) | source |
|
|
| Generation | renders for the recorded hosts only (`.agents/`, `.kiro/`, `.factory/`, `.opencode/`, `.cursor/`, `.copilot/`) in the source checkout; `gstack-patch-names` rewrites Claude `name:` fields in place | source |
|
|
| Render prune | renders of hosts the record does not name: links into the checkout removed, generated files moved to `$GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/`, other files kept | source / state root |
|
|
| Chromium | Playwright cache (`~/.cache/ms-playwright`), lock under the state root | machine |
|
|
| Config | `skill_prefix`, `timeline_stop_hook`, team-mode keys in `$GSTACK_STATE_ROOT/config.yaml` | state root |
|
|
| Claude arm | `~/.claude/skills/gstack` link, one dir per skill with a `SKILL.md` link, alias copies | selected host |
|
|
| Codex arm | `${CODEX_HOME:-~/.codex}/skills/gstack` runtime root, `gstack-*` links into `.agents/skills`, `.agents/skills/gstack` sidecar | selected host |
|
|
| Kiro, Factory, OpenCode, Cursor, Copilot arms | the host's `skills/gstack` runtime root (built beside the live one and swapped in) and `gstack-*` links | selected host |
|
|
| OpenCode commands | `~/.config/opencode/commands/gstack-*.md` with a managed marker (#2629); user command files are never touched | selected host |
|
|
| Registry | one row per activated install in `installs.tsv` | state root |
|
|
| Migrations | whatever each `v*.sh` repairs; marker in the state root | state root |
|
|
| Claude hooks | `~/.claude/settings.json` (heal, SessionStart, plan-tune, Stop) — only when Claude is selected | Claude |
|
|
| gbrain | `gbrain-detection.json`; the Claude render in `$GSTACK_STATE_ROOT/render/claude` — only when Claude is selected | state root / Claude |
|
|
|
|
Activation today: on macOS and Linux every install is a set of symlinks into
|
|
the source checkout, so a `git pull` changes the active payload before setup
|
|
runs and "keep the prior payload" means "keep the prior checkout" — which the
|
|
upgrade skill does on the vendored path (`.bak` restore) and records on the
|
|
git path (`PRE_UPGRADE_COMMIT`). On Windows, where setup copies instead of
|
|
linking, every copy is staged as `<dst>.gstack-new.<pid>` and swapped in only
|
|
when complete; an interrupted swap is repaired on the next run (a missing
|
|
destination is restored from `<dst>.gstack-old.<pid>`). Versioned payload
|
|
directories for the symlink platforms are not built yet.
|
|
|
|
### Install-context render contract
|
|
|
|
Committed renders name each host's default install root. A render for any
|
|
other root (project install, `CLAUDE_CONFIG_DIR`, renamed checkout) is made
|
|
with `gen-skill-docs --host <h> --install-root <abs path> --out-dir <tmp>
|
|
--link-root <dir>`: every default-root path becomes the given root, and
|
|
resolvers see it as `TemplateContext.installRoot` (null keeps committed bytes).
|
|
Per-install renders live in `$GSTACK_STATE_ROOT/render/installs/<host>-<id>/`
|
|
(`<id>` keyed by the root's realpath) and are recorded in the registry's render
|
|
column. Setup makes one for a Claude install outside `~/.claude/skills/gstack`
|
|
(renamed checkout, project-vendored copy, `CLAUDE_CONFIG_DIR`) and a global Codex
|
|
install outside `~/.codex/skills/gstack` (`CODEX_HOME`); repo-local Codex installs
|
|
resolve their root at run time. A root that is not a plain path (whitespace,
|
|
shell metacharacters) is named through a `<host>-<id>.root` alias symlink:
|
|
worktree-isolated Claude Code refuses a command path containing a space in any
|
|
quoting.
|
|
|
|
### Host renders in an install (#1694)
|
|
|
|
A checkout renders skills only for the hosts installed from it.
|
|
`bin/gstack-host-renders.sh` owns the record, `.gstack-installed-hosts` in the
|
|
checkout: setup adds each host it installs and never removes one, so
|
|
`./setup --host codex` keeps a `--host factory` render. The first run after an
|
|
upgrade seeds it from the hosts the checkout already serves (registry rows,
|
|
install roots that resolve to it, host skills that link into its renders, and
|
|
legacy copies with no runtime root). `scripts/build.sh` renders claude plus
|
|
the recorded hosts and prints which hosts and why; a checkout with no record (a
|
|
development checkout) or `GSTACK_RENDER_HOSTS=all` renders every host.
|
|
|
|
Every setup run then prunes the renders of unrecorded hosts with
|
|
`bin/gstack-relink`'s proof rules: a symlink into the checkout (strong proof)
|
|
is removed; a file proven generated (weak proof: the gen-skill-docs banner, the
|
|
generator's exact `openai.yaml` shape, byte identity with the checkout) is
|
|
moved to `$GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/`; every other file
|
|
stays where it is, and only directories left empty are removed. The backup's
|
|
`prune.log` lists every path. A gstack-upgrade migration runs
|
|
the same prune for an install upgraded without a setup run. Instruction-only
|
|
hosts (Hermes, OpenClaw, GBrain) are never installed by setup, so a user who
|
|
renders one by hand inside an install adds its name to the record first.
|
|
|
|
## Host tiers and capabilities
|
|
|
|
Every host declares `tier` and `capabilities` (`scripts/host-config.ts`).
|
|
One vocabulary is used everywhere: `./setup --help`, setup and `--status`
|
|
rows, host errors, and the README host matrix, all checked against
|
|
`hosts/index.ts` by `test/host-config.test.ts`.
|
|
|
|
| Tier | Meaning |
|
|
|---|---|
|
|
| `full` | Installs, renders, passes the conformance kit, and has a dated certification record below. |
|
|
| `experimental` | Installs and renders and passes the conformance kit; no certification record yet. |
|
|
| `instruction-only` | No install arm. `./setup --host X` prints what to copy and changes nothing. |
|
|
|
|
Rendering alone never certifies `full`.
|
|
|
|
| Capability | Values | Used for |
|
|
|---|---|---|
|
|
| `toolExecution` | boolean | preambles and `bin/` helpers run |
|
|
| `questions` | `native` / `prose` | structured question tool vs plain-text questions |
|
|
| `planMode` | boolean | plan-mode transitions |
|
|
| `delegation` | boolean | sub-agents |
|
|
| `browser` | boolean (needs `toolExecution`) | gstack's browser |
|
|
| `safetyHooks` | `enforced` / `advisory` | `/careful`, `/freeze`, `/guard` block (Claude) or only warn |
|
|
|
|
Hosts with `safetyHooks: 'advisory'` get one line at the top of `/careful`,
|
|
`/freeze` and `/guard`: "not enforced on <host>: advisory, not blocked".
|
|
|
|
## Certify your host
|
|
|
|
1. Pass the conformance kit: `bun test test/host-conformance.test.ts` installs
|
|
every installable host into a temp HOME, checks discovery directories, no
|
|
other host's variant, no duplicates, `./setup --status`, and an upgrade from
|
|
the previous release's install layout.
|
|
2. Run one representative workflow for real on the host (for example
|
|
`/review` on a small diff), and an upgrade from an existing install.
|
|
3. Add a row below with the date, host version, gstack version, and where the
|
|
transcript lives, then set `tier: 'full'`.
|
|
|
|
| Host | Date | Host version | gstack version | Evidence |
|
|
|---|---|---|---|---|
|
|
| claude | 2026-10-02 | Claude Code 2.1.284 (CI image pin) | v1.91.13.0 (1c54555) | gate-tier evals, real Claude Code sessions: https://github.com/garrytan/gstack/actions/runs/37033755821 |
|
|
|
|
Codex stays `experimental` until its periodic cases (`codex-discover-skill`,
|
|
`codex-review`) pass on the CI image's pinned Codex CLI and a row is added.
|
|
|
|
## GitHub Copilot CLI (#393)
|
|
|
|
Shipped as `experimental` (`hosts/copilot.ts`, `./setup --host copilot`):
|
|
skills in `~/.copilot/skills/gstack-*`, runtime root `~/.copilot/skills/gstack`
|
|
with a `.source-path` marker so `/gstack-upgrade` finds the checkout, names
|
|
prefixed `gstack-` (Copilot's built-in `/review` would win otherwise),
|
|
`disable-model-invocation: true` on sensitive skills, and a one-paragraph
|
|
tool-name glossary (`ask_user`, `exit_plan_mode`, `task`, `view`, `skill`)
|
|
inserted ahead of the preamble's STATUS rules. A shared directory was not
|
|
enough: Copilot CLI stopped reading `~/.claude/skills` in 1.0.36, gstack never
|
|
writes `~/.agents/skills`, and a Codex render carries Codex paths and the
|
|
Codex model profile.
|
|
|
|
Disposition of the community attempts:
|
|
|
|
| PR | Decision | Why |
|
|
|---|---|---|
|
|
| #2323 (@andrey-esipov) | Selectively reused, with credit | Kept: `~/.copilot/skills` and `.github/skills` roots, `copilot`-binary detection, `.source-path`, the `gstack-` prefix, the 1024-char description limit, uninstall coverage. Not kept: new schema fields and generator edits (predate `defineHost()`), an unguarded `rm -rf` of the runtime root (#2142), links to `setup`/`scripts`/Claude sources inside a recursively scanned dir, a test-only install backdoor in setup, and a blanket AskUserQuestion → `ask_user` rewrite. |
|
|
| #396 (@ridermw) | Rejected | Sed-rewrites Codex output into a shared `.agents/skills`; its E2E runner copies real `~/.copilot` credentials into a temp HOME. Its session scanner is a candidate for a later `/retro global` change. |
|
|
| #487 (@ridermw) | Rejected | Relies on `~/.claude/skills`, which Copilot CLI no longer reads. |
|
|
| #1852 (@lolisaigao1234) | Rejected | Detects `gh` instead of `copilot`, installs to a directory Copilot does not scan, links `bin` without `lib`. |
|
|
|
|
Unverified without a real Copilot CLI (why it is not `full`): autopilot may
|
|
answer `ask_user` itself, plan mode blocks mutating shell commands, symlinked
|
|
skill dirs need Copilot CLI 1.0.62 or later, and `COPILOT_HOME` other than
|
|
`~/.copilot` is refused for now.
|
|
|
|
## Instruction-only hosts
|
|
|
|
OpenClaw, Hermes, Slate and GBrain have no install arm. Hermes stays
|
|
instruction-only until someone certifies a native install (#2826 measured one
|
|
on Hermes 0.21.0): `./setup --host hermes` prints the digest path and the
|
|
generator command, and the Hermes render writes `name: gstack-<skill>` so
|
|
Hermes, which indexes skills by frontmatter name, cannot shadow them (#2825).
|
|
|
|
## How it works
|
|
|
|
```
|
|
hosts/
|
|
├── define-host.ts # defineHost() factory: shared defaults + derived fields
|
|
├── claude.ts # Primary host
|
|
├── codex.ts # OpenAI Codex CLI
|
|
├── factory.ts # Factory Droid
|
|
├── kiro.ts # Amazon Kiro
|
|
├── opencode.ts # OpenCode
|
|
├── slate.ts # Slate (Random Labs)
|
|
├── cursor.ts # Cursor
|
|
├── openclaw.ts # OpenClaw
|
|
├── hermes.ts # Hermes (Nous Research)
|
|
├── gbrain.ts # GBrain
|
|
└── index.ts # Registry: imports all, derives Host type
|
|
```
|
|
|
|
Each config file calls `defineHost()` and exports the resulting `HostConfig`
|
|
object, which tells the generator:
|
|
- Where to put generated skills (paths)
|
|
- How to transform frontmatter (allowlist/denylist fields)
|
|
- What Claude-specific references to rewrite (paths, tool names)
|
|
- What binary to detect for auto-install
|
|
- What resolver sections to suppress
|
|
- What assets to symlink at install time
|
|
|
|
The generator, setup script, platform-detect, uninstall, health checks, worktree
|
|
copy, and tests all read from these configs. None of them have per-host code.
|
|
|
|
## Step-by-step: add a new host
|
|
|
|
### 1. Create the config file
|
|
|
|
Configs are built with the `defineHost()` factory in `hosts/define-host.ts`.
|
|
You only write the fields that differ from the common external-host defaults;
|
|
everything else is derived from the host name. A fully-default host is two
|
|
fields (see `hosts/slate.ts` or `hosts/cursor.ts`):
|
|
|
|
```typescript
|
|
import { defineHost } from './define-host';
|
|
|
|
const myhost = defineHost({
|
|
name: 'myhost',
|
|
displayName: 'MyHost',
|
|
});
|
|
|
|
export default myhost;
|
|
```
|
|
|
|
That expands to the full `HostConfig` with these defaults:
|
|
|
|
- `cliCommand: 'myhost'` (the name; binary for `command -v` detection)
|
|
- `cliAliases: []`
|
|
- `defaultModel: 'claude'` (model overlay used when generation gets no explicit `--model`; codex overrides to `'gpt'`)
|
|
- `globalRoot` / `localSkillRoot`: `.myhost/skills/gstack`, `hostSubdir`: `.myhost`
|
|
- `usesEnvVars: true` (false only for Claude, which uses literal `~` paths)
|
|
- `frontmatter`: allowlist keeping `name` + `description`, no description limit
|
|
- `generation`: no metadata file, `skipSkills: []` (both outside-review skills are enabled; Claude and Codex explicitly omit their own wrapper)
|
|
- `pathRewrites`: the standard trio derived from the resolved paths
|
|
(`~/.claude/skills/gstack` → `~/{globalRoot}`, `.claude/skills/gstack` →
|
|
`{localSkillRoot}`, `.claude/skills` → `{hostSubdir}/skills`)
|
|
- `suppressedResolvers`: the GBrain pair (`GBRAIN_CONTEXT_LOAD`, `GBRAIN_SAVE_RESULTS`)
|
|
- `runtimeRoot`: `sharedRuntimeRoot()`, every file the skills run or read as
|
|
`$GSTACK_ROOT/<path>` (`bin`, `lib`, the compiled tools, `freeze/bin`, the
|
|
review checklists and specialists, the jargon list and question registry,
|
|
the AskUserQuestion docs, the DX Hall of Fame, `VERSION`, and the
|
|
office-hours and plan-design-review `SKILL.md` copies). It mirrors setup's
|
|
`_link_runtime_dists` and `_copy_runtime_skill_refs`;
|
|
`test/runtime-root-assets.test.ts` checks each staged root on disk. A host
|
|
with extra assets passes them: `sharedRuntimeRoot(['qa/templates'])`.
|
|
- `install`: `{ linkingStrategy: 'symlink-generated' }`
|
|
- `learningsMode: 'basic'`
|
|
|
|
Override any field by passing it to `defineHost()`. Two path-rewrite options:
|
|
|
|
- `extraPathRewrites`: appends entries AFTER the derived trio (e.g. kiro's
|
|
codex-path cleanup, or `{ from: 'CLAUDE.md', to: 'AGENTS.md' }` for
|
|
AGENTS.md hosts). Use this when the standard trio is right but you need more.
|
|
- `pathRewrites`: replaces the derived list entirely. Only for non-mechanical
|
|
cases — codex and factory rewrite the global path to `$GSTACK_ROOT` and add
|
|
an extra review-path rewrite; claude has an empty list.
|
|
|
|
The two are mutually exclusive (the factory throws if you pass both).
|
|
|
|
Shared constants exported from `define-host.ts` for spread-composition:
|
|
`CROSS_MODEL_RESOLVERS` (outside-provider review resolvers plus Review Army,
|
|
suppressed on hosts that opt out; Codex keeps outside reviews and suppresses
|
|
Review Army), `GBRAIN_RESOLVERS` (the default
|
|
suppression pair), and `EXEC_STYLE_TOOL_REWRITES` (the OpenClaw-style
|
|
lowercase-tool rewrites shared by openclaw and gbrain).
|
|
|
|
Good examples: `hosts/opencode.ts` (path + extra runtime assets),
|
|
`hosts/factory.ts` (tool rewrites and conditional fields), `hosts/hermes.ts`
|
|
(AGENTS.md host with custom tool rewrites and resolver composition).
|
|
|
|
### 2. Register in the index
|
|
|
|
Edit `hosts/index.ts`:
|
|
|
|
```typescript
|
|
import myhost from './myhost';
|
|
|
|
// Add to ALL_HOST_CONFIGS array:
|
|
export const ALL_HOST_CONFIGS: HostConfig[] = [
|
|
claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, myhost
|
|
];
|
|
|
|
// Add to re-exports:
|
|
export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, myhost };
|
|
```
|
|
|
|
### 3. Add to .gitignore and the render table
|
|
|
|
Add `.myhost/` to `.gitignore` (generated skill docs are gitignored), and add
|
|
`myhost:.myhost` to `GSTACK_HOST_RENDER_DIRS` in `bin/gstack-host-renders.sh`
|
|
so an install renders it only when it is installed and prunes it otherwise
|
|
(#1694; `test/host-renders.test.ts` checks the table against `hosts/*.ts`).
|
|
|
|
### 4. Generate and verify
|
|
|
|
```bash
|
|
# Generate skill docs for the new host
|
|
bun run gen:skill-docs --host myhost
|
|
|
|
# Verify output exists
|
|
ls .myhost/skills/gstack-*/SKILL.md
|
|
|
|
# Generate for all hosts (includes the new one)
|
|
bun run gen:skill-docs --host all
|
|
|
|
# Validate all host content and tracked output freshness, including the new host
|
|
bun run skill:check
|
|
# Claude install paths are rejected in prose; legitimate Bash fallbacks are allowed.
|
|
```
|
|
|
|
### 5. Run tests
|
|
|
|
```bash
|
|
bun test test/gen-skill-docs.test.ts
|
|
bun test test/host-config.test.ts
|
|
```
|
|
|
|
The parameterized smoke tests automatically pick up the new host. They verify: output exists, no path leakage, valid frontmatter,
|
|
freshness check passes, and outside-review skills match each host's exclusions.
|
|
|
|
### 6. Update README.md
|
|
|
|
Add install instructions for the new host in the appropriate section.
|
|
|
|
## Config field reference
|
|
|
|
See `scripts/host-config.ts` for the full `HostConfig` interface with JSDoc
|
|
comments on every field.
|
|
|
|
Key fields:
|
|
|
|
| Field | Purpose |
|
|
|-------|---------|
|
|
| `tier` | `full`, `experimental`, or `instruction-only` (see Host tiers) |
|
|
| `capabilities` | What the host runtime offers; rendering and docs must not claim more |
|
|
| `frontmatter.nameMatchesDirectory` | Write `gstack-<skill>` into `name:` for hosts that index by frontmatter name |
|
|
| `defaultModel` | Model overlay rendered when generation gets no explicit `--model` (validated against `ALL_MODEL_NAMES` in `scripts/models.ts`) |
|
|
| `frontmatter.mode` | `allowlist` (keep only listed) or `denylist` (strip listed) |
|
|
| `frontmatter.descriptionLimit` | Max chars, `null` for no limit |
|
|
| `frontmatter.descriptionLimitBehavior` | `error` (fail build), `truncate`, `warn` |
|
|
| `frontmatter.conditionalFields` | Add fields based on template values (e.g., sensitive → disable-model-invocation) |
|
|
| `frontmatter.renameFields` | Rename template fields (e.g., voice-triggers → triggers) |
|
|
| `pathRewrites` | Literal replaceAll on content. Order matters. Replaces the derived trio. |
|
|
| `extraPathRewrites` | (defineHost input only) Appended after the derived trio. |
|
|
| `toolRewrites` | Rewrite Claude tool names (e.g., "use the Bash tool" → "run this command") |
|
|
| `suppressedResolvers` | Resolver functions that return empty for this host |
|
|
| `coAuthorTrailer` | Git co-author string for commits |
|
|
| `boundaryInstruction` | Anti-prompt-injection warning for cross-model invocations |
|
|
|
|
## Validation
|
|
|
|
The `validateHostConfig()` function in `scripts/host-config.ts` checks:
|
|
- Name: lowercase alphanumeric with hyphens
|
|
- CLI command: alphanumeric with hyphens/underscores
|
|
- `defaultModel`: must be a known model family from `scripts/models.ts` `ALL_MODEL_NAMES`
|
|
- Paths: safe characters only (alphanumeric, `.`, `/`, `$`, `{}`, `~`, `-`, `_`)
|
|
- No duplicate names, hostSubdirs, or globalRoots across configs
|
|
|
|
Run `bun run scripts/host-config-export.ts validate` to check all configs.
|