Configuration Reference: .claude/ds-config.json

This page describes the repository contract for plugin v0.9.0. The file lives in the consuming repository, and its values override the plugin’s inline fallbacks.

The easiest way to create it is:

/devstride:setup

Every setting is optional at runtime, but setup writes explicit values so important behavior is visible and reviewable. Re-run /devstride:setup validate after a hand edit.

Branches

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:

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.

Release-unit integration branches

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.

Verification

With no typecheck command, push asks instead of guessing. With no test command, setup disables fast merges; if fast merges were enabled manually anyway, the item would have review but no local test gate.

Conditional cloud suite entry

{
  "name": "e2e-matrix",
  "alwaysRunWhenBase": ["productionBranch"],
  "manualTriggerLabel": "run-e2e",
  "runWhenChangedPaths": ["apps/web/**", "packages/e2e/**"],
  "ciChecksByBase": {
    "baseBranch": ["E2E (PR gate)"],
    "productionBranch": ["E2E (full matrix)"]
  }
}

An empty verify.skipDuringStoryBuilds means no slow cloud gate exists and no absent check should be awaited.

Local pre-ship checks

preShipChecks is an array of suites that run locally at a pull-request or production-release boundary and never appear in CI:

{
  "name": "integration-suite",
  "pathGlobs": ["packages/api/**", "migrations/**"],
  "command": "pnpm test:integration",
  "when": "perPr",
  "timeoutNote": "About 25 minutes; do not run beside another test process."
}

Entries run sequentially in array order. A red per-PR check blocks the pull request. A release check can be waived only by the owner, with the waiver recorded.

Keep a suite in exactly one place: verify.skipDuringStoryBuilds for cloud CI, or preShipChecks for a local ship-boundary run.

preCommitWiringChecks is a string array of repository-specific wiring checks the build loop expects before commits. Setup leaves it [] because only the repository can name these checks.

Generated artifacts

Generated files are regenerated and committed separately; they are never fixed by hand.

Review and CI ordering

Mixed draft-ordering booleans are unsupported but safe: the skills use the strictest behavior and report the mix.

Local Codex example

This is the DevStride repository’s command shape, not a universal default:

"localCommand": "codex exec review --base <base> -c model_reasoning_effort=\"xhigh\" -c mcp_servers.devstride.enabled=false"

The <base> placeholder is replaced with the review base. The reasoning flag pins the maximum tier. Disabling the DevStride MCP inside the isolated Codex review is load-bearing for this setup: leaving it enabled can wedge the review and look like a clean, empty result.

Cloud reviewer entry

{
  "name": "Copilot",
  "bot": "copilot-pull-request-reviewer[bot]",
  "how": "requested_reviewer",
  "value": "copilot-pull-request-reviewer[bot]",
  "graphqlBotId": "BOT_kgDOCnlnWA"
}

Each reviewer needs the identifiers required by its how mechanism. The skills iterate the full array. An incomplete entry can fail silently because GitHub may accept a request without registering a review event.

Pull requests, commits, and repository guidance

The lessons file is repository data. If it is created, make sure its path is not ignored.

DevStride hierarchy roles

Setup reads the real work-type hierarchy and asks you to confirm these roles. A configured type that no longer exists stops delivery; silently falling back could route planned work directly to the base branch.

GitHub Actions description

For draft-held ordering, workflows must also subscribe to opened, synchronize, reopened, and ready_for_review.

Production release

The release skill discovers navigation, content locations, routes, and release-note placement from the docs repository itself.

Validate changes

After editing:

/devstride:setup validate
/devstride:doctor

Setup validates the config’s commands, branches, tools, engines, roles, lessons path, and CI consistency. Doctor checks the surrounding installation and reports exact fixes without changing anything.