On this page

The Delivery Loop#

This page covers the mechanics. For why the loop works this way, see The Idea Behind the Loop.

Start with one item:

/devstride:build-item

build-item selects the next unblocked leaf, claims it when claims are configured, marks it In Progress, creates a branch, builds and reviews it, merges it through the configured path, updates the DevStride item, and stops after that iteration. Once you trust one pass, /loop /devstride:build-item repeats the process across the plan.

Status, comment, date, and link changes are live

The delivery loop updates your real DevStride organization. Git branches protect code changes; they do not delay roadmap writes.

The delivery profile#

Every iteration begins by resolving the plan’s delivery profile and announcing it with its source. The first match wins:

  1. a bare profile word — prototype, standard or extended — anywhere in the invoking skill’s arguments; build-item accepts one, as plan does;
  2. the Delivery profile: marker in the plan root’s description — a one-off has no plan root, so no marker;
  3. profile in .claude/ds-config.json;
  4. extended from 3.49.0 (standard before). A retired or unknown word, such as enterprise, still reads as standard, said out loud.

The profile sets how many readers the build engine fans out to understand the item, the widest adversarial review breadth it may choose, which verified findings are fixed in the item and which are dismissed with a rationale, how many rounds the local CLI reviewer gets at a merge boundary, the local gate an item must pass before it merges, and how long the loop waits for a cloud reviewer. The normal target of two adversarial cycles is the same under all three. Under extended only the size-shaped settings move — more understand readers (up to four) and a review breadth that may reach high-risk for a large diff — while the fix floor, the local gate, verification and review cycles are exactly standard’s. See Choose a delivery profile for the three profiles side by side.

Explicit configuration wins over the profile. epicIntegrationBranches.autoRelease, epicIntegrationBranches.fastStoryMerges.enabled and review.pollTimeoutMinutes stand whenever they are present in the file; the profile supplies a value only when the key is absent. A contradiction is honored and reported, never silently resolved.

The three review.* CI-ordering flags work differently: they describe what your workflows support — a draft hold, and a ready flip that releases CI — rather than a per-run choice. Review first and CI last is a floor under every profile, prototype included: where the workflows support the hold, every profile uses it. A repository that cannot prove the hold is reported as a setup blocker rather than quietly running CI alongside review.

review.localCommand is different: it names the local CLI reviewer, it does not schedule it. When present, that engine reviews every release pull request and every pull-request-path item under every profile. It never reviews an epic story that fast-merges with no pull request, under any profile, prototype included. The one fast-merged item it does review is a one-off above the small-fix limit, which gets a full local review before it lands on the release train (see One-offs on the release train). The profile decides only how many rounds it gets at those boundaries: one under every profile; profileOverrides.maxLocalReviewRounds raises it. null removes it everywhere.

review.localAssistCommand is support rather than a review round. When configured, the build engine may consult it once, read-only, for an ambiguous cross-module design, a critical contract, or a stubborn diagnosis. It does not write, does not satisfy the merge review, and does not run on routine work.

First understand the paths#

Situation Working base Item pull request? Later release
Planned leaf under a release unit; release-unit branches and fast merges enabled The release unit’s integration branch No. Local review, local checks, local merge. One full-diff release pull request carries the completed unit to epicIntegrationBranches.releaseTarget (under plan scope, to the plan’s integration branch).
Planned leaf under a release unit; fast merges disabled The release unit’s integration branch Yes, targeting that integration branch. The completed unit still gets its release pull request.
Release-unit branches disabled, or no release-unit ancestor baseBranch Yes, targeting baseBranch. No separate release-unit branch path for that item.
One-off, release train configured (releaseTrain.branch, and release.mergeTrainBeforeCut: true) The release train No when releaseTrain.fastMerges is true: local checks and a local merge onto the train. With releaseTrain.smallFixes set, a small fix relies on its build-time risk check and a larger one first gets a full local review on your machine (see One-offs on the release train). Otherwise yes, targeting the train. The train's pull request into baseBranch, which release opens and fully reviews before every cut. The item moves to the merged status when it lands and is Done only when the train reaches baseBranch.
One-off with no release train, or one whose change touches release.releaseBranchFixExclusions (deploy configuration, migrations) baseBranch Yes, targeting baseBranch. None. The item pull request is its full release gate.

A one-off may be filed under a release unit, so the skill does not infer its path from ancestry. It detects the one-off from the leaf type, title numbering, and dependency relationships, then explicitly bypasses release-unit branch derivation: a one-off never lands on an epic's branch.

Why a train: every merge into the base branch pays for its own CI run and, in many repositories, a deploy. One-offs that batch on the train get one full review and one CI pass at release time — the same bargain as an epic's release pull request — and the train ships with every release, so nothing waits longer than the next cut. A one-off that touches deploy configuration or migrations never rides it, because the train reaches production soon after it merges; such a change deserves its own pull request, its own CI and an earlier deploy to a development stage. The exclusion is checked against the spec when the item starts and again on the real diff just before anything merges onto the train, since a review fix can add such a file. A reviewed release unit is different (from 3.22.0): an epic that joins the train through its own fully reviewed release pull request may carry migrations and deploy configuration, because a pull request reviewed them. From 3.39.0 the release accepts that only with proof — the devstride/reviewed status the review leaves on GitHub (see Proof that a review settled) — never on a branch name alone; with release.devDeployVerification set, the release also waits for the development deploy before it merges to production.

