CLAUDE.md · garrytan/gstack

Sections

1. Commands
2. Testing
3. Project structure
4. SKILL.md workflow
5. Platform-agnostic design
6. Writing SKILL templates
7. Writing style (V1)
8. Browser interaction
9. Dev symlink awareness
10. Compiled binaries — never commit browse/dist/, design/dist/, or make-pdf/dist/
11. Redaction guard (PII / secrets / legal content)
12. Commit style
13. Slop-scan: AI code quality, not AI code hiding
14. Community PR guardrails
15. Checking out PRs from garrytan-agents
16. CHANGELOG + VERSION style
17. AI effort compression
18. Search before building
19. Local plans
20. E2E eval failure blame protocol

First lines (shown under the repo's MIT license)

# gstack development

## Commands

```bash
bun install          # install dependencies
bun run dev <cmd>    # run CLI in dev mode, e.g. bun run dev goto https://example.com
bun run typecheck    # strict tsc over product code (zero errors required)
bun run typecheck:test  # test-code type-debt ratchet
bun run build        # gen docs + compile binaries
bun run gen:skill-docs  # regenerate SKILL.md files from templates
bun run skill:check  # health dashboard for all skills
bun run dev:skill    # watch mode: auto-regen + validate on change
bun run slop          # full slop-scan report (all files)
bun run slop:diff     # slop findings in files changed on this branch only
bun run audit:manifest  # file slices for /claude-api prompt-audit; rerun it at each frontier-model release (CONTRIBUTING.md)
```

Test and eval commands, their cost and what each needs live in one table:
[Which command do I run?](CONTRIBUTING.md#which-command-do-i-run). The two you
need most are `bun run test` (free acceptance) and `bun run eval:bg:pr` (paid,
changed coverage). Retired names such as `test:evals` and `test:e2e` print their
replacement and exit 1.

Paid evals require `ANTHROPIC_API_KEY`. Codex E2E tests (`test/codex-e2e.test.ts`,
`test/codex-e2e-sol-scope.test.ts`) use Codex's own auth — the hermetic runner copies
only `auth.json` from `${CODEX_HOME:-~/.codex}` and pins `CODEX_HOME` in the child
env — no `OPENAI_API_KEY` env var needed.

**Hermetic E2E + env keys:** every E2E runner spawns children through
`test/helpers/hermetic-env.ts` (allowlist-scrubbed env, fresh seeded
`CLAUDE_CONFIG_DIR`, temp `GSTACK_HOME`, `--strict-mcp-config`); per-test
`env:` overrides merge last onto a COMPLETE hermetic env, so they're safe.
A PTY test that types a `/skill` command must pass `seedSkills: true`.
Debug against real operator state with `EVALS_HERMETIC=0`. Full detail
(env-shim, seeding tripwires, wiring tests):
[docs/TESTING_INTERNALS.md](docs/TESTING_INTERNALS.md).

**Test selection and tiers:** the sharded paid runner (`test:pr`,
`eval:bg:pr`, `test:gate:sharded`) selects tests from `git diff` through the
dependency lists in `test/helpers/touchfiles.ts` (`EVALS_ALL=1` forces
everything; `eval:select` previews the PR profile, `--profile full` the plain
touchfile selection). Classify every new E2E test in `E2E_TIERS`: safety guardrail or
deterministic functional test -> `gate`; quality benchmark, Opus model test,
non-deterministic, or external service (Codex, Gemini) -> `periodic`.
`test/e2e-tier-alignment.test.ts` enforces the tiers. CI lanes and periodic
exclusions: [docs/TESTING_INTERNALS.md](docs/TESTING_INTERNALS.md#test-selection-and-tiers).

## Testing

```bash
bun run test         # final full free acceptance after focused repairs and source freeze
bun run eval:bg:pr   # required changed PR coverage, with explicit deferrals
```

Follow [Validation discipline in AGENTS.md](AGENTS.md#validation-discipline):
prove repairs with focused checks first, complete required selected evaluations,
then run the full free suite once on the final integrated code. During repairs,
focused checks replace a full-suite run before every commit.

`bun run test` routes through `scripts/test-free-shards.ts`, whose strict
per-shard classification fails a shard that lacks bun's summary line.
`TREE_MUTATING` lists the files that still run in their own trailing serial
shard (today only `test/bootstrap-retention.test.ts`). Never type
bare `bun test` for the suite: it walks the whole repo, loading paid eval files
and missing the strict classifier. `bun run test:pr` runs the selected short
live behaviors and quality judges and reports deferred broad coverage. Full free
acceptance and required PR checks must pass before publishing. See
[testing policy](CONTRIBUTING.md#test-tiers) for commands and measured targets.
Tests that need Aside itself self-skip unless a Mac has the Aside app open.
Shard packing, judge reuse and engine skips:
[docs/TESTING_INTERNALS.md](docs/TESTING_INTERNALS.md#free-suite-runner-judge-reuse-and-engine-skips).

New or changed tests follow the [test value bar](docs/test-value-bar.md): each one
protects behavior a real regression would break, and contract tests (SKILL.md
goldens, and prompt bytes that are a contract as defined below) stay. The bar's
source is `scripts/resolvers/test-value.ts`.

In this repo, prompt bytes are a contract only when software reads them (a
parser, hook, grader or another skill consumes the exact text) or a recorded
eval shows the wording matters. Tests on skill templates and generated SKILL.md
pin structure, step order, routing tables, machine-read markers and
safety-critical lines; check safety lines case-insensitively, on meaning rather
than capitals. Leave behavior to E2E cases and judges. Don't pin emphasis,
capitalization, issue numbers, or a sentence a behavioral check already covers,
and when a rewrite changes a pinned sentence, replace the pin with a structural
or meaning-level check instead of pinning the new sentence. The terms are defined
in [docs/test-value-bar.md](docs/test-value-bar.md) ("Prompt-byte contract",
"Sentence pin"). Use `test/helpers/prompt-structure.ts` (`between`,
`expectTokens`, `expectAbsent`, `expectOrdered`, `expectMentions`) for
template/SKILL.md checks: tokens and order exactly, safety rules as
case-insensitive keyword co-occurrence in one sentence.
Projects tune `/ship`'s coverage gate with optional CLAUDE.md `## Test Coverage`
keys, all absent by default: `Minimum:`, `Target:`, `Generation cap:` (default 5),
`Base control:` (`auto` or `off`), `Base control budget:` (seconds, default 90) and
`Star rating:` (`auto` or `off`).

## Project structure

Full annotated tree: [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md).
Quick map: `browse/` gstack's own headless-browser CLI (the fallback
engine) plus the `/browse` skill, `design/` design binary, `make-pdf/` PDF
binary, `hosts/` typed host configs, `scripts/` build+DX tooling
(gen-skill-docs, resolvers — `resolvers/aside.ts` is the Aside contract),
`test/` validation+evals, `lib/` shared libraries (`aside-render.ts` renders
local HTML through Aside, falling back to the engine; `design-catalog.ts` is
the typed design anti-pattern catalog every design skill renders from), `bin/`
CLI utilities (`gstack-render.ts` is the render CLI skills call;
`gstack-design-detect.ts` and `gstack-design-md.ts` are the design detector
and open-DESIGN.md tools), `extension/` Chrome
extension, one directory per skill (`ship/`, `review/`, `qa/`, ...),
`.github/` CI, `contrib/` contributor tools, `docs/designs/` design documents.

## SKILL.md workflow

SKILL.md files are **generated** from `.tmpl` templates. To update docs:

1. Edit the `.tmpl` file (e.g. `SKILL.md.tmpl` or `browse/SKILL.md.tmpl`)
2. Run `bun run gen:skill-docs` (or `bun run build` which does it automatically)
3. Commit both the `.tmpl` and generated `.md` files, including a tier 2+ skill's
   `sections/preamble.md` (the shared preamble, rendered by
   `scripts/resolvers/preamble-hoist.ts`; change the preamble resolvers, never that file)

The same `gen:skill-docs` run writes two more generated files from `lib/`:
`review/design-checklist.md` (from `lib/design-catalog.ts`, through
`scripts/resolvers/design-checklist.ts`) and `lib/dom-dump.js` (from
`lib/dom-dump-script.ts`). Edit the catalog or the script source, regenerate,
and commit both; never edit the generated file
(`test/design-checklist-sync.test.ts` fails on drift).

Generation uses each host's `defaultModel` (`claude` for most hosts, `gpt`
for Codex, `gemini` for Antigravity's `agy`) unless `--model` is explicit. Codex installs additionally read the
top-level model from `${CODEX_HOME:-~/.codex}/config.toml`; rerun
`./setup --host codex` after changing that model. Note: `bun run build` and a
bare `gen:skill-docs --host codex` render the host default (gpt) — if your
Codex config.toml pins a different model, rerun `./setup --host codex`
afterwards to restore your profile (single-owner persistence is filed in
TODOS.md).

Browser steps in skills are `aside repl` scripts per
`scripts/resolvers/aside.ts`, each with its `$B` equivalent for the fallback
engine. To add a new browse command: add it to `browse/src/commands.ts` and
rebuild. To add a snapshot flag: add it to `SNAPSHOT_FLAGS` in
`browse/src/snapshot.ts` and rebuild. Local-HTML rendering in a skill template
is a `bun run ~/.claude/skills/gstack/bin/gstack-render.ts` call; new render
options go into `lib/aside-render.ts` (which handles the fallback), never into
a skill's own bash.

**Size budgets:** generated SKILL.md files warn above 160KB (~40K tokens);
`test/catalog-budget.test.ts` caps the always-loaded skill catalog at
`CATALOG_BUDGET_TOKEN_EQUIVALENTS` (1,393 today; each new skill ratchets it); and
`test/context-budget-ratchet.test.ts` pins per-skill token ceilings against
`test/fixtures/context-budget.json` (for legitimate growth or a landed
reduction, re-run `bun test/helpers/capture-context-budget.ts` and commit the
refreshed fixture in the same commit). Rationale and protocol:
[docs/CONTRIBUTOR_REFERENCE.md](docs/CONTRIBUTOR_REFERENCE.md#skill-size-budgets).

**Merge conflicts on SKILL.md files:** NEVER resolve conflicts on generated SKILL.md
files by accepting either side. Instead: (1) resolve conflicts on the `.tmpl` templates
and `scripts/gen-skill-docs.ts` (the sources of truth), (2) run `bun run gen:skill-docs`