Updating Blueprint

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 Codex, Claude Code, GitHub Copilot, and OpenCode adapters.

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/

Codex and GitHub Copilot 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.md and CLAUDE.md
• blueprint/config.json
• blueprint/project-plan.md and blueprint/build-plan.md
• blueprint/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 adds the optional pre-push hook offer to /ci and keeps history archive identifiers stable on Windows. Existing CI setups are left as they are; rerun /ci if you want the hook offer.

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:

Codex uses $tests browser and $check guide. 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 policy values; they now generate /check guide, which does not count as verification.

Run /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.10.0:

# npm
npx create-ai-blueprint@1.10.0 update

# pnpm
pnpm dlx create-ai-blueprint@1.10.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 Codex, Claude Code, GitHub Copilot, and OpenCode 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 -- --codex

--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. 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 /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

After a successful interactive update, the installer checks the globally installed CLI version. Matching versions continue without a question. If the CLI is missing or does not match, the installer offers to install or refresh the exact package version used for the update. The prompt explains that this is optional and that npx create-ai-blueprint@latest status and npx create-ai-blueprint@latest dashboard work without it. The prompt defaults to no. Non-interactive and --yes updates never install anything globally.

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.