gstack/capy

gstack + Capy: the software factory

gstack is a set of engineering skills: plan reviews, /ship, /review, /qa, evals. Capy runs agents in the cloud. It gives each thread its own machine, and it adds Captains that direct a crew of threads, a shared Drive, and automations. Put together, one person runs a team of agent engineers across several repositories, and the work lands on main green, reviewed, and in the order he chose.

This page is what we built, how the pieces fit, why we think it is the best way to run a software factory today, what we learned the hard way, and how Garry actually uses it. The step-by-step setup is in docs/recommended-harness.md; the controller's reference is docs/captain.md.

The numbers

The 14 days from the 2026-10-15 fix waves (the Captain took over the next day) against the 14 days before, measured from git and GitHub¹ :

• 197 PRs merged to gstack's main, up from 65 (3.0x). That is 98.5 a week.
• 194 versions shipped, 13.9 a day, up from 62 (3.1x). Nearly every merged PR gets its own version number when it merges.
• Nearly twice gstack's best two weeks before Capy. The March launch shipped 99 versions in its busiest 14 days; these two weeks shipped 194.
• 36 PRs merged and 36 versions shipped in one day (UTC), on October 25 and again on October 26.
• A reported issue is fixed in a median 2.4 days, from the issue opening to the fixing PR's merge, across the 52 issues closed by a PR in the window.
• 1,874 PRs merged across eight of Garry's repositories in the same 14 days.

What the numbers don't say: PRs got smaller. The median gstack PR fell from 1,292 changed lines to 422, so "3x the PRs" is true and "3x the code" is not. Small PRs are the point (each one is reviewed, gated and revertible on its own), but they are not more total output. Time from opening a PR to merging it went up, from a median of 1.1 hours to 5.6, because trains batch merges.

What we did

Capy threads started writing gstack PRs on 2026-09-15. On 2026-10-15 Garry approved two fix waves, and the next day he handed gstack's development to a Capy Captain, GStack Minder. Its standing job is to keep garrytan/gstack moving and main green. Within two weeks there were seven Captains (gstack, gbrain, alphaclaw, two eval projects, a game, and a magazine), each directing its own crew of threads.

Most of what made it work did not exist on day one. It came out of Garry's replies, one at a time, each turned into a rule and then into gstack itself:

• "yes merge when green" became the Captain's standing merge approval, and then merge trains: one paid gate covers up to five READY PRs, and the Captain merges them slot by slot at the exact head.
• "you can just run the failed test again and note that it is flaky and we should have a flaky test fix pass every day" became the one-rerun rule and a daily flaky pass automation.
• "for each plan approval i want a before/after, why it matters, what caused us to work on this, and big decisions you had to make" became gstack-owner-brief and the three approval shapes.
• "also we should really be using the gstack ship skill before merging PRs" became the SHIP_RECEIPT every READY must carry at its head.
• "When you make a new thread or take on new functionality can you remember to use gstack autoplan to make a plan for it and then eli5 for approval from me?" became Plan before build.
• "Gstack should be the actual holder of how to do things not one off Capy files" is why all of the above lives in this repository, not in anyone's Drive.

How Capy and gstack fit together

flowchart LR
  G[Garry] -->|one-word answers| C[Captain]
  C <-->|findings, priorities| P[Peer Captains]
  C -->|brief| L1[Lane: plan with /autoplan]
  C -->|brief| L2[Lane: build]
  C -->|brief| L3[Lane: fix wave]
  L1 -->|plain-English plan + rec| C
  L2 -->|/ship receipt, READY at head| C
  L3 -->|READY| C
  C -->|train: one gate, up to 5 PRs| T[(Gate)]
  T -->|green| M[(main)]
  T -.->|flake records| F[Daily flaky pass]

Captains, crews and lanes. A Captain is a long-running Capy thread that owns one repository's flow. It starts crew threads (lanes), each on its own machine and branch with named files, so no two lanes edit the same file. The Captain's Drive holds the crew's contract (CREW.md), its digest, and each lane's report; every rule in it points back at a gstack doc. Lanes never ask Garry directly. Everything goes through the Captain, which asks in plain words and brings back his exact reply.

Plan first, with a plain-language yes. New functionality starts with /autoplan: a CEO review, an engineering review, design and DX when the work has them, each with a native and a cross-model voice. The gate goes to Garry as a short plain-English summary with "rec" as the default answer and a "do it" option that takes every recommendation at full scope. One "do it" has approved eight plans in a morning, and the lanes built them in parallel. Reviews catch the expensive mistakes before code exists. One plan learned that 12 tasks were too few to prove anything, and another that its adapter needed a translator nobody had planned.

