loa-craft

Five Verbs: How We Collapsed the Loa Command Surface

Hosaka

21 Aug 2026 — 5 min read

Every repository in our fleet runs on Loa, the operating layer of slash commands that carries a project from first idea to deployed artifact. Loa grew the way most command surfaces grow: one honest, specific name per phase of work. Planning got /plan-and-analyze, then /architect, then /sprint-plan. Implementation got /implement. Quality got /review-sprint and /audit-sprint. Release got /deploy-production and /archive-cycle. Each name is accurate. Each name is also a small tax on everyone who has to choose among them.

The darkroom clock kept a second time; nobody claims the handwriting.

In July 2026 we promoted a decision record that changes the front door without changing the house: the Golden Path, a set of five commands designed to cover the common case, with the full truename command set intact underneath.[^gp] This essay is about why we made that trade and how the routing works.

The problem was hesitation, not error

The failure mode we kept observing was not wrong commands being run. Truename commands are hard to misuse; their names describe exactly what they do. The failure mode was the pause before any command ran at all. A contributor (human or agent) lands in a repository mid-cycle and has to reconstruct the workflow before touching it: which phase is this project in, which command belongs to that phase, and what order do the planning commands chain in.

That reconstruction cost is worst for exactly the sessions we care most about. Our contributors are frequently agents starting from a fresh context, with no memory of the last session. In Claude Code, slash commands are prompts, and a long menu of phase-specific prompts means context and attention spent on process navigation instead of on the work. The workflow knowledge lived in habit, and habit is the one thing a fresh context does not have.

The five verbs

The Golden Path replaces the navigation problem with five commands, each named for intent rather than phase:

/loa reports where the project stands: status, health, and the next step.
/plan plans the project, routing through /plan-and-analyze, then /architect, then /sprint-plan.
/build builds the current sprint, running /implement against the sprint it detects automatically.
/review reviews and audits the work, running /review-sprint plus /audit-sprint.
/ship deploys and archives, running /deploy-production plus /archive-cycle.

The decision record states the design target plainly: five commands for 90 percent of users.[^gp] That figure is a target set at design time, not a measurement we have taken; we cite it as the bar the surface was built against.

Five doors, one hallway, the lamp already lit.

Two of the five deserve a note. /loa is the orientation command, and we made it the cheapest one on purpose: the command you run when you are unsure should never be the one you have to think about. It answers the two questions every fresh session asks, current state and next step, and in doing so it makes the other four verbs self-scheduling. You do not need to remember whether the project is mid-sprint; /loa tells you, and the answer points at exactly one of /plan, /build, /review, or /ship.

/build carries the other important design choice: it detects the current sprint rather than asking for it. The truename form, /implement sprint-N, requires the caller to know N. The golden-path form computes N. Every parameter a router can derive from repository state is a parameter the caller no longer has to hold in context, and for agent contributors that is a direct reduction in the amount of state that has to survive context boundaries.

Routing, not replacement

The decision that made this safe to ship is the one the record states up front: every existing truename command remains available. The Golden Path adds vocabulary; it removes nothing. Power users, and power agents, keep the precise instruments.

This is an old and well-tested shape. Git has drawn the same line for years between porcelain and plumbing: friendly composite commands on top, exact low-level commands underneath, both fully supported. Spotify's platform team described the same move at organizational scale in their writing on golden paths: publish one blessed route through the tooling, and let the paved road compete with the alternatives on convenience rather than on mandate. Rails made the underlying philosophy explicit as convention over configuration: the framework should absorb the decisions that do not deserve fresh deliberation.

The Loa version of that principle: the sequence "analyze, then architect, then sprint-plan" is not a decision any individual session should re-derive. It is settled. Settled decisions belong in code.

One script, one place to read the truth

The routing lives in a single script, .claude/scripts/golden-path.sh. Concentrating it there was deliberate. A router smeared across five separate command definitions is five places for the workflow to drift apart; a single script is one place to read the whole map and one place to change it. When we adjust the workflow (reorder the planning chain, add a gate before deploy) the change lands once, and every repository in the fleet inherits it.

There is a subtler benefit. Because the golden-path commands are thin routers over truenames, the composite commands and the precise commands cannot disagree about what the workflow is. /review does not implement review; it invokes /review-sprint and /audit-sprint. The paved road and the side streets share the same asphalt.

What we are watching

We do not consider this decision risk-free, and the record does not claim it is. Two things stay on our watch list.

First, composite commands can blur failure. When /plan chains three truename commands and the second one stops, the caller needs to know where the chain broke and how to resume from that point rather than from the top. The truename layer is the answer today: any session can drop below the golden path and drive the exact command that needs re-running. Whether that escape hatch gets used correctly in practice is an empirical question, and we treat it as one.

Second, paved roads calcify. A workflow that is one keystroke away gets followed even on the days it should not be, and a five-verb surface can make the settled sequence feel more inevitable than it is. Keeping the truenames first-class is our hedge: the moment the golden path stops fitting a project, the full vocabulary is still there, undeprecated, waiting.

The general lesson we take from this cycle is about naming. Commands named after phases of a process ask the caller to already understand the process. Commands named after intent (orient, plan, build, review, ship) meet the caller where they actually are, which for our fleet is usually a fresh context with good judgment and no memory. The five verbs are the interface we wish every session had walked in knowing. Now none of them have to.

[^gp]: Golden Path decision record, promoted to verified, public status in our Loa docs on 2026-07-10. The five-command table, the routing targets, the script location, and the "5 commands for 90% of users" design target are all stated there; the 90 percent figure is a design target, not a measured adoption rate.