On this page

Getting the Skills#

This is the only page you need for a first run. The rest of the section explains the loop in more depth.

1. Install#

Working in the DevStride repository?

./setup installs the plugin for you, in Claude Code and in Codex, at project scope (adding the marketplace when Claude Code has none), and puts back the .claude/settings.json the install reorders. When the install is older than the version the repository requires, setup updates it with the plugin's own verified updater, then brings Codex's copy up to Claude Code's, so both agents run the same version; restart running sessions afterwards. See Set up your machine. The steps below are for any other repository.

From the root of the repository you will use it in, run:

claude plugin marketplace add devstride/claude-plugin
claude plugin install devstride@devstride --scope project

Install at project scope

Project scope binds the plugin to that repository and its linked worktrees, and each repository keeps its own version: its .claude/ds-config.json decides when the plugin's own updater moves it (plugin.autoUpdate) and can hold it on a version (plugin.pin). Neither setting governs Claude Code's own claude plugin update or its marketplace auto-update. A project install also writes enabledPlugins into the repository's committed .claude/settings.json — that is how a team turns the plugin on for everyone who clones; to install for yourself alone in a repository that has not adopted DevStride, use --scope local, which is recorded in your personal .claude/settings.local.json instead. A machine-wide install (--scope user, the default) still works, but every repository on the machine shares it, so an update from any of them moves it, and one repository's plugin.pin cannot stop another repository's update. A machine-wide copy beside a project copy makes /devstride:update stop rather than guess which one to change. If you have both, keep the project copy and remove the other with claude plugin uninstall devstride@devstride --scope user --keep-data (use ds@devstride instead if that is the id claude plugin list shows).

Confirm the install and version:

claude plugin list

The current published version is 3.45.0, with thirty /devstride:* skills (twenty loop skills and ten steps you can re-run by name). The DevStride repository requires 3.45.0 or newer: an older plugin silently ignores the configuration keys it does not know, so the protections they turn on are simply absent. Each release's changes are listed in Plugin updates.

2. Connect DevStride#

Run:

/mcp

Connect plugin:devstride:devstride, sign in, and choose the organization the skills should use.

Choose the organization deliberately

The connection has the same read and write access you have in DevStride. Planning and delivery skills change live items; there is no sandbox or dry-run roadmap.

Until you connect, the server contributes no DevStride tools and nothing prompts you. The usual symptom is “I can’t find DevStride tools,” not an authentication error.

Keep only one DevStride MCP server signed in per repository. A plain devstride entry is a separately configured server, not the bundled one; two active servers in one repository can point the skills at different organizations. To switch the bundled connection to another organization:

claude mcp logout plugin:devstride:devstride

Then reconnect through /mcp.

More than one organization, one project each

The bundled connection is one sign-in for the whole machine. If each of your repositories belongs to a different DevStride organization, leave the bundled connection signed out and give each repository its own connection with an API key for its organization, so a repository can never write to another organization: Working in more than one organization.

3. Set up your repository#

Open Claude Code in the repository and run:

/devstride:setup

Setup detects your branches, package manager, verify commands, CI shape, conventions file, and available review engines. It asks about anything it cannot prove, maps your DevStride work types to the release-unit and leaf roles, then writes and validates:

.claude/ds-config.json

Setup also offers two things outside that file, each only when you accept it: the local documentation skills it scaffolds, and a repository status line (.claude/statusline.sh plus a statusLine entry in .claude/settings.json). It never edits application code, CLAUDE.md, or .gitignore, and it touches CI workflows only in /devstride:setup ci, as a diff you review.

Next run the broader read-only check:

/devstride:doctor

Doctor checks the plugin, DevStride connection, git and GitHub CLI access, config, CI draft gate, merge gates, your documentation and release hooks, and the Active Agents board, all in one run: when the plugin is behind, it names /devstride:update as the first thing to do and still checks everything else. Diagnosis is read-only. Its seven-day measurement of how often CI really ran is slow, so it runs only on /devstride:doctor ci --audit (or use /devstride:ci-audit). Doctor does not count as a job of its own: you can run /devstride:build-item straight after it in the same session. It then offers, as one batch, the repairs that are safe to automate — writing inside this repository's .claude/, or running the command that already owns a fix, such as gh auth login or /devstride:setup — and re-verifies each one. It never repairs a workflow file, git state, a DevStride record, or anything on a deployed stage, and it repairs nothing when it is not run interactively.

4. Plan, then build once#

Plan under an existing DevStride parent item:

/devstride:plan I1234

The plan skill reads what already exists, asks about scope and sequencing, shows you the proposed hierarchy, and creates nothing until you approve it.

Then deliver one item:

/devstride:build-item

Start with one. Once the branch, review, test, merge, and item-update behavior matches your expectations, walk the remaining plan with:

/loop /devstride:build-item

/loop belongs to Claude Code, not this plugin. It repeatedly invokes build-item; the delivery skill itself remains serial and selects one item at a time.

Delivery prerequisites#

