How DevStride Is Built, and Why

Much of the code in this repository is written by Claude Code agents, often several at once, on more than one machine, landing in a codebase customers use the same day. That works because the system around the agents was designed for it. This page explains that design before any command does. Once the idea lands, the rest of these docs read as details of one plan rather than a pile of rules.

The idea in one paragraph

Work is planned in DevStride as a tree of items joined by "this must happen before that" links, so the next piece of work can always be worked out instead of chosen. An agent walks that plan one item at a time: it builds the item, checks it, merges it, and records what actually shipped on the item itself. Items under the same Epic collect on that Epic's own branch, where they are allowed to be unfinished. Only a finished, fully reviewed, production-safe Epic reaches develop, because in this repository develop is effectively production. Review always happens before the automated test runs (CI), and CI runs once, on the final reviewed code. Production releases are cut by the owner. Everything else exists to keep those few ideas true when many agents work at once.

The loop at a glance

Plan     Solution → Capability → Epic → Story / Defect, with dependency links
           │
Build    pick the next unblocked item → In Progress → branch → build
           → risk check → green local checks → merge onto the Epic's branch
           → update the item with what actually shipped → next item
           │
Release  last Story done → Epic is release-ready → owner cuts its one
           pull request into develop → full review → CI once → merge
           │
Promote  owner cuts release/YY-MM-DD from develop → full review → CI
           → owner says yes → master → production

Each stage is run by the DevStride plugin's /devstride:* skills, covered in The Planning Loop and The Delivery Loop.

Why it is shaped this way

A plan you can walk, not a list you pick from

What it is. A plan is a tree: grouping levels at the top, Epics in the middle, and Stories and Defects at the leaves, joined by dependency links. Each leaf is sized so an agent can build it in one sitting, and each one shows as a day on the plan's timeline.

Why. If "what's next" is a judgement call, an agent can't work through a plan unattended. With links in place, the next item is simply the highest-priority unfinished leaf whose blockers are done. The plan is still a guess, though: when the code proves it wrong, the agent rewrites the item's description to match what actually shipped and keeps the original as a comment.

The tracker is the memory

What it is. Each item's description, comments and status are the lasting record of the work. A review finding that is out of scope becomes its own item. It is never left as a sentence in a pull request.

Why. Pull requests close and nobody reads them again; agent sessions end and forget. The tracker is where the next session, or the next person, will actually look.

Epics are the safety unit, because develop is production

What it is. develop is promoted to master, and so deployed to customers, several times a day. So no Story merges straight to develop. Stories collect on their Epic's integration branch, and when the last one lands, the whole Epic goes to develop in a single pull request. Small one-off fixes that belong to no Epic ride a shared branch called the support train, which every release carries into develop. The one exception is a one-off that changes deploy configuration or the database migrations: it gets its own pull request into develop, so the shared development deploy runs it before any release does.

Why. There is no quiet period between develop and production in which to tidy up. A half-built feature on develop would be live within hours. The Epic is the unit that is complete enough to be safe, so it is both what we release and what we check for safety. Before an Epic merges, its new infrastructure must actually exist, anything that costs money must already be agreed with the owner, and every visible change must be safe to go live that afternoon.

Fast mode moves the review gate; it never removes it

What it is. A Story on an Epic branch gets no pull request of its own. It gets a quick, bounded risk check, plus a dedicated extra check whenever it touches sign-in or permissions, a database migration, anything that cannot be undone, or a contract a deployed service depends on. That extra check is never skipped. Then it must pass the local checks before it can merge. The full review and CI then run on the Epic's pull request, over the whole Epic's changes.

Why. A pull request, cloud review and CI run for every Story is expensive in money and in hours of waiting, and the Epic's pull request has to review all of that code anyway. Doing it once, on the finished Epic, also lets the reviewer see the Stories together. This only works because the Epic review covers everything: under fast mode it is the first time any outside reviewer or CI sees that code.

Review first, CI once

