Skip to content

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.

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"
  1. Configure the repository and the project once (Configure).
  2. Specify what version one must do, once (Specify).
  3. Plan one milestone (Plan).
  4. Build that milestone’s issues (Build).
  5. Release it (Release), then go back to Plan for the next milestone.

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 with TODO(spec) markers, a draft Plan: <v> issue (/dotplanning <v>), worktrees whose agent is gone with none still running (/wave <v>), or a chore/release-X.Y.Z branch for the milestone with no tag (/release X.Y.Z). /next prints that command on its Type: 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.

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.

What it’s for: Turn the template into your project: name, personas, stack, license, code owners, CI, and the git hooks.

Type this:

Terminal window
make doctor
make setup

Then, 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.

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

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

What it’s for: Audit once, cut the release, tag it, and close the loop.

Type this:

/pre-release full
/release

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

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.

Everything a step needs is in files and the tracker, so closing the terminal loses nothing but the conversation.

  • Configure and Specify: /kickoff and /spec resume from what the files show and skip what is answered. Run the same command again.
  • Plan: the ~/Downloads report, the Plan: <v> issue (ships in 0.8) and the labels already applied to your issues survive. /dotplanning saves each answer to the Plan: <v> issue, and make status shows 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::wip claims, pushed branches and open MRs survive. Run scripts/wt list to see them, scripts/wt release <issue> to give up a claim, and scripts/wt prune to remove merged worktrees. Automatic resume for /wave ships in 0.8.
  • Release: the chore/release-<version> branch, its MR and the tag survive. /pre-release full resumes from the issues it already filed and the earlier summary comments on Plan: <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.

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.