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

@@ -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 |

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.

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