On this page

DevStride for Claude Code#

The devstride Claude Code plugin turns a DevStride roadmap into a delivery loop: plan the work, select the next unblocked item, branch, build, review, merge, update the item, and continue.

To understand why the loop is shaped this way before learning the commands, read The Idea Behind the Loop.

The current version, 3.45.0, ships thirty skills: twenty loop skills, and ten steps that each run one of your repository's own hooks. For what changed in each release, see Plugin updates. The source and release history live in devstride/claude-plugin.

Each skill states its goal, the rules that must hold while it works, and the hard floors that no profile, override or shortcut removes — rather than a numbered script to follow line by line. That is how every loop skill reads from 3.6.0; what each one guarantees did not change.

The shortest path to value

  1. Install and connect the plugin.
  2. Run /devstride:setup in your repository.
  3. Run /devstride:doctor to find missing tools, authentication, or CI wiring — it repairs what is safe to repair and hands you the exact command for the rest.
  4. Plan under an existing DevStride parent item with /devstride:plan I1234.
  5. Deliver one item with /devstride:build-item.

Run one item before using /loop /devstride:build-item to walk the whole plan.

Afterwards, /devstride:doctor is the one command to re-run regularly — it checks the repository prerequisites and reports any required repairs. To stop updating the plugin by hand, turn on marketplace auto-update; it is off by default for third-party marketplaces like this one.

The model in one minute#

The skills use three roles instead of assuming your work-type names:

  • A leaf is an executable item, such as a Story or Defect, sized by the delivery profile.
  • A release unit is the parent item whose completion produces a release pull request, usually an Epic.
  • A grouping item is any parent level above those, such as a Capability, Module, or Solution.

/devstride:setup maps your organization’s real work types to those roles and records repository-specific settings in .claude/ds-config.json.

When an item gets a pull request#

Item path What happens
Planned leaf on a release-unit branch, fast merges enabled A bounded risk check, local review and local checks, then a local merge onto the release-unit branch. No item pull request. The full review and CI run once, on the completed release unit's pull request.
Planned leaf on a release-unit branch, fast merges disabled The item gets a pull request into the release-unit branch.
Planned leaf with release-unit branches disabled or no release-unit ancestor The item gets a pull request into the repository’s base branch.
One-off created with create-story or create-defect, release train configured It lands on the release train, one long-lived branch — with releaseTrain.fastMerges, after local review and local checks with no item pull request; otherwise by a pull request into the train. On that fast path, with releaseTrain.smallFixes set, a small fix (within both limits, no binary file, nothing on the high-risk list, nothing found by its risk check) skips its own review pass, and one over a limit or on the high-risk list gets a full local review first — Claude plus your configured CLI engine, no pull request and no CI — recorded at its exact commit, which must be the commit that lands. On landing it moves to the merged status (Review by default). The train's own pull request into the base branch gets the full review and CI at the next release, and the item is Done only when the train reaches the base branch.
One-off with no release train, or one that touches deploy configuration or migrations The item gets its own pull request into the base branch.

The distinction matters: a one-off never uses a release unit's branch, even when it was filed under one — the create skills allow that — so its path is never inferred from ancestry. The train exists because every merge into the base branch runs paid CI and often a deploy; batching one-offs gives them one full review and one CI pass per release, as an epic's release pull request does. A one-off that touches deploy configuration or migrations stays off it because the train reaches production soon after it merges; such a change deserves its own pull request and an earlier deploy to a development stage. A release unit that went through its own full review may carry them on the train. Which branch an item lands on is decided by one runnable helper, skills/build-item/scripts/routing.py — see Where work lands.

A release unit's own release pull request goes to the base branch by default. Set epicIntegrationBranches.releaseTarget to the release train and finished units ride the train instead. A plan root whose description carries the line Release scope: plan sends each of its release units onto one plan integration branch (planIntegrationBranches.pattern), and the whole plan then goes, in one pull request, to wherever its release units would otherwise have gone, once nothing outside its Deferred container is left. Before any merge onto the train or the base branch, a release hold in the description of the item or one of its parents (Release hold: not before <date>, or Release hold: after <item> is live) keeps the work waiting on its own branch, and a release stops before cutting while any item it carries is held.

Review first, CI last — when your repo supports it#

