Guided Setup
How /devstride:setup detects repository settings, writes one config file, and validates the delivery loop.
On this page
Guided Setup#
In the DevStride repository
The repository's configuration is already committed, so
/devstride:setupis rarely needed there: re-running it merges only what changed and keeps hand edits, and/devstride:setup validatechecks the existing configuration. Setting up a machine is a different command,./setup: see Set up your machine.
Run this after installing the plugin and connecting DevStride:
/devstride:setup
Setup’s job is to produce a repository-specific .claude/ds-config.json from evidence, not guesses, and prove that the resulting commands and branch roles work.
Before you start#
- A git repository with an
originremote. Setup checksoriginby name, because the delivery skills use that name. The delivery half assumes GitHub and GitHub Actions; on any other host setup says so plainly, and planning still works. - The GitHub CLI, signed in with write access. Validation fails without an authenticated
ghthat can push to the repository, because the loop cannot push, open a pull request or merge without it. python3on yourPATH. The config shape check, the status line and the Active Agents mode run small Python scripts that ship with the plugin.- A DevStride connection. The bundled server offers no tools until you sign in through
/mcp. Without it, setup offers two paths: write the config now without the work-type roles (reported as a required follow-up), or stop and resume after you sign in. It never guesses the roles. - A checkout on the right branch. When a config already exists and HEAD is on a different branch from its base branch, setup says so and offers to switch before it inspects anything, so it does not describe a stale branch over the maintained config.
What setup does#
- Finds the git repository root and
originremote, and records the forge host. - Detects the ecosystem, package manager, workspaces, and verify commands.
- Inspects GitHub Actions draft gating and branch roles.
- Finds coding-convention files, pull-request templates (wherever GitHub looks for them), and possible review engines.
- Looks for local-environment tooling (compose files, dev containers, seed and migrate scripts) and proposes the commands that create, recreate, migrate, seed and tear down this checkout's local instance.
- Proposes how this checkout resolves its deployment stage, if it deploys one at all, and which stage names are production.
- Reports what it found, then reads your DevStride hierarchy and asks you to confirm the release-unit and leaf roles.
- Asks only about unresolved choices.
- Writes or merges
.claude/ds-config.json. - Offers to scaffold the local documentation skills, and to give the repository a status line.
- Runs validation against the file it wrote.
Detected values carry their evidence. Ambiguous values become questions with candidates; unknown values become open questions. Detected values are confirmed in one batch, each with its evidence, instead of being asked about one by one.
The questions inspection cannot settle#
Setup always confirms the work-type mapping because it determines where integration branches and releases occur. It also asks, on every run:
- which delivery profile the repository runs (see below);
- what a merge to the production branch triggers, so
/devstride:releasecan quote the real consequence at the owner gate; - where your documentation lives (a directory here, a sibling checkout with its path and branch, a hosted service, or nowhere), how it is updated and published, and how release notes are pushed, then the names for the two local documentation skills and, optionally, a deploy-verification command that succeeds only once production serves the release commit;
- whether to give the repository a status line;
- from 3.62.0, when no board placement rules are set yet, which board each kind of item goes on when work on it starts (the same questions as the
boardsmode below; declining leaves it unset); - whether the lessons store should use a path other than
.claude/ds-lessons.md.
Setup also asks how this checkout's local instance relates to it (one instance per directory, per branch, or none) and, when the recreate command names an instance, whether it resets that instance in place or makes a new one. These are never detected.
An explicit answer always wins over detection.
Exact write boundary#
What setup may write
.claude/ds-config.jsonalways, and only what you accept beyond it: the documentation skills it scaffolds under.claude/skills/(never over an existing one); a repository status line (.claude/statusline.shplus astatusLineentry merged into.claude/settings.json); in/devstride:setup cionly, changes to your pull-request workflows and the optionalrelease-towercheck files, each offered as a diff you review; in/devstride:setup agentsonly, the Active Agents board, tag and shared view in DevStride, after a typed yes; and in/devstride:setup boards personalonly, your own board placement rules, in a file outside the repository.It does not edit code,
AGENTS.md,CLAUDE.md,.gitignore, Claude permissions, git config, or branches, and it never moves, edits or removes a DevStride item. It never installs or updates tools, and it never overwrites an existing.claude/statusline.sh.
The status line renders two lines of segments, each led by a symbol. Line 1 says where you are: model, effort, repository, checkout and branch. Line 2 says what is in flight: the plugin version this session runs, the deployment stage, the branch's pull request and any release in progress, and it prints only when something is on it. A segment with no value is omitted — symbol, value and separator together — so a repository with no deployment stage never shows a dangling stage marker. Checkout distinguishes the main checkout from a linked worktree, which matters because release-unit integration branches put work in worktrees. Stage appears only where a stage was configured, and turns red for a name you listed as production. The plugin segment is dim while current, and tells you when a newer copy is installed (/reload-plugins) or published (/devstride:update). The bar redraws every 30 seconds. Because the setting lives in the repository's own .claude/settings.json, it outranks any personal status line in ~/.claude/settings.json; use .claude/settings.local.json to override it for yourself alone.
After writing the status line, setup runs it once to prove it prints something, then asks about the one segment whose absence is ambiguous: the stage. Your answer either writes stage.resolve or records the segment in statusLine.hiddenSegments so nobody asks again; an unanswered question writes nothing. The script carries a "managed" marker line, which lets the session-start hook bring an older copy forward when the plugin ships a newer one (statusLine.autoUpdate, default on); delete that line to take the file over for good. See Status line.
Inspection and interviewing are read-only. The repository’s own verify commands run during validation and may themselves create caches, regenerate files, or format code; setup asks before running a command that looks mutating and reports if the tree changes.
How branch roles are detected#
The plugin has fixed no-config fallbacks—develop for normal work and release source, master for production and hotfixes—but setup does not blindly write those names. In a git repository with an origin remote, it enumerates the branches that actually exist and confirms remote-only or cached evidence before proposing four explicit settings:
baseBranchandrelease.releaseSource, where normal work lands and releases start;release.productionBranchandhotfixBaseBranch, where production releases and urgent fixes are based.
Setup recognizes exact common names among those existing branches:
| Likely role | Exact candidates |
|---|---|
| Development or pre-production | develop, development, staging, stage, canary, test, testing, qa |
| Production | main, master, production, prod |
| Single trunk | trunk |
One development candidate and one production candidate form a proposed pair. If several names match either role—for example both main and production—setup shows the candidates and asks; list order is not a ranking. A lone staging, canary, test, or QA branch is never promoted to production by name alone. Matching is on the whole branch name, so production-fix is not mistaken for production.
origin/HEAD helps identify the repository’s ordinary pull-request base, but it does not prove which branch deploys. An explicit answer or existing config always wins. protectedBranches always includes the base, production and release-source branches.
Doctor applies the same read-only detection when an absent branch setting falls back to a ref that does not exist. It prints the exact mapping setup would propose, but never edits the config. An explicit configured branch that does not exist is reported as invalid rather than replaced by a naming guess.
Cautious decisions setup makes#
- Setup asks which delivery profile the repository runs and writes
profileplus profile-consistent defaults,standardincluded. The three choices areextended(the default from 3.49.0, offered first),standardandprototype; a configuration with noprofilekey is told that the default moved and thatstandardkeeps the finer grain; the retiredenterpriseis read asstandard, and setup says so. The profile moves three keys:epicIntegrationBranches.autoRelease,epicIntegrationBranches.fastStoryMerges.enabledandreview.pollTimeoutMinutes(5 minutes underprototype, 10 otherwise). epicIntegrationBranches.autoReleasestarts asfalseunderstandardandextended, so a completed release unit stops at release-ready until an owner deliberately enables automatic release; underprototypeit starts astrue, and setup says so out loud, naming the branch, when it writes it. You can instead answerask, which no profile produces: the loop then asks the owner once per completed release unit.- Under
standardandextended, fast item merges are enabled when bothverify.typecheckandverify.testare set; otherwise each item keeps its own pull-request path, and setup names the missing verification command. Underprototypethey are enabled wheneververify.typecheckis set. Every fast-merged item still gets the build engine’s risk check and a green local gate; a local CLI reviewer is optional support, not a precondition. verify.skipDuringStoryBuilds,preShipChecks, andpreCommitWiringChecksstart empty. Setup does not invent expensive or repository-specific gates.- No detected local CLI means no second local CLI; no confirmed cloud reviewer means no cloud reviewer. The built-in Claude adversarial pass remains available. Setup always offers to name a local review engine it did not find.
- Setup records
lessonsDocbut never creates the lessons file.reviewis its only writer. - The
pluginblock is written asupdateCheck: true,autoUpdate: true,pin: null, and thesessionblock turns on the job-class gate, which stops one session from mixing authoring and execution commands. After setup or planning, run/clearbefore starting execution (it ends the session, giving up anything it holds, such as a checkout lease), or pass--same-sessionto one command to proceed in the same session. The session and deferred-work settings describe those defaults. - The
stageandlocalEnvironmentblocks are written even when every value isnull, because an absent block reads as "nobody asked".
What setup leaves for you to set#
Some settings change how work is sequenced across machines, how releases reach production, or how the loop is tuned. Those are your decision, so setup never asks about them and never switches one on: each stays absent or null until you add it by hand. Add what you need, then run /devstride:setup validate:
- Release coordination:
release.clearance(one release in flight at a time),releaseTower(the override label and hotfix pattern therelease-towercheck reads),release.autoStart.enabled,release.backstop,release.lightRelease.standingYesandrelease.fullRelease. See Release clearance, Releases that start themselves and Release backstop. - Story claims: the
claimsblock, so two agents never build the same story. See Story claims. - Session presence: the
presenceblock,{ "command": "<your command>", "intervalMinutes": 5 }. When it is set, the plugin's hooks run your command for every session — at start, on prompts, when a turn finishes and Claude waits for you, every interval from a small background keeper while the session lives, and at session end — with the event, state, session, machine, checkout, branch and item number in its environment. The plugin contacts no tracker itself; what a report means and where it is stored is your command's business. Absent, nothing runs. - Release branches and the release train:
release.releaseBranchPattern,release.releaseBranchFixExclusions,release.syncWorkflow,release.mergeTrainBeforeCut,release.migrationRenumber,release.devDeployVerificationandreleaseTrain.*. - Release hooks:
release.classifySkill,release.preMergeSkill,release.postDeployCheckSkill(Post-deploy health check),release.deployApprovalanddocs.knowledgeBaseSyncSkill. - The checkout pool:
pool.checkoutandpool.checkin, both or neither. See Checkout pool. - Tuning:
profileOverrides(pin one knob under a profile) andreview.localEffort.
The activeAgents block is the one exception: /devstride:setup agents writes it for you (see below).
What validation proves#
After writing, setup checks:
- the file's shape against the JSON Schema the installed plugin publishes: a wrong type, a value outside its allowed set, both forms of
release.clearanceor a retired key fails, and an unknown key is a warning that suggests the key you probably meant (keys your own tools read go inrepoLocalKeys; see The published schema); - every typecheck and lint command; tests are offered, never forced;
- the base, release-source, production, and hotfix branches, including their remote refs;
- the required GitHub toolchain:
origin, GitHub, and an authenticatedghwith write access; - every declared local or cloud review engine prerequisite, including that a catalogued local review command carries its read-only flag; a known unsafe command fails with a correction, and an engine the plugin does not recognize is marked unverifiable rather than failed (see Choosing a local review engine);
- the configured work-type roles against the connected organization;
- that the lessons store’s parent directory is writable;
- whether the configured CI ordering can actually settle after the ready-for-review flip: an expensive pull-request workflow without the draft hold fails, as does a draft-gated workflow whose triggers omit any of
opened,synchronize,reopenedorready_for_review; missing concurrency or production tree skips are cost warnings; - each named documentation skill exists and its read-only
checkmode passes; any deploy approval or verification command resolves, without being run; - with
release.clearanceset, its shape and a read-onlystatuscall.
Every check reports PASS, FAIL, SKIPPED, or UNVERIFIABLE. Setup runs all checks even after a failure and calls the repository loop-ready only when there are no failures. A skipped test or offline organization check is named rather than silently treated as a pass, and the verdict says when the working tree was dirty or the run was offline.
Re-run and validate modes#
Re-running /devstride:setup re-detects the repository and proposes only changes. A changed profile is proposed together with the three keys it moves, as one change; a hand-set value you keep is respected, and setup says the file now disagrees with its profile. Its deep merge preserves:
- keys it does not recognize;
- every
_-prefixed annotation; - any value it did not propose changing.
It does not normalize or replace the whole file. A documentation hook is cleared only after you explicitly say that documentation system no longer applies, and a pre-1.0 release.docsRepo block is migrated into a local skill only when you accept that change.
To validate an existing file without inspecting for a rewrite, asking questions, or writing anything:
/devstride:setup validate
| Argument | What it does | Writes |
|---|---|---|
| (none) | The full run: inspect, ask, write, scaffold, validate | .claude/ds-config.json, plus what you accept |
validate |
Runs validation against the existing file | Nothing |
ecosystem, verify, ci-inspect, branches, engines |
Inspects and reports one detector, then stops | Nothing |
docs |
Asks the documentation questions and the optional deploy-verification command, scaffolds the local skills, then runs the documentation check alone | The docs block, release.deployVerification, and the scaffolded skills |
ci |
Detects the CI-cost mechanics in your pull-request workflows and offers each missing one as an exact diff | Only the diffs you accept, plus ci.expectedRunsPerPullRequest if absent and the three review.* CI-ordering settings if you accept turning them on |
agents |
Sets up the Active Agents board, tag and shared view | DevStride, after a typed yes, and the activeAgents block |
boards |
Asks which board each kind of item goes on when work on it starts; boards personal asks only what differs for you |
The boardPlacement block after a typed yes, or, for personal, your own rules file outside the repository |
A detector-only run reports its findings and stops; it never writes a partial config. Use ci-inspect, not ci, for a read-only look at CI: the bare ci writes.
/devstride:setup ci#
/devstride:setup ci
This is the only mode that touches a workflow file. It looks for four mechanics in each pull-request workflow: the draft gate (every expensive job held while the pull request is a draft, with all four trigger types named), concurrency (a superseded run is cancelled), a skip on the production branch when its tree was already tested, and a courtesy check that tells a person who opens a non-draft pull request about the convention. For each mechanic that is missing, or present but inert, it shows the exact diff and applies only the ones you accept. If you accept a draft-gate diff while the three review.* CI-ordering settings are false, it proposes turning them on in the same change. It offers /devstride:ci-audit first, so you can measure before you change anything, and runs the CI checks from validation afterwards.
With release.clearance set, it also offers a fifth mechanic, release ordering: two files, .github/workflows/release-tower.yaml and .github/scripts/release-tower-check.mjs, which add a release-tower check to pull requests into the production branch. It passes a hotfix, the oldest open release pull request and one carrying the override label, holds a later release until the first merges or closes, and tells any other branch to retarget. Making it a required check on the production branch is your change, once it has posted green on one real release.
/devstride:setup agents#
/devstride:setup agents
The one setup mode that writes to DevStride, and it is opt-in. It shows which plans your agents are building on an Active Agents board. With no activeAgents block yet, it first asks for your repository's own start and end commands (the start command must contain <root>, which the loop fills with the plan root's item number). It then reads your organization, prints its name and every change it would make — the tag to create, each tag group's exact list before and after, the board to adopt or create, the view to create and the block to write — and acts only on a typed yes:
- Creates the agent active tag (green by default) if it is missing.
- Adds the tag to the tag group of every plan-root work type, always writing the merged full list, never only the new tag. A plan-root type with no tag group is reported and skipped.
- Adopts the configured board, or an existing board named "Active Agents", or creates one, asking once for the folder and status collection a new board needs.
- Creates a shared table view of the board named "Active Agents" with the columns Item, Status, Progress, Priority and Tags, copying the format of an existing view. When there is no view to learn from, it creates everything else and names the view as the one step left for you.
- Writes or merges the
activeAgentsblock, never overwriting your commands.
It never moves, edits or untags an item. A permission error stops it after reporting what was already done (tags and tag groups need MANAGE_LABELS). Running it again prints agents: nothing to change. From then on /devstride:build-item places each plan root it works under on that board and runs your commands as it starts and stops; /devstride:doctor agents checks the setup read-only.
/devstride:setup boards#
/devstride:setup boards
/devstride:setup boards personal
From 3.62.0 this mode says which board each kind of item goes on, so the build loop can put work there as it starts. It reads your organization — its work types, boards, teams, tags and custom fields — and never writes to DevStride or moves an item. It asks one question at a time, using your organization's real names:
- How your team works: on long-lived boards, in a folder of dated cycle boards, or a mix of both.
- Each kind of item: for every leaf work type and for your release unit, where an item of that type goes when work on it starts — a long-lived board, whichever cycle in a folder is running that day, or no board. It proposes an answer rather than assuming one: with cycles of two lengths, the longer cycles for the release unit and the shorter for the leaves. Types with the same answer share one rule.
- Exceptions: whether any work goes somewhere else, by team, tag, a custom field's value or the part of the plan it sits under. Each one becomes a rule ahead of the type rules, most specific first.
- Everything else: when a type is still unanswered, whether to add a last rule that catches it or to leave that type off boards.
It then checks the rules, prints them in plain words with where an item of each type starting today would go, and writes the boardPlacement block into .claude/ds-config.json only on a typed yes. A rule that fails its checks is fixed with you first. A cycle folder with no board covering today is reported but not refused, because only you can create that cycle's board. Running the mode again with nothing to change prints boards: nothing to change.
boards personal keeps one contributor's exceptions in a file of their own on that machine, outside the repository and shared by every checkout of it. Personal rules are read before the team's, so you state only what differs for you. They apply only when the repository has rules of its own, and they are never committed.
Work already on a board stays where it is; new work is placed as it starts. The rule shape and what the build loop does with it are in Board placement.
Setup versus doctor#
/devstride:setup validate proves the config file. /devstride:doctor checks the broader machine and repository state, including the installed plugin version, marketplace registration, DevStride connection, CI draft gate, merge gates, documentation skills, the Active Agents board and your board placement rules.
Both are designed to be re-run. Neither is a one-time step: /devstride:setup validate and /devstride:doctor write nothing until you accept something, so run them whenever config changes, whenever the loop behaves oddly, or simply at the start of a session.
Doctor runs in two phases. It diagnoses read-only and prints a finished report; then, in one batch with a single question, it offers the repairs it is allowed to make and re-verifies each by re-running the check that found it. Run non-interactively, it repairs nothing.
What it may touch is a fixed classification, not a judgment made in the moment:
| Tier | What doctor does | Typical findings |
|---|---|---|
| Repairs it | Writes the fix, then re-verifies. Every write lands inside this repository's .claude/, needs no network, changes no git state, and is undone by reverting a file. The one exception, asked about separately once the shared status line is committed, is removing a personal statusLine setting so the repository's takes over. |
A missing or half-configured status line; a status line set only in your personal settings; a segment with nothing to read from (it asks, then writes stage.resolve or records the segment as hidden). |
| Offers the command that owns the fix | Runs an existing command on your say-so, rather than reimplementing it. | gh not authenticated or missing a scope; a config that is absent or has branch roles that do not resolve; a localEnvironment or stage gap; a missing docs skill or a legacy release.docsRepo (/devstride:setup docs). |
| Reports only | Explains the fix and stops. | Workflow files, merge gates and branch protection, git state, DevStride records, anything on a deployed stage, an unrecognized config key, a conventionsDoc pointing at a missing file, a configured command that does not resolve, and more than one DevStride MCP server connected. |
Anything not named above is report-only. The boundary is the useful part: workflow files reach CI for everyone, branch protection affects every contributor, and a "correction" to a config key doctor merely failed to recognize would be a silent config change — so those stay decisions you make.
Doctor does not update the plugin
A plugin behind the newest release is reported, not fixed. Doctor tells you to run
/devstride:updateand stops, because that skill acts only on your explicit invocation. Session-startplugin.autoUpdateis the other path; doctor is not one.
Read next#
- Configuration Reference — every key setup may write or the skills may read
- The Planning Loop — create the first buildable plan
- The Delivery Loop — run one item through the configured gates