Blueprint can update its workflow layer as new skills and improvements are released. The updater has a narrow ownership boundary so your project state remains yours.
Use the runner for your project: npx for npm or pnpm dlx for pnpm. A pnpm-enforced project can reject npx with EBADDEVENGINES before Blueprint runs. Later npx examples on this page can use pnpm dlx with the same command and options.
Preview the update
Run a dry run from the project root:
# npm
npx create-ai-blueprint@latest update --dry-run
# pnpm
pnpm dlx create-ai-blueprint@latest update --dry-run
The plan reports files to add, update, remove, or treat as conflicts. It also shows the detected adapter selections, including Google Antigravity.
Apply the update
# npm
npx create-ai-blueprint@latest update
# pnpm
pnpm dlx create-ai-blueprint@latest update
The updater manages only these Blueprint-owned paths:
.agents/skills/.claude/skills/blueprint/workflow.md
Codex, GitHub Copilot, and Google Antigravity share the .agents/skills/
adapter files. OpenCode reuses compatible .agents/skills/ or
.claude/skills/ files, so updates do not create a separate
.opencode/skills/ tree.
Older installs may still contain blueprint/README.md. The updater removes an
unchanged managed copy because current installs no longer include it. A locally
modified copy is preserved and reported as a conflict for review.
It preserves these project-owned paths:
AGENTS.mdandCLAUDE.mdblueprint/config.jsonblueprint/project-plan.mdandblueprint/build-plan.mdblueprint/context/blueprint/history/blueprint/references/prototypes/
The 1.8.0 update adds the proportional-engineering wording to the managed
skills. AGENTS.md and blueprint/project-plan.md are user-owned and are not
rewritten. Existing projects that want the contract text in AGENTS.md or the
optional section 9 worksheet prompt in the project plan should copy them from
the source repository’s
AGENTS.md
and
project-plan.md.
The 1.7.0 update added an optional pre-push hook offer to /ci and kept
history archive identifiers stable on Windows. The hook offer has since been
removed. A hook that /ci already added is a project file, and it keeps working.
The 1.6.1 update includes completion recovery, rebuild handling, local-only
review snapshots, and automatic formatting of clear feature lists in Overview.
It preserves your existing build plan and entry/context files, so it does not
replace them with the simpler starter template. To adopt the expanded
commit and PR attribution guidance,
manually merge that guidance into AGENTS.md and
blueprint/context/ai-interaction.md, preserving project-specific rules.
Command migration
Two standalone skills are now modes of existing commands, two were renamed, and two were removed:
| Previous command | Replacement |
|---|---|
/browser-tests |
/tests browser |
/try |
/check guide |
/try latest |
/check guide latest |
/status |
/blueprint-status |
/doctor |
/blueprint-doctor |
/rollback |
/fix, written to remove the feature |
/release |
A build-plan feature, or /fix, that adds the deployment setup |
Version 1.16.0 removed the /rollback skill. To take out a completed feature,
write a fix that removes it, then uncheck its build-plan item if you plan to
build it again. Finish or abandon any in-progress rollback before updating. Existing
blueprint/history/rollbacks/ records stay as history, and an existing
git.rollbackBranchPrefix config key is ignored.
The /release skill has also been removed. Deployment setup is ordinary project
work: add it to your build plan, or use /fix for a small change. See
Preparing to Deploy.
Continuous Mode no longer offers a final integration audit. An existing
continuous.finalIntegrationAudit config key is ignored. To review a finished
run as a whole, run /audit full afterward.
Version 1.15.0 renamed /status and /doctor so they no longer hide the Claude
Code built-in commands with the same names. The blueprint status terminal
command is unchanged.
Codex uses $tests browser, $check guide, $blueprint-status, and $blueprint-doctor. Default /tests still sets up unit testing, and default /check still verifies behavior. The new Explore skill discusses ideas without changing files or requiring plans.
Run the managed update to install the new skills and references. With a manifest, unchanged retired skill files are removed and backed up. Customized copies are conflicts: the update stops without applying changes unless replacement is explicitly approved. Review and port custom instructions before choosing replacement. Legacy installs without a manifest follow the existing conservative conflict rules below and cannot assume old customized files are managed.
Existing AGENTS.md stays preserved. Manually update old command references
there and in your own instructions. The qualityGates.regular.tryGuide and
qualityGates.continuous.tryGuide keys keep their names and explicit configured
values; they generate /check guide, which does not count as verification.
Version 1.13.0 adds the when-testable try-guide policy and makes it the default
for new projects. Existing user-owned configuration is preserved during update,
so explicit manual, when-user-facing, and always values do not change.
Projects without a config file use the new built-in default after updating.
Choose when-testable manually if you want to change an existing explicit
policy to Automatic Try It Now proofs.
Version 1.14.0 moves the workflow reference out of AGENTS.md into the managed
blueprint/workflow.md, which agents read only when a command needs it. The
update adds that file and preserves your AGENTS.md, so an older project keeps
its longer startup file until you trim it. Run /blueprint-doctor to see which sections
can go; the trim is a manual edit.
Run /blueprint-doctor to check for missing proportional-engineering guidance in preserved AGENTS.md. Equivalent project wording is accepted. Missing guidance is a warning, not a blocker; review and merge only the missing guidance while keeping project rules and local-only visibility intact.
If latest runs an older version
Check the version printed in the update plan before proceeding. A cached
package resolution can run an older release even when the command uses
@latest. Pin the intended published version explicitly. For example, for
1.11.0:
# npm
npx create-ai-blueprint@1.11.0 update
# pnpm
pnpm dlx create-ai-blueprint@1.11.0 update
Use the version from the release list
when following this example after a newer release. The interactive adapter
picker was introduced in 1.8.0. Run without adapter flags or --yes in an
interactive terminal to select adapters. If an older updater offers to replace
a newer global CLI with an older version, answer No and rerun the intended
version.
Change adapters
Update can also change the installed adapters. In an interactive terminal it shows the same five-tool checkbox as the installer, pre-filled with the installed adapters. Press Enter to keep the current set, or check and uncheck tools before the plan is printed.
Adapter flags add an adapter without a prompt and never remove one:
npx create-ai-blueprint@latest update -- --antigravity
--yes and non-interactive runs keep the installed set. Removing an adapter is
interactive only. Its managed skill files follow the normal conflict and backup
rules, and skill directories left empty are pruned.
Adding Claude Code creates CLAUDE.md from the template only when the file is
missing. Removing Claude Code never deletes it. Google Antigravity reuses
.agents/skills/ without creating its own skill tree. OpenCode reuses a
compatible skill tree, so adding or removing Claude Code can move that tree
between .agents/skills/ and .claude/skills/; the plan says so when it does.
To preview the plan without the adapter prompt, run:
npx create-ai-blueprint@latest update --dry-run --yes
Adopt the lower-context defaults
The updater refreshes the managed skills and their shorter descriptions, but it
does not rewrite user-owned CLAUDE.md or blueprint/config.json files.
Existing projects therefore keep their current review experience after an
update.
The updater reports the exact obsolete project-overview.md and
current-feature.md import lines when they are present in the preserved
CLAUDE.md. Older layouts may also contain direct coding-standards.md and
ai-interaction.md imports, which are reported too. Remove every reported line,
then restart Claude Code in that project so its startup context and command
catalog reload. Run /blueprint-doctor afterward to confirm that CLAUDE.md imports only
AGENTS.md and to check the generated overview size. If project-overview.md
is 20,000 bytes or larger, rerun /overview before the next feature. The context
files remain in the project and workflow skills read them on demand.
To adopt the lower-interruption workflow, use:
"workflow": {
"stepReview": "feature",
"checkpointCommits": "disabled"
}
To keep the previous workflow exactly, leave or set both values as follows:
"workflow": {
"stepReview": "every",
"checkpointCommits": "enabled"
}
stepReview: "every" by itself restores per-step approval pauses but not the
checkpoint prompts. The compact overview, narrower Claude imports, and reduced
skill descriptions still save context with either configuration. Use /context all in Claude Code to inspect the live context result.
Return to an earlier workflow version
Use the same updater with an exact version and --force:
npx create-ai-blueprint@1.4.1 update --target . --yes --force
The updater replaces only managed skill files, removes managed files that do
not exist in that version, preserves plans and context, and writes a backup
under blueprint/.state/backups/. Returning to 1.4.1 restores its managed
workflow but does not rewrite user-owned CLAUDE.md. To reproduce its Claude
startup behavior exactly, restore these lines and restart Claude Code:
@blueprint/context/project-overview.md
@blueprint/context/current-feature.md
The Efficient, Guided, and Custom labels shown during onboarding are only
presets for these two values. There is no separate implementationStyle field,
and changing the low-level settings later affects the next Implement run.
The global command does not update Blueprint
The optional global blueprint command provides read-only status and dashboard
views. blueprint update is not supported. Always use the version-explicit
package command when changing managed files:
npx create-ai-blueprint@latest update
See the CLI Overview for the full command boundary.
Manifest and backups
New installs create blueprint/.state/manifest.json. It records the installed package version, selected adapters, and SHA-256 hashes for managed files. Commit the manifest when the rest of the Blueprint workflow is committed so another checkout has the same update baseline.
Before replacing or removing an existing managed file, the updater copies it into blueprint/.state/backups/. Backup and staging directories are ignored by the nested blueprint/.state/.gitignore file.
Conflicts
A conflict means a managed file no longer matches the version recorded in the manifest. The normal update command lists the file and asks before backing it up and replacing it.
For non-interactive runs, updates with conflicts stop without writing. Use --force only when you intentionally want to back up and replace those managed files:
npx create-ai-blueprint@latest update --force
Files at unsafe paths, such as symbolic links or directories where a regular managed file should be, are never replaced by --force. Resolve those paths manually and run the preview again.
Legacy installations
An installation created before update manifests can use the same command. Files that match the current package are adopted into the new manifest. Differing managed files are reported as conflicts because the updater has no earlier hash to prove they are unchanged.
Local-only mode
If the Blueprint workflow is local-only, the ignored blueprint/ directory already covers blueprint/.state/, so the update baseline remains local to that checkout. See Local-Only Mode for the full tradeoff.