Skip to content

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:

  • bash blocks 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 doctor warnings, WARN lines from make pre-push-checks) are on Troubleshooting.
  • Just want to see the workflow first? Try the 15-minute quickstart.
  • Lost? Run make status (or /next in 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.md that matches a change; a fragment is a one-line file in changelog.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.

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:

Terminal window
brew install git python3 glab jq shellcheck gitleaks direnv # macOS (Homebrew)
xcode-select --install # macOS: provides make
sudo apt install git make python3 jq shellcheck direnv # Debian / Ubuntu

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

Clone Blueprint, then run the check inside the clone, before step 1 changes anything:

Terminal window
git clone https://gitlab.com/macrodream/blueprint.git my-project
cd my-project
make doctor

Why: 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.

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:

Terminal window
cd my-project # the clone you made in step 0
bash scripts/customize.sh --init

Why: --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 in changelog.d/, or a macOS .DS_Store) sits in a path the reset deletes: website/ (with --keep-website, only website/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 the git clean -fdX command 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 .git directory or file anywhere below the top level except inside node_modules or .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 git error occurs while checking any of this, or GIT_LITERAL_PATHSPECS, GIT_NOGLOB_PATHSPECS, GIT_GLOB_PATHSPECS or GIT_ICASE_PATHSPECS is 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.md is reset to an empty [Unreleased] section, and changelog.d/ loses Blueprint’s fragments. Otherwise your first scripts/release.sh publishes Blueprint’s fragments as your release notes, and check-version-lockstep fails a 0.1.0 manifest as “behind” Blueprint’s 0.7.0.
  • docs/releases/v*.md, the versioned MR templates, and Blueprint’s own ADRs (docs/adr/0002 to 0011, with the docs/adr/assets/0002- evidence behind 0002) are removed, and the links to them in CLAUDE.md, .claude/rules/ and docs/harness/ are rewritten to plain text. ADR 0001 stays. check-stale-references fails 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.md stay: they are your spec format.
  • README.md becomes a stub with a [PROJECT NAME] placeholder.
  • CI_BASE_IMAGE in .gitlab-ci.yml is set to stock alpine, pinned by digest (the digest the shell-portability job pins). Blueprint’s ci-base image is Blueprint’s, and check-ci-image-pins refuses it in your project. Build and pin your own later (CI pipeline guide).
  • .blueprint-reset is 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.

Create an empty project in GitLab (don’t let it add a README, or your first push is rejected). Then:

Terminal window
glab auth login # once per machine; gh auth login only for a GitHub origin
git remote add origin git@gitlab.com:<group>/<project>.git
git push -u origin main

The 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).

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::wip and 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>-devops repo. 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 as packages/helm; Visiban’s devops directory stayed local and unversioned, which is the pattern to avoid. See Where deploy config lives.

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.md and 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.md saying so. It is optional, and /kickoff does not generate one.

Next: 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_METHOD in .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 (the changelog-check job skips MRs that carry it) and security::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.

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.

Put the product spec in docs/specs/ before you run /kickoff, and it starts from it:

  • Which spec. /kickoff looks for specs in docs/specs/, leaving out the README, the template and docs/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 run git 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 path section (### 1.5 GitLab project path in the numbered layout), a valid group/project from it is the default for the forge question, with the section and line it came from. Nested groups such as a/b/c are allowed, and a host prefix and a .git suffix are stripped. Any other value is ignored and your origin remote is used instead. The section names a GitLab project, so the default forge is GitLab; the GitHub <path> option stays selectable. With no origin, the spec’s path is the recommended default. If origin points at a different path or at GitHub, /kickoff shows 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, /kickoff recommends 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 a draft, the import refuses it, so run /spec <path> until it is ready first. 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 import is not available (it needs glab), /kickoff keeps 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; /kickoff assumes 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 main to origin now?” is asked on every run until main is on origin: /kickoff never commits, so its recommended answer is “No”. An answer that matches a common token, key or password shape is not saved either: /kickoff tells 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.

/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, govulncheck

Version files in scripts/release.sh:

Terminal window
# package.json:
sed -i '' "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" package.json
# pyproject.toml:
sed -i '' "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml # slash-ok

Hook patterns. post-edit-checks.sh gives Claude a reminder (as context, via additionalContext) when Claude edits a matching file:

# Django models → remind to check migrations
if 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:

Terminal window
make customize

It 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”
Terminal window
make setup # installs the pre-commit and pre-push Git hooks
make doctor # re-run: the hooks and forge-login lines should now pass

From now on:

  • git commit scans staged changes for secrets and runs format-check, lint, and typecheck — each is reported as skipped (not configured) while it is still the Makefile stub, and blocks the commit once configured and failing;
  • git push runs make 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.

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:

  1. Run /init if the repo has no CLAUDE.md yet. It generates a starter file from the codebase; edit it to match your real conventions before committing.
  2. Run /memory and prune stale or wrong entries; promote durable rules into CLAUDE.md.
  3. 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 --debug or ask Claude whether it received a post-edit reminder. If no reminder appears, make the scripts executable. You run chmod +x .claude/hooks/*.sh yourself 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.

main is protected, so the setup work lands the way every later change will:

Terminal window
git checkout -b chore/project-setup
git add -A
git commit -m "chore: configure project from blueprint"
git push -u origin chore/project-setup

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

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

If 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 import for 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 import create the issues and milestones. It also stamps Issue: #N on 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-hygiene flags likely duplicates (it reports only, so you close them yourself). Keep the one with a Spec: line, close the other as a duplicate of it, and check that the spec feature’s Issue: #N points at the one you kept.

Check: glab issue list shows the issues you expect, each capability once.

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

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

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:

Terminal window
scripts/wt new 12 # branch feat/12-<title>, worktree ../my-project-wt/12-<title>
cd ../my-project-wt/12-<title>
source .envrc
claude # 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 merged

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

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.