What it is. Every pull request opens as a draft, and CI does not run on drafts. Two reviewers run first, on every pull request: an adversarial Claude pass and the Codex command-line reviewer. GitHub Copilot joins only on pull requests into master, once, on the final version. When every finding is dealt with, the pull request is marked ready, and that is what starts CI, once, on the code that was actually reviewed. In this repository the heaviest cloud checks (the backend test suite, the linters and the UI tests) run on the release pull request into master, once per release. Before that, the same checks run on the team's own machines: every Story passes ds verify land (every type-check, lint on changed files, and every test that reaches the changed code) before it merges, and every pull request into develop must carry a green local-ci status, posted by a full local run of everything cloud CI would do. See local-ci.

Why. CI that starts before review finishes runs again after every fix, and each run is thrown away. Two rounds of review is the normal target. A confirmed serious problem keeps opening new rounds with no limit until a round finds none. A finding that needs an unlikely coincidence to happen at all is dismissed with a one-line reason rather than fixed "to be safe". Code written for imagined problems slows everyone down.

One word sets the rigor

What it is. A delivery profile (prototype, standard, extended or enterprise) sets how finely work is sliced, how hard it is reviewed and which checks a Story must pass, all together. This repository runs standard, with a few settings pinned on purpose. For example, a finished Epic waits for the owner instead of releasing itself. Some protections hold under every profile: every Story gets a risk check and green local checks, risky kinds of change get their dedicated check, and full review always comes before CI. See Choose a delivery profile.

Why. The settings depend on each other: big Stories under the strictest review produce dozens of findings each. One word keeps them in proportion.

Production releases are the owner's call

What it is. A release is cut from develop as a protected branch, release/YY-MM-DD, while develop keeps accepting merges for the next one. The release gets the full review and CI, then merges to master only when the owner explicitly says yes.

Why. Merging to master deploys to customers automatically. Starting a release only prepares it; it never counts as permission to deploy.

Many agents, one repository, one production

Several sessions share each machine, several machines share the repository, and all of them share one production. Each rule below exists because its opposite actually happened.

• A fixed set of checkouts, taken with a lease. Each machine has three checkouts: the main checkout, wt1 and wt2. A session takes one with a lease that records which session holds it, and hands it back when done. Agents never create extra worktrees: sessions once did, "to be safe", and left fourteen behind that nobody cleaned up. Twice, a session switched branches under another one that had looked free. See The Checkout Pool.
• Agents have identities of their own. An agent machine signs in to AWS with its own certificate, not a person's login, and one command can switch it off everywhere. The agents' own service credentials live in one private file outside every checkout, so ordinary commands never carry them. See Set up your machine and Agent service credentials.
• A guard that slows you down, and checks that actually stop you. A local hook refuses pushes straight to develop or master, and merges that break the routing rules. It is a speed bump, not a lock, and it fails open. The real boundary is on GitHub. A required check rejects any pull request into develop from a branch that has no business there, a second required check (local-ci) rejects one whose full local check has not passed on its exact head, and branch rules stop anyone from rewriting a release branch.

Knowledge lives in the repository

An agent's private memory stays on one machine and nobody else can see it. So a lasting fact about the team (a convention, a trap, a procedure worth repeating) is committed to AGENTS.md or to a skill under .claude/skills/. Those files change several times a day too, so an agent re-reads a rule from develop before acting on it, rather than trusting the copy it loaded hours ago.

What stays human

The agents run the loop from start to finish, but some decisions are never theirs:

• merging a release to master, which means deploying to customers;
• cutting a finished Epic's release into develop, which in this repository waits for the owner rather than happening automatically;
• anything that costs money or changes infrastructure, agreed before the Epic merges;
• a review finding that is ambiguous, or that can't be checked;
• signing in, or any other step only a person can do, which the agent hands over as one clear step.

Where to go next

• The idea behind the loop: the same design, as the public plugin describes it for any repository
• The Developer Guide: from a blank Mac to your first merged story, starting with Set up your machine
• DevStride for Claude Code: install the plugin and pick your entry point
• The Planning Loop and The Delivery Loop: each stage in detail