Telling Technology · Learning in public
All episodes
EP.31 — ONE COMMAND
A Claude Code workflow, on screen

One command ships my whole workspace

My workspace is about ~20 repos — a dashboard, a design system, three parallel rewrites, a content engine, a pile of smaller tools. Releasing meant remembering which one needed what: run the tests here, rebuild a registry there, promote a staging build to production somewhere else, then commit and push each repo by hand. It was a checklist I kept in my head, and the head is where checklists go to rot. So I gave the whole thing one door: type /release, it plans first as a dry-run, then fans out across every repo in order — and hands me a receipt. This one's pure efficiency: same result, a fraction of the fiddling.

A single terminal command, /release, at the top of the screen with a teal glow, fanning out into a grid of ~20 anonymized repo tiles (repo-01 … repo-20). Each tile shows a tiny checklist of steps — verify, sync, push — most already ticked green, a couple mid-run. The layout reads as one command orchestrating a whole workspace at once.
⌁ one /release · ~20 repos · plan first, then --go
The old way was a checklist I kept in my head ↓
01 The old way

Twenty repos, twenty little rituals

Every repo shipped a slightly different way. One needed its test suite green first. One needed a dependency sync before anything else built. One had a registry that had to be rebuilt or the app booted stale. One lived as a staging build that a human had to promote to production and then eyeball for a green health check. And the flagship repo — the one that runs everything — I was terrified of pushing by accident. So a "release" was really twenty small rituals done in the right order from memory, one terminal tab at a time. Miss a step and you find out in production, on a Sunday.

claude code — desktop
> i need to release the whole workspace again. what's the order?
From memory: tests on repo-03, dep sync on repo-07, rebuild the registry on repo-11, promote repo-14 staging→prod and check health, then commit+push each of the other ~16 — and do not push the flagship. That's the part that keeps rotting in my head.
A messy, hand-annotated release checklist pinned over a wall of terminal tabs: 'run tests → repo-03', 'sync deps → repo-07', 'rebuild registry → repo-11', 'promote staging→prod → repo-14', 'commit+push × 16', and a red scrawled 'DON'T push flagship'. Several items crossed out, the ordering visibly fragile — the by-hand release ritual.
the by-hand ritual
Twenty repos, each with its own step — kept in my head, done one tab at a time
02 The one door

One orchestrator, in a fixed order

The fix is a plan-by-default orchestrator — one script, one command. /release runs the same pipeline every time, in the same order: a verify gate (tests, a secret scan, unit checks — --full adds lint + build) → a dependency sync on the design system and a registry rebuild → a generated release-state block written into every repo's summary → a link check → commit + push per repo → the staging build promoted to production with a health check → a summary sent to my phone. Plan is the default; nothing ships until I add --go. Then it fans out across the real repos — in order, no tabs, no memory.

release_all.py --go
> /release --go
verify ✓ tests · secret-scan · unit → sync ✓ design-system deps → registry ✓ rebuilt → state block ✓ written to 20 summaries → links ✓ → push ✓ 18 repos → promote ✓ staging→prod, health 200 → 📲 receipt sent. flagship skipped — needs an explicit flag.
A terminal mid-run showing /release --go fanning out: an ordered list of pipeline stages — verify, sync, registry rebuild, state block, link check, push, promote, notify — each with a green check or a spinner, and a per-repo column ticking through repo-01 to repo-18 with the flagship greyed out and marked 'skipped (needs --push-flagship)'.
--go · in order
The same pipeline every time — verify → sync → push → promote → notify
03 The safety net

Every step idempotent, so a crash isn't a redo

Fanning out across twenty repos means twenty things that can fail — a flaky test, a network blip on push number fourteen. So the run writes its progress to logs/release-state.json as it goes, and every step is idempotent: run it twice and it does nothing the second time. A failed run doesn't start over — /release --go reads the state file and picks up exactly where it left off, skipping the repos already done. And the flagship repo stays hard-gated behind its own flag, so the one repo that runs everything can never ship by accident. Fast because it's one command; safe because it assumes it'll be interrupted.

