# AI Blueprint

what it does

AI Blueprint is a process layer you install into an existing app. It is not a framework starter and it is not another “generate the whole app” prompt. You scaffold the app first, then install the workflow:

npx create-ai-blueprint@latest

The point is to make the AI useful inside a controlled loop:

• plan before context: you maintain blueprint/project-plan.md and blueprint/build-plan.md
• context before code: /overview turns those plans into the AI-facing project overview and stops on open questions
• optional discovery before plans: /discovery can help draft the plans and waits for approval before writing them
• spec before implementation: /feature, /fix, and /rollback write the active spec, then stop for review
• diagnosis before repair: /debug reproduces and isolates failures without editing the project
• small reviewed steps: /implement builds one step at a time, shows the diff, proves the done-when, and waits for approval
• proof before closeout: /check verifies the spec against the real app, and /try gives the human review path
• browser proof when ui matters: /browser-tests adds a project-specific browser automation command that Feature, Check, and Continuous Mode can use
• audit before merge: /audit records findings with durable IDs and severities, supports focused quality, security, performance, and tests lenses, and /complete refuses to merge while P0 or P1 findings still need review
• release is separate: /release render and /release vercel prepare local config and smoke checks, but do not deploy without a separate yes

That is the whole product: a file-backed control system for AI-assisted building.

the gates

The current loop is stricter than the first version of the project:

/onboard
/discovery
/overview
/feature or /fix or /rollback
/debug when something is failing
/implement
/check
/browser-tests when UI proof matters
/try
/audit
/complete
/release

/onboard adapts the installed files to the actual repo. /doctor checks the setup without changing anything. /brief previews the next feature before a spec is written. /status helps recover after a context clear.

/discovery is optional. It is for the early conversations where the product is still fuzzy and the plans need help becoming concrete. It drafts the plans, shows them for review, and writes them only after approval. Manual plans still work exactly the same way.

/debug is read-only by design. It follows a failing test, broken build, runtime error, or unexpected behavior until it has evidence, then hands actual repair work to /fix or /implement.

The merge gate is the important part. /complete does not just commit whatever the assistant changed. It checks the active spec, archived history, git state, and audit ledger. P0 and P1 findings have to be closed by review, not merely patched by the same agent that found them. Push and deploy remain separate explicit approvals.

Continuous Mode keeps that same shape, but lets a project opt into a local one-feature-at-a-time run. It can move through planning, implementation, checks, and audit work, but it still follows the project’s policy and never pushes, deploys, publishes, sends email, or does destructive work on its own.

Rollbacks use the same discipline. /rollback finds the archived feature and the commit that introduced it, checks later dependency risk, writes a guarded rollback spec, and then goes through /implement, /check, and /complete. It does not rewrite history or delete the original feature archive.

why i built it

Vibe coding is describing a vague thing and accepting whatever comes back. It is fast until it is not: you end up with code nobody understands and a project that cannot be changed safely.

AI Blueprint is my answer to that. The assistant can still plan, build, inspect, and iterate, but it has to do that inside a written workflow with review gates. The human still owns the plan, the scope, the product decisions, and the final approval.

It also solves the context problem. A long chat thread is not project memory. The Blueprint stores the plan, generated context, active work, findings, and history in markdown files the next AI session can read.

how it’s built

a quick tour:

• installer package: create-ai-blueprint installs the workflow after an app has already been scaffolded
• tool adapters: Codex uses .agents/skills; Claude Code uses .claude/skills; GitHub Copilot reads the shared AGENTS.md; OpenCode is an explicit adapter choice while reusing compatible skill trees
• AGENTS.md entrypoint: cross-tool instructions live where modern coding agents already look
• blueprint folder: plans, generated context, current work, findings, and history live under blueprint/
• status CLI: blueprint status gives a read-only snapshot of current work, findings, Git state, drift, completion readiness, and next actions
• local dashboard: blueprint dashboard opens a read-only browser view over the same project status and workflow state
• project config: the workflow records allowed checks, browser-test commands, and the automation policy for regular commands and Continuous Mode
• managed updates: blueprint/.state/manifest.json tracks managed file hashes so updates can report conflicts instead of overwriting local changes
• command docs: the public site explains the loop, gates, rollback path, audit ledger, testing gate, adapter model, status CLI, and dashboard

The updater is intentionally narrow. It manages skill files and the installed adapter state. It preserves AGENTS.md, CLAUDE.md, project READMEs, plans, context, history, references, and prototypes unless you explicitly choose otherwise.

command map

Core build loop:

• /onboard: adapt the Blueprint to a fresh or early project
• /adopt: bootstrap planning from an existing codebase
• /discovery: turn a planning conversation into reviewed plan drafts
• /overview: turn plans into project context
• /feature: spec the next planned feature
• /fix: spec an unplanned bug or small change
• /debug: diagnose a failure without changing project files
• /implement: build the active spec in reviewed steps
• /check: prove the done-whens against the real app
• /try: write the manual test path for a human reviewer
• /audit: review broadly, or focus on quality, security, performance, or tests
• /complete: archive, commit, merge, and log with approval
• /continuous: run the same loop locally under the project’s automation policy

Supporting commands:

• /doctor: read-only setup health check
• /brief: preview scope before writing a spec
• /tests: add the stack-native unit test runner and turn on test gates
• /browser-tests: add the stack-native browser test runner and turn on UI gates
• /rollback: plan a reviewed reversal of a completed feature
• /release: prepare Render or Vercel readiness without deploying
• /prototype: explore static mockups before implementation
• /status: recover orientation after a context clear
• /autopilot: explicit opt-in bounded pass that still stops before closeout

what’s next

AI Blueprint is public, installable, and documented at ai-blueprint.dev. The package is now create-ai-blueprint@1.1.0, with Debug, focused Audit lenses, Discovery, a read-only status CLI, a local dashboard, browser-test setup, Continuous Mode, GitHub Copilot and OpenCode support, multi-adapter installs, package smoke checks, and the core build loop documented in the public repo.

The next careful step is making the automation feel useful without making it casual. Continuous Mode should stay boring, local, and reversible, while browser tests give visual apps a better way to prove that the work actually holds up.

the point was never to type less. it is to stay in control of a codebase the ai is helping you write.