Selection and branch choice#

Empty arguments mean “next.” You can also name a leaf, say next under I1234, or pass a parent item number by itself to scope selection under that plan.

The next item is the highest-priority open leaf whose blockers are Done, inside the earliest-dated open parent item. A blocker in the same release unit also counts once it has landed, meaning the unit's integration branch shows its merge in its git history (the merged status alone never counts, since a column of that name often holds an open code review); a blocker in another release unit counts only when Done, so the next unit waits until the previous one ships — except under plan scope (below), where a blocker landed on the plan's integration branch counts for every epic of that plan. Two units each waiting on the other are reported as a release-unit cycle, naming the edge to repoint, rather than as plain "blocked". Items in the plan's deferred container are never selected automatically; one you name by number is still built, as a one-off. With a claims block, a candidate another live agent holds is skipped (see Claims and session presence). Naming a leaf by number skips this selection, never the check that it is not already Done or landed: such a leaf is reported where it stands, not built again. Relationships are fetched explicitly because normal summary projections omit them.

Where work lands#

The working-base precedence is:

  1. an explicit branch override (refused when it names the production branch, the release source, a protected branch or a release branch, or does not exist on origin), else a non-null integrationBranch;
  2. for planned work, the nearest release-unit ancestor’s integration branch when epicIntegrationBranches.enabled is true;
  3. for a one-off, the release train when releaseTrain.branch is set and releases merge it (release.mergeTrainBeforeCut), unless its change touches the fix-exclusion paths;
  4. baseBranch.

The release-unit ancestor is found by walking the entire parent chain and fetching each ancestor’s work type. The integration branch is created from a fresh base branch on the unit’s first item and then reused; its date is the creation date, not the current date. When no branch matches the configured pattern but one on origin carries the epic’s number under an older naming, the loop stops and asks rather than cutting a second integration branch for the same epic.

