create-ai-blueprint

Install AI Blueprint into an already scaffolded app.

Official site | Documentation | Repository | Changelog

Requires Node.js 22 or newer. Run the installer from an application that has already been scaffolded and initialized as a Git repository.

npx create-ai-blueprint@latest

You can also use npm's initializer form:

npm create ai-blueprint@latest

The installer copies the Blueprint workflow files into the current directory:

• AGENTS.md
• CLAUDE.md
• blueprint/.state/manifest.json
• .agents/
• .claude/
• blueprint/

It keeps the app's root README.md alone.

The installed workflow includes optional Render and Vercel deployment readiness through /release or $release; it prepares local config and checks, but does not deploy without explicit approval.

The optional /ci or $ci skill sets up automatic GitHub checks separately from onboarding and adoption. It detects the real project commands, defines one Verify command from checks that already exist, and adds a matching pull request workflow without replacing existing CI. It does not invent tests or add git hooks, coverage, browser tests, security scans, or version matrices by default.

It also includes /rollback or $rollback for planning a reviewed reversal of a completed feature from its archived spec and exact git commit. Rollbacks keep the original feature archive and use the normal implement, check, and complete gates.

If you install --claude or --all while Claude Code is already open in the project, restart Claude Code in that folder so the newly added project skills appear.

Tool support

| Tool | Installed adapter | Invocation | | --- | --- | --- | | Codex | .agents/skills/ | $feature, $implement, or plain language | | Claude Code | .claude/skills/ | /feature, /implement, and other slash commands | | GitHub Copilot | AGENTS.md and .agents/skills/ | Ask Copilot to run the matching skill | | Other tools | AGENTS.md plus readable skill files | Ask the agent to follow the matching SKILL.md |

Options

npx create-ai-blueprint@latest -- --codex
npx create-ai-blueprint@latest -- --claude
npx create-ai-blueprint@latest -- --copilot
npx create-ai-blueprint@latest -- --all
npx create-ai-blueprint@latest -- --both
npx create-ai-blueprint@latest -- --force
npx create-ai-blueprint@latest -- --target ./my-app

The same flags work with npm create ai-blueprint@latest -- ....

The installer defaults to --all. --both remains as a deprecated alias for --all and prints a warning. GitHub Copilot uses AGENTS.md and the shared .agents/skills/ files; the installer does not manage .github/copilot-instructions.md.

Use --force to overwrite existing Blueprint files. Without --force, the installer asks before overwriting in an interactive terminal and exits in non-interactive runs.

Updating an existing installation

Preview the update plan:

npx create-ai-blueprint@latest update --dry-run

Apply the update:

npx create-ai-blueprint@latest update

The updater detects the installed adapters and manages only these paths:

• .agents/skills/
• .claude/skills/

It preserves AGENTS.md, CLAUDE.md, project and build plans, context, history, references, and prototypes. An unchanged blueprint/README.md installed by an older version is removed during update; a locally modified copy keeps the normal conflict protection. The blueprint/.state/manifest.json file records the installed version and hashes of managed files.

Locally modified managed files are reported as conflicts. Interactive updates ask before replacing them. Non-interactive updates exit unless you pass --force, which backs up the conflicting files before replacement. Backups are stored under blueprint/.state/backups/ and ignored by git.

The first update of a legacy install creates the manifest. Files that already match the current package are adopted automatically. Differing files remain conflicts so local changes are not lost.

Checking project status

Run the read-only status command from a Blueprint project or any directory inside it:

npx create-ai-blueprint@latest status

It reports build-plan progress, active work, findings, Git state, drift warnings, completion blockers, and one suggested next action. For scripts and integrations, request the versioned JSON object:

npx create-ai-blueprint@latest status --json

After an interactive Blueprint install or update, the installer checks the global CLI version. It offers to run the following command only when the CLI is missing or does not match the npx package version:

npm install --global create-ai-blueprint@latest

The prompt defaults to no and is skipped for matching versions, non-interactive runs, and --yes runs. Accepting it installs or refreshes the CLI at the same version used by the npx command. Global installation exposes the shorter forms blueprint status, blueprint status --json, and blueprint dashboard. Use --target ./my-app to inspect an explicit project directory. Status never edits project or Git state.

Opening the local dashboard

Run the on-demand read-only dashboard from a Blueprint project or any directory inside it:

blueprint dashboard

The command binds to 127.0.0.1 on an available port, opens the dashboard in your browser, and refreshes the existing status contract every second. It does not edit project files, run workflow commands, start the application, or make the dashboard available outside the local machine. It shows the full build-plan roadmap, active work and build steps, archived completed work, findings, Git state, completion blockers, and the suggested next action. Press Ctrl+C to stop it. Use blueprint dashboard --no-open when you want the URL without opening a browser. The older blueprint ui form remains as a deprecated alias.

The optional global blueprint command is limited to read-only project status and this local dashboard. Continue to use npx create-ai-blueprint@latest for installation and npx create-ai-blueprint@latest update for managed workflow updates.

Help and contributing

• Read the full documentation.
• Report reproducible problems through the repository's issue forms.
• Follow the repository's security policy for private vulnerability reports.
• Read the contribution guide before opening a pull request.

License

MIT