gstack/docs/gstack-2/HOST-COMPATIBILITY.md

# GStack 2 host compatibility

This matrix uses evidence tiers. It does not call a host “supported” merely
because its directory name exists in legacy setup code.

## Tiers

| Tier | Meaning |
|---|---|
| **Portable** | The canonical `skills/<name>/SKILL.md` tree follows the Agent Skills specification and uses no required host-private placement logic. This is a source-format claim. |
| **Verified** | The named layer and matrix cells passed against a recorded host/installer version. A scoped “Verified — installer” claim does not imply the host UI launched or executed judgment. |
| **Native** | A necessary host API adds behavior unavailable through portable skills while consuming the same canonical judgment source. Native is not “better”; it carries an additional adapter maintenance contract. |

Tiers are cumulative only when evidence says so. A portable host is not
automatically verified. A legacy generated host output is not a native GStack 2
bundle.

## Canonical installation

```bash
npx skills add time-attack/gstack
```

The standards installer owns host detection, destination paths, project/global
scope, copy versus symlink, updates, removal, and selected-skill installation.
Review its detected-host prompt; detection must never silently enroll a host.

Examples supported by the installer interface:

```bash
# One public skill only
npx skills add time-attack/gstack --skill plan

# Installer-managed global scope
npx skills add time-attack/gstack -g
```

Run `npx skills add --help` for the installed CLI version before scripting
agent-selection flags. GStack deliberately does not reproduce those flags or
host paths in `./setup`.

The expected discoverable names are exactly:

```text
plan
design
qa
debug
review
ship
```

`compat/*.md` and `references/legacy/*.md` are not `SKILL.md` files and must not
appear as additional skills. Installing a subset must not pull the other five
public entries unless the user selected them.

## Candidate installer matrix

The isolated standard-installer matrix passed 470/470 checks with `skills` CLI
1.5.19: 16 install cases and two removal cases. Default discovery projected
only canonical `skills/`; separate explicit-selection cases covered a single
canonical skill and an opt-in legacy alias. The matrix used symlinked and spaced
source paths matching a clean checkout where ignored legacy host trees are
absent. Every installed file was a physical copy and its hash matched the
selected source. The standard skill installation remains Markdown-only and
does not install the optional runtime. The committed evidence artifact is
[`evals/installation/install-matrix.json`](../../evals/installation/install-matrix.json).

| Host | Portable | Project all-six | Global all-six | Selected-skill coverage | Installer tier | Host UI/process |
|---|---|---|---|---|---|---|
| Claude Code | yes | pass | pass | no separate subset case | **Verified — installer** | pending |
| OpenAI Codex | yes | pass | pass | global `qa`, `review`, `ship` pass + removal pass; opt-in alias covered | **Verified — installer** | v1/v2 failed; live v3 pending |
| Cursor | yes | pass | pass | project `qa`, `review`, `ship` pass + removal pass | **Verified — installer** | pending |
| Pi | yes | pass | pass | no separate subset case | **Verified — installer** | pending |
| OpenClaw | yes | pass | pass | project `ship` single-skill pass | **Verified — installer** | pending |
| GitHub Copilot | yes | pass | pass | no separate subset case | **Verified — installer** | pending |

The representative selection cases installed exactly `qa`, `review`, and
`ship`, independently at project scope for Cursor and global scope for Codex,
then removed them noninteractively. Separate cases installed only `ship` for
OpenClaw and explicitly selected the `office-hours` compatibility alias for
Codex; neither alias nor unselected canonical skill was silently enrolled.
`--copy` was advertised and used.

This is filesystem/installer verification, not a claim that six host UIs loaded
or executed the skills. The Codex adversarial lane has no passing live result:
v1 and immutable v2 failed, while v3 is green only in its offline 18-test /
111-assertion harness and has not run live. The installer matrix used the
current local canonical projection through the published `npx skills` CLI, not
the still-unpushed GitHub branch URL.

Legacy generators currently know ten host names. That is historical breadth,
not proof that all ten install correctly. Kiro's old Codex-rewrite behavior and
other host-output transforms are outside the canonical 2.0 path.

## Verification procedure and evidence

Use a clean temporary home and project for every cell; never test against an
operator's live skill directory.

1. Record OS, host version, Node/npm version, and `skills` CLI version.
2. List the source and assert exactly six default entries.
3. Install all six at project scope and verify each host discovers only those
   six GStack public skills.
