The lifecycle
Which version? The large 0.8 changes (ships in 0.8) are still moving. See Which version should I use? before you start.
The big picture: A Blueprint project runs one loop. You Configure and Specify once. Then, for each milestone, you Plan, Build and Release, and the release loops back to the next plan.
Why it matters: Every command has its own reference entry, but no single place showed the order, what “done” looks like at each step, or what to type next. This page is that place. Start here when you are new, or when you have been away and are lost.
Lost right now? Run make status, or type /next in Claude Code (both ship in 0.8), to see where
you are and the one command to type next. See Where am I?, or find
your step in the checklist and run its Type this.
1. The loop in one picture
Section titled “1. The loop in one picture”flowchart TB C["Configure (once)"] --> S["Specify (once)"] S --> P["Plan (per milestone)"] P --> B["Build (per milestone)"] B --> R["Release (per milestone)"] R -. "next milestone" .-> P click C "/getting-started/lifecycle/#configure" click S "/getting-started/lifecycle/#specify" click P "/getting-started/lifecycle/#plan" click B "/getting-started/lifecycle/#build" click R "/getting-started/lifecycle/#release"
- Configure the repository and the project once (Configure).
- Specify what version one must do, once (Specify).
- Plan one milestone (Plan).
- Build that milestone’s issues (Build).
- Release it (Release), then go back to Plan for the next milestone.
2. The checklist
Section titled “2. The checklist”make status ships in 0.8. It prints this checklist for your project, one line per
step, so you can see which step you are on without remembering anything. Each marker
means:
- Done: the step’s files or tracker state are in place.
- Next: the first step that is not done. Run its Type this.
- Not started: a later step, waiting on the one before it.
- Blocked (
!): the step cannot proceed until something it names is fixed. - Interrupted (
⏸, drawn‖on a terminal): the step was started and stopped; the line names the command that resumes it: an unfinished/kickoff, a draft spec withTODO(spec)markers, a draftPlan: <v>issue (/dotplanning <v>), worktrees whose agent is gone with none still running (/wave <v>), or achore/release-X.Y.Zbranch for the milestone with no tag (/release X.Y.Z)./nextprints that command on itsType:line. - Cannot verify (
?): the script cannot confirm the step: the tracker did not answer or cut a list short, or a record or the spec’s front matter is incomplete. It is never shown as done. - Unplanned: work is being built with no milestone plan. That is fine for a free-form
/wave(see Build); it is only a note.
The Done when line under each step below says the same thing in words, for when you
cannot run make status.
3. One section per step
Section titled “3. One section per step”Every step has the same five headings: what it is for, what to type, what you will be asked, when it is done, and what comes next.
Configure
Section titled “Configure”What it’s for: Turn the template into your project: name, personas, stack, license, code owners, CI, and the git hooks.
Type this:
make doctormake setupThen, inside Claude Code at the project root, run /kickoff.
What you’ll be asked: A first round of free-text questions (what you are building, who uses it, the stack), then up to four multiple-choice rounds with a recommended default and its source on each. Step 4 of Start a project lists them.
Done when: make doctor is clean, the hooks are installed, and /kickoff has
finished without leaving [FILL IN markers behind (make customize lists any).
Next: Specify. Full walkthrough: Start a project.
Specify
Section titled “Specify”What it’s for: Write down what version one must do, and turn it into tracker issues.
Type this: /spec new to write a spec, or /spec <path> to audit one you already
have. When it passes the completeness gate, /spec import files the issues.
What you’ll be asked: The spec section by section, in template order. It asks only for what is missing.
Done when: the spec passes the completeness gate and its issues exist in the tracker,
each with an Issue: #N line written back into the spec, and its front matter’s
imported-version equals version.
Next: Plan. More: Spec-driven development.
What it’s for: Commit one milestone’s work before anyone writes code for it. Planning finds the missing screen or the undecided question while it is still cheap.
Type this:
/dotplanning 0.1What you’ll be asked: Twelve kickoff questions (theme, capacity, freeze date),
then, for every issue, whether it is committed (will land) or uncommitted (proposed,
not accepted). It never guesses. A project that uses dated milestones answers with
release:: labels instead; see Flows.
Planning is for committing a milestone’s work. A free-form /wave with no milestone needs
no plan; it shows as Unplanned in make status (ships in 0.8), not as an error.
The plan’s home will be the Plan: <v> issue, which /dotplanning creates or reuses and
keeps current (ships in 0.8). What it holds: Where things live.
Until 0.8 ships, the plan is the HTML report in ~/Downloads plus the labels on your issues.
Whether /voc runs for a given issue is decided by the
fast-paths table, not here.
Done when: every 🔴 gap and open question in the report is filed as an issue or
answered, and every issue in the milestone is committed or uncommitted.
Next: Build.
What it’s for: Turn the milestone’s committed issues into merged MRs, in parallel.
Type this: /wave, which creates one worktree and one delegated agent per issue, runs
the gates each change needs, and opens the MRs. See the guide
Start work with /wave and its entry in
Commands. When the MRs are green, /mass-merge is how a
wave lands: it stacks them, re-checks, and merges the safe prefix. For one issue by hand,
use scripts/wt new <issue>, then /mr.
What you’ll be asked: Which labels to pull from (and a milestone, if you use dated
ones), and a wave size (default 5). /mass-merge asks before it merges anything.
Done when: every committed issue in the milestone is merged on main with a green
pipeline, and scripts/wt prune has removed the finished worktrees. A committed issue
labeled waits::owner (it waits on a person, a paid run, a forge setting or a tag) does not
hold Build open: make status counts it on the Build row and /wave skips it. This ships in 0.8.
Next: Release. Per-issue gate chains: Development workflow.
Release
Section titled “Release”What it’s for: Audit once, cut the release, tag it, and close the loop.
Type this:
/pre-release full/releaseFix what /pre-release blocks on first. /release opens the release MR; you merge it,
then tag and publish by hand (Release workflow).
What you’ll be asked: /release confirms the suggested version before it changes
anything.
Done when: the release MR is merged and the tag is published.
Next: back to Plan for the next milestone. Once real users report on what
shipped, /voc-audit --calibrate scores what the persona panel predicted.
Did you run this first?
Section titled “Did you run this first?”Out-of-order runs produce work that looks fine and is not, so five skills check the step
before them and stop before doing anything (ships in 0.8): /spec import wants Configure,
/dotplanning wants Specify (or a project that says it has no spec), /wave <v> wants a
plan for <v>, /release <v> wants a passing /pre-release full on the current main, and
/pre-release full warns while committed issues are still open. A miss prints what is
missing, the checklist, one line of why, and a Next: command. A /wave with no milestone
needs no plan.
To go ahead anyway, add --anyway "<reason>", for example /wave 0.1 --anyway "hotfix". The
reason is printed back and recorded as gate: prerequisite/<step> — skipped (<reason>) in the
## Gates of any merge request the run opens. If the tracker cannot be reached the check says
so and asks you, instead of passing or refusing.
4. Getting back in
Section titled “4. Getting back in”Everything a step needs is in files and the tracker, so closing the terminal loses nothing but the conversation.
- Configure and Specify:
/kickoffand/specresume from what the files show and skip what is answered. Run the same command again. - Plan: the
~/Downloadsreport, thePlan: <v>issue (ships in 0.8) and the labels already applied to your issues survive./dotplanningsaves each answer to thePlan: <v>issue, andmake statusshows Plan⏸while that issue is a draft: run/dotplanning <v>again and it resumes where it stopped: the first unanswered question, or Step 3 when every question is answered (ships in 0.8). - Build: worktrees,
status::wipclaims, pushed branches and open MRs survive. Runscripts/wt listto see them,scripts/wt release <issue>to give up a claim, andscripts/wt pruneto remove merged worktrees. Automatic resume for/waveships in 0.8. - Release: the
chore/release-<version>branch, its MR and the tag survive./pre-release fullresumes from the issues it already filed and the earlier summary comments onPlan: <v>: it reports them and never refiles a finding./release <version>resumes from the branch, MR and tag: it reports what exists and offers to resume at the matching step, and never restarts silently or re-tags (both ship in 0.8). - One issue:
/next #<iid>(ships in 0.8) says where one issue sits: its phase, whether its work is in a worktree on this machine or an open MR, what blocks it, and the command to type to continue it. It never runs that command; you type it.
5. Where things live
Section titled “5. Where things live”Where things live maps each kind of work state (the plan, progress, findings, decisions and lessons) to its one home, and says whether it survives the session and whether a teammate can see it. The rule: decisions and progress live on the tracker; reviewed artifacts live in the repo.
6. When you need more
Section titled “6. When you need more”- Flows: the detail diagrams, one per flow.
- Development workflow: the gate chain for each kind of change.
- Commands: every command, what it does and when to use it.