In the shipped draft-hold configuration, pull requests open as drafts. Local and cloud reviewers settle first; marking the pull request ready releases CI on the final reviewed diff. A per-use cloud reviewer can be limited to pull requests into chosen branches (baseBranches) and asked only once, at the final reviewed head (requestPolicy: "final-head"). The DevStride repository configures no cloud reviewer: since October 14, 2026, Claude and Codex carry every review.

That ordering depends on your GitHub Actions workflows listening for ready_for_review and declining to run their gated jobs while the pull request is a draft. Repositories that configure all three draft-hold settings as false intentionally run CI alongside review instead. /devstride:setup detects the current shape, and /devstride:doctor reports mismatches without editing a workflow.

Choose a delivery profile#

One setting decides how much rigor the loop spends on each item: how finely a plan is sliced, how deep each spec goes, how wide the adversarial review fans out, how many local review rounds run, and which local checks gate a merge. Those knobs are coupled — coarse items with a wide review fan-out cost more than fine items would — so you pick one word and they move together.

  • prototype — a small team validating an idea, with no production users yet, where a small error is cheap.
  • standard — a working product cut into finer items; the middle ground. It was the default before 3.49.0.
  • extended — the default from 3.49.0: a working product built as fewer, larger items. It buys size, not lower rigor: only the size-shaped knobs move — leaf size, spec depth, how many readers the build engine fans out, and how wide the merge review may go. Every safety knob and every floor is exactly standard’s.
prototype standard extended (default)
Leaf size One vertical slice a user can see or use; scaffolding folds into the first slice that needs it Roughly one to two loop-hours: one contract or subsystem change with its tests Roughly one release-unit-day: a full subsystem or workflow with its own tests, sized so a build agent runs unattended for hours; foundation work sits inside the item that needs it
Spec depth Goal, acceptance criteria, files touched, Definition of Done — about 1,500 characters The full leaf template, capped near 5,000 characters The full leaf template, uncapped
Readers the build engine fans out to understand the item None — it reads the relevant files inline Up to 2, only for angles the spec does not pin Up to 4
Widest adversarial review Narrow, plus the security lens whenever the diff touches an auth boundary Contained; high-risk only when the item’s own diff touches an auth boundary or a migration High-risk whenever the item warrants it — a multi-hour, multi-module diff held to contained would get a standard item’s finders
Local CLI reviewer rounds at a merge boundary 1 1 1
Normal adversarial review cycles 2 2 2
Local gate before a merge Type-checks plus the touched test suites; the full suite runs at the release pull request Type-checks plus the touched test suites; the full suite runs at the release pull request Same as standard
Wait for a registered cloud reviewer 5 minutes 10 minutes 10 minutes

From finest to coarsest leaf size the order is standard, prototype, extended.

Shape targets (from 3.49.0). Each profile also has a usual plan shape: how many Stories an Epic holds and how many Epics a Capability holds. prototype: 2 to 4 Stories per Epic, 2 to 4 Epics per Capability. standard: 3 to 8 and 3 to 7. extended: 2 to 5 and 3 to 7. They are starting points drawn from one team's plans, not settings. /devstride:plan quotes them when it proposes Stories, asks once before keeping an Epic above its range, and reports the plan's shape against them at the end; /devstride:rebalance reports the same. Nothing refuses or blocks a plan for missing a range.

The enterprise profile is retired (plugin 3.12.0). Its grain cut work into pieces so small that review and merge ceremony cost more than the error exposure they removed, and every one of its rigor settings is still available as an override on extended or standard: profileOverrides with fixFloor: "all-confirmed", storyVerify: "full", maxLocalReviewRounds: 2 and understandReaders: 6, plus review.pollTimeoutMinutes: 20. A configuration or plan marker that still says enterprise is read as standard, and every skill says so in its first line rather than switching silently.

A configured local CLI reviewer runs at merge boundaries — a direct pull request or a release pull request — and not on a fast-merged item that has no pull request, under any profile. The one exception is a one-off over the releaseTrain.smallFixes limits, which gets a full local review, CLI reviewer included, before it lands on the release train. The rounds above are its budget within the normal cycle target.