logs/release-state.json
> push failed on repo-14. do i have to start over?
No. release-state.json has repo-01…13 marked done. Re-run /release --go and it resumes at repo-14 — the finished repos are skipped, not re-pushed. Idempotent all the way down.
A JSON file, logs/release-state.json, on screen: a 'done' array listing repo-01 through repo-13 with timestamps and commit hashes, repo-14 marked 'failed: push timeout', and repo-15 onward 'pending'. A caption arrow shows a re-run resuming at repo-14 rather than starting over.
resumable state
The run journals every repo — a re-run resumes at the first unfinished one
🛑

The flagship repo is the one thing it won't ship on its own

Automating a release is great right up until it auto-pushes the repo that runs your whole system. So the flagship is hard-gated: the fan-out skips it unless I pass an explicit --push-flagship. One command ships nineteen repos happily; the twentieth always needs me to say it out loud. Convenience everywhere it's safe, friction exactly where it isn't.

04 The receipts

Plan, fan-out, state file, and the ping

The dry-run plan it shows before anything moves, the --go run fanning out across the repos, the state file that makes it resumable, and the summary that lands on my phone when it's done. Tap any image to enlarge it and read exactly what's on screen.

A /release dry-run plan listing the repos it would touch and the ordered pipeline steps, with a 'plan only — pass --go to execute' footer.
the plan
The /release --go run fanning out across repos, pipeline stages ticking green and the flagship skipped.
--go fan-out
The release-state.json file with a done array, one failed repo, and pending entries — the resumable journal.
resumable state
A Telegram summary message: '✅ Release complete — 18 repos pushed, staging→prod promoted, health 200, flagship gated', with a duration and timestamp.
the ping
ONE COMMAND, WHOLE WORKSPACE

Twenty repos, in order, with a receipt — while I make coffee

The release didn't get smarter; it got boring, which is the whole point. What used to be twenty tabs and a checklist in my head is now one command that plans, verifies, fans out in a fixed order, resumes itself if it trips, refuses to touch the one repo it shouldn't, and buzzes my phone when it's done. That's the last manual step in the loop quietly closing — not as a flex, just as time I don't spend babysitting terminals anymore.

A clean final frame: on the left a single terminal line '/release --go' with a green '✓ done' beneath it; on the right a phone showing the Telegram receipt — '✅ Release complete · 18 repos · staging→prod · health 200 · flagship gated · 3m 41s'. Calm, finished, aurora-teal.
workspace release · release_all.py · plan-by-default · resumable via release-state.json · 2026-07-12
06 Steal this

The plan-by-default release pattern, for free

If you juggle more than a couple of repos, the shape is worth stealing: one orchestrator, a fixed pipeline, plan by default, execute only on --go, a resumable state file, and a hard gate on the one repo you must never ship by accident. Everything in this episode is free and open — clone it, run it, make it yours.

script release_all.py cmd /release · /release --go state logs/release-state.json rule plan first · gate the flagship
the pattern # Plan by default, execute only on --go, resume from a state file: # /release → dry-run: list repos + ordered steps # /release --go → fan out (verify → sync → push → promote → notify), journal to release-state.json # /release --go → after a failure, resumes at the first unfinished repo (idempotent); flagship skipped unless --push-flagship
↧ soon

The cleaned-up release_all.py is being scrubbed of real repo names for release. Comment RELEASE on the post and the bot DMs you the moment it's public.

Next episode

Next: the one repo the release refuses to ship on its own

Nineteen repos fan out on one command; the twentieth — the flagship that runs the whole system — stays hard-gated behind an explicit flag. Next up: why the most-automated workspace still keeps one deliberate manual switch, and what it takes to earn the right to flip it.

A darkened preview hinting at the hard-gated flagship repo the release won't ship on its own.
drops soon · follow so you don't miss it