AI Blueprint — brad traversy

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
spec before implementation: /feature, /fix, and /rollback write the active spec, then stop for review
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
audit before merge: /audit records findings with durable IDs and severities, 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
/overview
/feature or /fix or /rollback
/implement
/check
/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.

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.

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; both share the same workflow model
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/
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 and installed blueprint/README.md explain the loop, gates, rollback path, audit ledger, testing gate, and release prep

The updater is intentionally narrow. It manages skill files and the installed workflow README. It preserves AGENTS.md, CLAUDE.md, 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
/overview: turn plans into project context
/feature: spec the next planned feature
/fix: spec an unplanned bug or small change
/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 code quality, security, performance, tests, and drift
/complete: archive, commit, merge, and log with approval

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
/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 next work is less about the idea and more about hardening it through real projects: better examples, more e2e scenarios for the gates, clearer docs for findings and rollback, and using it as the reference workflow for newer builds like PortDoc, SkillPass, and ApiMocker.

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

Explorer

# AI Blueprint