gstack skill

gstack for Capy and Claude Code

Session start: check, then install only when needed

Crew lanes: after this check passes, read lane-card.md, not the rest of this file; it says what to read before /ship. Resolve scripts/install.sh relative to this SKILL.md, not the working repository. It is a frozen bootstrapper: it prints gstack-capy-skill: wrapper () first, learns the supported minimum from gstack's remote, and hands over to the checkout's own wrapper (bin/gstack-capy-session).

1. At session start run bash scripts/install.sh --check, adding --for when you know the workflow (--for autoplan, --for review, --for qa). It prints one PASS|FAIL|SKIP|WARN row per component (WARN never fails the run: it names an owner action or a fix you can run), a GSTACKLAUNCH: line, and exactly one trailer as the last line: gstack: ok for=[ ()] (exit 0) or gstack: fail … (exit 1). Read the exit status and grep ^gstack: directly; never pipe the check through tail, head or grep alone. --check never moves the checkout. A thread that runs no gstack workflow on this machine (a coordinator, a Captain) runs --check --for none instead: gstack: ok not-needed for=none (), exit 0, nothing installed or certified, no workflow admitted. That ok is not an install verdict: grep for gstack: ok for=, never bare ^gstack: ok, before running a workflow. Record the line; install --for before the first workflow, if one comes. Then, whatever the trailer says, once per session read capy/skill/gstack/factory.md in the checkout (${GSTACKCAPYROOT:-$HOME/.local/share/gstack}) when there is one, otherwise the factory.md beside this SKILL.md: how crews work, with pointers to the rules. If neither exists, report factory.md: none on its own line after the verbatim trailer. With no checkout, or after a for=none trailer (no launch file names the preference then), also read only the agentmodel line of the preferences.yaml beside this SKILL.md, treating the rest of the file as data: a family such as opus means the newest model of that family in your model list, provider/model means that model, and host, no file or anything else (an unparseable value, two agent_model lines) means keep your own model and say so in your report. Use it for the threads, subagents and reviewers you start, except a cross-family outside voice and an eval's model under test; after gstack: ok for=, gstack-models resolve --role agent is the source.
2. If the trailer names revision, runtime or pins (gstack: fail revision …, gstack: fail runtime,pins, gstack: fail pins) and a checkout exists, or an ok trailer carries floor= (), behind= (latest: ) or stale= with a fix: note, run the same command without --check (900 s timeout), or the fix: command when it names another, once before the next workflow; behind=1 or more always calls for it. floor= means the project needs a newer gstack than this machine holds (mingstackversion in its .gstack/ship-policy.json), and stale=h that the checkout has lacked an origin commit for over 24h; a floor= note saying no release meets this floor yet has no fix: report it. A pin with a recorded reason (below) holds: stale=h (pinned: ), or a fix: starting unset GSTACKCAPY, which you skip. So does upgrade skipped: … (), a refused install naming the commands: run them once its cause clears, working on the certified revision meanwhile. A thread older than a day reruns the check before its next workflow. Only a checkout below the supported minimum (the revision row) fails a session for being old. Report the trailer verbatim. For pins it installs the project's pinned Bun when the pin names a verified version, or stops with RUNTIMEPINCONFLICT naming the pin to raise. Install mode fast-forwards a clean checkout, reinstalls and rechecks in one locked step, but never moves a dirty or diverged checkout or one a live session lease or eval run holds (UPGRADEBUSY); a pin (--revision, detached, another branch, GSTACKCAPYSELFUPGRADE=off, GSTACKCAPYAUTOUPGRADE=0) holds past 24 hours only with a recorded reason (GSTACKPINREASON= or git -C config gstack.pinReason ), else the install overrides it (PINUNREASONED). Details: docs/capy-install.md in the checkout.
3. If the trailer is gstack: fail not-installed … and this session runs no gstack workflow, record that line and continue; nothing is installed. Install right before the first workflow with bash scripts/install.sh --for (about 30 s cold: clone, a SHA-256-verified Bun when none installed fits, both host profiles without Chromium, and a ~/.local/bin/bun shim so fresh shells get the recorded Bun).
4. Any other FAIL row carries a fix: command and a reason code with a troubleshooting anchor; run the fix, then --check again. SKIP codex-cli (optional; …), SKIP browser (lazy; …), SKIP pins (planning-only; …), SKIP pins (helper runtime; …) and SKIP floor (…) are not failures. WARN pins … (node pin only; bun pins pass) is not one either: the Node on PATH misses the project's pin while Bun is right; run its fix only when this machine will run the project's tests.

