Skip to content

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.

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:

  1. Take the renames first (the next section), so the later gates find nothing stale.
  2. Sync the gates that now fail and clear what each one reports.
  3. Remove the retired variable and add the new files.
  4. Run make pre-push-checks and fix what it reports.

Each entry ends with the issue it came from, written macrodream/blueprint#NNN.

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:

  1. Move each renamed skill: git mv .claude/skills/batch .claude/skills/wave and git mv .claude/skills/review .claude/skills/conventions-review (both renamed), then update each skill’s name: field.
  2. Replace every /batch and /review that meant your skill, not the bundled command, in CLAUDE.md, skills, agents, docs and scripts.
  3. Update any Skill(batch) or Skill(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 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

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

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

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

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

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

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

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 of image-sign-attest in ci/image-signing.yml, which now needs release-pipeline-gate.
  • If you override image-sign-attest in your own .gitlab-ci.yml, move the override into ci/image-signing.yml; the same job defined in two files fails.
  • If you tag production (the Full variant), set ALWAYS_REQUIRED in the script to jobs that run on production pipelines. The defaults, version-lockstep and osv-scan, run only on main and merge requests, so the gate would refuse every tag.
  • Set the RELEASE_GATE_TOKEN CI/CD variable before your first tag. It is required: the gate never falls back to CI_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 the read_api scope and the Reporter role, and store it as RELEASE_GATE_TOKEN, masked and protected. Protect the v* 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 in docs/harness/release-pipeline-gate.md.
  • Set TRUSTED_SERVER_HOSTS (for example ("gitlab.com",)) and TRUSTED_PROJECT_PATH (for example "group/project") in scripts/check-release-pipeline.py to 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 customize reports them only on a tree with a .blueprint-reset marker, which a tree reset from v0.7.0 does not have; the gate refuses at the tag either way. Empty, the gate trusts CI_SERVER_HOST and CI_PROJECT_PATH and prints a note saying so on every tag.
  • Take release-pipeline-gate’s new environment: key from .gitlab-ci.yml, then change RELEASE_GATE_TOKEN’s environment scope from * to release-gate, in that order, so only the gate job gets the token. See The token in docs/harness/release-pipeline-gate.md. RELEASE_PIPELINE_REF=production now also needs production to be a protected branch.
  • If you customized release-pipeline-gate, --check-ci-file now fails it. Every item of its before_script and script, and of a default: or top-level before_script, must be the gate script run with python3 -I, or a package install, one plain line per item. extends, hooks, after_script, variables, needs and merge keys on the job, and hooks or after_script in default:, fail too. Move other work to a job that needs: the gate, and move a variable to the job that uses it; see What a gate item may be in docs/harness/release-pipeline-gate.md.
  • Add dependencies: [] to release-pipeline-gate, as .gitlab-ci.yml now does: --check-ci-file requires 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 a spec: header and one document. --check-ci-file fails any other root form, and a ? key or a key holding $[[ ]].

macrodream/blueprint#315, macrodream/blueprint#323 and macrodream/blueprint#334

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 labels creates 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.md for the clearing rules.

macrodream/blueprint#213

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

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

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

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

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

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

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/** and CHANGELOG.md. Edit those by hand, and add a changelog.d/ fragment instead of editing CHANGELOG.md.
  • Read of nested .env and .env.*, .envrc, *.pem, *.key, id_rsa, credentials.json, ~/.ssh/** and ~/.config/glab-cli/**.
  • Bash: git reset --hard, forced git clean, curl or wget piped into a shell, forced pushes in any spelling, --no-verify, glab mr merge and merge API calls, and any bare git stash except list and show. Use scripts/wt stash instead.
  • Bash writes to .claude/settings*.json, .claude/hooks/** and hooks/**, git diff|log|show --output=<file>, and a glab, curl or wget argument or heredoc line starting /merge (a GitLab quick action).
  • Bash rm -r of the project, its parents, and absolute paths outside the project and the temp directories.

macrodream/blueprint#124 and macrodream/blueprint#165

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

  • scripts/wt new refuses a branch whose work already merged into origin/main; --force bypasses it. /wave pre-flights each candidate with scripts/wave-preflight.py. macrodream/blueprint#245
  • /release drafts an upgrade-urgency call and a breaking-change paragraph, passed to scripts/release.sh through RELEASE_SUMMARY_FILE. macrodream/blueprint#92
  • /dotplanning leads with the committed / uncommitted labels. Wording only. macrodream/blueprint#260

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.