aiblueprinthq/ai-blueprint

AI Blueprint – A file‑backed workflow for AI‑assisted coding

What it is – AI Blueprint is a framework that sits on top of any existing codebase and gives large‑language‑model (LLM) coding assistants a structured, file‑driven workflow. It does not replace your application framework; instead it records the planning, specification, verification and review steps that an AI agent (e.g., OpenAI Codex, Anthropic Claude Code, GitHub Copilot, Google Antigravity, OpenCode) should follow.

Why it matters – When AI generates code directly in chat, the intent, evidence of correctness, and review history often disappear. Blueprint makes those artifacts permanent files (specs, findings, audit records, history) that live alongside your source code and are version‑controlled with Git.

---

Core concepts

Concept	How it works
Project‑plan & build‑plan	Human‑written markdown files (blueprint/project‑plan.md, blueprint/build‑plan.md) that describe product direction and an ordered feature list.
Context files	Generated from the plans: project‑overview.md, current‑feature.md, findings.md, review.md. All adapters read the same files, so you can switch between Codex, Claude, etc.
Workflow commands	Five primary steps, each exposed as a chat skill (/feature, /implement, /check, /audit, /complete). The commands create or update the context files and optionally pause for human review.
Dashboard	A local, read‑only web UI (blueprint dashboard) that visualises the roadmap, active work item, findings and Git state in real time.
Git integration	Blueprint records each completed work item as a single commit (or a pull‑request branch) and can enforce gates such as independent review before merge.

---

Typical workflow (quick‑start)

1. Scaffold your app (e.g., npx create‑next‑app my‑app).
2. Initialize Git and install Blueprint:

   npx create‑ai‑blueprint@latest   # or pnpm dlx …
   

3. Onboard – run the onboard skill so Blueprint learns your stack, commands and preferred adapters.
4. Write plans – edit blueprint/project‑plan.md and blueprint/build‑plan.md (or generate them via the optional discovery skill).
5. Overview – run overview to turn the plans into durable context files and get a tracked checklist.
6. Feature cycle – for each item:
   • feature → creates a spec and waits for your approval.
   • implement → builds the spec in small, visible steps and offers a walkthrough.
   • check → runs the real application against the spec to prove acceptance.
   • audit → records any findings; unresolved P0/P1 block completion.
   • complete → runs final gates, archives the work, and asks for merge/pull‑request approval.

---

Supported AI adapters

• Codex (OpenAI)
• Claude Code (Anthropic)
• GitHub Copilot
• Google Antigravity
• OpenCode
• Any other “file‑aware” coding agent that can read the Blueprint markdown contracts.

---

Key features

• Spec‑first development – agents must produce a reviewed specification before writing code.
• File‑backed state – all specs, findings, audit records and history live as plain markdown files in the repo.
• Human‑in‑the‑loop gates – configurable review policies (manual, when‑sensitive, etc.) and explicit approval steps for merges, deployments, and destructive actions.
• Parallel work support – encourages separate Git worktrees/branches for concurrent agents.
• Live local dashboard – visual overview of roadmap, active work, and audit status.
• Extensible CLI – npx create‑ai‑blueprint@latest <command> (e.g., dashboard, status, doctor).
• CI integration – ci command can generate a GitHub Actions workflow that runs the same Verify command used locally.

---

Who should use it

• Teams that already rely on LLM coding assistants and want reproducible, auditable development.
• Projects where regulatory or security concerns demand documented specs and independent review.
• Solo developers who want a disciplined “AI‑pair‑programming” workflow without changing their existing stack.

---

Maturity & ecosystem

• Package – published on npm as create-ai-blueprint (latest version badge shown in the README).
• Docs & demo – official site (ai‑blueprint.dev), full documentation, and a YouTube demo video.
• CI status – GitHub Actions badge indicates a validation workflow runs on each push.
• License – MIT, allowing commercial and private use.
• Community – No explicit mention of a community forum, but the repo includes a changelog, release page and issue tracker for feedback.

---

Quick takeaways

• AI Blueprint is not a new programming language or AI model; it is a workflow layer that makes AI‑generated code traceable and reviewable.
• It works with any tech stack because it only manipulates markdown files and Git.
• The approach is spec‑driven, file‑backed, and human‑centric, aiming to keep product intent visible and verifiable while still leveraging AI coding agents.