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. Asks only about unresolved choices.
7. Writes or merges .claude/ds-config.json.
8. 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

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

• epicIntegrationBranches.autoRelease starts as false. A completed release unit stops at release-ready until an owner deliberately enables automatic release to the base branch.
• Fast item merges are enabled only when at least one local review engine is present and both verify.typecheck and verify.test are configured. Otherwise each item keeps its own pull-request path.
• 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 docs-repository block may be removed only after you explicitly say it no longer applies.

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, branches, engines, or docs:

/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 report fixes; doctor never applies them.

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