Configuration Reference: .claude/ds-config.json

This page describes the repository contract for plugin v3.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.

Delivery profile

Four profile knobs also exist as keys of their own elsewhere in this file. A key that is present is the operator’s decision and always wins; the profile fills in only when the key is absent, and setup writes each key consistent with the profile it was told so a fresh config and its profile agree.

• epicIntegrationBranches.autoRelease — when absent, prototype supplies true and the other profiles false; setup writes the same.
• epicIntegrationBranches.fastStoryMerges.enabled — when absent or true, prototype runs fast mode whenever an integration branch exists; a present false wins and is reported. The other profiles follow the key.
• review.pollTimeoutMinutes — when absent, the profile supplies 5 minutes (prototype), 10 (standard and extended) or 20 (enterprise); setup writes the same.
• review.openPullRequestsAsDraft, review.readyForReviewReleasesCi, review.ciHeldUntilReviewSettled — these describe what your workflows support, not what a profile does with it. Review first and CI last is a floor under every profile, prototype included; setup writes all three as detected facts.

review.localCommand is different: it names the local CLI reviewer, it does not schedule it. A present command puts the engine on the roster, and it reviews every release pull request and every pull-request-path item under all four profiles — never a fast-merged item with no pull request, under any profile. The profile decides only how many rounds it gets at those boundaries: one under prototype, standard and extended, two under enterprise. null removes the engine everywhere.

/devstride:doctor reports the effective profile, its source, and any key that contradicts it — for example a prototype profile beside autoRelease: false, which is honored as configured and reported.

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.

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 support train are protected by their own keys, whether or not protectedBranches lists them.

Release-unit integration branches

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.

Support train

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. 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.

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.

Local environment

localEnvironment describes how the repository stands up an isolated local instance, if it can. The delivery skills read it; they never guess it.

{
  "localEnvironment": {
    "create": "git worktree add ../<name> -b <branch> <base> && docker compose -p <name> up -d",
    "recreate": "pnpm db:reset",
    "recreateMode": "inPlace",
    "instanceName": "cat .instance-name",
    "seed": "pnpm db:seed",
    "migrate": "pnpm db:migrate",
    "teardown": "docker compose -p <name> down -v",
    "instanceBoundTo": "directory",
    "fetchOnSessionStart": false
  }
}

recreateMode cannot be inferred from the command text — a wrapper script is opaque, and each wrong guess fails in its own way: an in-place command treated as a second instance leaves the session on the old database, while the reverse resets an instance somebody is using. instanceName matters for the same reason: nothing else in the block identifies the current instance, and guessing from a directory name resets a different one, which on a shared machine destroys someone else's data silently.

The shipped default is every command null and instanceBoundTo: "none". With that default, branch-hotfix asks before touching a database and build-item treats the current checkout as the only environment. Setup gathers candidates from compose files, devcontainers, Nix files and package scripts and asks — it never reports a command as detected, because a compose file proves a stack exists, not how your team starts it; and instanceBoundTo is always asked, because no file says whether a second checkout gets its own database.

This block tells the loop what exists — declaring an environment never makes the loop run builds concurrently. Whether two checkouts can be tested at the same time is a property of the repository, not of this block: where the test infrastructure is shared across checkouts, test execution stays serial regardless of what is configured here.

Deployment stage

stage describes the cloud environment this checkout deploys to. The loop only ever reads it — it never creates, changes, or tears a stage down.

{
  "stage": {
    "resolve": "cat .sst/stage",
    "productionStages": ["prod"]
  }
}

Most repositories have no stage, and null is the honest answer rather than a gap: doctor reports the block as not applicable rather than missing, and resolve: null records that somebody looked. Setup proposes a command from the shapes it finds — an SST, Serverless, Pulumi, or Terraform layout, or a *_STAGE variable — but never reports one as detected, because finding the tooling does not tell it how your checkout picks its stage.

Three consumers use it: /devstride:release names the stage at the production gate, so the owner approves a specific consequence; /devstride:branch-hotfix says which stage the checkout points at before touching a database and stops to ask when that stage is production; and the status line renders it, in red for a production name.

Status line

Whether the repository has a status line is not a config key: the presence of .claude/statusline.sh and a statusLine entry in .claude/settings.json is the whole state. /devstride:setup offers to write both. The optional statusLine block covers two other things.