Some floors hold under every profile, and no override removes them:

  • Every item gets a bounded self-check and a green local gate before it merges.
  • Changes to authentication, migrations, irreversible state, or deployed contracts get immediate focused verification, even on a fast-merged item. A security finding is always verified by its own agent, never batched with others.
  • Full adversarial review runs at the merge boundary rather than twice per item: a direct item pull request is a boundary, and otherwise the release pull request reviews the batched full diff with every configured engine before CI.
  • Two adversarial cycles is the normal target, not a safety cap. After it, a verified P1 — or a serious P2, meaning likely to occur and material if it does — opens another cycle, and that repeats until a cycle finds none. No numeric target can stop those safety cycles.
  • Every follow-up reviewer receives the cumulative ledger of prior findings, verdicts, dispositions and fixes, so settled findings are not rediscovered or reversed.
  • Review comes first and CI last, on the final reviewed diff, in every repository whose workflows support the draft hold.

Set the profile once with /devstride:setup, which asks for it and writes "profile" plus matching defaults into .claude/ds-config.json, or add the key by hand. A plan can carry its own choice: /devstride:plan I1234 prototype writes a Delivery profile: marker line into the root item’s description, and that marker wins over the repository’s profile setting for everything under it. With no profile anywhere, the loop runs extended from 3.49.0 (standard before). To keep the finer grain, set "profile": "standard". /devstride:doctor reports the effective profile, where it came from, and any config key that contradicts it.

One item, end to end: a worked example#

Suppose your DevStride organization has a Capability I2000 — Webhook intake, your repository is set up, and the plugin is connected. The loop looks like this.

1. Plan. You run /devstride:plan I2000 standard. The skill reads what already sits under I2000, then asks: what source material exists, what is in and out of scope, where the release boundaries fall, what must ship first. You answer that signature verification must land before any retry logic. It shows a proposed hierarchy and creates nothing until you approve it:

I2000  Capability  Webhook intake
└─ I2010  Epic   Verified intake                    ← one release unit
   ├─ I2011  Story  [1] Verify webhook signatures
   ├─ I2012  Story  [2] Persist accepted payloads
   └─ I2013  Story  [3] Retry failed deliveries     (blocked by [1] and [2])

Every Story has blocked_by/blocks links, dates cascade from them, and the root's description carries Delivery profile: standard. You /clear, because planning and building are different job classes and the session gate keeps them apart.

2. Build the first item. You run /devstride:build-item. It fetches origin, selects I2011 as the only unblocked leaf (with a claims block configured, it first claims the item, so another agent that also claims, on any machine, skips it), moves it to In Progress, and cuts the Epic's integration branch (jane/26-10-06/epic-I2010-verified-intake) off your base branch, then I2011's own branch off that. ultracode-build reads the spec against the real code, implements it in small green commits, and runs the risk check — the diff touches an authentication boundary, so the security verifier is forced. Your configured local gate runs. With fast merges on, the Story merges onto the Epic branch with no pull request of its own; the item moves to Review with a comment naming the merge commit and what actually shipped, and, if what shipped differs materially from the description, the description is rewritten to match what was built (the original is kept in a comment, and any Knowledge Base spec linked to the item gets a note of the change). It becomes Done when the Epic's release pull request merges. If the change could add billable infrastructure, remove something callers still use, remove someone's access, or break a published interface, the loop also posts an internal notice on the item that mentions its author — a notice, never a gate. The handoff ends with two lists: what the loop did, and what you must do (nothing, this time).

3. Keep walking. /loop /devstride:build-item repeats that for I2012, then I2013 once both blockers have merged onto the Epic's branch. Along the way a reviewer notes a logging gap that is unlikely to matter; it is dismissed with a one-line reason in the merge commit, and nothing is filed. Had it been worth filing (a P1, a security finding, or one both likely to happen and material) and deliberately put off, it would have been filed in the plan's Deferred container — a bug as a Defect, any other follow-up as a Story — related to I2013, outside the chain. Deferred items are never built by the loop unless you name one, and the plan's closing report lists what is still open there. When I2013 lands the Epic has zero remaining leaves. Under standard, autoRelease is false, so the loop stops and reports the Epic release-ready instead of cutting anything.

4. Release the unit. You say yes (or run /devstride:build-item I2010 and approve the cut). The loop merges the base branch into the Epic branch, opens the Epic's release pull request as a draft, and runs the full review over the whole Epic diff — Claude's adversarial pass plus whatever review.localCommand and review.automatedReviewers you configured — because this is the first time any reviewer outside the build has seen that code. Findings are verified, fixed or dismissed with a reason, threads resolved. Then the pull request is marked ready and CI runs once on that final head. It merges only through the plugin's merge gate, which allows the merge when every required check has passed on exactly the reviewed commit and no review thread is left open. The Epic and each of its stories then move to Done, and the Epic branch is deleted.

