3.2 KiB
ADR 0001: public infrastructure tools
- Status: accepted for the GStack 2 candidate
- Date: 2026-07-20
- Scope: installation, first-use UX, browser binaries, release integrity, and updater ownership
Decision
Use public tools only where they have a narrow, replaceable responsibility:
| Responsibility | Decision | Boundary |
|---|---|---|
| Skill discovery, host placement, project/global scope, selection, update, and removal | Vercel Agent Skills CLI, pinned to 1.5.19 in verification | Canonical and exclusive skill lifecycle. GStack never silently enrolls a host. |
| Interactive terminal prompts | Clack, if adopted after the current zero-dependency prompt surface needs richer TTY UX | Presentation only; consent state, policy, transactions, and non-TTY flags stay in GStack. No dependency is added merely for styling. |
| Local browser binaries | Playwright | Existing local Chromium manager only. No cloud-browser provider. |
| Cross-platform launchers | Bun compile | Build-time native launcher production; the runtime remains host-neutral. |
| Release signing and verification metadata | Sigstore Cosign in release CI | CI signs immutable archives keylessly. Every client verifies byte count and SHA-256; Cosign verification is additional when already installed, never a mandatory end-user install. |
| Release attestations | GitHub artifact attestations | Provenance for release artifacts, with actions pinned to immutable commits and id-token: write limited to the signing job. |
GStack owns the product-specific remainder: the signed runtime manifest, capability consent, atomic install journal, rollback, doctor output, and the first-use prompt that appears only when a chosen skill needs an unavailable capability.
Rejected as mandatory dependencies
oclif: a second CLI framework would not solve skill placement, consent, or transactional updates and would expand the runtime dependency surface.eget: convenient binary download UX, but it does not encode GStack's fixed artifact host, manifest, capability, rollback, or privacy policies.miseandaqua: useful optional environment/package managers, but requiring either would add a package manager in front of the standard Agent Skills installer.- hosted browsers, device farms, alternate iOS drivers, ComfyUI, model weights, and GPU runtimes: outside the accepted architecture.
Consequences
The standard installer can evolve independently without GStack maintaining six
host adapters. The optional runtime has one auditable release format and no
automatic setup. Public-tool telemetry and network behavior must be disclosed
at the point of use; upstream Agent Skills telemetry can be disabled with
DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1.
The repository keeps tests for the pinned installer behavior and release contract. A future tool swap must preserve those contracts instead of leaking the tool's own nouns into the six-skill public surface.