AI-powered CLI tool that turns vague ideas into executable blueprints through a 6-phase pipeline.

You give it an idea. It asks smart questions, researches the domain, drafts a structured blueprint, reviews every point with you, analyzes its own process for improvements, then hands off a ready-to-execute plan.

Idea → Discovery → Research → Draft → Clarify → Analyze → Execute

1. Discovery — Adaptive questioning across 8 categories (scope, users, problem, constraints, technical, success criteria, risks, prior art). Builds a confidence score per category and stops when coverage is sufficient.

2. Research — Takes discovered requirements and runs web searches to find best practices, existing solutions, and technical context. Stores findings in an embedded vector database (LanceDB) for retrieval.

3. Drafting — Synthesizes requirements + research into a structured YAML blueprint with phases, steps, acceptance criteria, dependencies, risks, and verification criteria. Validated against a Zod schema.

4. Clarification — Maker-checker review. Walks through the blueprint section-by-section, presenting concerns and suggestions. You decide: keep / modify / remove / expand. Up to 3 revision rounds.

5. Meta-Analysis — Quantifies the session: questioning efficiency, research relevance, clarification rate. Generates insights and prompt improvements that feed into future sessions.

6. Execution Handoff — Packages the final blueprint with meta-insights, suggested approach, and complexity estimate. Ready for an execution agent or human team.

git clone https://github.com/Kitolochi/blueprint-agent.git
cd blueprint-agent
npm install
npm run build

# Required
export ANTHROPIC_API_KEY=sk-ant-...

# Optional — enables semantic vector search (falls back to hash embeddings without it)
export VOYAGE_API_KEY=pa-...

# New session
node dist/index.js "Build a real-time chat app"

# Custom output directory
node dist/index.js -o ./my-project "E-commerce API"

# Use Opus model for complex projects
node dist/index.js -m opus "Distributed event sourcing system"

# Set a spending cap
node dist/index.js --cost-limit 10.00 "Large enterprise project"

# Resume an interrupted session
node dist/index.js --resume ./blueprint-output/session_abc123/ledger.json

Each session produces a directory with:

blueprint-output/session_xxx/
├── ledger.json              # Full session state (resumable)
├── blueprint-draft.yaml     # Initial draft
├── blueprint.yaml           # Final blueprint after clarification
└── vector-db/               # Research findings (LanceDB)

The output is a structured YAML file:

version: "1.0.0"
metadata:
  title: "Real-time Chat App"
  sessionId: "session_abc123"
overview:
  problem: "Teams need instant communication..."
  goal: "Build a WebSocket-based chat application..."
  constraints:
    - "Must support 10k concurrent users"
phases:
  - name: "Foundation"
    order: 1
    steps:
      - title: "Set up project scaffolding"
        description: "..."
        acceptanceCriteria:
          - "Project builds without errors"
        estimatedEffort: "4 hours"
risks:
  - description: "WebSocket scaling under load"
    likelihood: medium
    impact: high
    mitigation: "Load test early, plan for horizontal scaling"
verification:
  smokeTests:
    - "Two users can exchange messages in real-time"
  acceptanceCriteria:
    - "All phases completed and verified"

• State-based handoff — Each agent reads/writes a JSON ledger on disk. No agent receives previous agents' conversation history. Enables resume after interruption and keeps token usage controlled.
• Anthropic Claude API — Direct SDK calls with tool_use for structured agent conversations.
• LanceDB — Embedded vector database for research findings. No external server needed.
• Voyage AI — Semantic embeddings with deterministic hash fallback for development.
• Ink + React — Terminal UI with phase-specific views and progress indicators.
• Self-improving — Meta-analysis results persist across sessions. The orchestrator reads past improvements and adjusts agent prompts at startup.

# Type check
npm run lint

# Run tests (55 tests across 4 suites)
npm test

# Watch mode
npm run test:watch

# Build
npm run build

MIT