AI Development

The DevStride plugin 3.9.0 provides twenty skills for planning, building, reviewing and releasing work, and this repository requires 3.9.0 or newer. Start with the Agentic Skills overview; the published source and changelog define this version's behavior.

Run /clear when switching from planning or setup to execution. Local review commands must run read-only; Setup and Doctor check known command templates and identify unverifiable engines. Below-floor defects go beside the plan in a deferred container rather than joining its execution chain. Set epicIntegrationBranches.autoRelease to "ask" for approval before each completed unit's release.

For existing installs, run /devstride:update and follow its reload instructions. What changed since 3.6.0, and why this repository needs it:

• 3.9.0 turns the routing rule — which branch an item lands on, and what its branches are called — into one runnable helper, routing.py, with canonical examples. The repository's own ds work command is tested against those examples, so an agent using the plugin and one using ds work always pick the same branch. See Where work lands.
• 3.8.0 cuts each production release as its own protected release/YY-MM-DD branch, so develop keeps accepting merges while a release is reviewed, and lets one-offs ride the support train. It also lets a cloud reviewer be asked once, at the final head.
• 3.7.0 limits a cloud reviewer to chosen base branches. This repository uses it to request Copilot only on pull requests into master, because Copilot re-reviewing every fix round on every pull request was about two-thirds of a month's GitHub bill.

An older plugin ignores the configuration keys it does not know, without an error: the release would be cut from develop and Copilot billed on every pull request again. Repository pins still apply; see Staying in sync.

The merge guard

Every Claude Code and Codex session in the repository runs a small hook, .claude/hooks/merge-guard.sh, before every shell command. It refuses the commands that would skip the delivery flow:

• a push to develop or master in any form — a named branch, HEAD:refs/heads/master, a forced +x:master, a bare push whose upstream is develop, --all or --mirror;
• a forced or deleting push to a protected branch, such as a release/* branch;
• git merge while on develop or master (--abort still works);
• gh pr merge into develop unless the merge-path rules admit the head (the same checker as ds merge-path check and the required merge-path check), and into master unless the head is a release or hotfix branch. When gh cannot read the pull request, it refuses that one command rather than guess;
• gh api writes to rulesets or branch protection.

It reads each command in a compound line on its own, so a push still counts inside if … then, a loop, after ! or {, or behind a wrapper such as timeout, xargs, caffeinate, sudo or env. It reads the command text only, so even a quoted string that mentions a merge can trip it — put such text in a file. Reads, commits, feature-branch pushes and gh pr create are never touched, and every release step is a pull-request merge it admits by name, so a release needs no switch. At session start the same hook prints one banner: which checkout you hold, where your branch lands, any open release and the support train.

Why it exists. Agents work from instructions that can be hours old, and anything on develop reaches production at the next release. A merge that skips its review costs a revert at best. The guard catches that honest mistake at the moment it is typed.

It is a speed bump, not the boundary. It fails open — no Python, an unparseable command or an internal error lets the command run and logs the reason to ~/.cache/devstride/merge-guard.log — because a guard that blocked everything whenever a tool hiccupped would stall every agent at once. It also sees only the command line, so a script or the GitHub web page gets past it. The real boundary is on GitHub: the required merge-path check on pull requests into develop and the branch rulesets. DEVSTRIDE_MERGE_GUARD=0 turns it off; never use that to get past a block — ask the owner.

The hook finds its script through $CLAUDE_PROJECT_DIR (the folder the Claude session started in), else the git root of the folder the hook runs in, and exits quietly where neither has it — another repository, or an old branch. Codex runs project hooks only after a person approves them once in its interactive /hooks screen, and a Claude Code desktop session runs them only when opened on the repository's folder. The repository's ds-agent-hooks skill records which surfaces have been proven covered and how to test one.

Agent service credentials

Agents reach outside services through their own least-privilege credentials, not through a person's browser session. The credentials live only in the agent secrets bundle: you store each one with ds secrets set agent <KEY> (value on stdin). They never go into the shared bundle or GitHub Actions — and never into any checkout's .env. ds secrets pull writes them to one private file outside every checkout, ~/.config/devstride/agent.env (mode 600; DEVSTRIDE_AGENT_ENV_FILE moves it), and only ds agent, ds quickbooks, ds graph, ds work and ds -b stripe billing-inventory read it. Why: every ds command loads the checkout's .env, so a token kept there would travel with every command run anywhere on the machine, the owner's own checkout included. None of the commands below needs a stage bind.

ds agent needs no AWS login at all. ds quickbooks and ds graph rotate-secret check the AWS login first, because the provider may hand back a new credential — a QuickBooks refresh token, a new Graph client secret — which is written straight back to the agent bundle and to ~/.config/devstride/agent.env in the same run. A new Graph secret is proven to sign in before it is stored, and the old one is retired only once every place holds the new one. If a store is only partly done, the command names where the value landed: put it in the bundle before anyone runs ds secrets pull, or the next pull brings back the old value.

Creating each credential in the first place — the API key, the GitHub token, the Intuit and Entra apps — is an owner step, done once in each provider's console and stored with ds secrets set agent. Every flag is in the Command Reference.

When an agent needs a browser

A real browser is the fallback of last resort, for the few tasks no agent credential covers yet — for example Stripe dashboard configuration, the Intuit developer console, the Teams app registration in the Azure portal, Seed, the Neon console, and anything only the DevStride UI shows. The repository's ds-agent-browser-fallback skill keeps the current list, and a task that is not on it is added there before it is automated.

• A dedicated, signed-in Chrome profile. Agents never drive a person's everyday browser profile. On each agent machine, add a Chrome profile named DevStride Agent in the same macOS session the agent runs in, install and connect Claude in Chrome there, and have the owner sign it in to each fallback site once. The agent opens each page and fills everything except the credential.
• Signed out? One notification, then move on. Before acting on a fallback site the agent checks the page is signed in — a redirect to the site's login page, or a sign-in form where the content should be. If it is signed out, the agent sends one notification naming the site and the blocked task, parks that task and takes the next one. It never polls, retries or waits on the login, and a second task blocked on the same still-signed-out site sends nothing more that session. It resumes once the owner says the site is signed in.
• Agents never type a credential. Not a password, not a one-time code, not in the agent profile either. Signing in is always the owner's single step.