Skip to content

by-carlos/plan-staged-rollout / skills/staged-rollout

staged-rollout

Unverified

Run 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.

FileKindSize
SKILL.mdskill md52.3 KB
references/decisions-format.mdmarkdown6.1 KB
references/estimates.mdmarkdown5.5 KB
references/plan-review.mdmarkdown7.4 KB
references/programme-format.mdmarkdown2.8 KB
references/remote-driver.mdmarkdown18.3 KB
references/templates/BRIEF.mdmarkdown3.0 KB
references/templates/LEDGER.mdmarkdown3.3 KB
references/templates/PLAN.mdmarkdown48.0 KB
references/templates/README.mdmarkdown8.2 KB
references/templates/RUNNER.mdmarkdown9.7 KB
references/templates/stage-N.mdmarkdown2.1 KB
references/templates/stage-f-review.mdmarkdown11.2 KB
scripts/artifacts_check.pyscript5.6 KB
scripts/effortlog.pyscript18.0 KB
scripts/estimates.pyscript14.4 KB
scripts/plan_run_local.pyscript31.4 KB
scripts/renumber_stages.pyscript13.2 KB
tests/fixtures/drift-plan/.plan/LEDGER.mdmarkdown1.0 KB
tests/fixtures/drift-plan/.plan/PLAN.mdmarkdown1.7 KB
tests/fixtures/live-plan/.plan/LEDGER.mdmarkdown564 B
tests/fixtures/live-plan/.plan/PLAN.mdmarkdown1.4 KB
tests/fixtures/live-plan/.plan/stage-0-scaffold.mdmarkdown90 B
tests/fixtures/live-plan/.plan/stage-1-build-api.mdmarkdown83 B
tests/fixtures/live-plan/.plan/stage-2-deploy-staging.mdmarkdown87 B
tests/fixtures/live-plan/.plan/stage-3-migrate-data.mdmarkdown97 B
tests/fixtures/live-plan/.plan/stage-4-warm-cache.mdmarkdown84 B
tests/fixtures/live-plan/.plan/stage-5-runbook.mdmarkdown87 B
tests/fixtures/live-plan/.plan/stage-f-review.mdmarkdown81 B
tests/test_artifacts_check.pyscript5.9 KB
tests/test_discovery_bound.pyscript2.3 KB
tests/test_estimates.pyscript10.7 KB
tests/test_plan_run_local.pyscript18.3 KB
tests/test_preflight_ahead.pyscript3.3 KB
tests/test_renumber_stages.pyscript17.0 KB

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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall