ADR-165: Loop-control bookends: start, develop, merge, release, wrap¶
Summary¶
- Decided: Five skills that the operator invokes, each paired with a way, carry work through a session:
/startopens it,/developcarries the loop,/mergelands an increment,/releasepublishes a release, and/wrapcloses the session./startand/wrapboth read the context gauge,ways context:/startadvises against starting late in a session, and/wrapscales the handoff to what the session is about to lose. Planning happens inside/start, because Claude Code reserves plan mode./developpicks the order of the early stages by where the uncertainty lies, then hands off to the existing stage skills and the code-reviewer subagent instead of reimplementing them.shipsplits into/mergeand/release./mergepicks its review path from two questions: how deep the machine review must be, and whether a human must approve. - Trades away: Every reference to
shipacross ways, skills and the skills catalog has to move tomergeorrelease. Five coordinated pieces are more to keep consistent than one skill. Enrichingship, a/developthat runs every stage itself, a separate/planskill, and a naming metaphor were rejected. - One-way? No. The record does not discuss reversal. The change adds skills and ways and renames one skill, all as text in the corpus.
- Probes: Not confident (start-dissuade): Should
/startadvise against starting when the session is well under way? Yes or no. Not confident (merge-gate): Should/mergepick the review path itself and ask you only when the case is unclear? Yes or no. - Inversion: At one end, the operator types each stage request by hand every time. At the other, one orchestrator skill runs every stage itself. This sits between them: named skills open, carry and close the loop, and each hands the stage work to the skills and ways that already exist.
Context¶
The project already teaches every stage of software work as a way — design, prototype, ADR, plan, build, PR, review, merge, docs, release each disclose themselves when triggered. What it has never named is the loop that carries a piece of work through those stages, or the ritual of opening and closing a working session around it.
Two concrete pains motivated this:
-
The tail is retyped every session. Outside a
/goalloop, the operator hand-types variations of "run a code review on this, fix the findings, and merge" many times a day. The doctrine for that tail already exists (the deliver workflow inmeta/workflows, the review-before-merge default indelivery/github) but there was no single named invocation for it. -
There is a closing bookend but no opening one.
wrap(skill +meta/wrapway) is a fully-realized terminal ritual: it squares the TaskList, writes a continuation prompt, and hands the operator a directed/compact. Nothing symmetric exists at the start of a session — orienting to where work was left off, framing intent, and warming context before planning.
Underneath both is a shift already recorded in core.md: the method is no longer
"ADR-driven development." Prose states claims; claims are held to the evidence
the running system produces; "the ledger is not the whole method." An ADR is one
stage among several, and the order of the early stages is not fixed —
design-first, prototype-first, and adr-first are all valid openings depending on
where the uncertainty lives (core.md's uncertainty-location map). The loop
has a variable front and a stable tail, and no way named that.
Decision¶
Introduce a five-verb loop-control family, each an operator-invocable skill with a corresponding way (the way is the when/why, the skill is the how — ADR-138):
| Skill | Role | Way |
|---|---|---|
/start |
Open the session — orient to prior state, greenfield interview, gauge-guard, warm context, then recommend planning | meta/start (new) |
/develop |
Carry the core loop; pick the loop shape (variable front / stable tail) and borrow the stage skills | meta/develop (new) |
/merge |
Land an increment — the four-square review gate → merge → cleanup | delivery/merge (new) |
/release |
Publish a release — version, changelog, artifacts | delivery/release (exists) |
/wrap |
Close the session → hand to a new one | meta/wrap (exists) |
Five load-bearing choices:
-
/startand/wrapare inverse gauge-aware bookends. Both read the same instrument (ways context).wrapchecks the session is near its end and scales the handoff to how much is about to be lost;startchecks the session is near its beginning and dissuades starting if it is not — starting is a beginning-of-session act. Same instrument, opposite pole. -
Planning lives inside
/start, not as a/planskill. Claude Code reserves plan mode; we do not claim that verb./startgathers state first, so when it recommends planning the context is already warm — plan mode inherits an oriented situation instead of a blank one. Likewrapand/compact,/startcannot itself invoke plan mode (skills/hooks cannot fire/commands); it prepares the ground and hands the operator the trigger. -
/developis a borrowing-router, not an orchestrator. It establishes the loop, selects the front order by where the uncertainty lives, lays the TaskList, then delegates to the reviewer (thecode-reviewersubagent),/merge, and/release, and lets the existing stage ways disclose. It does not reimplement what those already teach. (The monolithic-orchestrator reading was considered and rejected — see Alternatives.) -
shipsplits intomerge+release. "Ship" carried release-weight — version bumps, changelogs, artifacts — which made it the wrong name for the daily act of landing an increment./mergeis the light, high-frequency tail (branch → commit → PR → review-gate → merge → cleanup, minus publish);/releaseis the occasional heavy publish (ship's former Publish step). The daily retype now maps to/merge. -
The review gate is a four-square, not a single policy.
/mergeclassifies the work on two axes and picks the path, surfacing the call when ambiguous:
| machine review: light | machine review: deep / swarm | |
|---|---|---|
| human gate: none | run it — quick review → auto-merge | swarm review + adversarial verify → agent-gated merge |
| human gate: required | single-agent review → offer to read before merge | swarm review and operator approval before merge |
The X axis is driven by complexity / blast-radius; the Y axis by whether the work sets direction (e.g. an ADR) and whether the operator has already read it.
Skill ↔ way coverage¶
Most stages are already covered because /develop borrows them. New authoring is
concentrated in four places: meta/start, meta/develop (the variable-front /
stable-tail selector — the corpus's largest prior gap), delivery/merge (the
four-square + the previously-partial "fix/remediate per finding" coverage), and the
rename ripple through references to ship.
Consequences¶
Positive¶
- The daily "review, fix, merge" retype collapses to
/merge. - The session gains a symmetric opening ritual;
/startwarms context so planning starts oriented. - The loop's variable-front / stable-tail shape is named and disclosed for the first time, grounded in the claim→evidence method.
mergeandreleaseeach become honestly-scoped; neither overloads the other.
Negative¶
- A rename ripple: references to
shipacross ways, skills, and the skills catalog must all move tomerge/release. - Five coordinated surfaces (two new skills, one rename, one split, a hook, and new/revised ways) are more moving parts to keep coherent than a single skill.
Neutral¶
/reviewand/code-review(built-in review skills) are unchanged; the merge gate borrows thecode-reviewersubagent for its automated review.- Composes with
/goal: the manual/mergegate is the single-shot form of what a goal loop automates, mirroring thewrap/compaction-checkpointduality.
Alternatives Considered¶
- Fold the tail into
ship/ enrichship. Rejected: "ship" reads as release-weight, and the operator's daily act is iteration, not publishing. /developas a monolithic orchestrator that runs every stage itself. Rejected: it would duplicate the stage ways and violate the borrow-don't-recreate posture; the mode-setter + shape-selector reading keeps it thin.- A standalone
/planskill. Rejected: Claude Code reserves plan mode; planning folds into/startas an optional, context-warmed branch. - A dedicated non-agile naming metaphor (film: action/take/wrap; compiler; systems). Explored at length; the plain SE verbs (start/develop/merge/release) won for being literal, low-fatigue, and already the words for the acts.