4. Remove them through the standard installer.
5. Repeat at global scope.
6. Install a selected subset; verify unselected skills were not enrolled.
7. Reinstall/update without re-detecting or enrolling an unselected host.
8. Invoke a pure judgment mode with `gstack` absent from `PATH`.
9. Invoke a capability-dependent mode and verify one actionable runtime offer,
   without breaking judgment.
10. Exercise a path containing spaces and, where supported, symlink and
    read-only failure behavior.
11. Record exact command, exit status, output artifact, and cleanup result in
    [TEST-EVIDENCE.md](./TEST-EVIDENCE.md).

The automated filesystem portion is:

```bash
bun test test/gstack2-installation.test.ts
bun run scripts/gstack2/test-install-matrix.ts --full \
  --output /tmp/gstack2-install-matrix.json
```

The current matrix passed 470/470 installer CLI checks across 16 installs and two
removals; its JSON artifact is committed at
[`evals/installation/install-matrix.json`](../../evals/installation/install-matrix.json).
Steps 8–9, a passing live v3 adversarial run, and actual host UI loading remain
separate behavioral gates.

## Optional runtime/platform matrix

The optional runtime is separate from skill placement. From a repository
checkout, the one host-neutral setup entrypoint is:

```bash
./setup
~/.gstack/bin/gstack doctor --json
```

`./setup` resolves a symlinked checkout, reinstalls the frozen production
dependency set on every run,
builds missing allowlisted capabilities through the runtime-only build target,
validates and hashes every staged file, smoke-tests the CLI, atomically
activates the version, and writes stable POSIX and Windows launchers under
`$GSTACK_HOME/bin` (default `~/.gstack/bin`). The bundle uses `.exe` targets on
Windows and includes the CoreDevice/iOS bundle only on Darwin. Add the bin
directory to `PATH` if the short `gstack` command is desired.

Twenty-four focused installer tests pass with 336 assertions. They cover
manifests, paths with spaces,
source-root symlinks, internal-link/path-escape rejection, failed build/
validation/smoke rollback including native-load rollback smoke,
interrupted-pointer recovery, stable POSIX/Windows launchers, runtime-only
builder selection, deterministic exact Sharp/ngrok platform closure, managed
uninstall, and the host-neutral wrapper.

The deterministic clean macOS arm64 managed-bundle audit records 110
components, 1,829 files, 450,044,315 bytes, and 50 capability launchers. This
is a platform-specific bundle measurement, not a universal byte count;
platform-native package payloads differ. Setup installs frozen production-only
dependencies and excludes the development-only Claude Agent SDK. The
Sharp/ngrok closure is included. The Hugging Face sidecar is excluded and its
package is development-only, so setup installs neither its inference runtime
nor model weights and reports the L4 capability unavailable.

| Platform | Source-level target | Candidate evidence |
|---|---|---|
| macOS | Node runtime + local browser + physical iOS where applicable | Runtime installer 24/336 and deterministic clean macOS arm64 bundle audit pass. The uninterrupted broad singleton run is green at 6,240 pass / 226 expected skips / 0 fail across 383 files. The signed-device gate remains pending. |
| Linux | Node runtime + local browser | Declared Dev Container GStack 2 suite passed at 136/0 with 1,127 assertions across 15 files; log: `/tmp/gstack2-devcontainer-gate-candidate-final4.log`. The one-assertion difference from the focused macOS result is the platform-conditional read-only-mode check. A clean Linux arm64 container used production-only install with the development SDK and model runtime absent, passed a local-browser journey and Sharp full-page screenshot, and uninstalled while preserving state. Native-host broad Linux remains pending. |
| Native Windows | Node runtime; curated free tests; browser fallback where retained | **Blocked:** native Windows CI pending. The local Windows-safe singleton lane is green at 2,815 pass / 57 expected skips / 0 fail across 213 files, but it is not native evidence. |
| Dev Container | Pure skills and optional runtime; browser only when container supports it | Declared image builds; generated freshness and the 136-test GStack 2 suite pass, as does the clean runtime install/browser smoke. Full broad Linux coverage remains pending. |

The six portable skills remain useful when runtime installation fails. A
runtime failure must not remove or corrupt their standard-installer placement.

## Native adapters

No GStack 2 native tier is currently required or awarded. A future native
bundle needs an accepted issue showing that a host API is necessary, must load
the same canonical judgment modules, and must pass the portable parity suite.
Host-specific presentation metadata such as `agents/openai.yaml` does not by
itself create a second judgment source or a Native claim.