AI Blueprint: a file-backed, spec-driven workflow for AI coding agents

What problem AI Blueprint solves, and for whom

The README names the failure mode directly: AI coding gets unreliable when product intent lives only in chat, several features blur together, and claims such as "working" or "tested" are not backed by observable evidence. That is a workflow problem, not a model problem. A chat window has no durable record of what was agreed, so the next session starts from a summary that the previous session wrote about itself.

AI Blueprint targets teams that already have a working application and a coding agent that can read and write files. It supports Codex, Claude Code, GitHub Copilot, OpenCode and other file-aware agents. The README is explicit that it works with any application stack and does not replace your application framework or add application code. If you are looking for an app generator, this is not it. The scaffold has to exist first, and Git has to be initialized before the installer runs.

The intended user is someone who wants to keep judgement in the loop while the agent writes code. The README frames it that way: the point is not to remove judgment, it is to preserve it. That framing matters because most of the workflow's value comes from stopping the agent at defined points rather than letting it run from prompt to commit.

The five-command loop and what each step refuses to do

The workflow is a fixed sequence the README gives as a single line: feature, implement, check, audit current, complete. Each step has what the README calls a narrow job.

Feature selects one build-plan item and writes its buildable spec. Implementation does not begin until that spec is reviewed and approved. This is the first real constraint: the agent is not allowed to start coding from a vague prompt. Implement then builds the approved spec in small, visible steps. Check proves the acceptance criteria against the running application, which is a different thing from a passing build. The README states that Check runs the real app against the spec instead of treating a green build as behavioral proof.

Audit records durable findings, and unresolved P0 or P1 findings block completion. That is the sharpest rule in the framework: severity levels are not advisory. Complete closes the item, and the README notes that every completed implementation offers a read-only code walkthrough regardless of the configured review cadence.

Two supporting properties sit alongside the loop. One work item at a time means the current feature, fix or rollback has one explicit scope and one set of acceptance criteria. Proportional engineering requires a current need before adding abstractions, dependencies, services, configuration or specialized security machinery, and unknown scale defaults to the smaller reversible design. The README adds that real trust and data-integrity boundaries still apply, so the default is not a blanket excuse to skip security work.

Installing AI Blueprint and running your first feature

The README states the requirements plainly: Node.js 22 or newer, an existing application, and a Git repository. The package.json for the maintainer repository sets engines.node to >=22, which is consistent with that. The installer is not an application starter, so scaffold first. The README's example uses Next.js but says Blueprint works with any stack.

From the root of the new application, initialize Git if the scaffolder did not, then install Blueprint:

npx create-next-app@latest my-app
cd my-app
git init

Choose the command for your package manager. The README gives both npm and pnpm forms:

# npm
npx create-ai-blueprint@latest

# pnpm
pnpm dlx create-ai-blueprint@latest

One caveat the README calls out: a project that enforces pnpm through devEngines.packageManager can reject npx with EBADDEVENGINES before Blueprint starts. In that case use pnpm dlx and do not remove the package-manager requirement. The README also notes that the remaining npx examples work with pnpm dlx using the same command and options.

The interactive installer lets you select one or more adapters. It adds the workflow files those tools need and leaves your application's README.md alone. After installation, the README's next steps are: run onboard so Blueprint learns the real stack, commands, conventions, adapter setup and workflow visibility you want; write blueprint/project-plan.md and blueprint/build-plan.md directly or use the optional discovery skill; run overview to format the list into a tracked checklist without changing its scope or order; then run feature for the next planned item, review the generated spec, and begin implementation.

Invocation style depends on the tool. The README's table gives these examples:

Codex          $onboard, $overview, $feature
Claude Code    /onboard, /overview, /feature
GitHub Copilot Ask Copilot to run the matching skill
OpenCode       Ask OpenCode to run the matching skill

The README notes that formatting the plan list with overview needs no extra approval, but unclear scope or order does. On the first run it offers a reviewed local commit for the Blueprint setup and plans.

Where the workflow stops being the right tool

The most obvious misfit is a project with no Git repository. The README lists Git as a requirement and the installer's first-run behaviour includes offering a reviewed local commit, so a repository that does not exist yet has to be created before anything else works.

A second boundary is the application scaffold. The README repeats that Blueprint is not an application starter and does not replace your application framework. If your goal is to get a running app from a prompt, this adds a layer on top of whatever already produces the app.

A third constraint is the review cadence itself. Feature stops for spec approval before implementation. That is the design, and it costs time on small changes where the spec is obvious. The README does not document a way to skip the spec review for trivial edits, and it does not document rollback behaviour for an abandoned work item beyond naming rollback as one of the things that can hold a single scope and acceptance criteria. Treat the approval gate as fixed unless you find otherwise in the documentation.

The README also does not state a supported Node.js version below 22, and it does not describe what happens if you install into a repository with uncommitted changes beyond the first-run commit offer. Those are open questions to resolve before rolling the framework out across a team.

How it differs from letting the agent plan in chat

The real alternative is not a competing framework. It is the default behaviour of a coding agent: plan in the conversation, implement in the same conversation, and rely on the model's summary of what it did. That approach has no file-backed record, so the plan and the evidence disappear with the session. It also has no severity gate, because nothing in a chat transcript blocks completion on an unresolved P0 finding.

AI Blueprint swaps that for files under blueprint/ and a command sequence. Plans, specs, findings, review evidence and completed history stay as readable files in the project. The difference in approach is where the state lives. In the chat-first approach, state lives in the context window and is reconstructed each session. In Blueprint, state lives in the repository and the agent reads it. That makes the workflow auditable by anyone with a checkout, and it makes the framework's rules enforceable rather than advisory.

The cost is ceremony. You write or generate a project plan and a build plan, you review specs, and you run Check against the running app. The README notes the build plan can start as a plain feature list, and overview formats it into a tracked checklist without changing scope or order. So the entry cost is lower than it first appears, but the per-item cost is real.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-13. The releases listed are v1.9.0 on 2026-09-13, v1.8.0 on 2026-09-12 and v1.7.0 on 2026-09-11, so the project ships frequently enough that pinning a version matters. The npm package is create-ai-blueprint, and the README links to the changelog at CHANGELOG.md in the repository.

Upgrade cost is shaped by what the installer writes. Adapters for Codex, Claude Code, GitHub Copilot and OpenCode are generated into the project, and the README notes the installer adds the workflow files those tools need while leaving your application's README.md alone. When the framework changes, those generated files are the surface you re-run the installer against. The README does not document an upgrade command separate from the installer, so plan on re-running create-ai-blueprint and reviewing the diff.

The licence is MIT, per the repository and the badge in the README. MIT permits commercial use and modification with the licence and copyright notice preserved. That is a general description of the licence text, not legal advice; read LICENSE in the repository for the terms that apply to you. The maintainer package.json also declares MIT and marks the package private, which is about the maintainer tooling rather than the published installer.

Editorial conclusion

Adopt AI Blueprint if your team already runs a file-aware coding agent and wants specs, plans and review evidence to survive the chat session that produced them. Skip it if you have no application scaffold or Git repository yet, since the README states it is not an application starter and does not replace your framework. Before committing, verify that your agent's invocation style matches the adapter the installer writes for it, and confirm the pnpm devEngines.packageManager behaviour if your project enforces a package manager.

Frequently asked questions

Official sources

1. aiblueprinthq/ai-blueprint on GitHub
2. License: MIT
3. Project website
4. README
5. Releases