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.

Preview the update

Run a dry run from the project root:

npx 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 and Claude Code adapters.

Apply the update

npx create-ai-blueprint@latest update

The updater manages only these Blueprint-owned paths:

• .agents/skills/
• .claude/skills/
• blueprint/README.md

It preserves these project-owned paths:

• AGENTS.md and CLAUDE.md
• blueprint/project-plan.md and blueprint/build-plan.md
• blueprint/context/
• blueprint/history/
• blueprint/references/
• prototypes/

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.