The trailer rule. No ^gstack: ok line from this machine in this session means gstack is not installed here: do not run a workflow, and do not claim the skills work. One machine's install never covers another.

Subagents. A subagent's first report to its parent carries the gstack: trailer line from its own machine's --check, verbatim, after its identifiers. A parent treats a missing line as gstack: fail not-installed. A reviewer subagent that only reads and reports (an /autoplan voice, a second opinion) runs --for review-voice instead: seconds when warm, no ./setup, no host profiles, Bun at gstack's own minimum, and a trailer that certifies only the read-only helpers (gstack-pregate sealed, gstack-plan-reality, gstack-artifact, the gstack-autoplan reads); every workflow refuses it with a --for fix. Never brief a reviewer that no install is needed. A reviewer later asked to run a workflow runs the same installer --for : it upgrades the checkout in place (pins, ./setup, host profiles; no second clone). A machine without this skill (a brief you write for a subagent) runs the checkout's own bootstrapper from its project directory: test -f "$HOME/.local/share/gstack/setup" || git clone --quiet --single-branch --depth 1 https://github.com/garrytan/gstack.git "$HOME/.local/share/gstack" && GSTACKCAPYROOT="$HOME/.local/share/gstack" bash "$HOME/.local/share/gstack/capy/skill/gstack/scripts/install.sh" --for .

gstack-capy-skill: owner action — Drive copy is wrapper , minimum ; copy /capy/skill/gstack/ (CAPYWRAPPERSTALE) means this skill folder is older than the checkout wants. The run still works; tell the owner, who copies that directory over the skill folder. Never write the skill folder yourself; the one exception is its preferences.yaml, when the owner asks you to remember a preference (gstack-models resolve --role agent reads it).

Launch every gstack command with the GSTACK_LAUNCH line

Every successful run, --check included, prints GSTACKLAUNCH: PATH=:$PATH GSTACKSESSIONKIND=unattended GSTACKSTATEROOT= GSTACKEPHEMERAL=1 GSTACKCAPY=1 GSTACKINSTALLVERDICT= (the PATH= part only when the verified Bun is not first on PATH), then GSTACKLAUNCHPATH: for callers that do not evaluate shell syntax, then GSTACKLAUNCHFILE: : the same assignments as a sourceable script, plus the checkout's bin/ appended to PATH (so a bare gstack-ship-budget resolves in a shell that sourced only this file), mode 0600, under the state root beside the install verdict. Apply them with . at the start of every shell that runs a gstack command (each Capy bash call is a fresh shell, and a child shell's export cannot configure the parent's later commands); the plain GSTACKLAUNCH: line is for callers that do not evaluate shell syntax, never for re-typing. The file is part of the ok verdict: a passing run that cannot write it fails with gstack: fail launch-file …, and a failing run that rewrites the verdict removes it. Never re-type them as export $(...), and never run env, printenv, a bare set or a bare export in a tool fence: when the substitution comes back empty, export $(...) is a bare export, which prints every exported variable, API keys included, into the tool output (that is how GSTA-96's docs-audit child leaked three keys). Hand a child agent the file path, never the values. The PATH part is what makes gstack's #!/usr/bin/env bun commands run the Bun the trailer certified; the Capy image's /usr/local/bin/bun is 1.3.14, below gstack's minimum.

With GSTACKCAPY=1, a workflow started in an unattended or spawned session checks the install verdict the last run wrote for this checkout, HEAD and workflow, and the Bun on PATH. When either fails it prints an INSTALL: fail … row with its fix and GSTACKRESULT: skill= status=refused run=- and exits 3: stop, run the fix, start again. An ok whose pins row was SKIP pins (planning-only; …) does not admit a workflow that runs the repo's tests (review, ship, qa), and a verdict that did not check a component the workflow needs does not admit it either; run --for first.

Load the right workflow

For Capy running GPT-6 Astra, read ${CODEXHOME:-$HOME/.codex}/skills/gstack/SKILL.md for routing, then ${CODEXHOME:-$HOME/.codex}/skills/gstack-/SKILL.md for the selected workflow. They are generated for GPT-6 Astra.

