An efficiency overlay for gstack — same quality, far fewer tokens.
Never written code before? Start here → docs/GETTING_STARTED.md
That guide explains everything from zero — what these tools are, how to install them step by step, and how to run your first command — in plain language for someone who has never programmed. The rest of this README is for people who already know what gstack and Claude Code are.
This is not a fork. It's a thin layer of configuration, methodology, and a code-level audit that sits on top of a normal gstack install. You keep getting upstream updates from garrytan/gstack; this repo changes how you run it, not what it is.
gstack is Garry Tan's open-source "software factory" for Claude Code — 23+ specialist slash commands that turn the agent into a full engineering team. It is excellent, and it is deliberately token-heavy: the skills pack 25–35K tokens of behavior each, the project CLAUDE.md is ~51KB, and pipelines like /autoplan run several full passes. That cost buys real quality. The waste isn't the quality — it's paying for quality you didn't need on a given task, and re-paying for stable prompts that should have been cached.
gstack-optimized removes the waste without touching the quality.
Compress the mechanical. Never touch the judgment.
- Mechanical (cheap to make efficient): scaffolding, file reading, prose verbosity, redundant review passes, loading skills you'll never call.
- Judgment (where quality lives — leave it fully on Opus, fully verbose): product reframe (
/office-hours), architecture (/plan-eng-review), security (/cso), the review that catches production bugs (/review).
Every optimization in this repo is checked against this rule. If a change would cheapen a judgment step, it's not in here.
gstack-optimized/
├── README.md ← you are here
├── docs/
│ ├── GETTING_STARTED.md ← zero-to-running for non-coders (start here)
│ ├── OPTIMIZATION_DETAIL.md ← the 6 levers, in full detail
│ ├── PROMPT_CACHE_AUDIT.md ← lever 1: cache check (verify-only — see why inside)
│ └── BENCHMARKING.md ← how to actually measure the speedup (no guessing)
├── profiles/
│ └── TEMPLATE.project.md ← per-project profile that kills "averiguación" round-trips
├── routing/
│ └── LITE_VS_FULL.md ← when to run the cheap path vs the full sprint
├── config/
│ ├── gstack-optimized.config.yaml ← recommended ~/.gstack/config.yaml
│ └── apply.sh ← idempotent: applies config, prints next steps
├── LICENSE
└── .gitignore
New to all of this? Don't use this section — read docs/GETTING_STARTED.md instead. It installs Claude Code and gstack from scratch and explains every term. The steps below assume you already have gstack working.
Prerequisite: a working gstack install (~/.claude/skills/gstack). If you don't have one, install gstack first per its README (or the beginner guide above), then come back.
git clone https://github.com/dtrejopizzo/gstack-optimized.git ~/gstack-optimized
cd ~/gstack-optimized
./config/apply.shThis sets explain_level=terse and checkpoint_mode to local-only via gstack-config. Non-destructive and reversible. It does not modify gstack's source.
Copy profiles/TEMPLATE.project.md into each project and fill in the 5 fields (stack, test command, deploy command, what ships, slim skill list). Paste its contents into that project's CLAUDE.md. From then on, skills never burn tokens asking or searching for your stack.
Read routing/LITE_VS_FULL.md. Default to the lite path; reserve the full /autoplan pipeline for tasks with real product/architecture judgment. This is a habit change — it costs nothing and saves the most.
Follow docs/PROMPT_CACHE_AUDIT.md to confirm gstack's skill bodies are caching (they're static, so they usually are) and that no runtime output is breaking the cache prefix. After reading the source we downgraded this from "biggest win" to "verification" — the cache mostly works by default. Do it to be sure, not to expect a big new gain.
Run the baseline protocol in docs/BENCHMARKING.md before and after. Don't trust the numbers below — prove your own.
| Dimension | Original gstack | gstack-optimized |
|---|---|---|
| Skills loaded per project | All 35+ in the routing block | Only the 5–8 your project shape needs |
| Default workflow | Full sprint / /autoplan is the headline |
Lite by default, full only for judgment tasks |
| Prose verbosity | V1 (glossed, expanded) by default | terse (V0) by default |
| Prompt cache | Static skill files → already cacheable | Verified + protected (runtime output kept off the cache prefix) |
| Model usage | Opus-leaning across steps | Opus for judgment, Sonnet/Haiku for mechanical steps |
| Per-project config | Asks / searches when CLAUDE.md lacks it |
Pre-answered in a profile; zero round-trips |
| Measurement | gstack-analytics available |
Baseline-before/after protocol baked in |
| Relationship | The product | An overlay; upstream stays intact and updatable |
There is no clean, uniform 10x on tokens without cutting quality — anyone who promises that is selling something. Here's what's real and defensible:
| Scenario | Realistic gain | Where it comes from |
|---|---|---|
| A small task that used to go through the full pipeline | 3–6x | Lite routing (lever 3) |
| Verbosity / fixed preamble per call | structural cut | terse drops whole sections + right-sized routing (levers 2/5) |
| Mechanical steps (scaffolding, tests, file reads) | large | Model routing to Sonnet/Haiku (lever 4) |
| Repeated calls of the same skill | already mostly cached | gstack's skill files are static; the cache lever is verify-only (lever 1) |
| Net cost per typical sprint | 3–5x | All levers combined |
| Quality (bugs caught, review depth) | same or better | Judgment steps stay full + on Opus |
Correction we stand behind: an earlier draft headlined the prompt cache as a 5–10x win. After reading gstack's preamble.ts, that was wrong — the skill bodies are already static and cacheable, so the cache mostly works by default and this overlay can't claim that gain as new. The durable wins are lite routing + terse + right-sizing + model routing. Net per sprint is honestly 3–5x for the right project shape. See docs/PROMPT_CACHE_AUDIT.md for the full correction.
You only earn these numbers by measuring. See docs/BENCHMARKING.md.
- gstack is © Garry Tan — MIT. This overlay depends on it and changes nothing in his repo. Go star the original.
- gstack-optimized is MIT. See LICENSE.
Built as a configuration + methodology + audit layer. Fork it, tune it, make it yours.