The line renders Model · Effort · Repo · Checkout · Branch · Stage · PR and omits any segment it has no value for — label, value, and separator together — so a repository with no stage never shows a dangling Stage:. The script is repo-agnostic and identical everywhere, reading your config at runtime, so re-copying it is always safe. Line 2 carries a # ds-statusline: managed v<x.y.z> marker; deleting that line is the supported way to take the file over, and nothing replaces it afterwards.

Because a shared project setting outranks a personal one, a repository status line wins over a statusLine in your own ~/.claude/settings.json. Override it for yourself alone in .claude/settings.local.json.

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.

Mandatory review lenses

The adversarial fan-out ships five generic lenses and forces exactly one of them, security, on any diff touching the authentication boundary. Every repository has at least one more surface where the same reasoning holds — transactions and durable events under a rolling deploy, money-moving code, a permissions matrix — and the plugin cannot know which. From 3.4.0, review.mandatoryLenses lets the repository name that surface and the question a finder must answer over it.

{
  "review": {
    "mandatoryLenses": [
      {
        "name": "concurrency-and-rolling-deploy",
        "paths": ["backend/src/**/*transaction*", "backend/src/**/events/**", "backend/migrations/**"],
        "question": "For every changed hunk: what ordering or isolation assumption does it make; what happens under READ COMMITTED; what happens while old and new revisions run side by side during a rolling deploy; which claim in the change summary cannot be proven from test or command output?"
      }
    ]
  }
}

When a file in the diff matches an entry, ultracode-build's story risk check and the merge-boundary adversarial review each add one focused finder for it, carrying the entry's name as its lens and its question as its base question. It sits on the same footing as the forced security lens: the breadth ceiling and the delivery profile clamp generic finder breadth and never remove it. Findings are verified like any other — a mandatory-lens finding is not automatically P1; severity comes from the verdict. When review.localCommand uses the <context> substitution, the local engine receives each matched question as an additional hypothesis, never as a finding. Each matched entry is reported as mandatory lens <name>: ran (N findings); an entry that matched nothing is not mentioned, because "did not apply" is a different fact from "ran and found nothing". A malformed entry — missing name, paths, or question, or a non-array paths — is named once and ignored. /devstride:doctor validates entry shape and warns on a glob that would match every file. Setup mentions the key and never writes entries: only the repository knows its own risk surface, and the example above is a shape, not a recommendation. The contract is skills/ultracode-build/references/mandatory-lenses.md in the plugin repository.

Choosing a local review engine

The local reviewer is not tied to any vendor or model. review.localCommand is a command line, and an engine qualifies when four things hold:

1. its first token resolves on PATH;
2. it accepts the review prompt — on stdin via <context> (preferred: every cycle receives the exact scope plus the cumulative ledger) or against a diff base via <base>;
3. it writes its findings to stdout;
4. it can run read-only, so the reviewer never edits the tree.

Grok, Gemini, DeepSeek, and open-weight models served locally through a runner such as Ollama are all capable of this role, as is anything reachable through an OpenAI-compatible endpoint. Name your CLI when /devstride:setup asks and it is probed, validated against the contract above, and recorded for your repository. /devstride:doctor then holds it to the same contract — it never reports an engine as wrong merely for being one it does not recognize.

Two rules apply whatever the engine. Disable any agent tooling the CLI loads by default, the DevStride MCP above all: a reviewer that can reach live project data can wedge mid-review and return a clean, empty result that reads exactly like "no findings". And leave model choice to your own policy where the CLI supports it, rather than hardcoding one.

Codex is what setup offers when nothing else is chosen — a leading model whose template is verified — as a default, not a requirement:

{
  "review": {
    "localReviewerName": "Codex",
    "localCommand": "codex exec --ephemeral --sandbox read-only -c model_reasoning_effort=\"<effort>\" -c mcp_servers.devstride.enabled=false <context>",
    "localAssistCommand": "codex exec --ephemeral --sandbox read-only -c model_reasoning_effort=\"<effort>\" -c mcp_servers.devstride.enabled=false <context>"
  }
}

<context> is replaced with -, and the skill sends the exact review scope plus the cumulative ledger of prior findings on stdin — which is what lets a follow-up cycle check whether a fix held instead of starting cold. <effort> is routed per task; the template deliberately omits --model, leaving model choice to your own policy. Read-only sandboxing and the disabled DevStride MCP are both load-bearing: leaving the MCP enabled can wedge the review and look like a clean, empty result.

