Upgrading from 0.7
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: 0.8 ships several changes that break a project copied from Blueprint 0.7 or earlier. Some rename a skill, some add a gate that fails until you fix what it finds, one retires a variable, and some expect a file you may not have.
Why it matters: Nothing pulls updates from Blueprint into your project. Taking 0.8 is a manual merge, and each gate you sync fails your CI until its action is done. This page lists every action, grouped by what you do.
Before you start
Section titled “Before you start”This page is for a project created from Blueprint 0.7 or earlier, such as a downstream
repository that copied Blueprint’s .claude/, scripts/, ci/ and CLAUDE.md. If you
are starting a new project, you do not need it.
The upgrade is a manual merge. You copy or merge the 0.8 files you want from Blueprint, and the gates you copy report what is left. There is no upgrade command, and the plugin track that would pull updates is not committed work. Which version ships what is on Which version should I use?.
A suggested order:
- Take the renames first (the next section), so the later gates find nothing stale.
- Sync the gates that now fail and clear what each one reports.
- Remove the retired variable and add the new files.
- Run
make pre-push-checksand fix what it reports.
Each entry ends with the issue it came from, written macrodream/blueprint#NNN.
Renames
Section titled “Renames”Renamed: /batch is now /wave, and /review is now /conventions-review
Section titled “Renamed: /batch is now /wave, and /review is now /conventions-review”Claude Code ships a bundled /batch, and a project skill with a bundled skill’s name
replaces it. /review is an alias of the bundled /code-review, so it always ran the
built-in. Who is affected: any project that copied the batch or review skill.
Action:
- Move each renamed skill:
git mv .claude/skills/batch .claude/skills/waveandgit mv .claude/skills/review .claude/skills/conventions-review(both renamed), then update each skill’sname:field. - Replace every
/batchand/reviewthat meant your skill, not the bundled command, inCLAUDE.md, skills, agents, docs and scripts. - Update any
Skill(batch)orSkill(review)permission entry to the renamed skill in your settings.Skill(review)now resolves to the bundled/code-review.
scripts/check-stale-references.sh fails CI on every leftover reference until you finish.
While you work through it, RENAMED_SKILLS="" turns that rule off. macrodream/blueprint#101
Your own skills named like a bundled skill or built-in command
Section titled “Your own skills named like a bundled skill or built-in command”scripts/check-skill-names.sh (CI job skill-names, make check-skill-names) fails when
a .claude/skills/* name equals a bundled skill, built-in command or alias. It has no
opt-out. For example, a skill named code-review or security-review fails it.
Action: rename each colliding skill, its name: field, its references and its
Skill(...) permission entries, in the same change that syncs the check.
macrodream/blueprint#101
The voc agent is removed
Section titled “The voc agent is removed”The voc agent was a stale fork of the /voc skill. Action: delete .claude/agents/voc.md
if you copied it, and run the /voc skill wherever you invoked the agent by name.
macrodream/blueprint#132
Gates that now fail
Section titled “Gates that now fail”CI base image
Section titled “CI base image”0.8’s .gitlab-ci.yml sets CI_BASE_IMAGE to Blueprint’s own signed ci-base image, and
scripts/check-ci-image-pins.py fails in CI, naming every job that uses the image, in a
project outside Blueprint’s registry path. A local run only prints a note, so
make pre-push-checks does not catch it. The reset that rewrites it covers new projects only.
Action: after merging .gitlab-ci.yml, set CI_BASE_IMAGE to the alpine digest on the
shell-portability job’s image: line, or to your own ci-base image. macrodream/blueprint#308
Agent contract
Section titled “Agent contract”scripts/check-agent-contract.sh (CI job agent-contract, make check-agent-contract)
fails on a missing “Do not use” clause in an agent description, a review gate without the
Findings: 🔴 <n> · 🟡 <n> · 🟢 <n> summary line, a retired severity word, a gate with no
Bash and no brief contract, and an agent in neither of its two lists.
Action: for each agent your project added, give it a “Do not use” clause and add its name
to GATE_AGENTS or OTHER_AGENTS in the script. Review gates also move to the
🔴/🟡/🟢 scale. Deleting a shipped agent needs no script change. macrodream/blueprint#134
CLAUDE.md size
Section titled “CLAUDE.md size”scripts/check-claudemd-size.sh (CI job claudemd-size, make check-claudemd-size) fails
when any tracked CLAUDE.md exceeds 200 lines. It also bounds the launch total of the root
CLAUDE.md plus its @ imports at 500 lines (CLAUDEMD_MAX_LAUNCH_LINES), and holds the always-loaded files to the byte budget in scripts/claudemd-byte-budget.txt.
Action: move material into .claude/rules/ or docs/harness/ rather than raising the
limit. A nested exception goes in scripts/claudemd-size-allowlist.txt with its own
ceiling and a reason; the root file cannot be listed. macrodream/blueprint#98 and
macrodream/blueprint#120
One fast-paths table, and AGENTS.md
Section titled “One fast-paths table, and AGENTS.md”scripts/check-single-fastpath-table.sh (make check-single-fastpath-table) fails if the
fast-paths table header appears in more than one tracked file. It also fails when a rule
sits in both CLAUDE.md and AGENTS.md or in neither, when AGENTS.md names .claude,
or when the first line of CLAUDE.md is not @AGENTS.md.
Action: keep one table. See the AGENTS.md entry under new required files.
macrodream/blueprint#108 and macrodream/blueprint#45
Duplicate keys in CI YAML
Section titled “Duplicate keys in CI YAML”ci/python.yml had three top-level variables: blocks, and YAML keeps only the last, so
PYTHON_DIR, COVERAGE_THRESHOLD and the WS_* variables vanished. The new
scripts/check-yaml-duplicate-keys.py and scripts/check-ci-include-all.py (job
ci-yaml-lint, make check-ci-yaml) fail on a repeated mapping key in .gitlab-ci.yml or
ci/*.yml.
Action: if you copied ci/python.yml, merge your own top-level variables: blocks into
one. macrodream/blueprint#127
Unpinned CI components
Section titled “Unpinned CI components”scripts/check-ci-image-pins.py fails any include: component that uses @~latest, a
branch, a partial version or no version. Action: pin each component to an exact version.
Blueprint pins sast@3.5.0 and secret-detection@2.4.0. macrodream/blueprint#149
Unknown slash commands in Markdown
Section titled “Unknown slash commands in Markdown”scripts/check-stale-references.sh has a rule that fails a /name in Markdown matching no
project skill, agent, bundled skill, built-in command or alias. Action: fix the typo or
the removed skill. For a deliberate non-command, put the word slash-ok on its line, or
list the name in SLASH_EXTRA_OK. macrodream/blueprint#277
The release gate judges the tagged pipeline job by job
Section titled “The release gate judges the tagged pipeline job by job”release-pipeline-gate (now scripts/check-release-pipeline.py) refuses to publish when a
job in the tagged commit’s pipeline failed, was skipped or canceled, or is a manual job
nobody ran, including an allow_failure job, unless EXEMPT_JOBS in the script names it.
It also fails closed when it cannot read the pipeline. The RELEASE_PIPELINE_LIST
override is removed.
Action:
- Add your image build job to the
needs:list ofimage-sign-attestinci/image-signing.yml, which now needsrelease-pipeline-gate. - If you override
image-sign-attestin your own.gitlab-ci.yml, move the override intoci/image-signing.yml; the same job defined in two files fails. - If you tag
production(the Full variant), setALWAYS_REQUIREDin the script to jobs that run onproductionpipelines. The defaults,version-lockstepandosv-scan, run only onmainand merge requests, so the gate would refuse every tag. - Set the
RELEASE_GATE_TOKENCI/CD variable before your first tag. It is required: the gate never falls back toCI_JOB_TOKEN, which GitLab does not let read the project, pipelines or jobs endpoints, and the script exits 2 when the variable is unset. Create a project access token with theread_apiscope and the Reporter role, and store it asRELEASE_GATE_TOKEN, masked and protected. Protect thev*tags (Settings > Repository > Protected tags), because protected variables reach only protected refs and an unprotected tag pipeline would not get the token. The details are indocs/harness/release-pipeline-gate.md. - Set
TRUSTED_SERVER_HOSTS(for example("gitlab.com",)) andTRUSTED_PROJECT_PATH(for example"group/project") inscripts/check-release-pipeline.pyto your own. They pin the forge host and project in the reviewed script, the one anchor no pipeline variable reaches. Blueprint’s copy of the script pins Blueprint’s own repository, so if you take the script from upstream, replace both values, or the gate refuses every tag.make customizereports them only on a tree with a.blueprint-resetmarker, which a tree reset from v0.7.0 does not have; the gate refuses at the tag either way. Empty, the gate trustsCI_SERVER_HOSTandCI_PROJECT_PATHand prints a note saying so on every tag. - Take
release-pipeline-gate’s newenvironment:key from.gitlab-ci.yml, then changeRELEASE_GATE_TOKEN’s environment scope from*torelease-gate, in that order, so only the gate job gets the token. See The token indocs/harness/release-pipeline-gate.md.RELEASE_PIPELINE_REF=productionnow also needsproductionto be a protected branch. - If you customized
release-pipeline-gate,--check-ci-filenow fails it. Every item of itsbefore_scriptandscript, and of adefault:or top-levelbefore_script, must be the gate script run withpython3 -I, or a package install, one plain line per item.extends,hooks,after_script,variables,needsand merge keys on the job, andhooksorafter_scriptindefault:, fail too. Move other work to a job thatneeds:the gate, and move a variable to the job that uses it; see What a gate item may be indocs/harness/release-pipeline-gate.md. - Add
dependencies: []torelease-pipeline-gate, as.gitlab-ci.ymlnow does:--check-ci-filerequires it, so that an earlier stage’s artifact cannot replace the gate script. - Each CI file the pipeline reads must now open with a plain key at column 0, after at
most one bare
---line, and hold one document, or aspec:header and one document.--check-ci-filefails any other root form, and a?key or a key holding$[[ ]].
macrodream/blueprint#315, macrodream/blueprint#323 and macrodream/blueprint#334
The security::deferred check
Section titled “The security::deferred check”scripts/release.sh runs scripts/check-security-deferred.sh before the release commit.
It now fails closed when the security::deferred label does not exist, and it no longer
lets a deferral be cleared by removing the label or closing the issue. Two effects can
block your first GA tag:
- Create the label once:
glab label create --name 'security::deferred'(or, on GitHub,gh label create 'security::deferred').scripts/gitlab-bootstrap.sh labelscreates it too. - Any former deferral that was closed or unlabeled by hand, rather than by a merged
merge request that closed it or an eligible verified Maintainer, becomes a blocker until
you repair it. See
changelog.d/213.security.mdfor the clearing rules.
macrodream/blueprint#213
Removed or retired
Section titled “Removed or retired”SKIP_SECURITY_GATE=1
Section titled “SKIP_SECURITY_GATE=1”The self-asserted SKIP_SECURITY_GATE=1 prefix is retired, and
.claude/hooks/pre-mr-security-gate.sh now fails closed when jq or python3 is missing.
Action: stop using the prefix. After the required gates run, record them with
.claude/hooks/pre-mr-security-gate.sh record ran, or record skipped when the user said
to skip. The marker is keyed to the HEAD sha, so a new commit invalidates it.
macrodream/blueprint#125
--no-verify in /mass-merge
Section titled “--no-verify in /mass-merge”The /mass-merge skill no longer passes --no-verify on its pushes, so the pre-push hook
runs on each one. Action: drop the flag from your copy of the skill. The new Bash deny hook
(.claude/hooks/pre-bash-deny.sh) denies it. macrodream/blueprint#124
Old global CLAUDE.md block
Section titled “Old global CLAUDE.md block”The project policy moved out of global-claude-md.example into .claude/operating-rules.md,
which CLAUDE.md imports. Action: if you appended the old example to
~/.claude/CLAUDE.md, remove that block (it starts with # Global Claude Instructions).
Otherwise the stale copy loads next to the corrected project rules. macrodream/blueprint#108
Lockfile merge=union
Section titled “Lockfile merge=union”The merge=union rules for package-lock.json, yarn.lock and pnpm-lock.yaml are
removed from .gitattributes, because a union merge produces duplicated or inconsistent
entries that still parse. Action: remove the same rules from your .gitattributes. On a
conflict, regenerate the lockfile. macrodream/blueprint#140
New required files and settings
Section titled “New required files and settings”AGENTS.md
Section titled “AGENTS.md”AGENTS.md is the agent-agnostic project contract, and CLAUDE.md now imports it.
Action: if you copied Blueprint’s CLAUDE.md, add AGENTS.md, move your own filled-in
name, stack, and test and docs paths into it, and put @AGENTS.md on line 1 of
CLAUDE.md. Claude Code reads AGENTS.md on its own only when no CLAUDE.md exists.
macrodream/blueprint#45
.claude/rigor.json
Section titled “.claude/rigor.json”The rigor floor lists the paths whose changes always get the heavier audit, in two tiers:
floor.strict and the optional floor.strict-light (Sonnet round 1, Opus round 2).
scripts/check-rigor-floor.py, run in the mr-gate-ledger CI job, fails a merge request
that touches a floor path without the matching ## Gates ledger lines. Action: sync
.claude/rigor.json, then edit its path lists to match your project. Sync .claude/rigor.json and
scripts/check-rigor-floor.py together: an old checker reads only floor.strict and silently
ignores strict-light paths. macrodream/blueprint#234
A new hook and settings rules
Section titled “A new hook and settings rules”The PreToolUse Bash hook .claude/hooks/pre-bash-deny.sh is new, and
.claude/settings.json gains deny rules. If you merge settings by hand, take both, and
run scripts/tests/pre-bash-deny.test.sh. Your agents will now find these denied:
- Edit and Write of
.claude/settings.json,.claude/hooks/**,hooks/**andCHANGELOG.md. Edit those by hand, and add achangelog.d/fragment instead of editingCHANGELOG.md. - Read of nested
.envand.env.*,.envrc,*.pem,*.key,id_rsa,credentials.json,~/.ssh/**and~/.config/glab-cli/**. - Bash:
git reset --hard, forcedgit clean,curlorwgetpiped into a shell, forced pushes in any spelling,--no-verify,glab mr mergeand merge API calls, and any baregit stashexceptlistandshow. Usescripts/wt stashinstead. - Bash writes to
.claude/settings*.json,.claude/hooks/**andhooks/**,git diff|log|show --output=<file>, and aglab,curlorwgetargument or heredoc line starting/merge(a GitLab quick action). - Bash
rm -rof the project, its parents, and absolute paths outside the project and the temp directories.
macrodream/blueprint#124 and macrodream/blueprint#165
Tracker token for CI gates
Section titled “Tracker token for CI gates”Tracker-reading CI gates now retry on HTTP 429 and use a shared ISSUES_API_TOKEN CI/CD
variable (a masked read_api token) for the authenticated rate limit. Action: optional;
set it if your gates hit rate limits. macrodream/blueprint#123
Behavior changes with no edit required
Section titled “Behavior changes with no edit required”scripts/wt newrefuses a branch whose work already merged intoorigin/main;--forcebypasses it./wavepre-flights each candidate withscripts/wave-preflight.py. macrodream/blueprint#245/releasedrafts an upgrade-urgency call and a breaking-change paragraph, passed toscripts/release.shthroughRELEASE_SUMMARY_FILE. macrodream/blueprint#92/dotplanningleads with thecommitted/uncommittedlabels. Wording only. macrodream/blueprint#260
When you are done
Section titled “When you are done”Run make pre-push-checks. A gate that names a file or variable on this page tells you
which entry to reread. Report anything this page missed through the
giving feedback guide.