Guided Setup

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.

What setup does

1. Finds the git repository root and origin remote.
2. Detects the ecosystem, package manager, workspaces, and verify commands.
3. Inspects GitHub Actions draft gating and branch roles.
4. Finds coding-convention files, pull-request templates, and possible review engines.
5. Reads your DevStride hierarchy and asks you to confirm the release-unit and leaf roles.
6. Proposes how this checkout resolves its deployment stage, if it deploys one at all, and which stage names are production.
7. Asks only about unresolved choices.
8. Writes or merges .claude/ds-config.json.
9. Offers to scaffold the local documentation skills, and to give the repository a status line.
10. Runs validation against the file it wrote.

Detected values carry their evidence. Ambiguous values become questions with candidates; unknown values become open questions. One unambiguous repository fact is confirmed in a batch instead of being asked again individually.

The questions inspection cannot settle

Setup always confirms the work-type mapping because it determines where integration branches and releases occur. It also asks:

• what a merge to the production branch triggers, so /devstride:release can quote the real consequence at the owner gate;
• whether a sibling documentation repository should be updated during releases, including its path, branch, deploy behavior, default update policy, and release-note rule;
• whether the lessons store should use a path other than .claude/ds-lessons.md.

An explicit answer always wins over detection.

Exact write boundary

The status line renders Model · Effort · Repo · Checkout · Branch · Stage · PR, omitting any segment it has no value for — label, value and separator together — so a repository with no deployment stage never shows a dangling Stage:. 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. 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.

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:

• baseBranch and release.releaseSource, where normal work lands and releases start;
• release.productionBranch and hotfixBaseBranch, where production releases and urgent fixes are based.

Setup recognizes exact common names among those existing branches:

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.

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 profile plus profile-consistent defaults. The four choices are prototype, standard (the default), extended and enterprise. epicIntegrationBranches.autoRelease starts as false under standard, extended and enterprise, so a completed release unit stops at release-ready until an owner deliberately enables automatic release; under prototype it starts as true, and setup says so out loud when it writes it.
• Under standard, extended and enterprise, fast item merges are enabled when both verify.typecheck and verify.test are set; otherwise each item keeps its own pull-request path, and setup names the missing verification command. Under prototype they are enabled whenever verify.typecheck is 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, and preCommitWiringChecks start 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 records lessonsDoc but never creates the lessons file. review is its only writer.

What validation proves

After writing, setup checks:

• 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 authenticated gh with write access;
• every declared local or cloud review engine prerequisite;
• 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.

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.

Re-run and validate modes

Re-running /devstride:setup re-detects the repository and proposes only changes. 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

For read-only inspection of one detector, use ecosystem, verify, ci-inspect, branches, or engines. Two narrowed modes write, each only the keys its own questions answer: docs (the documentation hooks, and the local skills it scaffolds) and ci (the CI-cost mechanics, applied to your pull-request workflows as diffs you accept one by one):

/devstride:setup ci

A detector-only run reports its findings and stops; it never writes a partial config.

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, and merge gates.

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:

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.

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

Checks added in 3.5

Setup checks whether HEAD matches the existing configuration's base branch and offers to switch before inspecting a stale checkout. Setup and Doctor also verify the configured local review commands' read-only flags; known unsafe commands fail with a correction, while unknown engines are marked unverifiable. See Choosing a local review engine.

Choose epicIntegrationBranches.autoRelease: "ask" to approve each completed release unit individually. After setup or planning, run /clear before starting execution. The session and deferred-defect settings describe those defaults.