On this page
Key Shape Setup value or absent behavior Purpose
baseBranch string "develop" fallback Normal feature base and merge target.
hotfixBaseBranch string "master" fallback Fresh base for production hotfixes.
protectedBranches string[] ['develop', 'master'] fallback Heads the loop must not rebase, force-push, delete, or write lessons onto. Setup includes the base, release source, and production branch. From 3.8.0 an entry may be a pattern such as "release/*" — see Branch patterns.
integrationBranch string or null null Explicit working-base override. Non-null takes precedence over per-release-unit derivation.
branchNaming.pattern string "<prefix>/<MM-DD-YY>/<slug>" Feature branch shape.
branchNaming.prefixSource string "git user.name first name, lowercased; ask if empty or ambiguous" How the prefix is chosen.
branchNaming.dateFormat string "MM-DD-YY" Branch date format. From 3.6.0 both branch-feature and branch-hotfix take their date from it; branch-hotfix previously always used MM-DD-YY.

Static fallbacks versus repository detection#

develop and master are deterministic runtime fallbacks for a repository with no config. They are not claims that every repository uses those names, and /devstride:setup does not copy them when it can inspect origin.

Setup enumerates actual remote branches and uses exact common names as role candidates:

Role Candidate names
Normal development and release source develop, development, staging, stage, canary, test, testing, qa
Production and hotfix base main, master, production, prod
Possible single trunk trunk

Exactly one development candidate and one production candidate produce a proposed four-key mapping. Multiple matches remain a question; setup never picks whichever name happens to appear first. A development candidate without a production candidate can suggest baseBranch and release.releaseSource, but it cannot establish the production or hotfix branch.

The detector considers only branches that exist on origin, matches whole names rather than substrings, and treats origin/HEAD as evidence for the ordinary pull-request base rather than proof of production. Existing explicit config always wins.

/devstride:doctor config resolves the configured values or inline fallbacks and checks them against the remote. If an effective fallback does not exist, doctor prints the concrete candidates and the mapping setup would propose. Doctor never writes the file.

Branch patterns#

