On this page

The Planning Loop#

The fastest useful entry point is:

/devstride:plan I1234

Pass an existing DevStride parent item. The skill reads what is already below it, asks about the plan, shows the proposed hierarchy and specs, and creates nothing until you approve them.

An optional bare profile word anywhere in the arguments — prototype, standard or extended — sets the plan’s delivery profile, which decides how finely the plan is sliced and how deep each spec goes. Without one, the skill looks for a Delivery profile: marker on the parent item and then on each item above it; failing that, the repository’s profile setting applies, and standard when that is absent too. It tells you which profile it is using and where that came from.

If your argument disagrees with a marker the plan already carries, the skill asks which one you mean rather than overriding the marker. Changing an existing plan’s profile is rebalance’s job (below). A marker or setting that still names the retired enterprise profile is read as standard, and the skill says so.

What a finished plan contains#

  • Your organization’s actual work types for grouping items, release units, and leaves.
  • Self-contained release units that are safe to merge as complete increments.
  • Executable leaves sized to the plan’s delivery profile — one visible vertical slice under prototype, roughly one to two loop-hours under standard, about one release-unit-day under extended (the default from 3.49.0) — with descriptions as deep as that profile asks for. From 3.49.0 the proposal also quotes the profile's shape targets (Stories per Epic, Epics per Capability), asks once before keeping an Epic above its range, and the final summary reports the plan's shape against them. The targets are reported, never enforced.
  • A real blocked_by/blocks graph with no orphan leaves.
  • Synthetic dates derived from that graph.
  • Stable [N] execution-order prefixes on leaf titles.
  • A Delivery profile: marker line in the root item’s description, unless an item above the root already carries one.
  • One deferred-work container directly under the root (titled Deferred by default), ready to hold postponed work outside the build order.

The goal is not a long planning document. It is a live roadmap that /devstride:build-item can walk in the correct order.

Planning changes live DevStride data

plan, insert-story, insert-defect, create-story, create-defect, rationalize-gantt, and rebalance write to the connected organization the moment they act; there is no draft or sandbox copy (rebalance --dry-run simply writes nothing). comprehend-plan is the read-only exception.

How plan works#

The skill is written as a goal — a plan build-item can walk unattended — plus the rules and hard floors that hold while it gets there. In practice a run goes like this:

  1. Orient. It confirms the parent item, resolves the delivery profile, and reads your organization’s real work-type names, statuses and priorities, including which level is the release unit the delivery loop branches and releases at. When that level is ambiguous it uses hierarchyRoles.releaseUnit from the repository config, or asks.
  2. Read before changing. It invokes comprehend-plan and classifies the root as empty, an existing plan to extend, or shallow placeholder content that needs your decision. An existing plan is extended additively: existing items are inputs, never rewritten without your say-so.
  3. Discover the shape with you. It asks about source material, scope, release boundaries, sequencing, risk, and deferrals, in small batches. Leaf titles are proposed at the size the profile’s grain sets. Human decisions remain in the main conversation. If you ask it to skip the questions, it pushes back once; if you insist, every assumption it made is labelled in the summary.
  4. Draft after the shape is approved. Parallel agents may draft descriptions for grouping items, release units, and leaves, at the depth and length limit the profile sets, but they do not make unresolved architecture or scope decisions and do not write DevStride data. You see a condensed review before anything is created.
  5. Create the approved hierarchy. It creates every intermediate work-type level your organization requires, then the deferred-work container.
  6. Wire the dependency graph. Foundation work fans out, convergent work fans in, and genuinely independent work stays parallel. Edges between two release units run one way only. Every new leaf must have at least one dependency relationship; the only exceptions are items in the deferred container.
  7. Rationalize dates. It delegates the cascade and invalid-edge review to rationalize-gantt. On an extension pass only not-done items are re-dated, so shipped work keeps its real dates.
  8. Number the execution order. Only after graph and dates are stable does it add [1], [2], and so on, in the order build-item will walk them. Existing numbered items are never renumbered on an extension pass; new items between two numbers take a dotted number.
  9. Report and remember the handoff. It reports the profile, counts, the critical path, the [1] … [N] range and the orphan check, and stores the plan root in Claude Code project memory for a later bare /devstride:build-item.