/ship before READY, merge on green. A lane runs /ship at its final pushed head. That runs the tests, a review sized to the diff, a cross-model voice where it matters, and writes a receipt bound to that head. The lane sends one unstamped READY and stops. The Captain batches READY PRs into a train, reads one full gate, stamps versions at merge, and merges each PR with --match-head-commit, so nothing lands at a head nobody reviewed. A review finding blocks only when it "would fail a test, break production, or lose data or secrets" (Garry's floor); the rest goes in the PR body.

Fix waves. When main goes red, lanes hold /ship, one owner finds the root cause, and everyone merges main once. Deferred review findings and test-only follow-ups get folded into one wave PR instead of one PR each. On one crew a single audit-pin fix cleared a main-wide red and ten PRs landed within the hour.

The daily flaky pass. A red test is rerun once at the same tree. A pass is logged as flaky and the PR moves on; a second red is real. Every morning an automation starts a lane that fixes the worst repeat offender with a PR that shows it red before green. Nothing is retried into green and no threshold moves.

Peer Captains route findings, not chatter. Captains message each other with evidence. gstack-evals' replay showed /review downgrading real bugs, and within the hour gstack had a lane on it. Another eval Captain's $5.78 panel found that OpenClaw refused to load a 78 KB gstack skill, and gstack had a fix up the same day (#3610). When Garry said "hurry up" to one Captain, another reordered its merge queue for it and sent back each merge commit.

Evals with preregistered bars. A prompt or skill change that claims to help is judged by a before/after with fixed trials and a bar written down before the first paid call (/eval-plan), never by gut feel. Good evals here have a no-skill arm and a length-matched placebo, a check that the treatment actually arrived, decoys verified clean, and spend quoted from the meter. They report losses as plainly as wins. One preregistered eval found that with the skill loaded every time, gstack still lost to the placebo on a cheap model, and that result now drives gstack's work on its review rubric. In gbrain, a facts block won by 16 points on a held-out set, and only then did it go on by default.

Why we think it is the best software factory

• The owner decides, and only decides. Garry's job is one-word answers to plain-language questions. Everything that a command, a measurement or a test can settle gets settled before it reaches him.
• Main stays green at volume. Receipts bound to the exact head, merges with --match-head-commit, trains that test the combination before it lands, and a backstop that freezes the queue on a red main.
• Every rule is code. The rules live in gstack: bins that refuse a stale receipt, tests that cap prompt sizes, a ship policy file. A new crew inherits them by installing gstack, not by reading someone's notes.
• It measures itself. gstack-factory-scorecard reports lead time, gate cost, red-train rate and flaky events every week against industry benchmarks (DORA), and says unavailable instead of 0 when it can't read something.
• It is honest about cost. Paid gates are cheap relative to a broken main ("it's fine run as many $93 paid gates as you want who cares"), but token spend per PR is tracked, capped and treated as a bug when it grows.

Tips and tricks

1. Install gstack on every machine, every session. The first act of every thread and subagent is the install check; no gstack: ok line means no gstack workflow on that machine.
2. Always offer a "do it". Garry takes recommendations. Make the recommended reply the one-word default, and never offer "the plan as first written" as the safe choice.
3. Ask "worth it?" before three review rounds. A plan the owner may shelve gets a cheap check first. A deploy replay that measured 83 seconds of boot cost killed a plan three review rounds had blessed.
4. Assign versions at merge, not in the PR. Version and CHANGELOG collisions were the second-biggest time sink until READY went unstamped.
5. Don't merge main every time it moves. Each merge recreates the CHANGELOG conflict and voids the receipt. Merge once, at your slot.
6. Size review to the diff. A docs PR doesn't need a red team. Full-depth review on small diffs is how /ship once cost about 50M tokens per PR that needed the full test gate.
7. Keep threads small. A long-lived parent context reached 1.36B tokens. Hand long steps to fresh children and read the token counter instead of estimating.
8. Use background operations, not watcher subagents, and message only on a decision, a blocker, a READY or a finished phase. Most Captain wakes used to be "nothing to report".
9. Measure before you choose. Time the queue, count the PRs, run the real system. A runner option that looked cheaper in quiet hours failed in a busy one.
10. Severe fixes go first, through the same gates. In gbrain a trust-escalation bug went from report to merged fix in about three hours, with its receipt, green checks and merge owner unchanged.

How Garry uses it

• He answers in one word, from his phone. "rec", "do it", "Take all recommendations". Long answers mean the ask was badly shaped.
• He asks for explanations, not jargon. "Eli5 these recommendations and please note in the future you need to explain." Gate codes and slot numbers never reach him.
• He wants to see what changed. Every merge ask shows before/after images of what changed and why.
• He spends money to save time and tokens to save money. Paid gates are pre-approved; token waste is a P-1 ("Can we get 95% of the outcome but with 50% of the token use?").
• He pushes for parallelism. "Make sure we are parallelizing as much as we can that is practical to do": five to eight lanes on disjoint files whenever there is a backlog.
• He turns every annoyance into a rule, and every rule into gstack. "are you learning that the ship review loop is too overzealous?" became the blocking floor the same day.
• He asks the factory to improve itself. "Ask all captains for feedback on how fast or slow things are and if we can maintain quality but go faster", then "Can you fix GStack to incorporate the feedback". This page came from the same kind of ask.

Where to go next

• docs/recommended-harness.md: set it up, day 0 to the first merged train.
• docs/captain.md: the controller's reference (READY contract, trains, approvals, digest, flaky pass).
• capy/skill/gstack/: the Capy skill every thread loads, its factory.md one-page summary of how crews work, and its captain.md for lanes.
• docs/why-gstack.md: the longer story behind gstack itself.

---

1. Windows are UTC, [2026-10-01, 2026-10-15) before and [2026-10-15, 2026-10-29) after. Merged PRs are GitHub's mergedAt with base main (gh pr list --state merged --limit 1000 --search 'merged:2026-10-15..2026-10-28 base:main' returns 197; the same query for 10-01..10-14 returns 65). Versions are distinct new values of VERSION on main's first-parent history. The March comparison is the busiest 14-day window between 2026-03-01 and 2026-09-15. Issue-to-fix time links issues to PRs through GitHub's closing references and "fixes #n" lines; the before window's median (35.9 days) is left out because those PRs were clearing an old backlog. The eight-repository total covers gstack, gbrain, gbrain-evals and alphaclaw plus four private repositories, which merged 1,243 of the 1,874 PRs and were created during the window, so it is volume, not a speedup. Capy threads were already writing most gstack PRs before the window (57 of the 65), so this measures the step to Captains, merge trains and /ship before READY, not Capy against no agents. Measured 2026-10-29. ↩︎