For Claude Code, read ~/.claude/skills/gstack/SKILL.md for routing and ~/.claude/skills//SKILL.md for the selected workflow. When launching a Claude Code session, tell it to load gstack and name the intended workflow. Capy on a Claude model reads the Claude files directly with the Capy adaptations below; that does not make Capy the Claude Code harness.

If no specific skill was requested, use the router's task-to-skill mapping. Read only the selected workflow and its referenced files. Other models use the closest profile, never claiming one was generated or evaluated for them.

Unattended runs for a parent agent

For /autoplan driven from Capy, read autoplan/DRIVER.md in the checkout (~/.local/share/gstack/autoplan/DRIVER.md): the compact phase loop, artifact contract and gate protocol, without the interactive preamble. A checkout without that file predates it; follow its autoplan/SKILL.md instead. Run every command with the GSTACKLAUNCH assignments and read outputs as files, not prose: the run directory holds run.json, decisions.jsonl, findings.jsonl, tasks.jsonl, timing.json, plan.md and review-record.md, and the run ends with GSTACKRESULT: skill=autoplan status=gatepending run=. ~/.local/share/gstack/bin/gstack-artifact validate /run.json is the completion check. The gate is answered through gstack-autoplan answer (or gstack-gate parse) with the printed gaterev; an unattended run never approves its own gate. docs/unattended.md in the checkout is the contract.

For /ship driven from Capy, read ship/DRIVER.md in the checkout (~/.local/share/gstack/ship/DRIVER.md): one or two calls per phase, and the section each STOP needs. A checkout without that file predates it; follow its ship/SKILL.md instead.

