Start a project
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: Step 0 checks your machine, then eleven steps take you from an empty folder to your first merged MR and a planned first milestone. Most are one or two commands.
Where this fits: the steps below are the Configure and Specify stages, plus your first Plan and Build. The lifecycle shows the whole loop.
Why it matters: Each step wires one piece of the safety net. Skip one and a later step quietly does less than you think — so every step ends with a Check that proves it worked.
How to read it:
bashblocks run in a terminal. Commands starting with/run inside Claude Code, opened at the project root (claude).- If a Check fails, fix that step before moving on. Common snags (auth, the deny hook, roles, hook failures,
make doctorwarnings,WARNlines frommake pre-push-checks) are on Troubleshooting. - Just want to see the workflow first? Try the 15-minute quickstart.
- Lost? Run
make status(or/nextin Claude Code; both ship in 0.8). It shows which of the five lifecycle steps is done and the one command to type next — see Where am I? below.
Terms you’ll see (all in the Glossary): a gate is any check that can say no (CI job, script, or review agent); the pre-MR gate batch is the review agents run together before an MR opens; a fast path is the row of the Fast paths by change class table in
CLAUDE.mdthat matches a change; a fragment is a one-line file inchangelog.d/that becomes a changelog entry; a worktree is a second checkout of the repo on its own branch; the harness is the files around Claude Code that steer it; VoC (/voc) is a simulated persona panel, and a wave (/wave) runs several issues in parallel.
What you need installed
Section titled “What you need installed”This covers the harness, not your application — Blueprint doesn’t know your stack.
make doctor checks the tools in the table below (not bash or node) and tells you what each missing tool costs you. It does not check your Claude Code login, or the login of any forge CLI other than the one your origin remote names.
Blueprint is GitLab-first. Use glab; gh is only for a GitHub origin.
Install everything in one line:
brew install git python3 glab jq shellcheck gitleaks direnv # macOS (Homebrew)xcode-select --install # macOS: provides makesudo apt install git make python3 jq shellcheck direnv # Debian / UbuntuAdd gh to the brew line only if your origin is GitHub. On macOS, brew install make
installs gmake, not make, so use xcode-select --install. On Debian and Ubuntu,
glab, gh and gitleaks may not be in the default repositories: use the install pages
linked in the table. The minimums are git 2.31 and Python 3.9, so the default git and
python3 on older releases are too old: Ubuntu 20.04 ships git 2.25 and Python 3.8, and
Debian 11 ships git 2.30. Install newer versions first.
| Tool | Status | Minimum | Install | Login | Without it |
|---|---|---|---|---|---|
git |
Required | 2.31 | brew install git |
none | make doctor fails. |
make |
Required | any | xcode-select --install (macOS), apt install make |
none | make doctor fails. |
python3 |
Required | 3.9 | brew install python3 |
none | make doctor fails. The check scripts are Python. |
bash |
Required | 3.2 (the macOS default is fine) | preinstalled on macOS and Linux | none | The scripts and hooks do not run. |
claude (Claude Code) |
Strongly recommended; doctor warns | latest | brew install --cask claude-code, or curl -fsSL https://claude.ai/install.sh | bash (macOS, Linux, WSL); Windows, apt, dnf, apk: see the setup guide |
run claude once; it prompts you to log in on first run |
Git, CI, changelog and release tooling still work, but there are no review agents. |
glab (GitLab CLI) |
Strongly recommended; doctor warns (either glab or gh) |
latest | brew install glab |
glab auth login |
The duplicate-MR check, wt new <issue> and every skill that reads the tracker can’t see it; the stale-reference check and the security-deferred check fail closed. |
gh (GitHub CLI) |
Only if your origin is GitHub | latest | brew install gh |
gh auth login |
Nothing, on a GitLab origin. |
jq |
Strongly recommended; doctor warns | any | brew install jq |
none | The pre-MR security hook blocks every glab mr, glab api and merge_request command, which stops a Claude session opening an MR; the security-deferred check fails closed; the OSV severity gate’s --self-test can’t parse its fixtures. |
shellcheck |
Recommended | any | brew install shellcheck |
none | The local shellcheck gate does nothing; CI still runs it. |
gitleaks |
Recommended | any | brew install gitleaks |
none | The pre-commit secret scan does nothing locally; CI still enforces it. |
direnv |
Optional: only for worktrees | any | brew install direnv |
none | Run source .envrc yourself in each worktree. |
node |
Needed to build website/, run make gate-self-tests, and keep two pre-push gates from skipping |
22.12 | brew install node; Debian and Ubuntu nodejs packages are often older than 22.12, so use the download page |
none | You can’t build the docs site, make gate-self-tests fails, and the check-added-files-covered and check-app-fixture-gates pre-push gates skip. |
make doctor checks every tool in this table except bash and node, and warns about
a git or python3 older than the minimum. It also checks that your forge CLI is
logged in: glab for a GitLab origin, gh for a GitHub one, chosen from your origin
remote. Scripts pick the CLI the same way, so a GitLab origin never needs gh.
make doctor also warns when AGENTS.md is missing, or present but not imported by
CLAUDE.md.
Docker or a language toolchain are your project’s dependencies (Node is also Blueprint’s own, per the table above, if you use make gate-self-tests). Add checks
for them to the “Project-specific checks” section of scripts/doctor.sh.
0. Check your machine
Section titled “0. Check your machine”Clone Blueprint, then run the check inside the clone, before step 1 changes anything:
git clone https://gitlab.com/macrodream/blueprint.git my-projectcd my-projectmake doctorWhy: it tells you what is missing or logged out before you commit and push, rather
than at step 2’s glab repo view. Every warning names how to fix it (an install
command or a login command). It checks that git and python3 meet a minimum version
and that glab (GitLab) or gh (GitHub) is logged in to the host of your origin
remote. At this point origin is still Blueprint’s own remote, so the login check covers
Blueprint’s host, not the host of your future project; step 6 re-runs it after step 2
points origin at your project. With no origin it reports that as INFO, not a
failure. The .env line is INFO while .env.example has no keys that need a value.
Check: make doctor reports no MISSING. Re-run it at step 6, once the hooks and
origin are in place.
Next: 1. Create the repository. Hit a snag? See Troubleshooting.
1. Create the repository
Section titled “1. Create the repository”Run this step yourself, in a plain terminal, not through Claude Code. It replaces
.git on purpose. Claude Code’s Bash deny hook refuses the manual rm -r .git, but it
only reads the command line, so it does not block bash scripts/customize.sh --init: every
safeguard lives in the script itself, and you should be the one who reads its refusals.
One guarded command, which also avoids a chained shell line whose cd fails and runs the
rest in the wrong repository, does the whole step:
cd my-project # the clone you made in step 0bash scripts/customize.sh --initWhy: --init records .blueprint-version (the tag or commit you started from, which
the Feedback issue template asks for, and which is gone once .git is replaced), replaces
.git with a new repository, runs --reset-template (below), and makes the scaffold
commit chore: scaffold from blueprint. Your project starts with one commit and none of
Blueprint’s history.
It refuses, and changes nothing, unless it is run from the top level of an untouched
clone: origin is Blueprint’s own upstream (the only remote), there are no local commits,
stash or in-progress rebase or merge, the working tree is clean, a branch is checked out,
and .git is a real directory (not a linked worktree). It also refuses when a rollback
could not undo what the reset would do to an ignored file, because a rollback restores
tracked files only:
- an ignored file (such as
website/node_modules, an editor backup inchangelog.d/, or a macOS.DS_Store) sits in a path the reset deletes:website/(with--keep-website, onlywebsite/src/content/docs),changelog.d/,docs/releases/v*.md, the versioned MR templates,docs/specs/spec-intake.md, or Blueprint’s ADR files and evidence. The message names the path and thegit clean -fdXcommand that removes it; - an ignored file links to a removed Blueprint ADR, which the reset would rewrite in place (the reset’s other in-place edits touch tracked files, which a rollback does restore);
- a nested git repository exists, meaning a
.gitdirectory or file anywhere below the top level except insidenode_modulesor.claude/worktrees(git does not list the files of an ignored one, so they cannot be checked; an unignored one already fails the clean-tree check); - a
giterror occurs while checking any of this, orGIT_LITERAL_PATHSPECS,GIT_NOGLOB_PATHSPECS,GIT_GLOB_PATHSPECSorGIT_ICASE_PATHSPECSis set (they change what the checks match).
If a step fails after .git was swapped, it puts the original back. An INT, TERM, HUP or
QUIT does the same and exits 130, 143, 129 or 131; a second signal, or a closed output pipe
(--init 2>&1 | tee log, then ^C), does not interrupt the rollback. A KILL cannot be handled
and leaves .git.blueprint-orig, which you rename back to .git. To run it on a fork or
mirror of Blueprint, set BLUEPRINT_UPSTREAM_URL to that clone’s origin URL.
What it cannot rule out is a maintainer’s own clean checkout of a branch that upstream also
has: the old .git is deleted, and what is lost beyond what upstream can restore is local
config, custom .git/hooks, the reflog, non-branch refs, and tags that exist only locally
(even on commits upstream has). Your .git/info/exclude rules are copied to the new
repository, and files the old repository ignored stay out of the scaffold commit, while a
tracked file that your global core.excludesFile happens to match is still committed. The
new repository starts with an empty .git/hooks, and --init ignores your global
init.templateDir, core.hooksPath and core.fsmonitor, so the scaffold commit is not
hook-checked; step 6 installs the hooks. If the old .git cannot be removed at the end, the
message says so and it stays listed in .git/info/exclude. It takes --gitlab or
--github and --keep-website, described below.
A clone also carries files that are Blueprint’s, not yours. The reset inside --init
(also available alone as --reset-template) handles the history in one step:
CHANGELOG.mdis reset to an empty[Unreleased]section, andchangelog.d/loses Blueprint’s fragments. Otherwise your firstscripts/release.shpublishes Blueprint’s fragments as your release notes, andcheck-version-lockstepfails a0.1.0manifest as “behind” Blueprint’s0.7.0.docs/releases/v*.md, the versioned MR templates, and Blueprint’s own ADRs (docs/adr/0002to0011, with thedocs/adr/assets/0002-evidence behind 0002) are removed, and the links to them inCLAUDE.md,.claude/rules/anddocs/harness/are rewritten to plain text. ADR0001stays.check-stale-referencesfails on a link to an ADR file that is not there, so a missed one is caught.docs/specs/spec-intake.md, Blueprint’s own spec, is removed. The spec template, its README, the sample spec and.claude/rules/specs.mdstay: they are your spec format.README.mdbecomes a stub with a[PROJECT NAME]placeholder.CI_BASE_IMAGEin.gitlab-ci.ymlis set to stock alpine, pinned by digest (the digest theshell-portabilityjob pins). Blueprint’s ci-base image is Blueprint’s, andcheck-ci-image-pinsrefuses it in your project. Build and pin your own later (CI pipeline guide)..blueprint-resetis written. The reset does nothing once it exists, so a second run cannot wipe your own changelog.
Add --gitlab or --github to keep only your forge’s dependency bot: --gitlab keeps
renovate.json and deletes .github/dependabot.yml, --github does the reverse. Without
either flag both stay and the reset says so. Re-running with the same flag is harmless, but
the bot you keep must still be there: switching to the other forge after one has been
deleted is refused, and nothing is removed. Restore the file from Blueprint first. The reset also lists the files that still point at Blueprint’s own
URLs (the docs site, the repository, the issue tracker); retarget or drop them. Issue
numbers in CLAUDE.md, .claude/ and docs/harness/ are written as
macrodream/blueprint#NNN so they cannot be mistaken for your own issues, except in the
Bash deny hook files and their section of docs/harness/claude-code-config.md
(macrodream/blueprint#195). Bare numbers in scripts/, the CI files and the Makefile
are not rewritten.
The reset deletes website/, Blueprint’s own documentation site, so your Pages never
publish Blueprint’s docs. The website:build and pages CI jobs skip themselves when it
is gone. Add --keep-website if you mean to publish your own docs there: it keeps
website/ as a stub with a [PROJECT NAME] title, a placeholder site and repository
link, and one blank page in place of Blueprint’s content. make customize lists the
placeholders as [ ] until you set them. (--remove-website is still accepted; it is now
the default.) See Your docs site for the domain and
versioning choices. The reset cannot choose a copyright holder for LICENSE. make customize
lists that too.
Check: git log --oneline shows exactly one commit, and make customize no longer
lists CHANGELOG, fragments, release notes or ADRs as inherited.
Next: 2. Connect it to GitLab.
2. Connect it to GitLab
Section titled “2. Connect it to GitLab”Create an empty project in GitLab (don’t let it add a README, or your first push is rejected). Then:
glab auth login # once per machine; gh auth login only for a GitHub origingit remote add origin git@gitlab.com:<group>/<project>.gitgit push -u origin mainThe first push is the only direct push to main: it happens before step 3 protects the
branch and step 6 installs the hooks. From the next change on, the “never commit to
main” rule applies.
Why: glab, scripts/wt, the duplicate-MR check, and the /kickoff,
/spec import, and /mr skills all find your project through origin.
Check: glab repo view prints your project, and glab issue list runs without an
error (an empty list is fine).
Suggested layout
Section titled “Suggested layout”Blueprint’s two source projects, Visiban and
TruePPM, use the same shape: one flat group per
product, with the app repo named after the group. Here it is for a fictional product,
acme:
| Repo | Holds | Visibility | License |
|---|---|---|---|
acme/acme |
The app, its docs and its Helm chart | public | Apache-2.0 plus a NOTICE file |
acme/acme-www |
Marketing site | private | proprietary, plus TRADEMARK.md |
acme/acme-enterprise |
Enterprise edition code | private | proprietary |
acme/acme-android, acme/acme-apple |
Mobile apps, if you have them | private | your choice |
acme/acme-devops |
Cluster and environment config | private | n/a |
You do not need all of these. /kickoff (step 4)
asks which layout you want: Personal namespace, one repo (a fine start) or Group,
several repos (the table above). Add repos as the product grows. The enterprise repo only makes sense for an open-core product; see
Open core and editions.
- Use group-level labels when a product has more than one repo, so the same
committed,status::wipand similar labels apply everywhere. - Skip subgroups. Both source projects run flat at this scale, and subgroups add permission and path complexity with no payoff.
- Keep cluster and environment config in a private, versioned
<project>-devopsrepo. Never put it in the app repo, and never leave it unversioned on one machine. An unversioned config directory has no history, no review and no way to roll back. TruePPM keeps its chart in the app repo aspackages/helm; Visiban’s devops directory stayed local and unversioned, which is the pattern to avoid. See Where deploy config lives.
Public or private?
Section titled “Public or private?”Visibility changes more than who can read the code. These points depend on your GitLab tier and plan, so on GitLab.com SaaS check your tier before relying on any of them:
- CI minutes. Public and private projects can draw on different compute allowances. Check your plan’s current limits rather than assuming either.
- Security scanning. Availability of SAST and secret detection can differ by tier and by project visibility.
- Pages access control. A public project’s site is public by default; restricting it to project members depends on the Pages access-control setting and your tier.
- Confidential issues. In a public project, file security findings as confidential issues, so a vulnerability is not visible before it is fixed. A private project needs this less.
- Changelog and release notes. In a public project they are public. Write them for outside readers.
- Community files. A public project needs a
SECURITY.mdand the other community files a visitor expects. The public-project readiness checklist lists them. - Brand marks. A code license such as Apache-2.0 does not cover your product name or
logo. If the product has a brand, add a
TRADEMARK.mdsaying so. It is optional, and/kickoffdoes not generate one.
Next: 3. Set the GitLab project settings.
3. Set the GitLab project settings
Section titled “3. Set the GitLab project settings”/kickoff (step 4) can set the merge-request settings, the protected branch and tag,
the default branch and the labels below for you: it runs scripts/gitlab-bootstrap.sh,
which applies them through the GitLab API, shows the values first and skips anything
already set. Run its subcommands yourself with
bash scripts/gitlab-bootstrap.sh --project <group>/<project> --dry-run settings --merge-method merge
(then protect and labels). --dry-run writes nothing but still reads the forge, so
glab must be authenticated. It needs the Maintainer role, and it does not touch CI/CD
variables. With the Developer role, or for any step you decline, set the same things by
hand in the GitLab UI (the list below). make customize cannot see the GitLab side: it prints
the list as a reminder that never counts as remaining and names
bash scripts/gitlab-bootstrap.sh preflight as the check (it verifies the reset, glab
authentication, origin and that the project exists, not protected main, labels or MR settings). It does read the repo, so it lists
MERGE_METHOD in .claude/skills/mass-merge/SKILL.md as a [ ] item until the file holds exactly one
MERGE_METHOD = <value> line with the value merge, rebase-merge or ff-only and nothing after it.
Only the unfilled <merge | rebase-merge | ff-only> enum is filled by
bash scripts/gitlab-bootstrap.sh --project <group>/<project> settings --merge-method <value> (--dry-run first
shows the changes; --use-origin instead writes to the project origin points at). That command also sets the
forge’s merge method, squash to never, Pipelines must succeed (on when .gitlab-ci.yml exists), delete source
branch and default branch main, and needs the Maintainer role. merge-method --merge-method <value> writes only the
file, also needs --project or --use-origin, reads the forge, and exits 1 with MERGE_METHOD_UNVERIFIED when it
cannot. A missing MERGE_METHOD = line, two such lines, an invalid value or trailing whitespace is listed too, and
you edit the line by hand to exactly MERGE_METHOD = <value>; so do you on a GitHub-forge project.
-
Settings → Merge requests: turn on Pipelines must succeed and Delete source branch by default. Pick a merge method, and record the same choice as
MERGE_METHODin.claude/skills/mass-merge/SKILL.md. -
Settings → Repository → Protected branches: protect
main— Allowed to push: nobody; Allowed to merge: Maintainers. -
Settings → Repository → Branch defaults: default branch
main. -
Settings → Repository → Protected tags: protect
v*— Allowed to create: Maintainers. -
Manage → Labels: create
no-changelog(thechangelog-checkjob skips MRs that carry it) andsecurity::deferred(the GA-tag security check fails closed without it; see Deferred security follow-ups). -
Settings → CI/CD → Runners: a pipeline needs a runner to run on. On GitLab.com the default is instance runners, which GitLab hosts; check that Turn on instance runners for this project is on (see Instance, group and project runners). Four things on GitLab.com can keep a first pipeline from starting, none of them caused by Blueprint:
- Instance runners are turned off for the project.
- Your account may have to complete identity verification (email, phone or a payment method, depending on a risk score) before a free-plan namespace can run jobs on GitLab-hosted runners (identity verification, the CI error). This applies to the free plan.
- The namespace may be out of compute minutes. Free-plan namespaces get 400 a month (tier-dependent; compute minutes), and once the quota is used, pending instance-runner jobs are dropped (compute usage).
- A job’s tags must match a runner, or the job waits (configure runners).
On self-managed GitLab, or if you would rather run your own, register a runner; for group-level registration see Private CI runners. Verification and quota rules are tier-dependent and change, so check GitLab’s pages for your plan.
-
Settings → CI/CD → Variables: whatever your runners need. Releasing needs none of its own — tagging is done by hand (see Release workflow).
Why: a protected main plus Pipelines must succeed is what turns every review in
this system from advice into a requirement. Nobody — human or agent — can skip it.
Check: Protected branches lists main with nobody allowed to push.
Next: 4. Describe the project with /kickoff.
4. Describe the project with /kickoff
Section titled “4. Describe the project with /kickoff”Lifecycle step: Configure.
Run /kickoff in Claude Code. It asks in rounds, not one question at a time.
Round 1, in one message: what you’re building (a name and one sentence), who uses it
(three to five user types, each with a goal, their biggest frustration and what would make
them leave), the stack and where the code lives, and four to eight capabilities for
version one. It also asks for the copyright holder, the code owners (default: your GitLab username), a security contact (default: confidential issues on the project) and a support channel (default: the issue tracker). On GitLab it first runs a read-only
check (template reset, glab auth, the project) before any question, and stops if the
clone was not reset.
Then up to four multiple-choice rounds, four questions each, plus a short layout follow-up on GitLab and, for Open core, one for the enterprise package names. Each question offers a
default marked Recommended and says where the default came from (your origin remote,
git config, the template’s LICENSE, your Round 1 answer):
| Round | Asks |
|---|---|
| Persona context | each persona’s device and network, accessibility needs, locale, privacy sensitivity |
| Project and forge | GitLab (optionally also mirrored to GitHub, which keeps .github/ and adds a canonical-source banner to the README; otherwise .github/ is deleted) or GitHub, and the project path; open source or private, and the license; whether there is a public API contract yet; on GitLab, which of these to run: create the project, apply the merge-request settings, protect main and v*, create the labels |
| Repository layout (a short follow-up call after Project and forge; GitLab only) | Personal namespace, one repo or Group, several repos; for a group, which of the www, enterprise (open core only), devops and mobile repos you plan |
| Enterprise package names (Open core only; a short follow-up call, not gated on GitLab) | the package name(s) the open-source tree must never name, or Name it later. /kickoff writes them to edition-boundary.conf and runs the gate |
| Cost ledger (a one-question follow-up call after Workflow) | whether to record measured token counts per MR in its ## Gates section, with a readable ## Cost of this MR comment built from them; on is the committed default, and scripts/cost-ledger on|off switches it later |
| Build and CI | the ci/*.yml stack includes, the optional CI add-ins, the test and docs paths, the branching variant |
| Workflow | fast-path rows to drop, the docs version-callout format, the commitment label for the seed issues (or release:: dated milestones), template leftovers to clean up |
Both layout questions open by saying the answer is recorded only: /kickoff creates no group and no repository, and automatic creation is planned in #285. The enterprise repo is offered only when you chose the open-core license.
/kickoff records the layout and uses it for defaults only. The forge preview and the
final report list the repos you named with their default visibility (the app repo follows
your open source or private answer; www, enterprise and devops default to private), and,
for a group, pause before creating the labels so you can create them once on the group first
(otherwise they would be created on the project and duplicated). It does not create the
extra repos or the group labels; those stay your steps. On GitHub the layout question is
not asked.
It then writes AGENTS.md, CLAUDE.md, .claude/personas.md, CONTRIBUTING.md,
LICENSE (with the Copyright <year> <holder> line), CODEOWNERS, SECURITY.md (public repos only), a README.md, the hook patterns and rule globs, the Makefile targets and CI
includes for code that already exists (for code that doesn’t, it writes out the edit to
make when the code lands), and (if you chose them) the template reset and a first ADR recording the stack. It
runs make setup. On GitLab it then checks that the template was reset and glab is
authenticated, previews every forge change and the seed issues as one table, and applies
only what you confirm: the project, the settings, the protections, the labels, and one
feat: issue per capability, each skipped if it already exists (with a spec for the first
milestone, create these or run /spec import, not both: see
step 9). The merge method, the
visibility and whether to push main are asked in one multiple-choice call at that
confirmation. It does not commit. Its report lists every value it
assumed instead of asking, and everything it did not touch.
If you already have a spec
Section titled “If you already have a spec”Put the product spec in docs/specs/ before you run /kickoff, and it starts from it:
- Which spec.
/kickofflooks for specs indocs/specs/, leaving out the README, the template anddocs/specs/examples/. With one, it uses it; with several, it asks which one, or none. The spec gate reads only files git knows about, so for a spec you have not added yet it offers to rungit add -N <path>first, and runs it only if you say yes. - Round 1 comes prefilled. The name and description, the users, the stack and the first milestone are filled in from the spec, each with the section and line it came from. You confirm or correct them in the same one message; a field the spec does not cover is asked as usual. The spec is a default, not an answer: no question is skipped because the spec covers it.
- Round 3’s project path comes from the spec too. When the spec has a
GitLab project pathsection (### 1.5 GitLab project pathin the numbered layout), a validgroup/projectfrom it is the default for the forge question, with the section and line it came from. Nested groups such asa/b/care allowed, and a host prefix and a.gitsuffix are stripped. Any other value is ignored and youroriginremote is used instead. The section names a GitLab project, so the default forge is GitLab; the GitHub<path>option stays selectable. With noorigin, the spec’s path is the recommended default. Iforiginpoints at a different path or at GitHub,/kickoffshows both and asks which, rather than picking one. You confirm or correct the answer either way. - No seed issues by default, on GitLab. When the spec lists features and the project is
on GitLab,
/kickoffrecommends creating no seed issues and names/spec import <path>as your next step: the import creates one issue per feature, each traced to the spec, and one milestone per phase. If the spec is still adraft, the import refuses it, so run/spec <path>until it isreadyfirst. Seed issues with the same titles would make the import skip those features without linking them to the spec. You can still ask for seed issues. On GitHub, where/spec importis not available (it needsglab),/kickoffkeeps creating the seed issues as usual.
Step 9 covers /spec import itself and why to
pick one source of issues, seed issues or the import, never both.
You can run /kickoff again. It skips the questions it can prove were answered (filled
placeholders in AGENTS.md and CLAUDE.md, .claude/personas.md, LICENSE, SECURITY.md,
the CI includes, seed issues already on the tracker), tells you what it found, and asks the
rest. It does not guess an unanswered question. It also saves your answers after each round
in .claude/state/kickoff.json, a git-ignored file in your checkout, so a session that dies
after round 2 resumes at round 3 and says so, and a finished kickoff asks none of the
question rounds again. When a saved answer and a file you have since edited disagree, the file
wins and /kickoff tells you. What is and is not recovered:
- Recovered in the same checkout: every answer from the question rounds, including the ones that leave no trace in a file (the branching variant, the fast-path rows, the commitment label, “no optional CI add-ins”, the forge and project path, the repository layout and group repos, and “continue without the GitLab bootstrap”), and which questions you declined.
- Not recovered in a fresh clone: the state file is not committed, so a new clone of
your project resumes from what the files show, and asks the no-trace questions again (including the repository layout). A kickoff finished before the layout question existed is not asked again;
/kickoffassumes a personal layout and says so. - Never saved: the final confirmation and the merge method, visibility and first-push
answers at the forge preview. They confirm one preview, so the final confirmation is
asked again whenever the preview still has something to create or change, and skipped
when it has nothing. “Push
maintooriginnow?” is asked on every run untilmainis onorigin:/kickoffnever commits, so its recommended answer is “No”. An answer that matches a common token, key or password shape is not saved either:/kickofftells you, and asks it again next time. The check is best effort, so do not type a secret into an answer.
To change one saved answer without starting over, re-run /kickoff and choose “Change one
saved answer” when it lists what it found. It asks which answer, re-asks only that question,
and saves the new value; every other answer stays. Files still win: for an answer a file already
shows (the name, users, stack, license and the like), the saved value changes but the file does
not, edited or not, and /kickoff tells you the two now differ. Only the answers with no file
trace (the branching variant, fast-path rows, commitment label, optional CI add-ins, the
repository layout) are re-applied, and never over a file that differs from what a first run
would write; anything that touches the forge goes through the same preview and confirmation as
before. It never rewrites the rest of your project. To start the questions over, delete
.claude/state/kickoff.json. Seed issues that already exist are skipped, not duplicated.
Why: the rules live in two files, split by who reads them. AGENTS.md is the
project contract: stack, commands, invariants, forbidden operations and the
branch → MR → green-pipeline flow, in plain Markdown that any coding agent reads.
CLAUDE.md starts with @AGENTS.md, so Claude Code loads the contract too, and adds
only Claude Code workflow: personas, skills, review agents, hooks and the fast-path
table. A rule lives in one file or the other, never both. This is how agents learn your
project once instead of every session. A team using another coding agent alongside
Claude Code gets the contract from AGENTS.md alone; what it does not get (hooks,
skills, review agents) is on Agent portability. Take the users question seriously — vague personas make /voc
give vague feedback. (/voc is the Voice of the Customer panel: a design aid, never a substitute for real users.)
/kickoff writes no rules into .claude/security-invariants.md: a project that has no
code yet has no file-and-function entry points to record. If you choose, it deletes
Example rule A and Example rule B; Rule 1 (about Blueprint’s own harness) and the
grant-parity walk-through under How to add a rule stay. Add a rule with How to add a
rule once behavior crosses more than one surface.
make customize still warns about .claude/rules/backend.md and frontend.md until the
directories their globs name exist, and about frontend.md’s design tokens until you run
/import-design. Those are warnings, not open items.
By hand instead: replace [PROJECT NAME] and every [FILL IN …] in AGENTS.md,
CLAUDE.md and CONTRIBUTING.md, replace the example personas (Alex, Jordan, Sam,
Maya) in .claude/personas.md, and delete the SETUP CHECKLIST comment at the top of
AGENTS.md and CLAUDE.md. Keep @AGENTS.md as the first line of CLAUDE.md.
Resolve each [REMOVE IF NOT APPLICABLE] section (delete it, or keep it and strip the
marker) in AGENTS.md, CLAUDE.md, .claude/rules/*.md and docs/harness/*.md;
make customize lists every one it finds.
Check: grep -n "PROJECT NAME" AGENTS.md CLAUDE.md prints nothing, and
head -1 CLAUDE.md prints @AGENTS.md.
Next: 5. Configure your stack.
5. Configure your stack
Section titled “5. Configure your stack”/kickoff detects your stack from the tree and proposes these edits, then applies them
only if you say yes. Python, Node/TypeScript, Go and Docker are covered, and a mixed
repository gets the union. python3 scripts/detect-stack.py diff shows the same proposal
without writing anything: the Makefile recipes for the tools it finds evidence for (a
dependency, a config file or a package.json script, such as ruff check, npx tsc --noEmit, go test ./...), the matching ci/<stack>.yml include, and paths: globs for
.claude/rules/backend.md and frontend.md that match real directories. apply --confirm <plan-id> writes it, and refuses with exit 3 if the tree changed since the diff, or with
exit 4 if a file it would write has uncommitted edits. Declining leaves every file as it
is and the items on make customize; anything it cannot detect comes back as a one-line
hint. A declined proposal is saved as “no CI includes”, so a re-run does not ask again; choose “Change one saved answer” to be offered it again.
Deleting a rules file that matches no directory is a separate, explicit proposal
(--delete-unmatched-rules). The map it follows is .claude/skills/kickoff/stack-map.md, and
it fills only once the stack’s manifest
(pyproject.toml or requirements.txt, package.json, go.mod, a Dockerfile)
exists, and it puts any target that still fails (make format-check lint typecheck)
back to its stub: a configured target runs in the pre-commit hook, and against missing
code it refuses every commit. It turns a stack’s CI include on only when the files its
jobs run against exist (for Python a root requirements.txt and a test file, for Node
a package-lock.json with working lint and test scripts, for Go a package with a
test file); otherwise a red default-branch pipeline follows. Before then, its report
gives you the exact edits. For another stack, or if you skipped
/kickoff, do it by hand, checking the same before you uncomment an include: until you do, the Makefile’s lint, format-check,
typecheck, test, and build targets are stubs that print a warning and exit 0, and
make customize keeps listing them as [ ] (on the /kickoff path they show as [~]
deferred instead).
| What | Where | Why |
|---|---|---|
lint, typecheck, test, build (optionally format-check) |
Makefile — uncomment your stack’s block, or write your own |
Hooks, CI, and agents all call these same targets, so “passes” means the same thing everywhere |
| Stack CI jobs | .gitlab-ci.yml — uncomment the matching ci/*.yml include and set its variables |
Without one, CI runs only the governance jobs |
| Files that hold the version | scripts/release.sh |
/release bumps exactly these, and version-lockstep checks they agree |
| Edit-time reminders and guards | .claude/hooks/post-edit-checks.sh, .claude/hooks/pre-tool-safety.sh |
Point them at your stack’s real paths |
| Dependency updates | Keep renovate.json (GitLab) or .github/dependabot.yml (GitHub); --reset-template --gitlab or --github deletes the other |
Only one should run |
CI includes (see CI pipeline for every job):
include: - local: ci/python.yml # ruff, pytest + coverage, license check, optional fuzz + load test - local: ci/node.yml # eslint, vitest + coverage, license check - local: ci/docker.yml # kaniko build verification - local: ci/go.yml # golangci-lint, go test, govulncheckVersion files in scripts/release.sh:
# package.json:sed -i '' "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" package.json
# pyproject.toml:sed -i '' "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml # slash-okHook patterns. post-edit-checks.sh gives Claude a reminder (as context, via
additionalContext) when Claude edits a matching file:
# Django models → remind to check migrationsif re.search(r"models\.py$", file_path): messages.append("models.py modified — run the schema-check agent")pre-tool-safety.sh blocks edits to lock files and existing migrations and warns on CI
config and .env files. It blocks with exit code 2 and allows with 0. Set
BLUEPRINT_ALLOW_PROTECTED_EDIT=1 for a session to hand-edit a lock file or existing
migration on purpose.
Then run the checklist:
make customizeIt groups what is left by what to do first: Do now (reset, /kickoff, license),
Needs your stack (Makefile targets, the CI include), Deferred until your code
lands and Optional. Each item is [ ] to do, [✓] done, [~] deferred or [!]
warning. /kickoff marks the stubs and the CI include it leaves until a stack manifest
exists with a # BLUEPRINT-DEFERRED: <manifest> line directly above each; the report
lists those under [~] and counts them as Deferred, not Remaining. Once a listed
manifest exists the report ignores the marker and shows the stub as [ ] again. After the groups it prints “N items remaining
(expected on a new project)”, the next three steps and a short quick reference, and it ends with a
“Done so far / Next step” line that names the lowest-numbered step of this page that still has an open item
(for example, step 5, “Configure your stack”, with its anchor). When only optional or deferred
items are left it says all required steps are done and hands over: Next step: make status (lifecycle checklist), then Start a project step 7. With no origin remote it points at step 2, “Connect it to GitLab”. It only
reports — it never edits — so run it as often as you like. On a new project it exits 0;
that is not a failure.
Use bash scripts/customize.sh --strict in a script or CI job to exit 1 while any [ ]
item remains; deferred [~] items do not count, so --strict exits 0 when only they
are left. If your stack has no type checker, make
typecheck a no-op (@echo "no type checker") rather than leaving the stub, which
would keep showing as [ ].
Check: make customize shows no [ ] for lint or typecheck (and [ ] only
for other items you’ve decided to skip).
Next: 6. Install the hooks and check your machine.
6. Install the hooks and check your machine
Section titled “6. Install the hooks and check your machine”make setup # installs the pre-commit and pre-push Git hooksmake doctor # re-run: the hooks and forge-login lines should now passFrom now on:
git commitscans staged changes for secrets and runsformat-check,lint, andtypecheck— each is reported asskipped (not configured)while it is still the Makefile stub, and blocks the commit once configured and failing;git pushrunsmake pre-push-checks— the duplicate-MR check and the rest of the local gate suite.
Why: a problem caught on your machine costs seconds. The same problem caught in CI costs a pipeline and a context switch.
make setup installs into Git’s shared hooks folder, so one run covers every
worktree you create later, too.
Check: make doctor reports no failures and no forge auth warning.
Next: 7. Confirm the agent workflow is on.
7. Confirm the agent workflow is on
Section titled “7. Confirm the agent workflow is on”There is nothing to install. The rules that make Claude run the review agents at the
right moments (the Fast paths by change class table, the pre-MR gate batch, and the
cross-cutting rules in .claude/operating-rules.md) are part of the repository, and
Claude Code loads them, with AGENTS.md through its import, whenever you open it.
Why: project rules belong with the project. A copy in ~/.claude/CLAUDE.md would load
into every repository you open, including ones with none of these agents, and would
drift from the repo’s own table.
Check: in a fresh Claude Code session with only this repo loaded, ask “Which reviews does a bug fix need?” The answer should match the bug-fix row of the fast-path table.
First-time checks. Once per machine, after your first few sessions:
- Run
/initif the repo has noCLAUDE.mdyet. It generates a starter file from the codebase; edit it to match your real conventions before committing. - Run
/memoryand prune stale or wrong entries; promote durable rules intoCLAUDE.md. - Verify the post-edit hook fires: make a quick edit to a source file. Its reminder
goes to Claude as context, not to the chat UI, so check
claude --debugor ask Claude whether it received a post-edit reminder. If no reminder appears, make the scripts executable. You runchmod +x .claude/hooks/*.shyourself in your own shell: the Bash deny hook refuses it when Claude tries (hooks are protected files).
global-claude-md.example is now an optional starting point for personal preferences
only. Nothing in it is needed for the harness to run.
Upgrading from an earlier template? If you followed this step before, you appended the
old global-claude-md.example to ~/.claude/CLAUDE.md. Open that file and remove the
appended block (it starts with # Global Claude Instructions). Left in place, the stale
copy keeps loading alongside the corrected project rules, and the two will disagree.
Next: 8. Open your first MR.
8. Open your first MR
Section titled “8. Open your first MR”main is protected, so the setup work lands the way every later change will:
git checkout -b chore/project-setupgit add -Agit commit -m "chore: configure project from blueprint"git push -u origin chore/project-setupThen run /mr in Claude Code. It checks the branch, writes the description, and opens
the MR. It never merges — you do.
Why: proving the whole loop on a harmless change means the first real feature won’t also be the first test of your pipeline.
Check: the MR pipeline is green. Expect the governance jobs listed in
CI pipeline plus your stack’s jobs.
If you have not configured a stack (step 5), only the governance
jobs run, so green proves the governance suite, not your stack. If the pipeline sits in
pending or never creates jobs, that is usually runner availability, not your diff: see
My first pipeline is stuck in pending or created no jobs.
Then merge it.
Next: 9. Load your spec and design (optional).
9. Load your spec and design (optional)
Section titled “9. Load your spec and design (optional)”Lifecycle step: Specify.
/spec new my-product # write docs/specs/my-product.md/spec docs/specs/my.md # or audit a spec you already wrote/spec import docs/specs/my.md # a ready spec → milestones and tracker issues/import-design path/to/guide.md # design guide or token export → .claude/rules/frontend.mdIf you do not have a spec yet, or yours is rough, run /spec new first: it asks for
what the spec is missing and loops the completeness gate until it passes, and it sets
status: ready only when you say yes. The rules are in docs/specs/README.md.
/spec docs/specs/my-product.md audits a spec you already wrote, and bare /spec does
the next step for your spec’s status. The sequence, the
rule table, the override and the re-import loop are in
Spec-driven development.
/spec import runs the completeness gate first (a spec that is not status: ready is
refused unless you pass --allow-incomplete "<reason>"), shows what it parsed, and
creates issues only after you confirm — plus a milestone per phase. It writes
Issue: #N beside each feature, and a second run creates only the issues still missing.
/import-design lets ux-design and ux-review check against your
design system rather than generic advice.
Pick one source of issues. /kickoff seeds one feat: issue per first-milestone
capability, and /spec import creates one issue per spec feature. When both describe the
same work, running both duplicates the backlog, and neither duplicate check catches a
reworded title: the seed script matches only its own marker or the exact title, and the
import skips a feature only when an open issue has the same title.
- No spec, or a spec only for later areas: use
/kickoff’s seed issues for the first milestone, and skip/spec importfor it. - A spec for the first milestone: do not create seed issues at
/kickoff(on GitLab that is the default when a spec is staged, see If you already have a spec) and let/spec importcreate the issues and milestones. It also stampsIssue: #Non each feature, which seed issues do not. - Both already ran: list the open issues and look for pairs that name the same
capability, for example
glab issue list --search "<capability>"./tracker-hygieneflags likely duplicates (it reports only, so you close them yourself). Keep the one with aSpec:line, close the other as a duplicate of it, and check that the spec feature’sIssue: #Npoints at the one you kept.
Check: glab issue list shows the issues you expect, each capability once.
Next: 10. Plan the first milestone.
10. Plan the first milestone
Section titled “10. Plan the first milestone”Lifecycle step: Plan.
/dotplanning is the once-per-milestone kickoff plan. It needs a milestone. It comes from /spec import if your spec had phases;
otherwise create one in GitLab (Plan → Milestones) and assign the issues. Then:
/dotplanning 0.1It maps every feature to the screens, endpoints, models, and docs it needs, flags
anything with no issue or design behind it, lists decisions to make before coding, and
orders the work into workstreams. It asks you whether each issue is
committed (will land) or uncommitted (proposed, not yet accepted); with dated milestones the
choices are release::committed, reserve and stretch. It never guesses. The
plan is recorded on a Plan: <version> issue (ships in 0.8), a copy lands in ~/Downloads/dotplanning-<version>-<date>.html, and it offers to file
issues for the gaps (skip with --no-file).
Why: the cheapest moment to find a missing screen or an undecided question is before anyone writes code for it.
Run it once per milestone, before the first feature branch. Re-run only if the scope changes materially.
Check: the report opens, and every 🔴 gap or open question is filed as an issue or answered.
Next: 11. Build.
11. Build
Section titled “11. Build”Lifecycle step: Build.
From here on, work repeats one loop. Start it with
/wave: inside Claude Code, run /wave (even for a single issue). It asks
which milestone and labels to pull from, gives each issue its own worktree and agent, audits each
branch with completeness-check, and opens one MR per issue. Land the green MRs with /mass-merge
and finish with scripts/wt prune.
To work one issue by hand instead:
scripts/wt new 12 # branch feat/12-<title>, worktree ../my-project-wt/12-<title>cd ../my-project-wt/12-<title>source .envrcclaude # work the issue; Claude runs the reviews for its change class# inside Claude Code: /mr → opens the MR, records the reviews, adds "Closes #12" # bare-ref-ok: adopter issue# merge on a green pipeline, then from the main checkout:scripts/wt prune # removes worktrees whose branches have mergedWhich reviews run depends on the change — see Development workflow.
When the milestone’s work has merged, run /pre-release full, fix what it blocks on, and
cut the release with /release (see Release workflow).
Next: Where am I?, or Troubleshooting if something failed.
Where am I? make status
Section titled “Where am I? make status”Ships in 0.8.
From any step on this page, make status prints the lifecycle as a checklist and names the
one command to type next:
Blueprint · my-project
Once per project ✓ 1 Configure done make customize: all required checks pass ✓ 2 Specify done docs/specs/my-project.md — imported v0.2.0
Milestone 0.1 ✓ 3 Plan done Plan: 0.1 (#9) · 8 committed, 4 uncommitted ▶ 4 Build current 3/8 merged · 2 MRs open (1 red) · 2 in worktrees (last commit 3h ago) · 5 Release todo —
Next: /wave 0.1 (5 committed issues open; resumes 2 worktrees; 1 red pipeline(s) to fix)That is the plain text: what a pipe gets. In chat, /next and the phase skills show the
same checklist, in the same words, as a rendered table (scripts/blueprint-status --markdown). On an interactive terminal the same checklist is drawn in a box, with long lines wrapped under
their column and the glyph and step name colored: green for done, orange for unknown, and
bold for the step you are on. The glyph and the words carry the state, so nothing depends on
the color. Screen readers read box characters aloud: make status gives plain text on a
terminal too with git config --global blueprint.plain true (or BLUEPRINT_PLAIN=1, or
scripts/blueprint-status --plain). On a light terminal profile that does not report its
background (macOS Terminal), git config --global blueprint.background light picks the
darker shades. scripts/blueprint-status --help lists every switch.
Configure is steps 1 to 6 above (make customize), Specify is step 9 (/spec), Plan is
step 10 (/dotplanning), Build is step 11 (/wave or one issue at a time), and Release is
/pre-release full then /release. Plan, Build and Release repeat for every milestone:
once the release tag exists, the block moves on to the next milestone.
✓ is done, ▶ is where you are, · is not started, ! is blocked, ⏸ is interrupted
(drawn ‖ on a terminal; it names the command that resumes it, for example an unfinished /kickoff), and ?
means it could not be checked. Rows that read the tracker show ? when GitLab does not
answer in time; they never guess ✓. make status OFFLINE=1 skips the network and uses
the last answer if it is under 15 minutes old. No spec? Put {"spec": "none"} in
.claude/project.json and Specify reads ✓ (no spec).
In Claude Code the checklist also comes to you. Each session starts with one line, for
example Blueprint 0.1: ✓Configure ✓Specify ▶Plan ·Build ·Release — next: /dotplanning 0.1,
built from repo facts and the cached tracker answer (no network, so a tracker row can read
? after a quiet spell). /kickoff, /spec, /dotplanning, /wave, /pre-release and
/release end with the full checklist and its Next: line. /next prints the checklist,
says in plain words what the current step is for and what done looks like, and names the
command to type; it never runs that command for you. To hide the session line, put
{"env": {"BLUEPRINT_SESSION_STATUS": "off"}} in .claude/settings.local.json.
The full contract, including the --json output and the --require check the phase skills
use, is in docs/harness/lifecycle-status.md in your repo.
Next: Go deeper.
Go deeper
Section titled “Go deeper”- Issues are the unit of work — why every change starts from an issue.
- A day in the life — running several sessions at once.
- Flows — one diagram per lifecycle flow, from kickoff to release.
- Once a few MRs have landed,
/kaizenaudits the loop itself for friction.