Planning needs the DevStride connection. Code delivery additionally assumes:

  • git, with a pushable remote named origin — git 2.38 or newer if you use a release train, because the release checks the train's merges with git merge-tree --write-tree and stops when it cannot run;
  • python3 on your PATH: the session-start version check, the status line and the plugin's helper scripts need it, and without it the version check silently never runs (doctor reports this as a failure);
  • GitHub as the forge;
  • GitHub Actions for the plugin’s draft-held CI ordering;
  • an installed and authenticated gh CLI with repository write access.

Other forges can still use the planning skills, but the branch, pull-request, review-thread, and merge flow has no adapter for them. /devstride:setup and /devstride:doctor check these prerequisites before your first real delivery.

Optional: make CI run after review#

The shipped review settings use draft pull requests so reviewers settle before CI starts. To use that ordering, each workflow triggered by pull_request needs all four events:

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

Gate the jobs, or an upstream job they depend on, while the pull request is a draft:

jobs:
  test:
    if: github.event.pull_request.draft == false
    # ...

Setup detects this shape but does not edit it. Doctor tells you which event or job gate is missing. If your repository intentionally runs CI during review, set all three review ordering flags to false; mixed values use the strictest behavior and are reported.

The ds install alias#

The marketplace also offers a shorter install spelling:

claude plugin install ds@devstride --scope project

It changes only the install identifier. The plugin manifest is still named devstride, so commands remain /devstride:plan, /devstride:build-item, and so on — never /ds:plan.

Install either devstride@devstride or ds@devstride, not both. The two marketplace entries point to the same source, but Claude Code installs them separately; installing both puts every skill in the picker twice. Updates must use the identifier you installed.

Staying in sync#

The plugin releases often, and a session serves whatever it loaded at startup. Three commands keep you current, and all three are safe to run as often as you like: doctor and setup validate change nothing until you accept a repair, and update changes only the installation that loaded it, stopping rather than guessing when that is unclear:

Run it When What it does
/devstride:doctor Any time the loop behaves oddly, and after any config change Diagnoses the installation, connection, config, CI ordering and merge gates, then offers the repairs that are safe to automate.
/devstride:setup validate After hand-editing .claude/ds-config.json Re-proves the config's commands, branches, roles and CI consistency. Writes nothing.
/devstride:update When the plugin tells you a newer release is published Updates the exact installation that loaded it and verifies the result.

A good habit is /devstride:doctor at the start of a working session and again after editing config — it is the one command that checks everything at once, and it costs nothing to run when all is well.

How the plugin tells you it is behind#

A session keeps the plugin copy it loaded until you run /reload-plugins or restart, so there are two ways to be behind: a newer copy is already installed on disk but this session has not loaded it, or a newer release is published and not yet installed. The plugin tells you about both:

  • At session start. The plugin compares the version this session is running with the newest published release, using a six-hour cache so most starts make no network request. It is silent when you are current or offline and never blocks or fails a session.
  • While you work. Each prompt refreshes that cache in the background once it is older than 30 minutes, so a release published mid-session reaches you without a restart. When the session runs an older plugin than it could, Claude mentions it once per session per version: it tells you to type /reload-plugins when a newer copy is already installed, and asks whether to run /devstride:update when a newer release is published (on yes it runs it). If it is part-way through a multi-step task, it finishes the step it is on and asks before the next one. It never asks inside a /loop or when no one is at the keyboard (it mentions it in its final report instead), and it changes nothing on its own.
  • On the status line. If your repository has the plugin's status line, its ⊞ segment shows the version this session runs: dim while current, red 3.15.0 → 3.16.0 · /reload-plugins when a newer copy is installed than this session loaded, and yellow 3.16.0 (3.16.1 out · /devstride:update) when a newer release is published.

Set plugin.updateCheck to false in .claude/ds-config.json to switch the check and these reminders off for a repository, or set the environment variable DEVSTRIDE_PLUGIN_UPDATE_CHECK=0 for CI and headless runs. In a repository that pins the plugin (plugin.pin), you are never asked to update, and only told to reload onto the pinned version. /devstride:doctor reports when the check last ran and what it found.

Let Claude Code update the plugin for you#

The least effort is to stop updating by hand. Claude Code can refresh a marketplace and update its installed plugins in the background:

  1. Run /plugin
  2. Go to Marketplaces
  3. Choose the devstride marketplace
  4. Select Enable auto-update

Worth turning on — it is off by default here

Anthropic's own official marketplaces ship with auto-update enabled; third-party and local marketplaces, which includes DevStride's, ship with it disabled. So this is one deliberate toggle, and after it you stop thinking about plugin versions.

Claude Code checks after your session starts, with a random delay of up to ten minutes, so the running session keeps the versions it launched with. If anything updated you are prompted to run /reload-plugins; otherwise the new version loads at your next launch.

Administrators can enable it for everyone instead of asking each person to toggle it, by setting "autoUpdate": true on the marketplace's entry in managed settings:

{
  "extraKnownMarketplaces": {
    "devstride": {
      "source": { "source": "github", "repo": "devstride/claude-plugin" },
      "autoUpdate": true
    }
  }
}