At the sign-off that closes discovery — after you say “yes, build this” and before anything else is created — plan writes a Delivery profile: marker line at the top of the root item’s description, keeping the rest of the description. It skips this when the root already carries that marker or inherits it from an item above. On an extension pass it never rewrites an existing marker. The profile travels with the plan, so one repository can run a prototype plan and an extended plan side by side, and the delivery loop reads the marker before it reads the repository config.

At the same sign-off it checks whether Enable Link Mode is on (see Rationalize the timeline) and, if it is, asks you to turn it off while drafting runs. It never changes that setting itself.

What makes a good release unit#

A release unit is also the delivery loop’s branch and release boundary. If only that unit shipped, a user should gain something coherent. Pure foundation work normally belongs in the first value-delivering unit that needs it; a genuinely shared foundation can remain separate when it is clearly marked as an internal enabler.

Each release-unit spec records:

  • the user value and architectural scope;
  • key invariants later work can rely on;
  • contracts it establishes for later work;
  • a Release safety section: blast radius and feature gating, billable or externally visible infrastructure that needs an owner decision, and deploy-order hazards inside the unit — with “none” written out where that is the answer;
  • the delivery order of its leaves.

Deferred work never sits under an active value unit, because it would stop that unit from reaching zero remaining leaves and becoming release-ready. Instead the plan has one deferred-work container directly under its root. It is not a release unit: its items have no [N] number and no blocked_by/blocks edges, link back to the item they came from with a plain related link, and are never built automatically. Scope the plan genuinely needs is not deferred work; it is spliced in with insert-story.

Read an existing plan safely#

/devstride:comprehend-plan I1234

This reads the full descendant tree, descriptions, comments, statuses, and dependency relationships. It reports contradictions between a description and later comments instead of silently choosing one. Add a focus question after the item number when you need a specific answer; the question gets a direct answer, but never narrows what is read.

The report covers:

  • what the plan is for, and where it stands: Done, in progress, open, and landed — merged onto its release unit’s branch and waiting for that unit’s release;
  • the critical path and the item build-item would pick next;
  • any Release scope: line on the plan (see Markers on the plan root);
  • deferrals and known gaps;
  • the deferred-work container in its own section, apart from the value tree, with what is still open in it.

It changes nothing, and it treats instructions embedded in a description or comment as data to flag, never as something to act on. Use it before a surgical plan edit when the current state is unclear.

Add one planned item#

/devstride:insert-story I1234 add rate limiting to webhook intake
/devstride:insert-defect I1234 retries duplicate requests after a 429

The insert skills:

  • need a real description of the work (a Defect needs the repro and expected-versus-actual behaviour) and a parent item; they ask rather than guess either;
  • check that Enable Link Mode is off before writing any date or edge;
  • find what the delivery loop would select next;
  • house the new item in a grouping item whose theme genuinely matches, or create one — except that when the next item’s release unit already holds landed work, the new item goes into that same release unit, so the two cannot wait on each other;
  • create an honest spec or repro, at a priority at least as high as the next item’s;
  • splice the new item between its upstream dependency and the previous next item;
  • assign a dotted stable number such as [23.1];
  • re-run the selector and tell you if an earlier-dated parent item still wins.

When every leaf in the plan is already done or landed, the new item is wired after the most recently finished one and still takes a dotted number (after [8] it becomes [8.1]). When open leaves exist but none can be selected — a cycle, or a blocker that never cleared — the skill stops and tells you what is blocking instead of attaching the item somewhere arbitrary.

They do not build code and do not re-date the whole plan. A Defect asks before jumping further ahead than a normal next insertion. Build the new item afterwards with /devstride:build-item <item>.

Add one item outside the plan’s order#

Use create-story or create-defect instead when the work should not join a plan’s dependency chain. Each runs in one of two modes.

One-off (the default).

