Skip to content

Quickstart

Which version? The large 0.8 changes (ships in 0.8) are still moving. See Which version should I use? before you start.

The big picture: A 15-minute demo on a throwaway copy, so you can watch the workflow handle one small change before committing to a real setup.

Why it matters: It’s easier to judge a process by seeing it than by reading about it. You’ll see Claude read the project rules, work on a branch, pick a review path sized to the change, and produce a small, conventional commit.

Want the whole loop? The lifecycle shows every step from setup to release.

Yes, but: nothing here is worth keeping. When you’re ready for real, go to Start a project. Not sure Blueprint fits yet? See the maturity ladder.

1. Clone Blueprint into a scratch directory

Section titled “1. Clone Blueprint into a scratch directory”
Terminal window
git clone https://gitlab.com/macrodream/blueprint.git blueprint-demo
cd blueprint-demo
git remote remove origin

Removing origin matters. The merge-request flow, scripts/wt, the issue-collision check and glab all find the project through origin, and a fresh clone still points it at Blueprint’s own GitLab project. With it gone, nothing in this demo can query or write to Blueprint’s tracker.

Then check your machine and install the hooks:

Terminal window
make doctor
make setup

make doctor needs git, make and python3, and this demo also needs the claude CLI installed (curl -fsSL https://claude.ai/install.sh | bash on macOS, Linux or WSL, or brew install --cask claude-code; other platforms are in the setup guide). It prompts you to log in the first time you run claude. Blueprint is GitLab-first: use glab, and gh only for a GitHub origin. See What you need installed for the full list and what each missing tool costs you. make setup installs the git hooks the demo is meant to show. make doctor runs first, so it warns that the git hooks are not installed; that clears after make setup. Its direnv warning is fine for this demo, and .env shows as INFO: not needed on the template. The Troubleshooting page explains each warning.

Terminal window
claude

The first line Claude Code shows is Blueprint’s progress line (ships in 0.8), for example Blueprint —: ▶Configure ✓Specify ?Plan ?Build ?Release — next: make customize. On this unconfigured copy it always reads ▶Configure; type /next any time to have the current step explained and the one command to type named.

3. Give it one simple, self-contained change

Section titled “3. Give it one simple, self-contained change”

Something small and low-stakes, kept local. For example:

Add a one-line CONTRIBUTORS.md file listing yourself as a contributor. Commit it on a
branch locally, following this repo's own conventions. Do not push and do not open a
merge request.

The demo ends at a local commit. Until step 5 there is no remote, and even then origin points at this same directory, never at GitLab.

Notice what happens without you asking for it:

  • Claude reads CLAUDE.md (with the AGENTS.md it imports) and CONTRIBUTING.md for the branch-naming and commit conventions before writing anything
  • It works on a branch, not directly against your checkout
  • Because this is a docs-only change, it recognizes the fast path for it (see the Fast paths by change class table in CLAUDE.md) rather than running every review gate it has available. A gate is any check that can say no; a fast path is the table row that lists which gates a change needs. The Glossary defines both

Ask it directly: “Which reviews are you running for this change, and why those and not others?” The answer should name the specific fast-path row it matched.

The checks compare your branch against origin/main, which no longer exists after step 1. Recreate origin as a pointer to the demo’s own .git (not to GitLab):

Terminal window
git remote add origin "$(pwd)/.git"
git fetch origin

Then run:

Terminal window
make pre-push-checks

on the branch it created. This is the real governance suite, the checks the pre-push hook runs: issue-number collisions, migration numbering, hook and CI parity, shell lint, and docs links. It passes on a fresh clone with no project stack configured (shellcheck is optional locally and skipped when absent; CI always runs it), and it exists so a passing check means the same thing everywhere, not just in the agent’s own judgment.

A passing run exits 0 and no check fails. On a clone you have not reset it also prints some WARN lines, and those are expected: one group from the spec check, which reads Blueprint’s own spec (docs/specs/spec-intake.md, removed by customize.sh --init or --reset-template) and reports PASS WITH WARNINGS for decisions still undecided, and one group from the evals check, for agents that have positive cases and no negative control. Only the spec group clears on reset; the evals group stays until your project adds a negative-control case or removes evals/. Neither blocks the push. See make pre-push-checks prints WARN lines.

make lint, make typecheck, make test, and make build are stubs until Start a project step 5 configures them. Until then they print a warning and exit 0.

Terminal window
git log --oneline -3
git diff main

You should see a small, scoped commit with a conventional-commit message — not a sprawling diff touching files you didn’t mention.

The quickstart shows you the shape of the workflow on a trivial change. A real project needs the full setup — a GitLab remote, branch protection, your actual stack wired into the Makefile and CI, and the agent harness (the rules, agents, skills and hooks that steer Claude Code; see the Glossary) turned on globally. That’s Start a project, and it takes longer than 15 minutes because it’s setting up something you’ll actually keep.

When you’re done experimenting, delete blueprint-demo/ — nothing in it is meant to be kept.

Next: carry your make doctor result into Start a project. Any MISSING line is a tool to install first; a WARNING you saw here (hooks, direnv) is usually safe to ignore, and Troubleshooting says which.