From 3.8.0 one anchored matching rule is used for protectedBranches entries, release.releaseBranchPattern and release.releaseBranchFixExclusions: * matches one or more characters within one path segment, ** one or more across segments, a date token such as <YY-MM-DD> matches a date, a trailing [-n] allows an optional -2, -3 … suffix, and everything else is literal. A name is tested against the whole pattern, never as a substring, so release/* does not match foo/release/x and stacks/** does not match docs/stacks/x. Why: an unanchored match fails silently — it either protects nothing or refuses a harmless fix. A release branch and the release train are protected by their own keys, whether or not protectedBranches lists them.

Release-unit integration branches#

Key Shape Setup value or absent behavior Purpose
epicIntegrationBranches.enabled boolean true Give each release unit its own integration branch. false sends planned items to baseBranch.
epicIntegrationBranches.pattern string "<prefix>/<MM-DD-YY>/<epic-number>-<epic-title-slug>" Integration branch pattern. The date is the branch’s creation date. An existing integration branch is found by matching this pattern, anchored, so a marker such as epic-<epic-number>-… still resolves (from 3.8.0). A branch found only under an older naming makes the loop stop and ask rather than cut a second one for the same epic (from 3.9.0, which also catches dated older names).
epicIntegrationBranches.slugRule string Kebab-case, lower-case, [a-z0-9-], strip [N], about six words Deterministic release-unit slug rule.
epicIntegrationBranches.releaseTarget string "baseBranch" Base of the completed release-unit pull request. The literal baseBranch resolves to the configured branch. Naming the release train's branch (releaseTrain.branch) makes a finished release unit join the train through its reviewed release pull request, so every release carries release units and one-offs to the base branch together, with one CI run.
epicIntegrationBranches.autoRelease boolean or "ask" false for standard and extended; true for prototype, which setup says out loud When true, the loop cuts and merges the release-unit pull request after the final leaf. false stops at release-ready. "ask" (from 3.5.0) asks the owner once per completed release unit before cutting and merging its pull request; when nobody can answer (an unattended run) it behaves as false and says so. No profile writes "ask"; it is set by hand or in setup's interview. A present value wins over the profile.
epicIntegrationBranches.deleteBranchAfterRelease boolean true Delete the release-unit branch after a successful release. Set false to retain it.
epicIntegrationBranches.mergedStatusName string or null "Review" The status a leaf moves to when it lands somewhere that is not yet its final destination: its release unit's integration branch, a plan integration branch, or (from 3.32.0) the release train for a one-off. It has landed but is not Done until it reaches its release target; only an item whose own pull request merges into the base branch goes straight to Done. Matched by name in the item's work type's statuses, so one value works in any organization. null, or an organization with no status of that name, keeps the leaf's status; the comment and the git history still record the merge. From 3.10.0.
epicIntegrationBranches.fastStoryMerges.enabled boolean Setup writes the value consistent with the chosen profile; runtime fallback is enabled With an integration working base, locally review and merge the leaf with no item pull request. For prototype setup writes true whenever verify.typecheck is set, since Claude’s pass is the local engine and the story gate is type-checks plus the touched suites; for standard and extended it writes true when both verify.test and verify.typecheck are set, and otherwise false, naming the missing command. A local CLI engine is not a precondition under any profile. A present value wins over the profile.
epicIntegrationBranches.fastStoryMerges.requireLocalVerifyGreen boolean true Require the configured local checks before a fast merge.
epicIntegrationBranches.fastStoryMerges.epicReleaseIsFirstCloudPass boolean true Tell the release review that it must inspect the full accumulated diff.

If the repository is public and you would rather no tracker numbers reach branch names, use an integration-branch pattern without <epic-number>, such as "<prefix>/<MM-DD-YY>/<epic-title-slug>"; the key already tolerates it.

Plan integration branches#

Key Shape Absent behavior Purpose
planIntegrationBranches.pattern string with <prefix>, the date token, <plan-number> and <plan-title-slug>, e.g. "<prefix>/<MM-DD-YY>/plan-<plan-number>-<plan-title-slug>" absent: no plan can release as one unit From 3.30.0: the branch a plan releases its epics onto when its root's description carries the line Release scope: plan. Each finished epic's release pull request merges onto this branch instead of epicIntegrationBranches.releaseTarget; a blocker in a sibling epic of the same plan counts once it has landed there; and when nothing outside the plan's deferred container remains, one pull request takes the whole plan to the release target. The slug follows epicIntegrationBranches.slugRule. The branch is cut at the plan's first epic release and is merge-only, like an epic branch. A plan that carries the line while this key is unset stops with a config gap.
planIntegrationBranches.example string absent Descriptive only: a sample branch name. Nothing reads it.

Plan scope is opt-in per plan: setup never writes the key unasked, plan adds the marker line only when you ask for it, and plans without the line behave exactly as before. It suits a deliberate build whose epics depend on each other. It is not a way to keep unfinished features from customers; a stored product setting does that. The contract is skills/build-item/references/plan-scope.md in the plugin repository.

Release train#

Key Shape Absent behavior Purpose
releaseTrain.branch branch name, e.g. "train/release" One-offs use baseBranch From 3.8.0: one long-lived branch that one-off items — those with no release unit above them — land on instead of the base branch. It is created off the base branch on first use. From 3.31.0, when the configured branch is not on origin but exactly one other train/* branch is, the loop uses that one and names the rename, with the commands that perform it, instead of creating a second, empty train; with several other train/* branches it asks which one is live.
releaseTrain.fastMerges boolean false: a one-off on the train takes the full pull-request path, into the train With true, a one-off merges onto the train after the local risk check and local gate, with no pull request of its own, exactly as a fast-merged story does on an epic branch. From 3.32.0 the one-off then moves to epicIntegrationBranches.mergedStatusName (Review by default) and becomes Done only when a release ships it.
releaseTrain.smallFixes { "maxFiles": 5, "maxChangedLines": 500 } absent: every fast one-off gets its own local review pass, and no landing gate applies From 3.23.0: a fast one-off within both limits (maxFiles changed files; maxChangedLines lines added plus removed), with no binary file, nothing on the high-risk list (release.productionReview.highRiskPaths plus release.releaseBranchFixExclusions) and nothing found by its risk check, is a small fix: it skips its separate local review pass, keeps its risk check and local gate, and the train's pull request is its full review. From 3.34.0 a one-off that is not a small fix gets its full review before it lands, on your machine: review runs in LOCAL-FULL mode (Claude plus the configured local CLI engine at merge-boundary depth, the full suite as its gate, no pull request and no CI run), and the merge commit records the cycles and every finding's disposition. From 3.35.0 the landing is checked by a review receipt recorded at exactly the branch's head, so any new commit, including one that resolves a conflict with the train, needs the review again; run it yourself with /devstride:review local-full <base>.
releaseTrain.reviewEveryLanding boolean false: a small fix lands with no review of its own and the train's pull request reviews it From 3.61.0: every one-off lands with its own LOCAL-FULL review receipt, sized to the change (smallFixes then only sizes the review: a small fix gets one cycle with a narrower Claude pass, and the local CLI engine runs on every one). The receipt's first line rides in the landing's merge commit, and a repository admin's devstride/landing-reviewed status on the reviewed commit proves it; a receipt line without that status counts for nothing. The train's pull request lists every item it carries with its receipt under Review evidence, runs no review round when every commit is covered (its pre-ship checks run and CI starts once), and otherwise reviews only what has no proven receipt. The production pull request's one highRiskEngine pass stays.
releaseTrain.lateArrivals "offer" or "restart" "offer" From 3.23.0: what happens to a one-off that lands while the train's pull request is under review. "offer" freezes the release at its cut: the late one-off joins it only when the owner says so, and otherwise ships with the next release. "restart" absorbs it and runs the review again over the whole snapshot, until the first ready-flip or three restarts.

Until 3.22.0 this block was called supportTrain (the support train, usually train/support). The old name, with all four keys under it, is still read when releaseTrain is absent, and /devstride:doctor notes it; a file carrying both is a config error. Train snapshots are named release-train-<date> and their pull requests are titled Release train:, so a repository whose merge rules admit only */*/support-train-* must add */*/release-train-* before updating.

The train ships only when release.mergeTrainBeforeCut is true: before each cut, release opens the train's pull request into the release source, runs the full review, the pre-ship checks and CI once, merges it, and marks every one-off it carried Done. A train configured without that key would never ship, so the loop bypasses it and routes one-offs to the base branch, saying why. A one-off whose change touches release.releaseBranchFixExclusions never rides the train either. A reviewed release unit may carry those paths onto the train (from 3.22.0): the release's exclusion check covers only work no pull request reviewed — fast-merged one-offs, direct commits and fixes on the snapshot. From 3.39.0 the review must be proven, not inferred from a branch name: a settled review posts a devstride/reviewed commit status on the final reviewed head, and the check accepts a release unit only when its merged head carries that status for that same pull request, posted by an account with admin permission on the repository. A unit without that proof is checked file by file like any other commit; units merged before 2026-11-10 00:00 UTC keep the older branch-name rule. Before any one-off merges onto the train, and before an epic releases, the loop also checks for a release hold on the item and its ancestors. Why: every merge into the base branch costs its own CI run and often a deploy; batching one-offs gives them one full review and one CI pass per release. The train is protected by this key alone — never rebased, amended or force-pushed — and release moves it forward after every release, by fast-forward or by merging the source into it.

Two optional sibling keys found in established configs are descriptive only: epicIntegrationBranches.example shows a sample branch name, and epicIntegrationBranches.fastStoryMerges.localEngines documents the expected local roster. The skills resolve actual behavior from the active settings and probes.

Powered by DevStride