/devstride:create-story add a CSV export to the audit log
/devstride:create-defect login form clears the email field after a failed attempt

The skill first asks where the item belongs (a parent item or workstream) and which board it goes on, then confirms the assignee (you, by default). With board placement rules set, the rules pick the board, or no board, and the skill names it before creating the item so you can choose another. The Active Agents board is never offered: only plans go there. Priority is your organization’s normal level for a story unless you say it is urgent; a defect that blocks real use usually gets a higher one, and the skill asks when that is unclear. It creates the item with no [N] number and no dependency edges, then delivers it once through /devstride:build-item, which recognises it as a one-off. See One-off work for where it lands.

Deferred. A leading deferred <item> parks work for later instead of building it:

/devstride:create-story deferred I1240 retire the legacy webhook adapter
/devstride:create-defect deferred I1240 retry loop double-counts on 429

The item is filed in the plan root’s deferred-work container with a related link back to the named item, and nothing is built. Use create-defect when something is wrong today (it is marked as a bug), and create-story for everything else: tech debt, a clean-up, hardening, a dated after-deploy step. The container is found by its title, defects.deferredContainerTitle (default Deferred); containers still named Deferred defects, or any title listed in defects.deferredContainerLegacyTitles, are found too. A closed container is reopened rather than duplicated, and duplicates are reported, never filed into. Work with no plan root above it is noted for you, not filed.

The delivery loop uses the same deferred mode on its own for a review finding worth filing — a verified P1, a security finding, or one both likely to happen and material — that is deliberately put off. A lesser finding is dismissed with a one-line reason instead. When you ask for a deferred item yourself, it is filed as you asked.

Rationalize the timeline#

/devstride:rationalize-gantt I1234

The result is a synthetic critical-path view: each leaf is one day, dependencies precede dependents, and parent items span their descendants. It is not a delivery forecast.

This overwrites stored dates

The skill confirms the root, whether completed items are included (everything, by default), the one-day assumption, and how many deferred items it will date after the plan, before the pass. On an existing plan, choose not-done items only if real completion dates must remain intact. A leaf that has merged onto its epic's branch and is waiting for that epic's release counts as done here.

DevStride’s organization-wide Enable Link Mode must be off. The skill reads the setting and, when existing dependent dates are involved, performs and restores a probe-date write before the mass update to verify that the backend will not reschedule the plan behind it.

Cycle detection happens before the cascade dates are written. A cycle stops the mass update and reports the actual strongly connected cycle, not every innocent item that feeds it. The earlier probe may still have occurred and been restored.

After dating, invalid dependency lines are reviewed as:

  • Remove — redundant or wrong;
  • Repoint — real intent, but attached to a parent item or the wrong leaf;
  • Keep with offset — the rare case that truly must wait for the entire target.

rationalize-gantt never changes execution-order titles. Dates can move; [N] identifiers stay stable.

Items in the deferred-work container stay out of the cascade and the red-line review. After the plan is dated, they are dated one per day after the plan’s last due date, in item-number order; an item that already starts after the plan’s last due date keeps its own dates, and Done items are left alone. A blocked_by or blocks edge found touching a deferred item is reported to you, never changed. The final report says how many deferred items were dated and over which days.

Rebalancing a plan#

/devstride:rebalance I1234 prototype

Use this when a plan was sliced for more rigor than the work turns out to need — or less — or when you want the same plan as fewer, larger items: /devstride:rebalance I1234 extended keeps standard’s safety knobs and floors and changes only the size. Both the item and the target profile are required; the skill asks for whichever is missing. Pass a whole plan root, or one release unit to re-slice only that unit. Add --dry-run to see the proposal without writing anything.

