gstack: Instructions file for Claude Code

gstack development

Commands

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?. 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.

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.