# AI Blueprint

what it does

AI Blueprint is a workflow you install into an already-scaffolded app. It doesn’t choose your framework or generate an entire product from one prompt. It gives the coding agent a written plan, a bounded feature, and checks to satisfy before the work is closed.

npx create-ai-blueprint@latest

You own two planning files: blueprint/project-plan.md for the product and blueprint/build-plan.md for the ordered work. Blueprint turns those into durable context, then keeps the active spec and completed history in the repo.

the working loop

The usual path is:

/onboard or /adopt
/overview
/feature or /fix
/implement
/check
/audit
/complete

These are Claude Code-style skill names. Codex uses the matching $skill form or plain language. The terminal CLI manages the installation and status; it doesn’t run the coding skills itself.

• Plan: /discovery helps draft the two planning files when needed.
• Scope: /feature turns one build-plan item into a spec for approval.
• Implement: build the approved scope, then walk through the code.
• Verify: /check tests observable behavior against the spec.
• Review: /audit records findings and can request an independent reviewer.
• Close: /complete runs the final gates and requests merge approval.

/explore investigates an idea against the code without changing files. /debug diagnoses a failure before repair. Neither is an invitation to quietly start implementing.

checks are different kinds of evidence

A passing test command is useful, but it isn’t proof that the application works for the person using it. Blueprint keeps those checks separate:

• Verify: the project’s repeatable test and build command.
• Check: evidence that the current feature satisfies its done-whens.
• Audit: code review, with focused quality, security, performance, or test lenses.
• Check guide: a read-only manual walkthrough using /check guide.
• Independent Audit: a fresh reviewer checks a specific checkpoint.

Independent review defaults to sensitive work. It can run as an isolated reviewer when the adapter supports the required metadata, or hand off to a fresh session. If it can’t establish the required reviewer context, it stops rather than treating self-review as independent.

The receipt records what was reviewed and what ran. Relevant code changes make it stale. Reviewer identity is declared metadata, not cryptographic proof, and configuration never grants permission to merge or deploy.

For setup, /tests adds a unit-test harness, /tests browser adds browser testing, and /ci aligns GitHub checks with the project’s Verify command. The old /try and /browser-tests entrypoints have been consolidated into /check guide and /tests browser.

status without rereading the whole chat

blueprint status gives a read-only terminal view of the current work. blueprint dashboard presents that state in the browser, with light and dark themes. Both work from files rather than treating a long chat as project memory.

The repo holds the active spec and overview under blueprint/context/. The findings ledger and independent-review receipt live there too. Completed feature records stay under blueprint/history/.

Finding recovery is explicit. Fixing a finding does not itself waive the review needed to close it. /doctor checks workflow health and can offer a reviewed reset of malformed generated dashboard state.

tool adapters and updates

Codex, Claude Code, GitHub Copilot, and OpenCode are supported adapters. They share the project’s planning files and workflow policy. The installer can manage more than one adapter, and changing tools does not require moving the project’s history back into a conversation.

Managed file hashes help the updater identify conflicts. Project-owned plans and history are preserved rather than overwritten with a fresh template. The current published release is create-ai-blueprint@1.10.0.

automation has boundaries

Autopilot is an explicit, bounded spec-and-implementation pass that stops before completion. Continuous Mode works through reviewed build-plan items serially under the project’s configured gates.

Neither mode grants permission to push, publish, or deploy. Sending messages and destructive actions also stay outside those modes’ authority. /release prepares local Render or Vercel readiness; it isn’t a deployment approval.

why i built it

I want AI to help me build software without losing track of what changed or why. A vague prompt followed by a convincing demo isn’t enough when I need to maintain the app next month.

Blueprint keeps the decisions and evidence beside the code. The agent can do a lot of the work, but I still own the scope and the decision to ship.

The docs cover the current commands and configuration. The repository contains the installer and the workflow files themselves.