The Idea Behind the Loop
What the DevStride plugin for Claude Code is designed to do in your repository, and why: a plan an agent can walk, a tracker that remembers, release units that keep half-built work off your shared branch, review before CI, once, and one release at a time across every machine.
On this page
- The Idea Behind the Loop
- The core idea
- The loop at a glance
- Each design choice: what it is, and why
- A plan an agent can walk
- The plan is a hypothesis
- The tracker is the memory
- Release units keep half-built work off your shared branch
- A release train for work outside any plan
- Fast mode moves the review gate; it never removes it
- Review first, CI once
- One word sets the rigor
- One item at a time per session, one claim per item
- Every session reports itself
- One release at a time: release clearance
- The standing yes
- Your repository decides
- What stays human
- Where to go next
The Idea Behind the Loop#
A coding agent can already write a good change. The hard part is everything around the change: knowing what to build next, keeping half-finished features away from users, making sure review findings don't vanish, and not paying for the same CI run five times. The devstride plugin is a set of Claude Code skills that handles that surrounding work, so an agent can deliver a whole roadmap one item at a time, mostly unattended, in your repository and against your DevStride organization.
This page explains the idea and the reasons behind it. The pages after it explain the commands.
The core idea#
Plan the work in DevStride as a tree of items joined by dependency links, so the next piece of work can always be worked out rather than chosen. Let an agent walk that plan one item at a time, recording on each item what actually shipped. Group the items into release units, usually Epics, that collect on their own branch and move on only when complete and fully reviewed. Run review before CI, and CI once, on the reviewed code. Let only one release be in flight at a time. Leave production to a person, or to a standing yes that person wrote down in advance.
The loop at a glance#
plan grouping items → release units (Epics) → leaves (Stories, Defects)
joined by blocked-by / blocks links
│
build-item next unblocked leaf (claimed first, if claims are on) → In Progress
→ branch → build → risk check → green local checks
→ merge onto the release-unit branch
→ record what shipped on the item → next leaf
│
release unit complete → one release pull request into its release target
unit (your base branch, or the release train) → full review → CI once → merge
│
one-off no release unit above it → its own pull request into the base branch,
work or onto the release train, which ships with the next release
│
release one release at a time: train merged → cut → review → owner's yes
(or a written standing yes) → production → health check → hand back
/devstride:plan builds the tree, /devstride:build-item walks it (and /loop /devstride:build-item keeps walking), and /devstride:release takes finished work to production.
Each design choice: what it is, and why#
A plan an agent can walk#
What it is. Every plan is a hierarchy with three roles: grouping items at the top, release units in the middle, and leaves that are the actual work. /devstride:setup maps your organization's real work-type names onto those roles. Every leaf has dependency links, and the next item is always the highest-priority unfinished leaf whose blockers are done, inside the earliest-dated open parent. A blocker in the same release unit also counts once it has merged onto that unit's branch. A blocker in a different release unit counts only when Done, so the next unit waits until the previous one has reached its release target.
Why. An agent can't work unattended if "what's next" is a judgement call. With the links in place, selection is a rule, and the plan's timeline matches the order the loop will actually build in.
The plan is a hypothesis#
What it is. Before building, the agent checks the item's spec against the real code. When the work turns out differently, it keeps the original spec as a comment and rewrites the description as what shipped, deviations included. Where your DevStride organization supports it, that rewrite also reaches every Knowledge Base spec linked to the item: each gets a note of what changed, or is marked out of sync when it can't be updated. Because those specs can have customer readers, the note says what was built in plain words and leaves out branch, commit and tool names.
Why. Plans are guesses. A tracker that still describes the plan after the code went another way misleads everyone who reads it later, and a spec that quietly falls behind its item misleads the people who read the spec.
The tracker is the memory#
What it is. Items, their comments and their as-built descriptions are the lasting record. Newly discovered scope is spliced into the plan as a new item. 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 one Deferred container under the plan root (defects.deferredContainerTitle): a bug as a Defect, any other follow-up, such as tech debt or a dated after-deploy step, as a Story. The container sits outside the build order, so it is tracked without holding the plan open; when the plan is dated, its items go after the plan's last story, and when the plan finishes, the closing report lists what is still open there. Any other unfixed finding is dismissed with a one-line reason in the pull request or merge commit, and nothing is filed for it.
Decisions about timing live on the items too. A line such as Release hold: not before <date> or Release hold: after <item> is live in an item's description keeps that work, and anything under it, off the release path until the hold lifts. Every machine reads the hold the same way.
Why. Pull requests close, and agent sessions forget everything when they end. A finding or a hold that lives only in a pull request description or a chat message is never seen again. The tracker is where the next session, and the next person, will look.
Release units keep half-built work off your shared branch#
What it is. Each release unit gets its own integration branch (epicIntegrationBranches). Leaves merge onto it one at a time, and may be unfinished there. When the last leaf lands, the whole unit moves on in one release pull request, into your base branch or, if you set epicIntegrationBranches.releaseTarget to it, onto the release train. A leaf merged onto the unit's branch is not Done yet: it moves to a merged status (Review by default, epicIntegrationBranches.mergedStatusName) and becomes Done when the unit reaches its release target. Only a leaf's own pull request into the base branch makes it Done straight away.
A plan whose release units depend on each other can opt in to releasing as one unit: a Release scope: plan line in the plan root's description sends each finished unit to a plan integration branch, lets a blocker in a sibling unit count once it has landed there, and releases the whole plan when nothing outside the Deferred container is left. It is a rare, deliberate choice, never a way to hide unfinished features from customers.
Why. On many teams the base branch reaches users quickly, sometimes within hours. A feature merged leaf by leaf would be live before it was finished. The release unit is the smallest piece that is complete enough to be safe, so it is the unit you release and the unit you check for safety. That is why the planning skill shapes each one as a slice of real value, and asks while planning about blast radius, billable infrastructure and deploy order.
A release train for work outside any plan#
What it is. A one-off item has no release unit above it. Without a train it opens its own pull request into the base branch. If you configure a release train (releaseTrain.branch) and have releases merge it (release.mergeTrainBeforeCut), one-offs collect on that one long-lived branch instead, and every production release first merges the train into the base branch through its own reviewed pull request. Without release.mergeTrainBeforeCut, nothing would ever ship the train, so one-offs go to the base branch and the loop says why. With releaseTrain.fastMerges, a one-off merges onto the train after its risk check and local checks, with no pull request of its own. It moves to the merged status, and becomes Done when the train reaches the base branch.
With releaseTrain.smallFixes set, how much review a fast-merged one-off gets before it lands scales with its size:
- A small fix (within
releaseTrain.smallFixeslimits, no binary file, nothing on the high-risk list, and nothing raised by its risk check) skips its own review pass; the train's pull request is its full review. - A larger or riskier fix gets its full review on your machine before it lands, with no pull request and no CI run: Claude and, if you configured one, your command-line reviewer, run as
/devstride:review local-full <base>. A landing gate checks that this review was recorded at exactly the commit being merged, so a later change needs it again.
One-offs that touch deploy configuration or migrations (release.releaseBranchFixExclusions) never ride the train: they take their own pull request into the base branch, so they reach a development environment before any release carries them. A reviewed release unit may carry such changes onto the train, but only with proof of its review: a devstride/reviewed status the review posts on its final commit, which counts only when posted by an account with admin permission on the repository. A unit without that proof is checked file by file like any other commit.
Why. Every merge into the base branch can mean a paid CI run and a deploy. One-offs that batch on the train get one full review and one CI pass at release time, and the train ships with every release, so nothing waits longer than the next cut. Reviewing a large one-off before it lands means a late find holds up that one fix, not the whole release.
Fast mode moves the review gate; it never removes it#
What it is. With fast merges on (epicIntegrationBranches.fastStoryMerges.enabled), a leaf gets no pull request of its own. It gets a bounded risk check and must pass your local checks before it merges. Any leaf that touches authentication, a migration, anything that can't be undone, or a contract a deployed service depends on also gets a focused verifier, decided from the actual diff. No setting skips that. The full review, with every configured reviewer, and CI then run on the release-unit pull request, over the full diff of every leaf.
Why. A pull request, cloud review and CI run for every leaf is expensive, and the release pull request has to review all of that code anyway. Doing it once, on the finished unit, costs less and lets the reviewer see the leaves together. The trade only holds because the release review is a full review, not a re-check: under fast mode it is the first time cloud review or CI sees that code.
Review first, CI once#
What it is. Pull requests open as drafts, and your CI workflows skip drafts. (That needs your workflows' support; /devstride:setup detects it and /devstride:doctor reports any gap.) Every configured reviewer runs first: Claude's adversarial pass always, plus an optional local command-line reviewer (review.localCommand) and optional cloud reviewers (review.automatedReviewers). A cloud reviewer can be limited to certain target branches (baseBranches), or asked only once, on the final version (requestPolicy: "final-head"). When every finding is settled, the pull request is marked ready, and that releases CI once, on the code that was reviewed.
A reviewer counts only when it returns a result: its findings, or an explicit "no findings". A reviewer that crashes, times out or prints nothing has not reviewed anything, and a round in which no reviewer returned a result fails; it is never settled or merged.
Every pull request the loop merges, from a leaf's own pull request to the production release, goes through one merge gate. It merges only an open, non-draft pull request still at the commit that was reviewed, with every required check passed on that commit, no unresolved review thread and no reviewer asking for changes. It uses an administrator merge only when GitHub is holding a pull request that meets all of that, so it never bypasses a red check, a conflict or a missing approval.
Why. CI that runs alongside review runs again after every fix, and those runs are thrown away. Two review cycles is the normal target. A confirmed P1, or a serious P2 (one that is both likely and material), keeps opening cycles with no limit until a cycle finds none. Each follow-up gets the full record of earlier findings, so settled issues aren't rediscovered or reversed. If the review makes no progress, or a required reviewer is missing, the loop stops and asks a person rather than spinning or merging.
One word sets the rigor#
What it is. A delivery profile (prototype, standard or extended, set with profile) moves the related settings together: how finely work is sliced, how deep each spec goes, how widely review fans out, which findings are fixed straight away, and which local checks gate a merge. A plan can carry its own profile, recorded in its root item.
Why. These settings depend on each other: big items under the strictest review produce dozens of findings each. Some things no profile removes: every leaf gets a risk check and green local checks, risky changes get their focused verifier, full review runs before a merge into the base branch, and CI waits for it. See Choose a delivery profile.
One item at a time per session, one claim per item#
What it is. Each session builds one item at a time, and starts each pass by fetching the latest state from your remote and noticing what other people landed. Several sessions, on one machine or many, can walk the same plan when you add a claims block: before an item moves to In Progress, the session claims it, and only one session can win that claim. A session skips an item another live session holds and takes the next one; an item you named that someone else holds stops the run and says who holds it, on which machine and since when. The holder renews the claim at each step, and releases it when the item is Done or has landed on its branch. A claim left by a session that stopped expires on its own (after 240 minutes for a story by default), so a crashed session never holds an item forever. If claims are unavailable, the loop carries on without them and says so once.
Why. DevStride updates are live, there is no draft mode, and tests usually share infrastructure. Walking the plan in order and starting from current facts, rather than from memory, keeps the loop's statements about "what is merged" true. When two agents read the same list of ready work, a check like "nobody has started this yet" passes for both at the same second; a claim that only one can win is what stops the same story being built twice.
Every session reports itself#
What it is. A claim shows only the sessions that hold one. A session reviewing, waiting on tests or waiting for its person has none. If you name a command of your own in a presence block, the plugin's hooks run it for every session: when it starts, as it works, when it is waiting for you, when it ends, and on an interval (presence.intervalMinutes, every 5 minutes by default) while the session's process is alive, so a long turn stays visible and a killed session is reported gone. Each report says when the session last actually did something, so your command can tell a session that is hung from one that is busy. What your command does with a report, where it stores it and when it expires is up to you. With no command named, the plugin's own reporter (from 4.0.0) sends every session to DevStride's Agent Fleet, so every member's sessions are seen without any setup beyond an API-key connection.
Why. A view of who is working that only counts claim holders undercounts exactly when someone is watching it. Presence is for display only; claims still decide who acts.
One release at a time: release clearance#
What it is. When releases can be cut from more than one machine, or by more than one person or agent, set release.clearance. The release skill then claims clearance, a single permit for the release in flight, kept as a git ref in your repository, as a DevStride claim, or by commands you supply. A second session asking for it is told who holds it and waits; the next cleared release carries its work. The holder keeps a heartbeat, so a session that crashed goes stale and its clearance can be taken over, but a stale release whose pull request is still open is only ever adopted and resumed, with your yes. A live release that has sat in one phase past its time budget is flagged as stuck: that is an alarm for you, never a takeover. The release hands clearance back as soon as production is healthy and the branches are settled; documentation and the rest of the close-out follow in the same session, listed as owed until each is done. A hotfix is never held. /devstride:setup ci can also add a release-tower check that passes only a hotfix, the oldest open release pull request, or one you labelled as an exception. Make it required on your production branch and even an administrator cannot land a second release beside the first.
With release.clearance.scope: "cut-to-deploy", the permit is held only from cutting the release to confirming its deploy, so the next release can merge its train and run its review while this one deploys. The post-deploy health check then runs after the hand-back, and its verdict is posted as a release/post-deploy status on the production merge commit; the next release can be cut and reviewed, but cannot merge into production until that status is green, unless you override it in words.
With release.clearance.scope: "merge-and-deploy" (from 3.61.0), the permit shrinks to the part that really must happen one at a time: the merge into production and the deploy. Releases wait in a queue, first cut, first merged. No release is cut while another release pull request is open into production, so the next one is cut the moment the one ahead merges, built on top of that merge, and checked, reviewed and tested while the one ahead deploys. If production moves before it merges, because the release ahead was reverted or a hotfix landed, it is rebuilt on what is there now and checked and tested again. This scope needs release.releaseBranchPattern.
With a claims block, the step before the cut is guarded too: every release first claims the release-train claim, so only one session runs the train phase. Add release.autoStart.enabled and releases start themselves: when a one-off lands on the train, an epic's release merges onto it, or a release finishes, the session checks whether the train holds work beyond the base branch and, if it wins that claim, starts the release. From 3.45.0 a backstop covers the case where nobody noticed: set release.backstop and a check you run on a schedule starts a release only when the oldest work on the train has waited longer than you allow and no release is already under way. You run it in a recording-only shadow mode first, so you can see what it would have started before you let it start anything.
Why. Two releases in flight at once review, test and deploy each other's changes, and a release that is half-finished when its session dies needs someone to find it. One permit, visible to every machine, with a heartbeat and an owner-only adoption path, keeps releases in single file without anyone watching the queue.
The standing yes#
What it is. By default every production merge waits for your explicit yes in the moment. You can instead give a standing yes, in your configuration, for releases that meet every condition:
- Light releases (
release.lightRelease.standingYes): a release your classify skill calls light, whose tree is identical to the reviewed train. - Full releases (
release.fullRelease.standingYes, with the date you gave it inownerDecision): a release of any kind at exactly the commit that was reviewed, where every migration file it adds or changes is one you approved by content, listed inapprovedMigrations. Renumbering a migration keeps its approval; any edit to it needs a new one.
Both also need every required check green, no unresolved review thread, every pre-ship check passed with none waived, the pre-merge production check clear, the development deploy check passed when you configured one, the previous release's health check green where that gate is on (the cut-to-deploy scope), and this release first in line for clearance. Without release clearance there is no line to be first in, so a standing yes never applies. When all of that holds, the release merges, approves its deploy and records one comment on its pull request saying so. Anything else, such as a new or edited migration without an approval, a deleted migration or a waived check, waits for your yes as before. A release that started itself and can't merge on the standing yes sends you one notification and waits.
Why. Asking for the same yes on a release that passed every gate you would have checked yourself only adds waiting. A written rule, checked by code on every release, keeps the decision yours while letting releases that clearly qualify go out without you being awake for them.
Your repository decides#
What it is. Everything repository-specific (branch names, check commands, reviewers, release settings) lives in .claude/ds-config.json, which /devstride:setup writes and then tests by running it. Where the file disagrees with a skill's built-in default, the file wins. The plugin publishes the file's shape as a JSON schema, and /devstride:setup and /devstride:doctor check your file against it, warning about a key they don't recognise.
Why. The loop has to fit your repository, not the other way round. Your conventions file (conventionsDoc) is how the code it writes ends up looking like yours.
What stays human#
The loop runs from selection to merge without stopping, except at decisions that belong to a person:
- Production.
/devstride:releaseprepares, reviews and verifies the release, then waits for your explicit yes before merging to production, unless a standing yes you wrote covers that exact release. Starting it is never permission to deploy. - Releasing a finished unit. Under
standardandextended, setup writesepicIntegrationBranches.autoRelease: false, so a finished unit stops at release-ready."ask"makes it ask each time. - Approving migrations. An entry in
approvedMigrationsis added only on your own words, in a commit of its own, and each release names every approved migration it carries. - Taking over someone else's release. Adopting a stale release with an open pull request, or one flagged as stuck, needs your yes, and for a stuck one your word that its session has stopped.
- Owner decisions in the plan. Billable or externally visible infrastructure, and anything gated on a human or infrastructure step, is flagged rather than decided.
- Consequences you should hear about. Just before an item merges, the loop checks its final reviewed change for four kinds of consequence, plus any you add: new billable infrastructure, removing something callers still use, removing someone's access, and a change that could break a published interface. What it finds is posted as one internal comment on the item, mentioning its creator, with the file and lines as evidence, and is repeated in the release recap. It is a notice, not a gate (
consequenceNotices). - Ambiguous findings. A review finding that is ambiguous or can't be checked comes back to you.
- Anything only you can do. Each hand-off ends with two lists, what the loop did and what you must do yourself, such as signing in.
Where to go next#
- DevStride for Claude Code: the model in one minute, profiles side by side, and entry points
- Getting the Skills: install and connect
- Guided Setup: what
/devstride:setupreads, writes and checks - The Planning Loop and The Delivery Loop: each stage in detail
- Configuration Reference: every setting named above, including the release train, release clearance, releases that start themselves, the release backstop and story claims