From 2e7c80eeca2c4af6af201f73d586d8b2b5ee0b26 Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 29 Oct 2026 19:39:12 +0000 Subject: [PATCH] docs(capy): capy/README.md, the gstack + Capy software factory: how it fits, measured before/after, tips, how Garry uses it Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- README.md | 1 + capy/README.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/captain.md | 4 +- 3 files changed, 232 insertions(+), 1 deletion(-) create mode 100644 capy/README.md diff --git a/README.md b/README.md index 222b96893..5a3cd01a0 100644 --- a/README.md +++ b/README.md @@ -242,6 +242,7 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file |-----|---------------| | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) | | [The recommended harness](docs/recommended-harness.md) | gstack + Capy from zero to the first merged train: install, the Captain and its Drive, trains, the daily flaky pass, the twice-weekly release, the factory scorecard, what is Capy-specific, known Capy limits | +| [gstack + Capy: the software factory](capy/README.md) | What we built with Capy Captains and gstack, how the pieces fit, the measured before/after, tips, and how Garry uses it | | [Why gstack](docs/why-gstack.md) | The story, the productivity numbers and their caveats, Karpathy's failure modes, parallel sprints | | [Install details](docs/install.md) | Setup timing, requirements in detail, team mode, the hooks setup registers, agent harness registration | | [Other agents](docs/hosts.md) | Agent harnesses (OpenClaw, Hermes, dots, QM, Muse Code, Grok, any other), OpenClaw and ClawHub, per-host notes, the Codex profile and model tiers, outside-review providers, the design binary's models | diff --git a/capy/README.md b/capy/README.md new file mode 100644 index 000000000..6a9e4cc28 --- /dev/null +++ b/capy/README.md @@ -0,0 +1,228 @@ +# 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](../docs/recommended-harness.md); the controller's +reference is [docs/captain.md](../docs/captain.md). + +## The numbers + +The 14 days after the first Captain took over gstack (2026-10-15) against the +14 days before, measured from git and GitHub[^1]: + +- **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).** Every merged PR + ships as its own version. +- **Twice gstack's best fortnight before Capy.** The March launch shipped 99 + versions in its busiest 14 days; this fortnight shipped 194. +- **36 PRs merged and 36 versions shipped in one day**, on October 25 and again + on October 26. +- **A reported bug 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 +started running gstack's own development through a Capy Captain, GStack +Minder, and gave it one standing job: keep `garrytan/gstack` moving and keep +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](../docs/captain.md#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](../docs/captain.md#the-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](../docs/captain.md#approvals-three-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](../docs/captain.md#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 + +```mermaid +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 -->|ELI5 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 ELI5 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; it +was a fix lane in gstack within the hour. Harness Evals' $5.78 panel found that +OpenClaw refused to load a 78 KB gstack skill; gstack fixed it the same +afternoon ([#3610](https://github.com/garrytan/gstack/pull/3610)). When Garry +said "hurry up" to one Captain, another reordered its merge queue for it and +sent back each merge sha. + +**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](../docs/skills.md)), never by vibes. +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. +Another showed a facts block winning 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 DORA-style bars, + 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. +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 jump the queue.** A trust-escalation bug went from report to + merged fix in about three hours; explain it afterwards. + +## 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](../docs/recommended-harness.md): set it up, day 0 to the first merged train. +- [docs/captain.md](../docs/captain.md): the controller's reference (READY contract, trains, approvals, digest, flaky pass). +- [capy/skill/gstack/](skill/gstack/): the Capy skill every thread loads, and its [captain.md](skill/gstack/captain.md) for lanes. +- [docs/why-gstack.md](../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 --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. diff --git a/docs/captain.md b/docs/captain.md index e955acfb7..b0e4fd841 100644 --- a/docs/captain.md +++ b/docs/captain.md @@ -8,7 +8,9 @@ controller the same model at run time is [`/captain`](skills.md#captain) (it als to `/crew`); the lane-side rules for a thread working under a Captain are in [`capy/skill/gstack/captain.md`](../capy/skill/gstack/captain.md) and [capy-install.md](capy-install.md#working-under-a-captain). Every file named below has a -copy-paste template under [`captain/templates/`](../captain/templates/). +copy-paste template under [`captain/templates/`](../captain/templates/). For the story of how +Garry's crews run this day to day, with measured numbers, read +[capy/README.md](../capy/README.md). ## The model in one paragraph