by-carlos/plan-staged-rollout / skills/staged-rollout
staged-rollout
UnverifiedRun a large build as many small, resumable sessions by decomposing it into a `.plan/` folder of dependency-ordered stages with an evidence ledger, then executing one stage per fresh session. Use when the user says "this is too big for one session", "plan a staged rollout", or describes a multi-day build that needs cross-session progress tracking.
references/templates/README.md
View on GitHub# `.plan/` — <Project name>
Ledger-driven, one-stage-at-a-time rollout, built to run in **short,
low-context sessions you can pick up whenever you have time**. Each stage runs
in its own fresh session and lands as its own PR, so context never accumulates
and any single stage is easy to review or undo.
## How to run a stage
Start a **fresh** session and paste one line:
> Follow the instructions in `.plan/stage-<N>-<slug>.md`.
That's the whole prompt — the stage file points the session at the shared
protocol and frozen decisions in `PLAN.md`. If this repo has the
`plan-staged-rollout` plugin installed, asking to **"run stage \<N> of the
plan"** — or the explicit command `/plan-staged-rollout:stage-run <N>` — is
the same thing with ergonomics (it also runs the model/effort weight check
for you). The `.plan/` folder works standalone either way; the plugin is
convenience, not a dependency.
Every way of running a stage takes the same two steps before the work:
- **Brief stamp.** If `BRIEF.md` exists and its stamp no longer matches
`PLAN.md`'s hash, the session regenerates the brief from `PLAN.md` and
commits it on the plan branch — so the brief you read is never older than
the plan.
- **Decisions in force.** The session shows the entries of the repository's
decisions document whose `Paths:` overlap the stage file's `## Artifacts`,
and treats them like frozen decisions. The document is the one `PLAN.md`'s
Frozen decisions record as adopted (an existing current-decisions
document, or `DECISIONS.md`), else `DECISIONS.md` at the repository root.
Without a `BRIEF.md` or a decisions document, the matching step does nothing
and the stage runs as it always has.
Run stages in any order allowed by their `depends`. The **runnable set** is
every `todo` row in `LEDGER.md` whose dependencies are all `done` or
`skipped` — often more than one. Stages in that set do not depend on each
other, so you can run them
**concurrently, one per fresh session** (one terminal each) — each one works
in its own worktree, so they never collide. `PLAN.md`'s *Runnable set & waves*
defines the set and shows how waves and the critical path are derived from the
`Depends` column — they are never stored as a column of their own.
<!-- If a strict majority of stages in PLAN.md's stage index share a `model`,
bootstrap fills in a line here, e.g.: "6 of 8 stages recommend `opus` —
setting it as your session default means the weight gate only prompts on the
exceptions." Delete this comment (and the line above, if bootstrap didn't add
one) once filled. -->
## Files
- `PLAN.md` — architecture, **frozen decisions**, stage index, and the
operating protocol every stage session follows. Single source of truth for
decisions; changed only when a decision changes.
- `LEDGER.md` — status table + per-stage as-built notes. The tracker that
changes as you execute; the resume point and cross-session memory.
- `BRIEF.md` — the one-page brief, generated from `PLAN.md` (stamp on line
1, never edited by hand). Feedback on it goes into `PLAN.md`, and the brief
is regenerated.
- `stage-<N>-<slug>.md` — one small, self-contained stage each.
- `RUNNER.md` — the stage-runner contract: how a session with no plugin and
no prior context (a fired cloud session included) runs one stage from the
one-line instruction "run stage \<N> of plan branch \<branch>; first run
`git fetch origin <branch> && git checkout -B <branch> origin/<branch>`,
then follow `.plan/RUNNER.md`". Keep the checkout in the instruction: a
cloud session starts on the default branch, where this folder does not
exist.
- `decisions-format.md` — a copy of the portable decisions-document spec. The
final review stage reads it first, and a cloud session has no plugin to
read it from.
- `BLOCKED.md` — only present once a stage has been blocked outside the
ledger: by an unattended driver that ran out of attempts, or by a stage
session that blocked after its stage branch existed (`PLAN.md`, *Recording
a block*). Either way it is kept out of `LEDGER.md` so it never collides
with a stage branch's unmerged ledger edits, and a session's section points
at the stage branch and PR that hold the full runbook. Delete a stage's
section there once that stage is resolved.
## Git & worktree model
```
main
└── plan-<slug> ← plan branch; .plan/ lives here
├── plan-<slug>-s0 → PR → plan-<slug>
├── plan-<slug>-s1 → PR → plan-<slug>
└── ...
plan-<slug> → final PR → main ← at /plan-close
```
**The clone holds the plan; worktrees hold the work.** This clone stays on
`plan-<slug>` for the whole plan — that is the only branch checked out here,
which is why `.plan/` is always in front of you. Each stage branch is checked
out only in its own sibling directory, created when the stage starts and
removed once its PR merges:
```
../<repo>-s1/ ← worktree, branch plan-<slug>-s1
../<repo>-s3/ ← worktree, branch plan-<slug>-s3 (running concurrently)
```
A fresh worktree has only tracked files, so a stage that needs untracked local
setup (`.env`, local config, caches) copies it in and says so in the ledger. A
worktree with uncommitted or unpushed work is never removed automatically — it
is reported, shows up in every later preflight, and blocks closeout.
`.plan/` is **tracked** on the plan branch, and the plan branch is pushed with
an upstream. Don't add `.plan/` to `.gitignore`: an untracked plan can't
produce the per-stage commits and PRs this model runs on, and a local-only
plan branch makes each session's sync a silent no-op.
When two stages run at once, nothing above changes — there are simply two
stage branches open in two worktrees, both cut from the same plan-branch tip.
The plan branch is the serialization point: their PRs merge one at a time, and whoever merges
second first merges the plan branch into their stage branch and re-runs the
stage's acceptance check. `PLAN.md`'s *Concurrent stages* has the full rules,
including the one race worth knowing about — the `done` ledger write is a
direct commit on the plan branch, so it is made after the fast-forward and
replayed (never force-pushed) if a sibling wins.
Every stage gets its own branch and PR into the plan branch — the only
supported model, fixed at bootstrap. Branch names are flat (`plan-<slug>-s3`,
not `plan/<slug>/s3`) because git refs can't nest a branch under an existing
branch name. Commits on a stage branch are compulsory and incremental —
logical units as the stage progresses, not one commit at the end. Branch
creation and pushes are autonomous on feature branches — the agent creates
and pushes stage/plan branches without asking, and opens the stage PR as a
compulsory part of finishing a stage; merges are offered and happen only on
your OK, and it never pushes to `main`. The one carve-out is `merge: auto` on
`PLAN.md`'s plan flags line: that is your OK given in advance for **stage PRs
only**, so the session squash-merges its own stage PR once checks are green —
the plan→main PR is yours in every mode. A stage cannot be marked `done` until
its PR is merged into the plan branch. Stage PRs are squash-merged into the
plan branch; the final PR from the plan branch into `main` is a normal
(non-squash) merge, so each stage keeps its own commit on `main`. This needs
the GitHub repo to allow both squash merging and merge commits (recommended:
squash message = "Pull request title and commit details", merge-commit
message = "Pull request title and description").
## Closeout
When every ledger row is `done` or `skipped`, close out the plan — ask to
**"close out the plan"**, or run the explicit command
`/plan-staged-rollout:plan-close`, which is where the closeout steps live. It
distills `PLAN.md` + the ledger into the final PR body, removes any stage
worktree that is merged and fully pushed (anything holding unpushed work stops
it instead), deletes `.plan/` as the last commit — or keeps it, per the
`plan-dir` flag on `PLAN.md`'s plan flags line — and proposes the PR from
`plan-<slug>` to `main`.
**Closeout runs unattended too:** `/plan-staged-rollout:plan-close
--unattended` applies the plan flags instead of asking and opens the PR.
Merging that PR into `main` is always a person's job, in every mode.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |