AI Blueprint

A file-backed, spec-driven workflow for building real software with AI while staying in control.

Official site | Documentation | Video demo | npm | Releases | Changelog

AI Blueprint gives coding agents a shared process for planning, building, verifying, and documenting one feature at a time. Plans, specs, findings, review evidence, and completed history stay as readable files in your project instead of disappearing with the chat that created them.

It works with any application stack and supports Codex, Claude Code, GitHub Copilot, OpenCode, and other file-aware coding agents.

Start with the scaffold-first Quick Start below.

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.

Blueprint adds a controlled loop:

• Spec before code. The agent writes a feature or fix spec and stops for review before implementation.
• One work item at a time. The current feature, fix, or rollback has one explicit scope and one set of acceptance criteria.
• Proof before completion. Check runs the real app against the spec instead of treating a green build as behavioral proof.
• Findings with teeth. Audit records durable findings, and unresolved P0 or P1 findings block completion.
• Independent review when it matters. A fresh reviewer session can inspect an exact checkpoint and leave a staleness-checked receipt.
• Human approval at external boundaries. Commit, merge, push, deployment, publication, and destructive actions keep their approval gates.

The point is not to remove judgment. It is to preserve it while AI helps write the code.

AI Blueprint is a workflow overlay, not an application starter. Scaffold the app first and initialize Git before installing it.

Requirements: Node.js 22 or newer, an existing application, and a Git repository.

First create the application manually or with the scaffolding CLI for your framework or language of choice. This example uses Next.js, but 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
npx create-ai-blueprint@latest

Next:

1. Run onboard so Blueprint learns the real stack, commands, conventions, adapter setup, and workflow visibility you want.
2. Write blueprint/project-plan.md and blueprint/build-plan.md directly, or use the optional discovery skill to develop them through conversation.
3. Run overview to turn those plans into durable project context. On the first run, it offers a reviewed local commit for the Blueprint setup and plans.
4. Run feature for the next planned item, review the generated spec, and then begin implementation.

Use the invocation style for your tool:

The interactive installer lets you select one or more adapters. It adds the workflow files needed by those tools and leaves your application's README.md alone.

See Getting Started for the complete installation and onboarding walkthrough. For a project that already has shipped features, start with Adopting an Existing Codebase.

The normal feature loop is:

feature -> review spec -> implement -> check -> audit current -> complete

Each step has a narrow job:

1. Feature selects one build-plan item and writes its buildable spec.
2. Implement builds the approved spec in small, visible steps.
3. Check proves the acceptance criteria against the running application.
4. Audit reviews the complete branch delta and records actionable findings.
5. Complete runs the final gates, archives the work, and asks before merge.

Other work enters the same control loop:

• Use fix for a small unplanned change or confirmed bug.
• Use debug first when the cause is unclear.
• Use rollback to reverse a completed feature without erasing its history.
• Use try when you want a human manual-review guide.

Read Core Workflow for the full lifecycle and command-specific behavior.

Codex uses the matching $skill form. Other adapters use the invocation style shown during installation. Each command has a dedicated page in the documentation.

Two files remain the planning inputs you own:

Blueprint turns those inputs into project state that any installed adapter can read:

This state stays tool-independent. A project can move between supported agents without moving its plan and history back into chat.

Read Writing Your Plans and the File Reference for the detailed contracts.

Blueprint separates several kinds of proof that are easy to blur together:

• Verify command: project-owned type checks, tests, builds, or other repeatable checks.
• Check: observable proof that the current work satisfies its spec.
• Audit: branch-aware review across quality, security, performance, and tests, with focused lenses when needed.
• Independent Audit: a fresh reviewer session inspects an approved checkpoint using the selected installed adapter and model.
• Try guide: a read-only manual walkthrough for human review.

Independent review records the target, permitted base, spec hash, requested and actual reviewer metadata, Check result, commands, evidence, findings, and remaining risk. Relevant later changes make the receipt stale. Adapter, model, and fresh-session identity remain declared metadata, not cryptographic proof.

All quality gates default to manual. Projects can make them conditional or required through blueprint/config.json without granting permission to merge, push, deploy, publish, or waive findings.

Read Code Quality, Audit, and Project Configuration for the complete rules.

Blueprint keeps durable project context available without loading every workflow rule into every Claude Code turn. New installations auto-import only the core project instructions, compact overview, and active spec. Workflow skills load coding standards and interaction rules when they are needed, and implementation uses one feature-level review packet by default.

/overview keeps generated project context below 20,000 bytes, while /doctor flags oversized legacy overviews. A controlled Opus 5 test measured 55% less startup context and about 36% less Feature context after compacting the overview.

Existing projects keep their own CLAUDE.md and configuration during updates. Run /doctor afterward, then follow the updating guide for any recommended cleanup. Read the benchmark for the full method, charts, results, and limits.

Automatic checks are an explicit setup step, not part of installation or onboarding. Run ci when you want Blueprint to define one project-specific Verify command from checks the repository already has and create or align a matching GitHub workflow.

Verify is the recipe. CI runs that same recipe automatically on pull requests and default-branch pushes. Blueprint does not invent a test runner, coverage target, browser suite, security scan, or version matrix just to fill the workflow.

Read CI Setup for the full contract.

The conservative workflow remains the default. Two explicit modes can automate bounded local work while preserving the same gates:

• Autopilot runs one feature or fix through its configured regular gates, then stops before completion.
• Continuous Mode processes reviewed build-plan items serially with one local branch and one local main commit per completed feature.

Neither mode pushes, deploys, publishes, sends messages, performs destructive actions, waives findings, or makes uncovered product decisions.

Read Autopilot and Continuous Mode before using them.

Codex, GitHub Copilot, and OpenCode can share .agents/skills/. Claude Code uses .claude/skills/, which OpenCode can also reuse. The installer avoids duplicating the same skills under .opencode/skills/.

Read Tool Adapters for selection, invocation, and project-layout details.

Use only what the project needs:

• discovery develops detailed plans through a reviewed conversation.
• doctor checks Blueprint health without changing files.
• status reports progress, drift, blockers, and the suggested next action.
• tests adds or normalizes stack-native unit testing.
• browser-tests adds an explicit repeatable browser harness.
• ci aligns one project Verify command with GitHub checks.
• prototype creates throwaway static mockups before the build loop.
• release prepares local Render or Vercel configuration and readiness checks.

The documentation has one page for every command, plus guides for testing, configuration, manual review, updating, and troubleshooting.

Check a Blueprint project without changing it:

npx create-ai-blueprint@latest status

Preview and apply managed workflow updates:

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

An optional global installation exposes the shorter read-only status and local dashboard commands:

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

The dashboard binds to 127.0.0.1, reads the same project files and Git state, and stops when you press Ctrl+C. It does not run workflow commands or expose the project outside the local machine.

Read Updating Blueprint, CLI Status, and Local Dashboard for details.

• Getting Started
• Core Workflow
• Command Reference
• Project Configuration
• Testing
• Manual Review
• Local-Only Mode
• Troubleshooting

• Follow SUPPORT.md for usage questions and reproducible bugs.
• Follow SECURITY.md to report vulnerabilities privately.
• Read CONTRIBUTING.md before opening a pull request.
• Review CHANGELOG.md for published package history.

AI Blueprint is available under the MIT License.