Getting Started

What Blueprint adds

AI Blueprint is an AI coding workflow framework for an application you already scaffolded. It adds durable planning files, focused agent skills, and review gates without adding application code or replacing your application framework.

Blueprint is not an app starter. Choose your language, framework, architecture, and infrastructure first.

Fresh project setup

1. Scaffold the application

Use the stack that fits the project. Astro is only an example.

npm create astro@latest my-app
cd my-app
git init # if the scaffolder did not create a repository

2. Install Blueprint

Run the installer inside the application directory.

Choose the command for your project’s package manager:

# npm
npx create-ai-blueprint@latest

# pnpm
pnpm dlx create-ai-blueprint@latest

A project that enforces pnpm through devEngines.packageManager can reject npx with EBADDEVENGINES before Blueprint starts. Use pnpm dlx in that project; do not remove its package-manager requirement.

The remaining npx create-ai-blueprint@latest examples also work with pnpm dlx create-ai-blueprint@latest, keeping the same command and options.

The interactive installer shows Codex, Claude Code, and GitHub Copilot in a checkbox list. Google Antigravity and OpenCode are available too. Codex and Claude Code are selected by default. Keep those choices or select another combination. The installer adds only the compatible adapter files the selected tools need.

It also creates blueprint/.state/manifest.json, which lets later updates distinguish unchanged Blueprint-owned files from local modifications.

Before copying, the installer checks its destinations and stops on symbolic links, incompatible file types, or a target below a regular file. Resolve the reported path and rerun the installer; it does not partially copy Blueprint around that conflict.

Interactive setup also offers to install the optional Blueprint CLI, which provides the blueprint command for project status checks and a live local dashboard.

3. Onboard the project

Run $onboard in Codex or /onboard in Claude Code. Google Antigravity also uses /onboard. In GitHub Copilot or OpenCode, ask the tool to run the onboard skill. It inspects the real stack, commands, and coding conventions. It also checks adapters, ignore rules, and project configuration alongside any existing verification or CI. It reports the current checks without creating new CI or enabling automatic quality gates.

New installations default to one feature-level implementation review and no step checkpoint prompts. If you want the previous experience, set workflow.stepReview to every and workflow.checkpointCommits to enabled. Changing only stepReview restores the per-step approval pauses, not the checkpoint prompts.

New installations also default tryGuide to when-testable. Testable features finish with one compact Try It Now proof, while documentation-only and invisible internal changes do not get invented instructions. Existing projects keep their user-owned configuration when updated.

Onboarding presents that choice as Efficient or Guided, with Custom for selecting each setting separately. These are shortcuts that write the existing low-level values, not permanent modes. You can change either setting later. Every style retains the final read-only code walkthrough option.

Optional: add automatic GitHub checks

Run $ci in Codex or /ci in Claude Code when you want one project-specific Verify command and a matching GitHub Actions workflow. The skill uses only checks that already exist, proves the recipe locally, and stops before push or remote ruleset changes.

You can skip this setup and continue planning. See Testing and CI for the full model.

4. Write the two plans you own

Fill in blueprint/project-plan.md with as much product detail as the project needs, then write blueprint/build-plan.md as a short ordered feature list. Plain bullets or numbered lines are fine; Overview adds tracking checkboxes. These are the inputs you continue to own. See Writing Your Plans for worked examples of both.

You can write the plans directly or develop them through any AI conversation. If you want guided help, run $discovery in Codex or /discovery in Claude Code. Discovery is optional, can span as many turns as needed, and writes only after you review and explicitly approve both drafts.

5. Generate project context

Run $overview in Codex or /overview in Claude Code. It formats clear feature lists while preserving scope, order, IDs, and completion state, and asks before making semantic plan changes. Review the generated blueprint/context/project-overview.md before building. Overview keeps this durable project context below 20,000 bytes so workflow skills can load it on demand without carrying a detailed copy of both plans. On an eligible initial run, Overview offers a reviewed local commit for the Blueprint setup and plans before Feature 1. It asks first, skips local-only installations, and refuses to include unrelated application changes.

The shortest successful loop

Once setup is complete, repeat this sequence for each feature:

/feature -> review -> /implement -> /check -> /complete

The skills stop at important boundaries. They do not merge, push, deploy, publish, or send anything without the approval required by the workflow.

When you explicitly want Blueprint to continue through the remaining build plan, run $continuous or /continuous. It repeats the local feature lifecycle with one branch and one local main commit per feature, and it never pushes. See Continuous for its stopping conditions and Project Configuration for its limits and gates.

When a Verify command is configured, implementation and completion use that same recipe. GitHub Actions runs it automatically after the workflow is published.

If a completed feature later needs to be removed, follow the reviewed Rollback command instead of rewriting git history or deleting the feature by hand.

Already have a codebase?

Use the existing codebase guide instead of onboarding as a fresh project. Adoption surveys the working repository and accounts for features that are already shipped.

Keep the workflow current

Use the Updating Blueprint guide when you want newer skills and workflow documentation. The updater preserves plans, project context, history, and project entry files.

Learn the everyday loop

/feature -> /implement -> /check -> /audit current -> /complete

Run these in AI chat, using $ instead of / in Codex. Review the feature spec before implementation. Check exercises the promised behavior; Audit reviews the implementation. Showing Audit here does not change your configured review gates.

Unsure whether an idea belongs in the plan? Start with /explore. Use /status to resume work and /fix for a confirmed small unplanned change. The command guide groups the full command set by purpose.