A renamed train is never created beside the old one (from 3.31.0). When the configured releaseTrain.branch is not on origin but exactly one other train/* branch is, one-offs keep riding that branch and the loop names the rename and the commands that cut it over; with several, it asks which one is live. A release stops and names the rename rather than releasing without the train.

Plan scope (from 3.30.0) is opt-in per plan. A plan root whose description carries the line Release scope: plan releases as one unit: each finished epic's release pull request goes onto a plan integration branch (planIntegrationBranches.pattern) instead of the train or base branch, new epic branches are cut from that plan branch once it exists, and when nothing outside the deferred container remains, one pull request takes the whole plan to epicIntegrationBranches.releaseTarget. Each epic still gets its one full review, on its pull request onto the plan branch; its stories become Done only with the plan's release. When the plan branch is more than a week old or carries a migration or deploy configuration, the loop asks you once whether to release the plan early, and never does so unasked. Plans without the line behave as described everywhere else on this page, and a one-off under such a plan still rides the train.

The precedence is code, not prose. From 3.9.0 one dependency-free helper, skills/build-item/scripts/routing.py, decides where an item lands and names its branches — JSON in, JSON out — and build-item follows its answer: target for an item's working base, release-target and epic-base for where a release unit goes and what it is cut from, small for the small-fix rule and excluded for the fix-exclusion check. Codex, a script or a person can run the same file and get the same answer. routing-fixtures.json beside it holds the canonical examples, so a repository that implements the rule in its own tooling can test that tooling against them and fail when the two drift; the DevStride repository’s ds work command is held to them that way. Why: the rule used to live only in skill prose, and every agent that re-derived it was a chance to land work on the wrong branch.

The same pattern now covers the other decisions a person or another tool might need to reproduce exactly. Four more dependency-free Python files in skills/build-item/scripts/ each have canonical fixtures beside them: item-status.py (which status and comment an item gets at start and landing, from 3.32.0), review-gate.py (whether a one-off may land on the train, from 3.35.0), release-holds.py (whether held work may ship, from 3.36.0) and consequence-notices.py (whether a consequence notice is posted, and what it says, from 3.41.0). A fifth, skills/pr/scripts/merge-gate.py (whether a pull request may merge, from 3.38.0), reads GitHub to decide and is tested in the plugin's own test suite rather than by fixtures beside it.

What one iteration does#

  1. Establish ground truth, then select, validate and claim. When pool.checkout is set, lease a checkout once per run and keep it across items. Fetch from origin first, read what other authors landed on the working base since the last handoff, and say so when another session appears active. Then show the ready set, check for human or infrastructure gates, and compare the item’s full spec with the current code. With a claims block, claim the chosen item before anything moves it. With an activeAgents block, the plan root is placed on your Active Agents board once per run and your start command runs; end runs at every exit. Only a plan ever goes on that board. With board placement rules (from 3.62.0), the item and its release unit are then put on the board the rules name, before the item's status moves; an item someone already put on another board stays there, and a board that cannot be found is one line in the progress table, never a stop.
  2. Move to In Progress. This is a live DevStride update, decided by item-status.py and read back before branching.
  3. Create the item branch. branch-feature stops on a dirty tree and branches from the resolved working base.
  4. Build and adversarially review. ultracode-build understands the contract, implements in small green commits, and runs a mandatory maximum-effort Claude review whose breadth scales with risk, up to the profile’s ceiling. Security is always forced on a diff touching the authentication boundary, and from 3.4.0 any lens the repository declares in review.mandatoryLenses is forced the same way whenever the diff touches its paths — one focused finder each, in the story risk check and again at the merge-boundary review, which no profile or breadth ceiling removes. See Mandatory review lenses.
  5. Settle the configured delivery path, then merge through the guards. Either local fast review and merge, or a pull request through pr and review. Before any merge onto the release train or baseBranch, a release hold on the item or an ancestor stops the merge and the branch waits. Just before every merge the loop runs the consequence check, and a pull-request merge goes through the merge gate.
  6. Complete the item. item-status.py decides the move. Only an item whose own pull request reached the base branch is Done. An item merged anywhere else has landed but is not Done: it moves to the merged status (epicIntegrationBranches.mergedStatusName, Review by default) with a comment naming the merge. A story on a release unit's integration branch becomes Done when the unit's release pull request merges; a one-off on the release train (merged status from 3.32.0) becomes Done when the release carries the train into the base branch. The loop never moves an item out of a done-type status. Then set the branch-to-merge date window (a one-off on the train gets only its start date), link the pull request or record the fast-merge commit, record any material difference between the planned and shipped spec, and release the item's claim with outcome done.
  7. Track discoveries. New scope with no existing home becomes an inserted Story instead of disappearing into pull-request prose, and a review finding worth filing (a P1, a security finding, or one both likely to happen and material) that is deliberately put off goes into the plan's deferred container — a Defect for a bug, a Story for any other follow-up. Any other finding is dismissed with a one-line reason in the pull request or merge commit, and nothing is filed.
  8. Sync and count down the release unit. A clean working base and the count of leaves neither Done nor landed become the handoff for the next iteration. The deferred container counts toward neither; when a plan reaches zero, the report lists what is Still open in Deferred. The checkout lease is returned only at a terminal exit or a hand-over.
  9. Release the completed unit when allowed. Automatic cut and merge happens only when epicIntegrationBranches.autoRelease is true, and never while a release hold sits on the unit, an ancestor or any leaf it carries. When the release pull request merges, the release unit is closed out first (a comment naming the pull request, and Done where it tracks a status), then every landed leaf is marked Done with a comment linking it; their dates stay those of their merge onto the unit's branch. Under plan scope the close-out only comments, and Done waits for the plan's release. When nobody closes it out (an owner merged the release by hand, or a run stopped right after the merge), the next /devstride:build-item <root> does it before choosing what to build. Setup writes it false for the standard and extended profiles, so a newly configured repository stops at release-ready for an owner; for prototype it writes true and says so.

The skill renders its own numbered progress table as it moves. The skill file states a goal, the rules that must hold and its hard floors, and names its steps 0–8 with a 6.5 so the progress table and other skills can refer to them; the list above is a reader-oriented summary, not those internal labels.

Verification names its path#

From 1.2.0, a review verdict that rests on having looked — a browser, a running service, a manual run — reports "verified X via path Y", never a bare "verified". Behavioural states are usually reachable by more than one route, and a fix confirmed on one of them proves nothing about the others, so the verdict lists the routes to the same state and says which were and were not exercised. A reviewer later finding an untried path is the process working. The engine also asserts what it measures — scoping checks to the live container rather than a stale one — and rules out an expired session or a service that is not running before reading code.

Ground truth before the loop acts#

From 3.3.0, the first act of build-item and of release is git fetch --prune origin, followed by a read of what other people — and other sessions of yours — landed on the branches the run will touch. A branch push by another author, an open pull request that is not yours, or a merge you did not make is evidence that another session is active, and the loop says so explicitly before touching that branch. Every fact carried in from a memory handoff — the integration branch, the last item that shipped, "nothing else has landed" — is treated as a claim to verify against origin or gh before it is acted on; when the two disagree, the remote wins. A checkout can be current while the conversation is not, which is why this is a step at the start of every iteration rather than something the branch step happens to do later. A repository can also opt in to a bounded fetch at every session start with localEnvironment.fetchOnSessionStart; it shortens the window but does not replace the step. Rationale: skills/build-item/references/ground-truth-at-start.md in the plugin repository.

Human-facing output#

Two rules apply to everything the loop says to you. A claim about repository or delivery state — merged, published, CI green, "nothing else has landed", another session active — is read from origin, gh, or the live target at the moment it is made, never from the local checkout, a summary, or memory; a claim that cannot be backed that way is labelled unverified wherever it is repeated. And every handoff, plan, or reviewer prompt ends with two explicit lists, steps the loop does and steps you must do yourself — a login, an approval, a dashboard check, a command only you can run — with an empty second list saying nothing required from you.

Coordination and guards around every merge#

Claims and session presence#

With a claims block (from 3.21.0), two agents on two machines never build the same story. build-item claims the chosen story before it moves to In Progress and renews the claim at each step and build phase. A story another live agent holds is skipped for the next candidate; one you named, or the one a session resumes, stops instead and names the holder's machine and session and since when. An expired claim is taken over. Completion releases the claim with outcome done; a stop releases nothing, so the claim expires on its own (240 minutes for a story by default) and a person can resume within that window. When claims are unavailable — no claim tools on the server, a key without permission, or DevStride unreachable — the loop carries on without them and says so once. Hotfixes never claim. From 3.43.0 every claim names its machine and session the same way, from one helper, so a fleet view reads one spelling. See Story claims for the keys.

A claim only shows sessions that hold one. Session presence (from 3.42.0) closes that gap: name a command in presence.command and the plugin's hooks report every running session through it — at start, on prompts, when a turn finishes and Claude waits for you, every presence.intervalMinutes (default 5) while the session's process lives, and at the end, including when the process is killed or crashes. Each report carries the event, a state (starting, working, waiting, ended), the session, machine, checkout, branch and the item number the branch carries. From 3.44.0 it also carries when the session last did anything (PRESENCE_ACTIVE_AT), so a hung session can be told from a busy one. Presence is display only — claims decide who acts. From 4.0.0, where no command is named (no presence block, or one with only intervalMinutes), the plugin's built-in reporter sends every session to DevStride's Agent Fleet itself, once a minute by default, on any machine whose DevStride connection carries an API key. It sends a short fixed list (the session's id and name, the machine's name, the branch, the checkout folder's name, an item number the branch names, the plugin version and the event), never session text, a prompt, a file or a path. A named command always wins over it; "presence": null in the repository, or DEVSTRIDE_PRESENCE=0 on a machine, switches both off. Your presence command may keep the session's own story claims alive while it is active and release them when it ends.

Release holds#

From 3.36.0 a hold is data on the item. A line in an item's description — usually the epic's — keeps its work off the release path:

  • Release hold: not before 2026-11-09 lifts at midnight that day in release.holdTimeZone (an IANA zone; UTC by default); an instant with its offset also works;
  • Release hold: after I20101 is live lifts once that item is in production: under release.clearance.scope "cut-to-deploy" or "merge-and-deploy", once its release's post-deploy check passed; under other scopes, once its production merge happened.

A hold line that does not parse holds, naming the item and the line. build-item checks the item and every ancestor before a one-off or story merges onto the release train or the base branch, and before an epic releases; held work waits on its own branch and the run moves on. release checks again before the train snapshot and before the cut, and stops naming the held item. Remove the line to lift a hold early. Taking work back off the train is always your call.

Consequence notices#

From 3.41.0, once per item, on the final reviewed diff and just before the merge, build-item checks whether the change could cost money, cut someone off or break a caller: new billable infrastructure, removing something callers still use, removing someone's access, or a change that could break a published interface (an API, webhook, tool, command or documented URL). Each finding names its category, the file and the changed lines, and one plain sentence on who or what is affected. When there is one, the loop posts an internal comment on the item that mentions the item's creator, and the run's recap repeats it.

It is a notice, not a gate: nothing waits on it. A helper refuses a finding whose lines the diff did not change, posts nothing when the same notice is already there, and withdraws an earlier notice the final change no longer supports. An epic's release checks the release unit too, and both the epic release recap and the production release's go-ahead repeat every notice the release carries, after checking each one still holds. consequenceNotices.enabled: false turns the check off, notify names more people to mention, and categories adds your own.

Recording what was really built#

When a story ships materially differently from its description, the completion step keeps the original description in a comment and replaces the description with an as-built version: a Deviations list with a one-line reason each and an As shipped summary. From 3.40.0 it sends that through DevStride's record_as_built_change tool, which also writes a note into every Knowledge Base spec linked to the item, or marks the spec out of sync when it cannot, and reports any spec it skipped. Because that note can reach customers, it leaves out branch, commit and tool names and never says the work is available yet. On a server without the tool, or for an item it refuses, the description is updated directly as before. A story that shipped as specified writes nothing.

One merge gate#

From 3.38.0 every pull-request merge the loop makes — an item's pull request, the release train's pull request, an epic release, the production release and the sync back — runs skills/pr/scripts/merge-gate.py <n> <head> and then exactly the command it prints. It prints a merge only for an open, non-draft pull request still at the reviewed head, with every required check passed on its newest run there, no unresolved review thread and no change request. Pending, failed, cancelled or missing checks refuse and name the check. It adds an admin override only when GitHub reads the pull request as blocked with all of that true, so an admin merge can never bypass a conflict, an out-of-date branch, a missing approval or a red check. The production merge also holds every other check to the same rule (--all-green).

A review in which no engine returned a result also fails, on every path (from 3.38.0): a crash, timeout, non-zero exit or empty output is not a result, and such a round is never settled, flipped, recorded or merged.

Fast merges: no item pull request#

With epicIntegrationBranches.fastStoryMerges.enabled: true, a planned leaf on an integration branch receives:

  • the Claude adversarial pass from the build engine;
  • the profile's immediate-risk verification whenever the item's own diff touches authentication, a migration, irreversible state, or a deployed contract;
  • the profile’s story gate — the local checks the delivery profile requires before a merge, type-checks plus the touched test suites under every profile (the storyVerify: "full" override adds the full test suite and lint);
  • a --no-ff merge onto the release-unit branch after all findings and checks settle.

There is no item pull request, cloud reviewer, CI run, or review-thread bookkeeping. Those gates move to the completed release unit; they are not declared passed on the item.

Fast mode requires a completed build-time risk check (its immediate-risk verifiers and matched mandatory lenses included) and a valid verification receipt for the final tree. Without either, the item falls back to the pull-request path and the loop says why. Under prototype, fast mode applies whenever fastStoryMerges.enabled is absent or true; a present false wins and is reported. Red local checks always stop the merge.

When the unit reaches zero open leaves and automatic release is enabled, the loop:

  1. merges the current base branch into the shared integration branch without rebasing it;
  2. runs the configured local verification;
  3. opens the release-unit pull request into its release target — epicIntegrationBranches.releaseTarget, or the plan branch under plan scope — merge-only, so the story merges it is read from stay intact;
  4. reviews the full accumulated diff, because this is the first cloud and CI pass over fast-merged code;
  5. checks consequence notices for the unit and every leaf it carries, then merges through the merge gate only after review and applicable gates settle;
  6. deletes the integration branch only when deleteBranchAfterRelease allows it;
  7. links the release pull request back to the release unit and its constituent leaves;
  8. when docs.updateOnEpicRelease is true, stages documentation for the change without publishing it — the production release publishes it — and never writes release notes;
  9. when the unit merged onto the release train and release.autoStart.enabled is set, checks whether to start a release (see Releases that start themselves).

With autoRelease: false, none of those release mutations starts automatically; the unit is reported release-ready. With autoRelease: "ask", the loop asks for approval for each completed unit before cutting and merging its release pull request, and when nobody can answer (an unattended run) it behaves as false and says so.

One-offs on the release train#

With releaseTrain.fastMerges true, a one-off on the train takes the same fast path as an epic story, with the train in place of the integration branch: the completed risk check, a green local gate, and a --no-ff merge onto the train whose subject leads with the item number, because release reads it later. With releaseTrain.smallFixes set, how much local review it gets depends on its size (from 3.23.0 and 3.34.0):

  • A small fix — within releaseTrain.smallFixes (maxFiles, maxChangedLines), no binary file, nothing on the high-risk list (release.productionReview.highRiskPaths plus release.releaseBranchFixExclusions), and a risk check that raised no finding, launched no immediate-risk verifier and matched no mandatory lens — skips its own review pass. The train's pull request is its full review.
  • Anything larger gets a LOCAL-FULL review on your machine before it lands: Claude and the configured local CLI engine at merge-boundary depth, with the full cycle target and P1 continuation, and the local gate at full width — no pull request, no cloud reviewer, no CI run. The train's pull request into the base branch stays the batch's one CI run.

Without releaseTrain.smallFixes, no fix counts as small and none gets LOCAL-FULL: every train one-off gets the same local-only review an epic story gets.

Every one-off reviewed before it lands (releaseTrain.reviewEveryLanding, from 3.61.0). With it set, no one-off skips its review: each gets a LOCAL-FULL review sized to the change — one cycle with a narrower Claude pass for a small fix, the full cycle target for anything else, and your local CLI engine on every one. The landing's merge commit carries the first line of its review receipt, and a repository admin's devstride/landing-reviewed status on the reviewed commit proves it on GitHub. The train's pull request then lists every item it carries with its receipt under Review evidence and needs only CI, plus a short review of anything with no proven receipt, such as a landing from before the setting, a conflict resolution or a commit made directly on the train. No reviewer reads how the one-offs interact with each other; the one CI run over the whole train is the check for that.

From 3.35.0 the landing is gated in code: skills/build-item/scripts/review-gate.py check must answer small, reviewed (a settled LOCAL-FULL review recorded at exactly this head, tree and merge base) or not-applicable (no releaseTrain.smallFixes set) before the merge. Any new commit, including a merge of a moved train, is a new head and needs the review again. You can run the same review by itself with /devstride:review local-full <base>, and a repository's own landing command can run the same gate file. From 3.38.0 the recorded review lists each engine's result; a receipt from before that is reviewed again.

After the item lands, the run's recap says it is on the train and becomes Done when the next release ships it. With release.autoStart.enabled, the run then checks whether to start a release, keeping its checkout until that answers.

Pull-request path#

pr authors the configured body, requests every configured cloud reviewer when it opens the pull request, and delegates findings and CI settlement to review.

In a draft-held repository:

  1. The pull request opens as a draft.
  2. Claude, the configured local CLI, and configured cloud reviewers run concurrently. A cloud reviewer with baseBranches is requested only on pull requests into one of those branches, and one with requestPolicy: "final-head" is asked once, when every other finding is settled, on the head about to release CI — and again only after a fix that answered one of its own findings. A reviewer left out by its scope is announced as not requested, never waited on and never counted as failed; if the local engine then fails on a pull request no cloud reviewer was asked to review, the loop stops for a human review. Each cloud reviewer request must be proven registered — a review_requested event on the pull-request timeline — within two minutes; otherwise that reviewer is dropped for the run and reported, and nothing waits for it. review.pollTimeoutMinutes bounds only the wait for a registered reviewer’s review — and that wait is adaptive: the loop polls on a lengthening interval and stops at the reviewer’s own historical 95th-percentile latency plus a safety margin, learned per machine from GitHub’s own timestamps, never beyond the timeout, and the full timeout while fewer than five samples exist. Stopping at a learned bound is reported exactly as a timeout would be. The local CLI runs in the background with its input redirected, so it can never sit waiting for input; with review.localEffort set, the first full round runs at its initial tier, a follow-up over the fixes at followUp, and a round checking a fix for a P1 or serious P2 at safety. A round in which no engine returned a result fails and stops.
  3. Findings are verified — refuted unless reproducible — and the profile’s fix floor decides which verified findings are fixed in the item; the rest are dismissed with a rationale, except that one worth filing (a P1, a security finding, or one both likely and material) is captured as a deferred item instead, and cloud threads are replied to and resolved. Two adversarial cycles is the normal target across every reviewer. Past it, only a verified P1 or a serious P2 — likely to occur and material if it does — opens another cycle, and that repeats until a cycle finds none; lower findings cannot extend the target. Each follow-up receives the cumulative ledger of prior findings and dispositions and inspects only the changes since the previous cycle — unless a computed rule sends it back over the whole diff: a file the earlier cycle never touched, more than half of its lines rewritten, or a rebase. A settled finding is therefore not rediscovered or reversed. An unchanged patch, no progress, or an unavailable required reviewer stops for a human rather than spinning or merging.
  4. Qualifying repeatable lessons may be written to lessonsDoc before CI.
  5. The head is refreshed against its base when safe.
  6. Matching local preShipChecks run against the final reviewed diff while the pull request remains held.
  7. Marking the pull request ready releases CI.
  8. The final head commit must show every applicable check successful; absent, skipped, pending, or stale results are not green. The merge then goes through the merge gate at the reviewed head, never the live one.

The draft hold is conditional on review.openPullRequestsAsDraft, review.readyForReviewReleasesCi, and review.ciHeldUntilReviewSettled. When all three are false, the pull request opens ready and CI runs alongside review. Mixed values take the strictest behavior and are reported.

Draft-held CI also needs workflow support

GitHub Actions must listen for opened, synchronize, reopened, and ready_for_review, and the relevant jobs must be gated while the pull request is a draft. Setup detects this but never edits it; doctor reports the exact gap.

Proof that a review settled#

From 3.39.0, when a review settles READY, review posts a devstride/reviewed commit status on the final reviewed head, naming the pull request and the base it was reviewed against (a pull request retargeted since gets none). A tree-identical rebase before merging carries the proof to the new head. release relies on it when the train carries an epic: a release unit may bring migrations or deploy configuration onto the train only when its merged head carries that proof for the same pull request into the train, so a branch named like an epic proves nothing. Only an account with admin permission on the repository counts; an admin withdraws a proof by posting failure. A unit without proof is checked file by file like any other commit and named in the release. A unit merged before the proof existed keeps the older rule, and the release pull request names it. Failing to post is reported, never a stop.

One-off work#

/devstride:create-story add a one-time export
/devstride:create-defect retry creates duplicate records

The create skills ask for a parent, board, and assignee, create the item without plan numbering or dependency edges, and invoke build-item <new-item> once, which terminates instead of selecting another item. Where the one-off lands follows Where work lands: the release train when one is configured — in which case the item moves to the merged status with a comment saying it ships with the next release, and becomes Done when the release carries the train into the base branch — otherwise its own pull request into the base branch, which is also the path for a one-off touching deploy configuration or migrations.

create-defect deferred <item#> and create-story deferred <item#> (from 3.24.0) park a postponed bug or follow-up in the plan root's one deferred container instead, never built by the loop. The container is titled Deferred by default (containers under the older Deferred defects title are still found).

Use insert-story or insert-defect when the new work belongs in an existing plan and should be reached by the dependency walk.

Hotfixes#

/devstride:branch-hotfix fix-login-crash

This creates a branch from a fresh hotfixBaseBranch, so the fix does not carry unreleased development work. It does not open a pull request; build the fix, then use /devstride:pr targeting the production branch. A hotfix never takes a story claim or release clearance, and nothing in the release tower or the previous-release check holds it up; a release in flight on a release branch learns of the landed hotfix, merges the production branch into its release branch and reviews the change again (a merge that leaves the tree unchanged needs no new review).

Production release#

/devstride:release

This is separate from a release-unit pull request. It promotes release.releaseSource to release.productionBranch. Each hook it calls runs through its own step skill (classify-release, pre-ship, pre-merge-check, post-deploy, update-docs, sync-knowledge-base, write-release-notes), so a step that failed can be re-run by name.

  1. Prepare (step 0). With a claims block, claim the release-train claim first. Confirm the shape and adopt an open release pull request rather than opening a second one. Prove CI can stay last. Fetch, read what other authors landed on both branches recently, and say so when another session appears active. With release.clearance set (default scope), claim clearance now.
  2. Merge the release train first, when release.mergeTrainBeforeCut is true: a snapshot of the train (the live train keeps receiving one-offs) goes into the release source through its own fully reviewed pull request (with releaseTrain.reviewEveryLanding, reviewed only where no landing receipt covers it), CI runs once, it merges through the merge gate, every one-off it carried is marked Done, and the live train is brought up to date. Before the snapshot and again before it merges, release holds are checked over everything it carries, and the exclusion check refuses migrations or deploy configuration that no proven review covered. A releaseOnly pre-ship check with runAt: "train" (from 3.28.0) runs here on the snapshot and is not repeated later on the same snapshot.
  3. Compute the delta and cut. Compute the release delta and its class from classify-release (LIGHT or FULL; anything unclear is FULL), and stop on any release hold in it. When release.releaseBranchPattern is set, cut the release branch from the release source, named by the pattern for today (for example release/26-10-03, then -2, -3 on a re-cut when the pattern ends in [-n]); otherwise the release source itself is the head. Open the production pull request, as a draft whenever pull-request CI exists, so CI waits for the review.
  4. Review. Run the configured review roster — or, with release.productionReview.reviewIdenticalTree: false and a tree identical to the one a full review already settled on its way into the release source, only one pass of highRiskEngine over the changed files under highRiskPaths. Then classify again at the head the checks test, run the release-only local pre-ship checks (an owner's waiver is --skip <name>, reported as WAIVED), and settle CI once.
  5. Prepare documentation. Build the documentation plan for the delta; nothing is published yet.
  6. Ask for the go-ahead. Run your pre-merge production check (release.preMergeSkill): HOLD stops before asking. Then present the exact release: the class, each pre-ship result or waiver, the docs and release-notes plan, every consequence notice the release carries, the clearance status, and the release.autoDeployOnMerge consequence.
  7. Merge on a yes. Wait for explicit owner approval — or the standing yes below. With release.devDeployVerification set and a delta touching a fix-exclusion path, wait for the development deploy first. On the yes, confirm the head is still the reviewed head, there are no unresolved threads and, with clearance, that this pull request is the one on final, then merge through the merge gate with every check held to green.
  8. Confirm the deploy and its health. When release.deployApproval is set, the same yes approves the waiting deploy through the configured command right after the merge; you are never sent to a provider's screen to approve. Confirm the deploy (by release.deployVerification or by you), then run your local post-deploy health skill (release.postDeployCheckSkill; under scope: "cut-to-deploy" it runs after step 9's hand-back instead, as described below) — never before the deploy is confirmed, so it measures this release rather than the previous one or an in-flight rollout. PASS continues, FAIL stops for a rollback decision, NOT RUN asks you whether to proceed, and an unset key reports not configured.
  9. Close out, then hand clearance back. With a release branch, sync the production branch back into the release source by pull request (otherwise the release branch’s fix commits would never reach it), then delete the release branch once both contain it; with a release train, bring the train level. With clearance, hand it back here, recording the work still owed.
  10. After the hand-back, in the same session, one at a time: hand the delta to your local documentation skill (docs.updateSkill) so core docs are updated by default, unless suppressed, and, only once they are published, refresh your knowledge base (docs.knowledgeBaseSyncSkill); run the post-deploy check's own close-out when it said it owes one; and write a release note through your local release-notes skill — only if you passed --release-notes. A failed step stays owed. Finish with the recap.

Clearance: one release at a time#

With release.clearance set (from 3.11.0), only one release is in flight across every machine and person. A second release asking for clearance is told who holds it and waits; the next release carries its work. The holder records each phase as it goes — from 3.33.0 including final, the wait for your yes — and a release that sits in one phase past its budget shows as STUCK, an alarm for you rather than a takeover. A failed health check, or a close-out that stops early, keeps clearance for the retry.

With scope: "cut-to-deploy" (from 3.27.0), the release merges the train without clearance, claims clearance just before the cut and hands it back as soon as the deploy is confirmed and step 9's branch work is done. The post-deploy health check then runs as the first owed item and posts its result as the release/post-deploy commit status on the production merge commit. The next release can cut, review and test meanwhile, but does not merge to production until that status is success, unless you override it in words recorded on the pull request. A session that stopped after the hand-back leaves the status pending; any session finishes it with /devstride:release post-deploy only.

With scope: "merge-and-deploy" (from 3.61.0), clearance is held only for the merge into production and the deploy. Releases queue, first cut, first merged: no release is cut while another release pull request is open into production, so the next one is cut as soon as the one ahead merges, built on top of that merge. Its pre-ship checks, development deploy wait, pre-merge check, review and CI all run outside clearance while the one ahead deploys. The checks record what production looked like when they ran; at the claim, made only once you have said yes, and again just before the merge, the release confirms production has not moved. If it has — the release ahead was reverted, a hotfix landed — the release gives clearance back, brings production in, and is reviewed, checked and tested again before it may merge; any yes given before is void. Once its deploy is confirmed it hands clearance back at once and runs its post-deploy check first, so the release behind can merge as soon as this one is healthy. It needs release.releaseBranchPattern. See Release clearance.

Releases that start themselves#

With a claims block (from 3.29.0), every release — started by hand or not — claims the one release-train claim before it opens or adopts the train's pull request, so only one session runs the train phase. When both release.clearance and release.releaseBranchPattern are set, it hands the claim on once the release branch is cut under clearance (under merge-and-deploy, once its release pull request is open), so the next train phase can run while this release deploys; without either, it holds the claim until the run ends. A claims outage never lets a release carry on without it: a release you started stops and names the outage, and an automatic start does nothing.

With release.autoStart.enabled as well, a release starts itself after build-item lands a one-off on the train, after an epic's release pull request merges onto the train, and after a release finishes its own close-out. From 3.61.0 build-item also looks at every story boundary and when its loop starts, so it notices a claim handed on by the release ahead, and a release that levels the train after its deploy starts the next one itself when work is waiting. It starts only when the train holds work beyond the release source and the session wins the claim; a session that loses carries on with its own work. An automatic release that cannot merge on the standing yes stops at the go-ahead and sends you one notification naming the release, why it is waiting and its pull request link.

The standing yes. With release.lightRelease.standingYes, a light release whose tree is identical to its reviewed train merges and has its deploy approved without an in-the-moment yes. With release.fullRelease.standingYes (from 3.37.0), so does a release of any class at exactly its reviewed head, when every migration file it adds or changes has been approved by content: the file's git blob id is listed in approvedMigrations, added only on the owner's own words in a commit of its own. A renumbered migration with the same content keeps its approval; any edit needs a new one. Both routes also need every required check green, zero unresolved threads, every pre-ship check passed and none waived, the pre-merge check clear, the previous release's post-deploy check green, the development deploy done when that wait is configured, and this release alone on final — so without release.clearance, which is what reports "on final", the standing yes never applies. The release then posts one comment on its pull request saying it merged on the standing yes. Anything else — a new, edited or deleted migration without approval, a waiver, a pre-merge hold — waits for your explicit yes. See Releases that start themselves.

Release backstop#

Releases that start themselves start when work lands. From 3.45.0, release.backstop adds a safety net for work that lands and then waits because no session noticed it. Run /devstride:release backstop on a schedule, by hand or from a scheduled session such as /loop 10m /devstride:release backstop. Each run starts a release only when the oldest landing on the release train has waited longer than maxWaitMinutes (default 120 minutes, at most a day, counted from when git records the landing's merge), no release is in progress (no open release pull request, and clearance free when release.clearance is set; under cut-to-deploy and merge-and-deploy, from 3.61.0, only the release-train claim counts), and no release hold applies. Otherwise it does nothing and tells you why.

When several machines run the check at once, they compete for one claim keyed by the oldest waiting landing, so only one starts a release. The claim is never renewed and lapses after maxWaitMinutes: if the release it started stops early, for a hold, a red check or your no, the backstop tries again at most once per maxWaitMinutes while the work still waits.

Start with mode: "shadow". The check then only records, in the claims store, what it would have started, and changes nothing. Once those records show one start per piece of waiting work, at the right time, and none while a release was running, switch to "live": the backstop then starts the release the same way an automatic start does, so the unattended stop and the standing yes apply unchanged. The backstop needs a claims block, and when your claims run through your own commands, claims.commands.get, because it reads its claim before taking one; /devstride:doctor reports either gap as an error. See Release backstop.

Release branches and late arrivals#

There is no release freeze any more (from 3.8.0). Pull requests into the release source are not settled, parked or waited for, and ci.freezeBaseWhileReleasePrReady is ignored. With a release branch, a merge into the source meanwhile simply ships in the next release; without one, it advances the release pull request’s head, and the review round runs again before the owner is asked.

A one-off that lands on the live train while the train's pull request is under review follows releaseTrain.lateArrivals. With "offer" (the default) it joins only on your word, before CI is released, and gets one full review pass of its own; otherwise it ships next time. With "restart", review stops, the late work is absorbed and the review starts again over the whole snapshot, up to three times and only until CI is released.

A release branch is protected. Fixes found during review are new commits on it — never a rebase, amend or force-push. A fix that touches release.releaseBranchFixExclusions (deploy configuration, migrations) is refused: merge it to the release source by a normal pull request, abandon the release branch and re-cut. A hotfix that reaches production meanwhile is merged into the release branch and re-reviewed. Why a branch at all: the release source keeps moving while a release is reviewed, so cutting a branch freezes what ships without freezing everyone else’s work.

Release notes are opt-in: --release-notes (or --release-notes draft to read the note before it is published). Without the flag no note is written, and nothing in the loop decides that a release deserves one. Passing no docs or skip docs suppresses the docs phase and the knowledge-base refresh. docs only updates documentation for an already-shipped delta; release-notes only writes the note for one; post-deploy only finishes a post-deploy check a stopped session left pending.

Switching from planning to execution#

Run /clear before moving from setup or planning into building, reviewing or releasing. The session gate introduced in 3.5.0 keeps those job classes separate; a build loop may still deliver multiple stories in one session. /devstride:doctor and /devstride:update are neutral (from 3.18.0), so running Doctor first never blocks the build that follows. To continue in the same session on purpose, add --same-session to the command; remember that /clear ends the session and gives up anything it holds, such as a checkout lease. See Session boundaries and deferred work for intentional overrides.

A verified finding worth filing (a P1, a security finding, or one both likely to happen and material) that is deliberately put off is filed beside the plan in its one deferred container (titled Deferred from 3.24.0; a container under the older Deferred defects title is still found) and related to the reviewed item — a Defect for a bug, a Story for any other follow-up; any other unfixed finding is dismissed with its one-line reason, and nothing is filed. They do not enter the active dependency chain, are not auto-selected, and do not hold the completed release unit open. Newly discovered implementation scope still enters the plan through insert-story.

Powered by DevStride