5. Promote to production. When you want it live, /devstride:release cuts release/26-10-06 from your release source (if release.releaseBranchPattern is set), opens the production pull request, runs the same full review (with release.productionReview.reviewIdenticalTree set to false, a tree identical to one already reviewed gets at most one pass over the files it changes under your high-risk paths) and the release-only pre-ship checks, settles CI, and then stops with a summary that quotes your release.autoDeployOnMerge text. Nothing merges until you answer yes — unless you have written a standing yes into your configuration (release.lightRelease.standingYes, release.fullRelease.standingYes), which covers only a release whose every gate is green. After the merge it approves a waiting deploy if you configured release.deployApproval, waits for the deploy to be confirmed, runs your post-deploy health skill if you registered one, updates your documentation through your local docs skill (and your knowledge-base sync skill, if you have one), and writes a release note only if you passed --release-notes.

That is the whole loop: one planning conversation, one command repeated per item, one owner decision per release unit, one per production release.

Two important safety boundaries#

DevStride writes are live

The bundled DevStride MCP server connects to your real organization. Item creation, status changes, comments, descriptions, dates, and dependency changes are immediately visible. There is no draft roadmap or dry-run mode.

Planning therefore asks for sign-off before creating a hierarchy. rationalize-gantt separately confirms scope because it overwrites stored dates and may remove or repoint dependency edges.

Code changes keep the normal git safety net: branches, diffs, review, tests, and merge history.

Production promotion is owner-cut

/devstride:release prepares the production pull request, review, configured local pre-ship checks and CI. It then stops for explicit owner approval before merging into the production branch, and updates documentation once the deploy is confirmed. The one exception is a standing yes the owner writes into the configuration ahead of time — for a light release identical to its reviewed train, or for any release whose gates are all green and whose migrations the owner approved file by file — described under Releases that start themselves. Both are off by default, and neither applies without release clearance configured. With release.releaseBranchPattern set, the release is cut as its own protected branch, so the release source keeps accepting merges while the release is reviewed; those ship in the next release.

Pick the right entry point#

The plugin ships twenty loop skills. Every one of them is reachable from this table.

Goal Command
Configure the loop for this repository, or re-check a configuration after editing it /devstride:setup (/devstride:setup validate writes nothing)
Change your workflows so CI runs once per pull request — the draft hold, cancelling superseded runs, skipping a production-branch run for a tree already tested — shown as diffs you accept one by one /devstride:setup ci
Create the optional Active Agents board, tag and view in DevStride /devstride:setup agents
Say which board each kind of item goes on when work on it starts /devstride:setup boards (/devstride:setup boards personal for exceptions of your own)
Check the installation and repository, and repair what is safely repairable /devstride:doctor (or one section, such as /devstride:doctor agents)
Update the plugin to the newest release /devstride:update
Measure what CI really costs, read-only /devstride:ci-audit
Understand an existing plan without changing it /devstride:comprehend-plan I1234
Create or extend a roadmap /devstride:plan I1234
Add one item to an existing plan /devstride:insert-story ... or /devstride:insert-defect ...
Re-date a plan and tidy its dependency links after structural changes /devstride:rationalize-gantt I1234
Deliver the next planned item /devstride:build-item
A running plan is taking far too long /devstride:rebalance I1234 prototype
A plan should run as fewer, larger items at standard rigor /devstride:rebalance I1234 extended
Create and deliver unplanned work once /devstride:create-story ... or /devstride:create-defect ...
Park a follow-up or a bug in the plan's Deferred container, without building it /devstride:create-story deferred I2013 ... or /devstride:create-defect deferred I2013 ...
Build one scoped item without the selection, merge and status steps around it /devstride:ultracode-build I2011 <goal> (normally build-item calls it, once the branch exists and the item is In Progress)
Commit and push the current branch, type-checked, in your commit style /devstride:push
Open a draft pull request for the current branch and take it through review /devstride:pr
Review an existing pull request and settle it /devstride:review <PR#>
Give a branch with no pull request its full local review before it lands on the release train /devstride:review local-full <base>
Start a feature branch by hand, or an urgent fix from production /devstride:branch-feature <name> or /devstride:branch-hotfix <name>
Promote the release source to production /devstride:release
Start a release when work has waited on the release train too long, from a schedule (with release.backstop set) /devstride:release backstop
Finish a release's post-deploy check after its session stopped (with release.clearance.scope set to "cut-to-deploy" or "merge-and-deploy") /devstride:release post-deploy only
Re-run one step a release or build failed at the step by name, for example /devstride:update-docs (see below)

