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 reach your main development branch only when complete and fully reviewed. Run review before CI, and CI once, on the reviewed code. Leave production to a person.

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 → 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 your base branch
unit        → full review → CI once → merge
              │
release     owner-approved promotion from your base branch to production

/devstride:plan builds the tree, /devstride:build-item walks it (and /loop /devstride:build-item keeps walking), and /devstride:release prepares the production promotion.

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.

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 moves the original spec into a comment and rewrites the description as what shipped, deviations included.

Why. Plans are guesses. A tracker that still describes the plan after the code went another way misleads everyone who reads it later.

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 is filed in a Deferred defects container under the plan root (defects.deferredContainerTitle), outside the build order, so it is tracked without holding the plan open. Any other unfixed finding is dismissed with a one-line reason in the pull request or merge commit, and nothing is filed for it.

Why. Pull requests close, and agent sessions forget everything when they end. A finding that lives only in a pull request description 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 goes to your base branch in one release pull request. 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 that release pull request merges. Work outside any plan has two routes. It can open its own pull request into the base branch. Or, if you configure a support train (supportTrain.branch), it collects on that train, which each production release merges first (release.mergeTrainBeforeCut). Changes to deploy configuration or migrations can be kept off the train (release.releaseBranchFixExclusions), so they reach a development environment before any release carries them.

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.

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.

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, extended or enterprise, 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, on purpose

What it is. The loop builds one item at a time, and starts each pass by fetching the latest state from your remote and noticing what other people landed.

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.

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.

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:release prepares, reviews and verifies the release, then waits for your explicit yes before merging to production. Starting it is never permission to deploy.
• Releasing a finished unit. Under standard, extended and enterprise, setup writes epicIntegrationBranches.autoRelease: false, so a finished unit stops at release-ready. "ask" makes it ask each time.
• Owner decisions in the plan. Billable or externally visible infrastructure, and anything gated on a human or infrastructure step, is flagged rather than decided.
• 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:setup reads, writes and checks
• The Planning Loop and The Delivery Loop: each stage in detail
• Configuration Reference: every setting named above