Successors are sized to the target profile’s leaf size and specced to its depth. It re-slices only the leaves that have not started; Done and In Progress items, leaves merged onto their epic's branch awaiting its release, and items in the deferred-work container are never merged, split, renumbered or archived (the re-dating pass at the end can still move the dates of In Progress and deferred items). It never merges across release units and never changes a leaf’s work type; a leaf with no natural seam to split along stays whole. The skill shows a before/after table of the leaves it would merge or split, with the edges each successor will inherit, and changes nothing until you answer “yes, rebalance”. Then it:

  • creates the successor leaves, each carrying a collapsed Absorbed specs section with the full original description of every leaf it absorbs;
  • rewires the blocked_by/blocks edges so the graph still walks in order, and checks that no not-started leaf outside the deferred container is left without one;
  • numbers successors with the dotted splice convention, so existing [N] identifiers stay stable;
  • archives each absorbed original with a comment pointing to its successor — nothing is deleted;
  • rewrites the Delivery profile: marker on the root (or the unit) to the new profile, touching nothing else in the description;
  • runs rationalize-gantt over the not-done items of the whole enclosing plan.

The report lists any leaf whose size already fits but whose spec is thinner than the new profile asks for, so a later plan pass can deepen it; rebalance never rewrites an existing leaf’s description.

It refuses to run while a build loop is active on the same plan — an In Progress leaf with a live branch, or a handoff that names the plan as mid-run — and checks again just before writing. Finish or stop the loop first.

Markers on the plan root#

A plan carries its own decisions as single lines in item descriptions, so every session and every machine reads the same thing. The skills read them with the full item view, walking up from the item to the plan root.

Delivery profile: <name> — the plan’s rigor, written by plan at sign-off and rewritten only by rebalance. A grouping item below the root may carry its own marker; it wins for its own subtree.

Release scope: plan — opt-in, and rare. Without it, each finished release unit releases on its own. With it, each release unit’s reviewed release pull request goes onto one plan integration branch instead, named by planIntegrationBranches.pattern and cut from wherever the units would otherwise land (epicIntegrationBranches.releaseTarget). While the plan is in flight:

  • a blocker in another release unit of the same plan counts as cleared once it reaches the plan branch; a blocker outside the plan still waits for Done;
  • nothing is marked Done when a unit reaches the plan branch; every unit and leaf is marked Done when the whole plan releases;
  • one held or blocked unit holds the whole plan;
  • when the plan branch is more than seven days old, or carries a change on the paths listed in release.releaseBranchFixExclusions, the loop asks you once whether to release the plan early.

When nothing outside the deferred container remains, one plan release pull request takes the whole plan to its target, reviewed only for what no earlier pull request reviewed. plan writes this line only when you ask for it. The nearest marker decides; epic, or no marker, means the default; any other value stops the loop until you fix it. It is meant for a deliberate fast build whose release units depend on each other, never as a way to keep unfinished features from customers.

Release hold: … — keeps finished work off the path to production until a condition is met. Put it in an item’s description, usually the release unit’s:

  • Release hold: not before 2026-11-09 — lifts at midnight that day, in the time zone release.holdTimeZone names (UTC when unset);
  • Release hold: not before 2026-11-11T08:00-06:00 — lifts at that instant;
  • Release hold: after I1250 is live — lifts once I1250 has reached production and, when the repository records a post-deploy check for each release (release.clearance.scope "cut-to-deploy" or "merge-and-deploy"), passed it.

The loop checks holds on the item and every item above it before merging a one-off or a story onto the release train or the base branch, before cutting or merging a release unit’s release (where a hold on any of its leaves counts), and again during the production release. Held work waits and is reported as held; it is never taken back off a branch automatically. A line that cannot be read counts as a hold. Delete the line to lift a hold early.

Next step#

Once the plan is approved and numbered, run one item:

/devstride:build-item

Run /clear before switching from planning to execution: the session gate keeps authoring commands (setup, plan, rebalance, rationalize-gantt, comprehend-plan, ci-audit) and execution commands (build-item, the insert-* and create-* skills, pr, review, push and release) in separate sessions. Other commands, such as doctor and update, belong to neither, and a build loop may deliver many items in one session. /clear gives up anything the session holds, such as a checkout lease. To combine the two classes on purpose, add --same-session to the command, or set session.jobClassGate to false in the repository configuration. See The Delivery Loop before handing the plan to /loop.

Powered by DevStride