Skill Audit
A compact reference for all thirty skills shipped by the DevStride Claude Code plugin.
On this page
Skill Audit: All Thirty Skills#
Version 3.45.0 ships the thirty skills below: twenty loop skills and, since 3.20.0, ten steps that each run one of your repository's own hooks. They always invoke as /devstride:<name>, including when the plugin was installed through the shorter ds@devstride marketplace entry.
Each skill file states a goal, the rules that must hold, and its hard floors, rather than a numbered script. The descriptions below say what each one guarantees.
Planning#
| Skill | Invocation | What it does |
|---|---|---|
plan |
/devstride:plan <parent-item> [description] [profile] |
Interactively shapes a grouping item → release unit → leaf roadmap, writes approved items and dependencies, rationalizes dates, and numbers the execution order. Reads the existing plan first. |
comprehend-plan |
/devstride:comprehend-plan <item> [focus question] |
Reads the complete descendant tree, descriptions, comments, status, and dependencies. Strictly read-only. |
insert-story |
/devstride:insert-story [parent-item] <description> |
Creates one Story and splices it into an existing plan’s dependency order. It does not build the code. |
insert-defect |
/devstride:insert-defect [parent-item] <description> |
Creates and splices one Defect. It asks before moving an urgent defect ahead of the normal next item. |
rationalize-gantt |
/devstride:rationalize-gantt <plan-root> |
Recomputes a synthetic one-day-per-leaf timeline and reviews invalid dependency edges. It overwrites selected dates and may remove or repoint edges. |
rebalance |
/devstride:rebalance <plan-root> <profile> |
Re-slices a live plan’s not-started leaves to a new delivery profile, sizing the successors to that profile’s leaf size, after you approve a before/after table. Archives absorbed originals with a pointer, rewires dependencies, numbers successors with the splice convention, rewrites the root marker, then re-dates not-done items. Refuses to run while a build loop is active on the plan. |
Planning writes to the connected DevStride organization except for comprehend-plan. None of these skills writes repository code.
Delivery#
| Skill | Invocation | What it does |
|---|---|---|
build-item |
/devstride:build-item [item | next | next under I#### | plan-root] |
Orchestrates selection, status, branch, build, review, merge, completion, and release-unit closeout for one leaf. Empty means next. |
create-story |
/devstride:create-story [deferred <item>] <description> |
Creates, places, assigns, and delivers one standalone Story — onto the release train when one is configured, else by its own pull request. No plan numbering or dependency splice. A leading deferred <item> instead parks the follow-up in that plan root's deferred container, where it is never built. |
create-defect |
/devstride:create-defect [deferred <item>] <description> |
Creates, places, assigns, and delivers one standalone Defect. A leading deferred <item> instead parks the bug finding in that plan root's deferred container, where it is never built. |
branch-feature |
/devstride:branch-feature <branch-name> |
Creates and pushes a feature branch from the resolved working base, dated with branchNaming.dateFormat. Stops on a dirty tree. |
branch-hotfix |
/devstride:branch-hotfix <branch-name> |
Creates a hotfix branch from a fresh production branch, dated with branchNaming.dateFormat like a feature branch. It does not open the pull request. |
ultracode-build |
/devstride:ultracode-build <item> <scope> |
Understands, implements, tests, commits, and adversarially reviews one item. It does not open or merge a pull request. |
pr |
/devstride:pr [item] |
Opens the pull request, requests configured cloud reviewers, delegates review and CI settlement, runs matching local pre-ship checks, and optionally links the item. |
review |
/devstride:review [PR#] |
Resolves the configured roster, verifies and settles findings, writes qualifying lessons, releases draft-held CI, and requires green at the final head commit. Also has local-only and pre-ship-resume modes for callers. |
push |
/devstride:push |
Stages intended tracked and named new files, commits, runs configured typechecks, and pushes. It never opens a pull request. |
release |
/devstride:release [--release-notes true|draft] [no docs | docs only | release-notes only | post-deploy only | backstop] |
Merges the release train first when configured, cuts the release branch when release.releaseBranchPattern is set, and prepares the production pull request, review, local release checks and CI; asks the owner before the production merge unless a standing yes you configured covers the release (release.lightRelease.standingYes, release.fullRelease.standingYes); then updates documentation through your local docs skill by default and writes a release note only on --release-notes, both after the deploy is confirmed. From 3.45.0, backstop runs the release backstop check instead: it starts a release only when work has waited on the train longer than release.backstop.maxWaitMinutes and nothing is releasing it, and otherwise does nothing and says why. |
build-item chooses between two delivery shapes:
- A planned leaf on a release-unit branch uses a local merge with no item pull request when fast merges are enabled. With fast merges disabled, it gets a pull request into that release-unit branch.
- A one-off never uses a release unit's branch, even when filed under one. With a release train configured (
releaseTrain.branchplusrelease.mergeTrainBeforeCut) it lands on the train and ships with the next release; without one — or when it changes a file matchingrelease.releaseBranchFixExclusions— it gets its own full pull-request path into the base branch. WithreleaseTrain.smallFixesset, a one-off on the train within that size limit skips its separate local review pass, and a larger or riskier one gets a full local review on your machine before it lands.skills/build-item/scripts/routing.pymakes that decision, and anything else (Codex, a script, a person) can run it and get the same answer.
Steps#
Each step runs exactly one hook your .claude/ds-config.json names and prints a fixed verdict as its first line. release, build-item, pr and branch-hotfix call them in order; run one by name to re-run a step that failed. With its hook unset a step says NOT CONFIGURED (or applies its stated default) and the caller carries on. The four safety steps (classify-release, pre-ship, post-deploy, pre-merge-check) are stricter: when their hook is configured but missing, failing or gives no verdict, they take the stricter path, never a pass.
| Skill | Invocation | What it does |
|---|---|---|
classify-release |
/devstride:classify-release [payload] |
Asks release.classifySkill whether a release is light or full. Anything but a clear answer is RELEASE CLASS: FULL; unset, every release is FULL. Read-only. |
pre-merge-check |
/devstride:pre-merge-check [payload] |
Asks release.preMergeSkill whether production needs anything before the merge, before the owner is asked for the go-ahead. PRE-MERGE: CLEAR, HOLD or NOT RUN; an unreadable answer is NOT RUN. Read-only. |
pre-ship |
/devstride:pre-ship <pr | release | train> <select | run> <base> <head> [--skip <name>] [--only <names>] [--ran-at-train <names>@<sha>] |
Selects and runs the matching preShipChecks for a pull request, a release or the release train. --skip (release only) is the owner's explicit waiver, reported as WAIVED; --only re-runs the failed checks after a fix; --ran-at-train lets a release skip runAt: train checks that already passed on the commit the release branch was cut from, or on one with the same tree. A failure names every failed check. |
post-deploy |
/devstride:post-deploy <check | close-out> <payload> |
Runs release.postDeployCheckSkill and passes its verdict through: POST-DEPLOY HEALTH: … in check, POST-DEPLOY CLOSE-OUT: … in close-out. An unreadable answer is NOT RUN. |
update-docs |
/devstride:update-docs [update <payload> | check] |
Runs docs.updateSkill once. UPDATE DOCS: PUBLISHED only on evidence the docs are live; STAGED for a draft awaiting the owner; CURRENT when nothing changed. |
sync-knowledge-base |
/devstride:sync-knowledge-base [sync <payload> | check] |
Runs docs.knowledgeBaseSyncSkill after documentation was published live. A failure never undoes the documentation push and prints a runnable re-run line. |
write-release-notes |
/devstride:write-release-notes <publish | draft> <payload> |
Runs docs.releaseNotesSkill, only when the owner asked for a release note. |
local-environment |
/devstride:local-environment <verb> [<name>] [--branch <b>] [--base <ref>] |
Runs one localEnvironment command (create, recreate, migrate, seed, teardown or name) with its placeholders filled. |
lease-checkout |
/devstride:lease-checkout <member> <purpose> |
Leases one checkout of the repository's pool through pool.checkout; build-item calls it once per run. |
return-checkout |
/devstride:return-checkout [member] |
Returns the leased checkout through pool.checkin when the run ends or hands over. |
Setup and diagnostics#
| Skill | Invocation | What it does |
|---|---|---|
setup |
/devstride:setup [validate | ecosystem | verify | ci-inspect | branches | engines | docs | ci | agents | boards [personal]] |
Detects repository settings, confirms DevStride hierarchy roles, writes .claude/ds-config.json, and validates it. It also offers the scaffolded docs skills and a repository status line, and CI workflow diffs in setup ci. setup agents adopts the Active Agents board and tag, and is the only mode that writes to DevStride. setup boards asks which board each kind of item goes on and writes those rules after a typed yes. validate and detector-only runs write nothing. |
doctor |
/devstride:doctor [env | plugin | devstride | config | ci [--audit] | gates | docs | agents] |
Checks git and the GitHub CLI, the installed and running plugin version, the DevStride connection, the config file against the published schema, branch roles, the CI draft gate, merge gates, every hook, claims and release clearance, and the Active Agents board. It suggests existing remote branches when static fallbacks do not resolve. Diagnosis is read-only; it then offers the repairs that are safe to automate as one batch and re-verifies each. Invoked non-interactively it repairs nothing. See What doctor checks. |
ci-audit |
/devstride:ci-audit [days] [workflow] |
Measures what CI actually costs over a window (seven days by default): executed runs per pull request per workflow (the design is one each), runs started before the final reviewed head, post-merge push minutes, release pull requests re-run by a moving base, and the named offenders with their likely cause. Read-only. |
update |
/devstride:update |
Updates the exact plugin installation that loaded the command, verifies the installed copy against the published tag, and says whether /reload-plugins is enough or a restart is needed. Stops rather than guessing when an install is pinned, administrator-managed, unbound, or ambiguous. |
What doctor checks#
Run /devstride:doctor with no argument to check everything, or name one section. Each check reports PASS, FAIL or N/A, says in plain words what it found, and for a failure adds why it matters and the exact fix. The report ends ready, ready-with-warnings or not-ready, with one next action. A check doctor did not run is never reported as passed.
| Section | What it checks |
|---|---|
env |
git, a remote named origin, the GitHub CLI installed and signed in, and the active account's scopes: repo and read:org, plus workflow when the loop edits workflow files. A token from GH_TOKEN or GITHUB_TOKEN is called out, because gh auth refresh cannot change it. |
plugin |
The plugin is installed and enabled; the version on disk and the version this session runs (they differ until you reload); the marketplace is registered; the newest published release; python3 is on your PATH; each cloud reviewer's learned wait times; the last session-start update check for this repository; and whether the .claude/settings.json that enables the plugin is committed. When the plugin is behind, /devstride:update becomes the first next action and doctor carries on through every other section. |
devstride |
A DevStride connection exists, is connected, and is the only one. Doctor never calls a DevStride tool to test this. |
config |
The config file against the schema (below); the four branch roles exist on origin, and the base, release source and production branches are listed in protectedBranches; the effective delivery profile, where it came from, and any key that contradicts it (informational, since an explicit key wins); localEnvironment; stage, whose resolve command runs once, with a warning when it names a production stage; the shared status line; that every configured command resolves; that conventionsDoc exists; and consequenceNotices. |
ci |
The draft hold: the three draft settings agree with each other and with your workflows, every pull-request workflow lists opened, synchronize, reopened and ready_for_review, and every job is gated on the draft condition, directly or through a job it needs. A missing cost mechanic, such as concurrency with cancel-in-progress, or a tree-identical skip on production pushes that can actually fire, is a warning. |
gates |
Whether anything checks code before it merges: the effective profile's story and release-unit gates have the verify commands they need; the review roster, with each catalogued local engine checked for its read-only flag (an engine doctor does not recognise is reported as unverifiable, not failed); review.mandatoryLenses; and that each preShipChecks command resolves. |
docs |
Every hook that names one of your repository's skills (documentation, release notes, knowledge-base sync, post-deploy, release classification, pre-merge): unset is N/A, and a named skill must exist and must not be gitignored. Only the documentation and knowledge-base hooks' read-only check self-test is run. A leftover release.docsRepo block fails, because the release skill never acts on it; /devstride:setup docs migrates it. The section also checks that the deploy approval and verification commands resolve (never running them), and covers release clearance and claims. |
agents |
The Active Agents block: the board is adopted and not archived, the tag exists and is allowed on every plan-root work type, no Stories or Defects sit on the board, no Done item carries the tag, and both commands are found (never run). With no block it only says, as information, whether an Active Agents board exists to adopt. From 3.62.0 it also checks your board placement rules on every run: a board or folder that is gone or archived, a cycle folder with no board for today (only you can create one) or none for the day after today's cycle ends, a team, tag, work type or custom field your organization does not have, a kind of item no rule answers for, a rule that an earlier catch-all rule always beats, and whether personal rules are in effect or ignored. It never moves an item. |
The status-line check runs on every invocation, whichever section you name. Doctor does not count as a job of its own in the one-job-per-session gate, so you can run /devstride:build-item straight after it.
Config validation#
Doctor runs the installed release's validator (skills/doctor/scripts/validate-config.py) on .claude/ds-config.json and reports its lines in its own words: ERROR fails, WARN is a warning, NOTE is informational. Among what it catches:
- A wrong shape, such as a list where a command belongs, or both forms of
release.clearance. An unknown key is only a warning, naming the key you probably meant; keys your own tools read go underrepoLocalKeys. - Keys that must be set together:
pool.checkoutandpool.checkin. release.autoStart.enabledwithout aclaimsblock is an error, because two sessions could otherwise start the same release.- From 3.45.0,
release.backstop.modeset toshadoworlivewithout aclaimsblock is an error, and so is aclaimsblock of your own commands withoutclaims.commands.get, because the backstop reads its claim before taking it. The same mode without a release train (release.mergeTrainBeforeCutandreleaseTrain.branch) is a warning, since no work ever waits on one. AmaxWaitMinutesoutside 15–1440 or a mode other thanoff,shadoworliveis an error. - A standing yes that cannot take effect is a warning:
release.lightRelease.standingYeswithoutrelease.classifySkillorrelease.clearance, andrelease.fullRelease.standingYeswithoutrelease.clearance, an owner decision date or migration globs. A malformedrelease.fullRelease.approvedMigrationsentry is an error. - A
release.clearance.scopeother thanrelease,cut-to-deployormerge-and-deployis an error, and so ismerge-and-deploywithoutrelease.releaseBranchPattern, because each release brings production into its own release branch when the release ahead merges. preShipChecks[].rerunAtMergeon an entry whosewhenis notreleaseOnly, or together withrunAt, is an error.- The old
supportTrainname is a note; carrying it besidereleaseTrainis an error. - An empty deferred-container title is a warning.
- A number outside its sensible range, such as
presence.intervalMinutesoutside 1–60 or aclaims.expiryMinutesvalue outside 1–1440, is a warning, and the default stands.
Claims, clearance, presence and consequence notices#
claims— absent is N/A. With thedevstrideprovider, doctor checks that your DevStride connection offersclaim_workby listing its tools, never by calling it. Missing is a failure: the server has no claims yet, or your key's user lacks the permission to manage agent claims;build-itemthen runs without claims and says so once. Withcommands, each command must resolve; none is run.release.clearance— with thegithubordevstrideprovider, doctor runs itsstatusonce, read-only, and reports the line;UNKNOWNfails with its cause. With thedevstrideprovider it also checks that credentials are present, and that acredentialsFileis readable by you alone (mode 600 or stricter). It never prints a credential or a holder. With no release-tower workflow beside it, doctor notes that/devstride:setup cioffers one. See Release clearance.presence— the validator checks the block's shape and interval. Doctor does not run the presence command.consequenceNotices— doctor reports whether notices are on, how many categories apply and who is notified beside the item's author. A malformed block fails; anotifyname that DevStride cannot find is a warning.
Repairs#
After the full report, doctor lists every repair it may make, numbered, and asks one question for all, some or none. Apart from the personal cleanup below, it writes only inside this repository's .claude/: the shared status-line script (never overwriting one that exists) and its statusLine setting, including refreshInterval: 30, and, for a status-line segment with nothing to read from, your answer (a stage.resolve command or a hidden segment). For other fixes it runs the command that already owns them, such as gh auth login, gh auth refresh, /devstride:setup or /devstride:setup docs, and confirms each of those separately even when you said yes to all. After each repair it re-runs the check that found the problem. Removing a personal statusLine key is asked separately, and only once the shared status line is committed and working. Doctor leaves its writes unstaged and uncommitted. It never repairs a workflow file, git state, a DevStride record or a deployed stage, and never updates the plugin. The tier table is in Setup versus doctor.
Measuring run-once CI#
A plain run prints one line saying run-once was not measured. /devstride:doctor ci --audit measures the last seven days with the ci-audit method: executed pull-request runs divided by the workflows that ran per pull request. 1.0 is the design; above it, doctor names the pull requests, workflows and causes. /devstride:ci-audit measures the same thing in more detail.
Which command should I use?#
| Situation | Use |
|---|---|
| No buildable roadmap exists | plan |
| You need to understand a plan before changing it | comprehend-plan |
| New work belongs in a sequenced plan | insert-story or insert-defect |
| New work is an unplanned, standalone request | create-story or create-defect |
| The item already exists and should ship | build-item |
| A production fix must start from production code | branch-hotfix, then build and pr |
| The release source is ready for production | release |
| A running plan is taking far too long per item | rebalance |
| The loop behaves unexpectedly, or config changed | doctor — safe to re-run any time |
| The plugin is behind the newest release | update |
Read next#
- The Planning Loop — how the planning skills compose
- The Delivery Loop — when item and release-unit pull requests happen
- Configuration Reference — repository-specific behavior