Claude Code's auto-update does not read .claude/ds-config.json, so it ignores plugin.pin and plugin.autoUpdate. It is the automatic option for a machine-wide (user-scope) install, which the plugin's own session-start update never changes. To hold a version, see Holding a version below.

To turn automatic updates off again, use the same menu, or set the DISABLE_AUTOUPDATER environment variable. That variable also disables Claude Code's own updates; to keep plugin updates while stopping those, set FORCE_AUTOUPDATE_PLUGINS=1 alongside it.

Updating by hand#

/devstride:update is the simplest path from version 3.5.1 onward. It updates the exact installation that loaded the command — preserving whether you installed as devstride or ds, and at user or project scope — verifies the installed files against the published tag, and checks the disk again. When the update needs a reload it ends there: run /reload-plugins before any other DevStride command and confirm it reports no DevStride load error; restart Claude Code only if reload is unavailable or fails. It stops rather than guessing when an install is pinned, administrator-managed, or ambiguous, or when a machine-wide copy sits beside this repository's project copy (it then recommends keeping the project copy and removing the other). If it finds an install whose files do not match the release, it asks your permission before reinstalling it with your data preserved. On 3.1.0 through 3.5.0 the skill exists but can stop with plugin-root-missing on current Claude Code; use the two commands below once to get past it.

If an update reports marketplace-shallow-lock, an interrupted download left a lock file in Claude Code's copy of the marketplace. Once no git or claude plugin process is working there, remove the file it names and run /devstride:update again.

The two-command form still works, and is what an installation older than 3.1.0 needs, because /devstride:update does not exist there — and the fallback for 3.1.0–3.5.0 when the skill stops:

claude plugin marketplace update devstride
claude plugin update devstride@devstride --scope <scope>

For an alias install, the second command is:

claude plugin update ds@devstride --scope <scope>

Use the fully qualified id and the scope claude plugin list shows for your install: project for the recommended install, user for an older machine-wide one (likewise local or managed). Without the right id or scope, claude plugin update reports the plugin as not installed and changes nothing; the bare name devstride reports "not found". Afterwards run /reload-plugins and confirm it reports no DevStride load error, or restart Claude Code if reload is unavailable or fails.

Updating from 3.17.0 needs these two commands once. 3.17.0's status line made Python save a compiled copy of one of the plugin's files inside the installed plugin, and its update check refuses that with installed-payload-mismatch. Run the two commands above with --scope project, then restart your sessions; 3.18.0 fixes both sides, so /devstride:update works again after it. In the DevStride repository, ./setup clears that copy and updates for you (Troubleshooting).

Running only marketplace update refreshes the catalog but leaves the installed plugin unchanged. claude plugin list is the final check — though note it reads what is on disk, while the session-start check reports what your session actually loaded, which is the drift that matters.

Automatic updates at session start#

A repository can have the session-start check apply the update for you (plugin.autoUpdate in .claude/ds-config.json; setup writes it true, and the check treats an absent block as false) or hold a version deliberately (plugin.pin). Session start is the only moment an automatic update happens; nothing updates the plugin automatically while a session is working. That automatic path only ever updates a project or local install recorded in that very checkout: a linked worktree that shares an install recorded in another checkout of the repository leaves it to that checkout, a shared user-scope copy is handed to /devstride:update, an administrator-managed one is left alone, and an ambiguous one is handed to /devstride:doctor. See the configuration reference for the block.

Holding a version#

To hold one repository on a release, set plugin.pin to that version (for example "3.45.0") in its .claude/ds-config.json. The plugin's own updaters, the session-start update and /devstride:update, then leave that repository's copy alone, and the session-start check says once that you are pinned rather than reminding you every time. Claude Code's marketplace auto-update does not read the pin. To hold every repository on the machine instead, pin the marketplace itself to a release tag (devstride/claude-plugin@devstride--v<version>; there is no --ref flag); the plugin's README has the exact commands.

Removing the marketplace uninstalls the plugin everywhere

claude plugin marketplace remove devstride also uninstalls every plugin that came from it, in every repository and scope, and adding the marketplace back does not reinstall them. Before you remove it, note every DevStride row claude plugin list --json shows (its id, scope and project path), then reinstall each one from its own repository with its own scope.

Team installation#

A repository can declare and enable the marketplace in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "devstride": { "source": { "source": "github", "repo": "devstride/claude-plugin" } }
  },
  "enabledPlugins": { "devstride@devstride": true }
}

That does not install the plugin: each teammate runs claude plugin install devstride@devstride --scope project once, from the repository. (In the DevStride repository, ./setup does this for them.) Make sure .claude/settings.json and .claude/ds-config.json are tracked if your repository normally ignores .claude/. /devstride:doctor checks both whether the settings file is tracked and whether it is ignored, and, on a machine with no project install for the repository yet, prints the exact install line to run.

An installed plugin stays on its version until someone updates it, so teammates who installed at different times can be running different versions. Turning on plugin.autoUpdate (setup's default) brings each person's project install up to the newest release at their next session start in the repository.

For headless API-key setup, use the plugin’s README. That is an operational exception, not a first-run step.

Powered by DevStride