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”git clone https://gitlab.com/macrodream/blueprint.git blueprint-democd blueprint-demogit remote remove originRemoving 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:
make doctormake setupmake 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.
2. Start Claude Code
Section titled “2. Start Claude Code”claudeThe 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 abranch locally, following this repo's own conventions. Do not push and do not open amerge 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.
4. Watch the workflow activate
Section titled “4. Watch the workflow activate”Notice what happens without you asking for it:
- Claude reads
CLAUDE.md(with theAGENTS.mdit imports) andCONTRIBUTING.mdfor 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.
5. See the verification
Section titled “5. See the verification”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):
git remote add origin "$(pwd)/.git"git fetch originThen run:
make pre-push-checkson 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.
6. Inspect what it produced
Section titled “6. Inspect what it produced”git log --oneline -3git diff mainYou should see a small, scoped commit with a conventional-commit message — not a sprawling diff touching files you didn’t mention.
If this makes sense, keep going
Section titled “If this makes sense, keep going”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.