Run one step by itself#

From 3.20.0, each of the ten hooks below is also a skill of its own: the six hooks that name one of your repository's local skills, your local pre-ship checks, your local-environment commands, and the two checkout-pool commands. release, build-item, pr and branch-hotfix call these steps in order; when one fails, you re-run just that step by name instead of the whole release. Each step runs exactly one hook your .claude/ds-config.json names and prints a fixed verdict as its first line.

Step What it runs First line
/devstride:classify-release release.classifySkill: is this release light or full? RELEASE CLASS: LIGHT or FULL
/devstride:pre-merge-check release.preMergeSkill: does production need anything before the merge? PRE-MERGE: CLEAR, HOLD or NOT RUN
/devstride:pre-ship the preShipChecks commands, for a pull request, a release, or the release-train snapshot (train); select lists them, run runs them (--skip <name> records an owner's waiver at a release, --only <names> re-runs some) PRE-SHIP SELECTED: <names> or PRE-SHIP: NOTHING TO RUN; then PRE-SHIP: PASS (3 ran, 0 waived) or FAIL <names>
/devstride:post-deploy release.postDeployCheckSkill, in mode check or close-out POST-DEPLOY HEALTH: PASS, FAIL or NOT RUN, or POST-DEPLOY CLOSE-OUT: DONE or PARTIAL
/devstride:update-docs docs.updateSkill, in mode update or check UPDATE DOCS: PUBLISHED, STAGED, CURRENT or FAILED; UPDATE DOCS CHECK: PASS or FAIL
/devstride:sync-knowledge-base docs.knowledgeBaseSyncSkill, after docs were published live KNOWLEDGE BASE SYNC: DONE, CURRENT, FAILED or NOT RUN
/devstride:write-release-notes docs.releaseNotesSkill, only when asked RELEASE NOTES: PUBLISHED, DRAFTED or FAILED
/devstride:local-environment one localEnvironment command (create, recreate, migrate, seed, teardown or name) LOCAL ENVIRONMENT <verb>: DONE or FAILED
/devstride:lease-checkout pool.checkout LEASE: LEASED <member>, BUSY <member> or ERROR
/devstride:return-checkout pool.checkin RETURN: RETURNED <member>, REFUSED <member> or ERROR

With a hook unset, a step says NOT CONFIGURED and the caller carries on — except the four safety steps, which take the stricter path: an unclassified release is FULL, a broken pre-ship check fails, and an unreadable post-deploy or pre-merge answer is NOT RUN and you are asked. Every step is safe to re-run; re-running a failed one is the supported recovery.

Your repository's own skills#

Six of those hooks name a skill that lives in your repository, at .claude/skills/<name>/SKILL.md, rather than a shell command:

Setting The step that runs it What your skill does
docs.updateSkill update-docs Updates your documentation for a shipped change — at a production release, only after the deploy is confirmed
docs.knowledgeBaseSyncSkill sync-knowledge-base Refreshes a knowledge base from the published docs; a failure never undoes the docs
docs.releaseNotesSkill write-release-notes Writes a release note, only when the owner passed --release-notes
release.postDeployCheckSkill post-deploy Checks production health after the deploy, and in close-out mode does any work it owes once the release is live
release.classifySkill classify-release Says whether a release is light or full
release.preMergeSkill pre-merge-check Says whether production needs anything before the release merges

The plugin never edits your documentation itself: /devstride:setup docs asks where your docs live and scaffolds the documentation-update and release-note skills for you to refine, and the config only names them. /devstride:doctor checks that every skill a setting names exists, and runs only the documentation and knowledge-base skills' read-only check. Every other hook your repository can supply is not a skill: deploy approval and verification, and the Active Agents and session-presence hooks, are shell commands, and release clearance and story claims use either a built-in provider or your own commands; the plugin's skills/setup/references/seam-registry.md lists every hook with what it receives and what it must answer, and the Configuration Reference describes the settings.

Powered by DevStride