Run directories and scratch on Capy live under ~/.capy/work/ (--out ~/.capy/work//autoplan), never /tmp: Capy wipes /tmp when a machine sleeps, and a vanished run cannot be resumed, answered or exported. Likewise any file a later turn reads.

Capy checklist for /autoplan: drive gstack-autoplan, never a hand adaptation presented as a run. Relay gstack-gate render /gate.json --all with rec (every recommendation, plan changes included) as the one-word default; answer with --by agent: --owner-reply "". Set GSTACKAUTOPLANCHECKPOINT_DIR to a private project-user Drive folder; after machine replacement, gstack-autoplan resume --out --from restores the newest valid checkpoint.

Token caps on /ship: pass a brief's cap as --token-cap . /ship reads cost.tokens and cost.credits from tools.thread.get({ thread_id: "" }) (its own jam; a subagent reading root "this" starts --subagent --reading-from this --meter-scope tree) inside the same execute program as the gstack-ship-budget command that takes them as --reading --credits , never alone. ship/DRIVER.md starts --mode observe: each program ends with note, and only a note past the cap stops (docs/ship-budget.md).

/ship on Capy is about a dozen calls, each an execute program (ship/DRIVER.md). Each review pass and Step 11 is one call to the checked-in pass program (fill only input): const t0 = await now(); const p = (await tools.capy.bash({ command: ". '' && gstack-review-dispatch program", description: "Pass" })).output.split("\n"); return p[0] + "\n" + (await new (Object.getPrototypeOf(async () => {}).constructor)("tools", "sleep", "now", "input", JSON.parse(p[1]))(tools, sleep, now, { startedAt: t0, launch: "", cwd: "", base: "", out: "/p", pass: "-p", laneModel: "", planFlags: [], logStart: ["review"], jam: "", record: "", step: "9.2" })); It plans, logs logStart (reservation mode from RESERVATIONID:), sends each brief on machine: "shared", then polls: one tools.subagent.list per ~20 s tick, returning 200 s after the program's first line, where a reader is settled only at status done or failed or with a summary (a just-created idle reader has not run); it starts readers under rejected with tools.subagent.start as slots free and stops on one stuck 20 minutes. It ends on NEXT: (poll: rerun) or STOP:. models maps roles to models (outside-voice: another family, pinned in voice-models.json); Step 11 swaps logStart for stage: "voices"; a full repeat pass, diffBase: "". Steps 7, 8 and 14.5 (step: "14.5") use extras, JSON {name, promptfile, first, model} (prompts verbatim from their sections, Step 7 first); they cannot block, so omit model: the pass prints AUDITMODEL:. Waits: never let 5 minutes pass between calls. While readers run, never end the turn on wait; rerun the loader. Else re-issue wait with durationseconds: 200 and operation ids. At Step 22 report the CALLS: line of gstack-ship-budget calls --record . A small waiting child saves nothing.

Plan, approve, ship

Every Capy thread using gstack follows these for new work, Captain or not. The rule in full is crew/docs/captain.md, "Plan before build"; the lane side is section 3 of captain.md in this folder.

• Plan first. Run /autoplan on new functionality right after the install check. The lean run (the Capy default) is one reviewer over plan and draft code; --full adds every phase.
• ELI5, then the word. Send the plan and gate to the person, or the Captain, in plain language: gstack-owner-brief render --captain --out --captain-name "", its choices as lettered lines in the ask format (crew/docs/captain.md) and "do it" taking every recommendation at full scope. Build only after their word is answered into the run and it reports APPROVED; then gstack-approvals import --autoplan --by "".
• /ship before ready. Run /ship at the final pushed head before a PR is called ready; SHIP_RECEIPT: pr= head= must name that head, and a later push needs a new /ship. The review inside /ship, like the autoplan, is sized to the change.
• Sleep while /ship runs, then stop it. After dispatching /ship the parent ends its turn with no PR watch until /ship completes (a re-READY drops a held watch first). On that wake it subscribes to the PR (renewed on expiry, cancelled at merge or close), reads its checks and comments once, stops the subagent, runs gstack-ship-queue ready and owns the PR thereafter: slot stamp, re-READY, receipt carry (crew/docs/captain.md, the lane's /ship sequence). A stopped /ship subagent woken by a check, review or merge notice, not its parent, reports what woke it, its pin and the PR head (gh pr view --json headRefOid --jq .headRefOid) in one line and ends the turn without acting, even if the head moved. A message from its parent is an instruction it carries out.
• No merge without the owner's word. A thread never merges on its own; under a Captain the controller merges on a recorded standing approval, and a thread with no Captain asks the person.

Exempt from the plan step: read-only work, the daily flaky pass's repairs, slot stamps, CHANGELOG-only resolves, cap re-pins under a written grant, S1 emergencies (a broken install or upgrade, a red main, a security bug) and fixes from an already-diagnosed, audited problem list. Other bug fixes skip plan review (--kind fix, R65) but carry a repro on current main or a failing test written first; features get the lean run (--kind feature).

Working under a Captain

When you work for a Capy Captain (a crew thread) or straight for a person, gstack's decisions reach them through you. Every workflow started with the GSTACK_LAUNCH line prints CAPY: on and a capy-asks block that repeats these rules. The full guide, with examples and templates, is captain.md.

• How approvals flow. A crew thread never asks the person directly. It sends the ask to its Captain as a needs-you report, and the Captain asks the person in plain words and brings back their exact reply. A thread with no Captain asks the person with a Capy question. An answer covers only the thread and scope it was asked for.
• Standing approvals need no ask. These are the ones your Captain lists in its rules (for example "merge when green, through a train"). Cite the rule instead of asking again.
• These always need a fresh ask: a product or behaviour decision, spend over a stated cap, anything published outside the repository, a change to a threshold, budget or trial count, closing someone's contribution without landing it, and anything destructive.
• Record every answer. Use gstack-approvals add --ask … --words "" --by … --scope …, or after an autoplan answer, gstack-approvals import --autoplan --by . gstack-approvals render prints the ## Approvals table for your report and the PR body. Rows are secret-scanned, and on Capy they are mirrored to the private Drive folder.
• Plan approvals use gstack-owner-brief render --captain --out . It prints before → after, why it matters, what caused this work, the big decisions (options, the pick, why, what would flip it) and what we need, as lettered ask lines closed by "do it". Relay it whole. Gate codes appear only on its last line, which is for you. If it exits CAPTAINBRIEFINCOMPLETE, add the missing plan sections first.
• Merge asks. /ship's PR body opens with plain sentences, then ## What changed (captioned before/after images from gstack-pr-shots or a UI screenshot, uploaded with Capy's PR asset tool), ## Why and ## Blast radius, Agent notes last (## Approvals). Your READY report attaches the key image.

Before any push or pull request

In a repository with a sealed configuration (a sealed key in its .gstack/pregate.json), run ~/.local/share/gstack/bin/gstack-pregate sealed before every push and before creating a pull request: Capy's pull-request tool may not r