For structured Codex review output, the catalogue also supports base mode:

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

<base> receives the pull request's actual base, and a template with no placeholder gets --base <value> appended. Base mode can run the first cycle, but a follow-up is skipped rather than run blind, because it has no way to receive the prior cycle's dispositions.

Setup and Doctor check both local command templates against the plugin's review-engine catalogue. A known engine missing its read-only flag fails with the required correction; a command that disables or widens the sandbox fails too. An unknown engine is reported as UNVERIFIABLE, not certified read-only. The codex review form uses -c sandbox_mode=read-only; it does not accept the codex exec flags --sandbox or --ephemeral after the subcommand. Base mode has no stdin context or cumulative ledger. Setup explains that tradeoff before proposing migration and does not propose it when only one local review round is configured.

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.

Two optional fields decide when a reviewer is asked. Both exist because a cloud reviewer is often billed per review, and requesting it on every round of every pull request is what drives that bill.

Pull requests, commits, and repository guidance

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

If the repository is public and you would rather no tracker numbers reach its commit history, set itemTagFormat to ""; no item tag is then added to any commit subject, and the key already tolerates the empty value.

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.

The draft hold makes CI run once per pull request; the rest of a CI bill comes from superseded runs, production-branch pushes re-testing a tree the base branch just tested, and release pull requests re-run by a moving base. /devstride:setup ci applies the four workflow mechanics that remove those (the draft gate, per-pull-request concurrency with cancel-in-progress, a tree-identical skip on production-branch pushes, and a draft-convention check for humans) as reviewed diffs, and /devstride:ci-audit measures the result — executed runs and minutes, never raw run counts.

Production release

Post-deploy health check

The plugin does not know what "healthy" means for your production system — alarms, dead-letter queues, error rates, a synthetic transaction — so, exactly as with the documentation hooks below, it holds one fact: the name of a local skill that does. The release skill invokes that skill once, after the production deploy is confirmed and before documentation, release notes, and the close-out, as check followed by a fenced JSON payload of productionBranch, mergeCommit, and deployConfirmedAt.

The skill's first line must be exactly POST-DEPLOY HEALTH: PASS, POST-DEPLOY HEALTH: FAIL, or POST-DEPLOY HEALTH: NOT RUN, followed by evidence lines that each name the command that produced them. PASS continues and carries the evidence into the close-out. FAIL stops the release and asks the owner for a rollback decision — it never continues to documentation or notes on its own. NOT RUN (missing credentials, an unreachable endpoint) is reported as this-run degradation and the owner is asked whether to proceed; it is never a substitute for FAIL. /devstride:doctor checks that a configured name resolves to an existing skill. The full contract is skills/release/references/post-deploy-check.md in the plugin repository.

Documentation hooks

The plugin never edits documentation itself. /devstride:setup asks where your documentation lives, how it is updated, and how release notes are pushed, then scaffolds the two local skills from its templates and writes only their names here. Each skill accepts update (docs) or publish / draft (notes) with a structured delta payload, and a read-only check mode that setup and doctor run. Core documentation is updated by default on every production release (no docs suppresses it); release notes are written only when you pass --release-notes, and only after the production merge is confirmed and the deploy verified — nothing in the loop decides that a release deserves a note.

release.docsRepo (versions before 1.0.0) is deprecated: the release skill reports it and runs without docs; /devstride:setup docs migrates it into a local skill.

Plugin updates

plugin controls the session-start version check.

The check reads the version the running session loaded, not the version on disk, so it reports exactly the drift claude plugin list cannot see. It never blocks a session and never fails one. To update on demand, run /devstride:update, which resolves the exact installation that loaded it and verifies the result. After a verified change, /reload-plugins is usually enough; restart only if reload is unavailable or fails. Set the environment variable DEVSTRIDE_PLUGIN_UPDATE_CHECK=0 to disable it for CI or headless runs. /devstride:doctor reports when it last ran and what it found.

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.

Session boundaries and deferred defects

The session gate allows one build loop to work through multiple stories. For an intentional exception, pass --same-session, set session.jobClassGate: false, or set DEVSTRIDE_SESSION_GATE=0. The hook fails open on errors.

Deferred defects link back to the reviewed item. They have no execution-order prefix, dependency-chain splice or delivery phase; the loop neither selects them automatically nor treats their container as a release unit. Newly discovered scope that belongs in the active plan still goes through insert-story.