On this page
Key Shape Default Purpose
review.localCommand string or null null Optional second local review engine. null means the built-in Claude pass is the only local reviewer. Naming it does not schedule it; see Delivery profile for where and how often it runs. The template may carry <context> (the skill substitutes - and sends the scope plus the cumulative ledger on stdin) or the older <base> placeholder (the ref the engine diffs against). A template with neither keeps working — --base is appended.
review.localAssistCommand string or null null A read-only second opinion the build engine may consult once for an ambiguous design, a critical contract, or a stubborn diagnosis. It is support, not a review round: it never writes, never satisfies the merge review, and never runs on routine work.
review.adaptiveReviewerWait boolean absent means true Stop waiting on a registered cloud reviewer once the wait passes that reviewer's learned latency — its 95th percentile plus a margin, learned per machine from GitHub's own timestamps — bounded below by the registration window and above by pollTimeoutMinutes, and the full timeout while the cache is cold. false pins the fixed bound. The cache is advisory, lives under ~/.cache/devstride-plugin/, and can be deleted to start cold. Setup never writes this key.
review.localReReviewScope "delta" or "full" absent means delta unless the scope rule decides otherwise The scope every follow-up cycle reviews — Claude, local CLI, and cloud alike, despite the key's local-sounding name. A follow-up reads only the changes since the previous cycle, falling back to the whole diff by a computed rule: a file the earlier cycle never touched, more than half of its lines rewritten, or a rebase. "full" pins them all to the whole diff. Setup never writes this key.
review.localEffort { "initial", "followUp", "safety" }, each a tier your CLI accepts, e.g. { "initial": "max", "followUp": "xhigh", "safety": "max" } absent: <effort> follows the task and risk route From 3.14.0: the reasoning tier the local engine's <effort> placeholder receives for each kind of round. initial is the first full round and any other full-diff run; followUp is an ordinary follow-up that reads only the fixes and the ledger; safety is a round checking the fix for a verified P1 or serious P2 (absent, it takes initial). A missing field falls back to the route. Values pass through verbatim, and each run records the tier and the field that chose it in the review ledger. Setup never writes it.
review.localReviewerName string "Codex" The name findings are attributed to in the roster and reports. Set it to whichever engine you configured.
review.automatedReviewers array [] Cloud reviewers to request. how: "requested_reviewer" (a bot requested through GraphQL by its node id) is the one request mechanism the review flow implements. Empty means no cloud wave and nothing to wait for. Each entry may be scoped to base branches and to a request policy — see Cloud reviewer entry.
review.openPullRequestsAsDraft boolean true Open pull requests as drafts in a draft-held repository.
review.readyForReviewReleasesCi boolean true Treat the ready flip as the action that releases CI.
review.ciHeldUntilReviewSettled boolean true Hold CI until review settles. All three ordering flags false means CI runs alongside review.
review.pollTimeoutMinutes number Per profile: 5 (prototype) or 10 (standard, extended); setup writes the profile’s value Bound on waiting for a cloud reviewer whose request has been proven registered (a review_requested timeline event). It does not cover the two-minute registration window — after which an unregistered reviewer is dropped for the run and reported — or the CI wait.
review.resolveAddressedThreads boolean true Reply to and resolve fixed, dismissed, or captured review threads.
review.notifyWhenSettled boolean absent means off Notify after a standalone settled review. Driven review never notifies.
review.mandatoryLenses {name, paths, question}[] absent or [] means none From 3.4.0: review lenses the repository forces on its own risk surface. A matched entry adds one focused finder to the story risk check and to the merge-boundary review, on the same footing as the forced security lens. See Mandatory review lenses. Setup never writes entries.

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?"
      }
    ]
  }
}
Field Meaning
name Kebab-case lens name. It labels the finder, its findings, and the report line.
paths Non-empty array of globs matched against repo-relative paths of the hand-written files in the diff under review. Globs are anchored path patterns, never bare substrings: **/events/** matches an events directory anywhere, while events alone matches nothing.
question What the finder must answer for every changed hunk in the matched files. It is the finder's base question, not a hint.

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.

The engine's result must be its findings or an explicit no-findings verdict. From 3.38.0 a crash, a kill, a timeout, a non-zero exit, or empty or unreadable output counts as a failed engine, never as "no findings", and a round in which no engine returned a result is never settled or merged. From 3.44.1 every launch has its standard input redirected (from the prompt file or /dev/null), so an engine can no longer hang waiting for input.

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, or per kind of round when review.localEffort is set; 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=\"<effort>\" -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 it has no way to receive the prior cycle's dispositions: a follow-up under the codex review --base form runs against the base without the ledger and is reported as degraded, and an older base-only template skips the follow-up rather than run it blind, with Claude's contextual check in its place. Either way the review points you to /devstride:setup review.

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.

Field Absent behavior Purpose
baseBranches Requested on every pull request From 3.7.0: a list of exact branch names. The reviewer is requested only on a pull request whose base, re-read from GitHub on every review run, is one of them — ["main"] keeps it on production releases and hotfixes while the local engines cover everything else. A reviewer left out is announced as not requested, never waited on, and never counted as a failed engine. If the local engine then fails on such a pull request, no independent engine has reviewed it, so review stops for a human review. A value that is not a list of names is treated as absent, and /devstride:doctor warns about an empty list.
requestPolicy "every-round": requested when the pull request opens and on every follow-up cycle From 3.8.0: "final-head" requests the reviewer once, when every other finding is settled, on the head about to release CI — and once more only after a fix commit that answered one of its own findings. A verified P1 or serious P2 still keeps opening cycles.
Powered by DevStride