Getting Started

What Blueprint adds

AI Blueprint is a workflow overlay for an application you already scaffolded. It adds durable planning files, focused agent skills, and review gates without adding application code.

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.

npx create-ai-blueprint@latest

The interactive installer shows Codex, Claude Code, GitHub Copilot, and OpenCode as a checkbox list with all four selected by default. Keep one or more tools selected and it adds only the compatible adapters they need.

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

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, /onboard in Claude Code, or ask GitHub Copilot or OpenCode to run the onboard skill. It inspects the real stack, commands, coding conventions, adapters, ignore rules, project configuration, and any existing verification or CI. It reports the current checks without creating new CI or enabling automatic quality gates.

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 turn blueprint/build-plan.md into a short ordered checkbox list. 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. Review the generated blueprint/context/project-overview.md before building.

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.