# AI Blueprint

what it does

a process layer you overlay onto an already-scaffolded app, not an app skeleton. the loop:

• you write two files: project-plan.md (the what and why) and build-plan.md (an ordered feature list). that’s the only input you maintain.
• everything else is generated: /overview distills the two plans into a single source of truth, surfacing contradictions as open questions to fix in the plans.
• build one feature at a time: /feature specs the next item and stops at a review gate; /implement builds it step by step, showing and explaining every diff; /complete logs it, commits it as one feature, and squash-merges.
• three gates keep the ai on a leash: spec before code, small reviewable steps, exactly one feature in flight at a time.

why i built it

vibe coding is describing a vague thing and accepting whatever comes back. it’s fast until it isn’t: you end up with code nobody understands and a project that can’t be changed safely. i wanted the opposite, a way to keep the ai genuinely useful while staying in control of a codebase it’s helping me write.

it also solves a quieter problem. when the load-bearing rules of a project live only in a human-readable README, two different ai sessions will re-derive them differently and contradict each other. the blueprint encodes those rules where agents actually read them. it’s the same workflow that underpins my Coding With AI course, extracted into something anyone can drop into their own repo.

how it’s built

a quick tour:

• AGENTS.md is the canonical entry: the open cross-tool standard read by Codex, Cursor, Copilot, Gemini CLI, Aider, and 20+ others. CLAUDE.md slims down to import it plus the context/ auto-loads, so there’s one source of truth, not two.
• single-purpose skills: /overview, /feature, /fix, /implement, /complete, /prototype, plus /adopt (onboard an existing repo), /status (orient after a context clear), and /check (run the app against a feature’s done-whens), each a plain-markdown SKILL.md. distinct verbs over subcommands, chosen for learnability.
• scaffold then install: scaffold the app in an empty dir, then run npx create-ai-blueprint@latest. the installer lets you pick Codex, Claude Code, or both, then drops only the workflow files your app needs.
• the feature is the unit of history: /implement offers optional per-step checkpoints on a branch; /complete makes the one real feature commit and squash-merges, so main stays one clean commit per feature no matter how many checkpoints accumulated.
• testing is a gate, not a dependency: the blueprint installs no test runner. declare a test command in AGENTS.md and tests gate logic-bearing steps; declare nothing and logic still rides on screenshot plus build. the shared layer names no framework, so a go project and a typescript project use the same docs.
• one blueprint/ folder: the two hand-written plans sit at its root where you look; everything the ai manages lives in context/ and history/ under it. only CLAUDE.md, AGENTS.md, and .claude/ stay at the repo root, because that’s where tools read them, so the overlay never collides with your app’s boilerplate.

what’s next

it’s public, has a real site at ai-blueprint.dev, and the docs now lead with the control loop instead of a pile of internal skill details. the next move is using it in public: the workflow is the spine of the Coding With AI course and the reference process for newer projects like PortDoc and AI Skills Directory.

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