🗺️ Blueprint AI

Agentic project planning powered by Amazon Nova 2 Lite. Turn any project idea into a structured build plan — with phases, code reviews, architecture diagrams, and cloud memory.

What Is Blueprint AI?

Blueprint AI is a persistent CLI agent that lives in your terminal. Describe your project in plain English — it asks the right questions, generates a structured phase plan, reviews your code as you build, and remembers everything across sessions.

One model. One command. Full agentic loop.

npm install -g blueprint-ai
cd your-project-folder
blueprint

Features

| Feature | Description | |---|---| | 🧠 Agentic Planning | Nova asks clarifying questions, then generates 4–7 sequenced build phases | | 🔍 Code Review | Cross-checks your actual code against every phase plan | | 🔄 Phase Reconciliation | Re-plan from any point — completed phases are preserved and archived | | 📊 Architecture Diagrams | Nova generates a Mermaid diagram; rendered to PNG via mermaid.ink | | 🎨 UI Mode | Upload Figma/design images → Nova generates ASCII wireframes + React TSX | | 🗂️ Session Memory | S3-backed cloud memory — pick up exactly where you left off | | 🔎 @history | Ask anything about past sessions in natural language | | 🤖 Agent Prompts | Every phase includes a ready-to-paste prompt for Cursor, Windsurf, Copilot |

Quick Start

1. Prerequisites

• Node.js 18+
• AWS account with Bedrock access (Amazon Nova 2 Lite, us-east-1)
• Tavily API key (free at tavily.com)

2. Install

npm install -g blueprint-ai

3. Configure

Create a .env.local file in your project folder:

AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1
TAVILY_API_KEY=tvly-...

AWS credentials need: AmazonBedrockFullAccess + AmazonS3FullAccess

4. Run

cd your-project-folder
blueprint

Describe your idea. Blueprint AI handles the rest.

Commands

| Command | What it does | |---|---| | @plan | Generate (or reconcile) project phases from your idea | | @review | Review the entire project against all phases | | @review phase 2 | Review a specific phase | | @review login.ts | Review a specific file | | @ui | Upload design images → Nova generates React specs + TSX | | @history | Ask anything about past sessions (@history did we add auth?) | | @progress | Show current phase completion dashboard | | @help | Show quick reference in the terminal | | exit / quit / bye | Save session to cloud and exit |

Plain English — No Commands Needed

Blueprint AI understands natural language. These all work:

"I want to build a food delivery app"
"Generate my project phases"
"I finished phase 2, check my code"
"Upload my Figma mockup"
"Where am I in my project?"
"What did we decide about the database?"
"Re-plan from phase 3 onwards"

How It Works

1. Describe your project — Blueprint AI asks 3–5 clarifying questions
2. Nova generates a phase plan — 4–7 sequenced phases with files, dependencies, and deliverables
3. Architecture diagram — Nova writes Mermaid code → mermaid.ink renders a PNG → saved to .blueprint/diagram.png and embedded in project.md
4. You build Phase 1, then run @review phase 1 — Nova cross-checks your code against the plan
5. Repeat per phase — session history is saved to S3 so you pick up exactly where you left off

The .blueprint/ Folder

Everything Blueprint AI creates lives here:

.blueprint/
├── project.md              ← Your project vision + architecture diagram
├── diagram.png             ← Rendered architecture diagram (PNG)
├── phases/
│   ├── phase-01.md         ← Phase 1 plan + agent prompt
│   ├── phase-02.md
│   └── ...
├── phases-history/
│   └── 2025-03-01/         ← Archived phases after @plan reconcile
│       └── phase-01.md
├── reviews/
│   ├── phase-1-review-2025-03-01.md   ← Timestamped, never overwritten
│   └── phase-2-review-2025-03-02.md
├── ui/
│   ├── screens.md          ← ASCII wireframes + design tokens
│   └── components/
│       ├── Dashboard.tsx
│       └── LoginScreen.tsx
└── progress.md             ← Phase completion status (updated on every review)

Agent Prompts

Every phase file includes a ready-to-paste agent prompt for your coding agent:

@plan → .blueprint/phases/phase-01.md → copy the "Agent Prompt" block
→ paste into Cursor / Windsurf / GitHub Copilot
→ the coding agent builds the phase exactly to spec

Phase Reconciliation

When you run @plan on a project that already has phases:

1. Blueprint AI reads progress.md to find completed phases ✅
2. Completed phases are archived to phases-history/
3. Nova reads the remaining incomplete phases + your new request
4. Generates a smart revised plan — only for work that remains
5. Completed progress is never lost

UI Mode

@ui

1. Enter paths to up to 3 design images (PNG, JPG, WebP)
2. Answer 6 clarifying questions (app type, color theme, component library, etc.)
3. Nova analyzes your designs multimodally
4. Generates: ASCII wireframes, component lists, design tokens, full React TSX code
5. Saved to .blueprint/ui/

Session Memory

Blueprint AI remembers you across sessions:

• Each user gets a persistent UUID (~/.blueprint-ai/config.json)
• Sessions are synced to your private S3 bucket (blueprint-ai-{id})
• When you return, Nova reads your last session summary and greets you with context
• @history did we implement JWT auth? — ask anything about past sessions

Code Review System

@review performs a structured cross-check:

• Completeness — does every planned file/feature exist?
• Correctness — does the code match the specified architecture?
• History — tracks issues across reviews (RESOLVED / RE-FLAGGED / NEW)
• Extra code — flags files outside the plan
• Quality — missing validation, hardcoded values, security issues, no error handling

Severity levels: [HIGH] / [MEDIUM] / [LOW]

Every review is timestamped and saved to .blueprint/reviews/ — never overwritten.

Integrations

| Service | Role | |---|---| | Amazon Nova 2 Lite | All AI responses — planning, review, chat, UI analysis, history | | AWS Bedrock | Hosts Nova via Converse API (streaming + batch) | | AWS S3 | Cloud backup for .blueprint/ + session transcripts | | Tavily | Web search data source — Nova generates all responses from the data |

Note: Tavily only fetches raw data. Nova generates every user-facing response. This ensures all intelligence comes from Amazon Nova.

Environment Variables

# Required
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1
TAVILY_API_KEY=tvly-...

Place this in a .env.local file in your project root. Blueprint AI loads it automatically on startup.

Architecture

Blueprint AI uses a single model (Amazon Nova 2 Lite) in 6 distinct modes:

| Mode | Use | Tokens | Reasoning | |---|---|---|---| | converse | Project intake + Q&A | 1024 | — | | plan | Phase generation | 4096 | ✅ Medium | | review | Code review | 6000 | ✅ Medium | | ui | UI spec generation | 8192 | — | | history | Session Q&A | 2048 | — | | summary | Session summarization + diagrams | 512 | — |

Contributing

Issues and PRs welcome. Built for the Amazon Nova AI Hackathon 2025 — Agentic AI category.

License

ISC © Blueprint AI

Built with ❤️ for the Amazon Nova AI Hackathon 2025 — Agentic AI category.