Blueprint

Product Introduction

1. Definition: Blueprint is an open-source planning copilot and agentic skill framework designed to orchestrate the software development lifecycle (SDLC) for AI coding agents. Technically, it functions as a pre-coding diagnostic and specification tool that integrates via the "skills.sh" protocol or as an IDE extension for Cursor, Windsurf, and VS Code. It bridges the gap between high-level human intent and low-level code execution by generating structured, grounded implementation plans.

2. Core Value Proposition: Blueprint exists to solve the "hallucination and haste" problem inherent in modern coding agents like Claude Code or GitHub Copilot. Instead of allowing an agent to rush into writing code based on ambiguous prompts, Blueprint forces a "stop-and-think" phase. It uses codebase exploration and interactive multiple-choice questioning to surface hidden technical debt and architectural requirements. This ensures that the final output—a comprehensive Markdown plan—can be executed by an AI agent in a "one-shot" manner, significantly reducing iterative debugging and wasted tokens.

Main Features

1. Grounded Contextual Questioning: Unlike generic LLM prompts, Blueprint performs a deep read of the local codebase to identify specific areas of ambiguity. It generates targeted, multiple-choice questions that address technical edge cases, dependency conflicts, and architectural preferences. This feature utilizes an iterative feedback loop where the user’s answers inform subsequent probes, ensuring the planning agent understands the unique constraints of the existing repository.

2. Agent-Agnostic Skill Integration: Blueprint is built on the skills.sh standard, making it compatible with a wide array of agent harnesses including Claude Code, Codex CLI, Gemini CLI, and Pi agent. It operates through simple terminal commands (e.g., /blueprint and /blueprint-generate), allowing it to be injected into any agentic workflow as a modular tool rather than a locked-in platform.

3. Structured Plan Generation and Templates: The tool converts user input and codebase analysis into a standardized Markdown plan. Users can choose from built-in templates such as "Default" (covering implementation phases, testing strategies, and open questions) or "Concise" (focusing on expected behavior and specific changes). Furthermore, Blueprint supports custom JSON-based templates, allowing engineering teams to enforce internal documentation standards for all AI-generated code.

Problems Solved

1. Pain Point: Premature Code Execution and Agent Drifting. Coding agents often "guess" at implementation details when faced with vague instructions, leading to code that technically runs but violates project architecture or misses key requirements. Blueprint addresses this by decoupling the "planning" and "coding" phases, ensuring the agent has a verified roadmap before a single line of code is modified.

2. Target Audience: Software Engineers, Technical Architects, and AI Tooling Developers. It is particularly valuable for senior developers managing "agentic" workflows who need to ensure that AI-generated PRs meet quality standards, and for developers using AI-first IDEs like Cursor or Windsurf who want more control over the agent's decision-making process.

3. Use Cases:

• Greenfield Project Scaffolding: Defining the initial architecture and tech stack for a new repository.
• Complex Feature Expansion: Adding sophisticated layers (e.g., caching, authentication) to existing large-scale codebases where manual planning is time-consuming.
• Research and Prototyping: Rapidly iterating on new system designs where the trade-offs are not yet fully understood.
• Technical Debt Reduction: Planning large refactors where the agent must account for numerous interconnected dependencies.

Unique Advantages

1. Differentiation (Input-First vs. Review-Later): Most specification generators (like Spec-kit) ask the agent to write a long document which the human then reviews. Blueprint reverses this order. It prioritizes human input at the start of the process through granular questions, ensuring the agent's internal model is aligned with the user’s mental model before the plan is even drafted.

2. Key Innovation: The "Open Questions" surfacing mechanism. Blueprint is specifically engineered to identify what it does not know. By explicitly listing "Open Questions" in the generated plan, it prevents the silent failure of coding agents where they would otherwise make a "best guess" that results in technical debt.

3. Multi-Modal Availability: Blueprint offers the flexibility of a CLI tool for automation-heavy workflows and a visual sidebar extension for VS Code/Cursor users, catering to both terminal-centric and IDE-centric developer preferences.

Frequently Asked Questions (FAQ)

1. Is Blueprint compatible with Cursor and Windsurf? Yes, Blueprint is available as a dedicated extension for Cursor, Windsurf, and VS Code. It can also be added as an agent skill via npx to be used within the terminal-based agent interfaces of these editors.

2. How does Blueprint differ from the "Plan Mode" in Claude Code? While Claude Code's plan mode is optimized to unblock the agent quickly with brief questions, Blueprint focuses on a deeper understanding of the user's intent. It asks more comprehensive questions to "catch what you didn't think to think about," making it better suited for complex architectural changes rather than simple bug fixes.

3. What file formats does Blueprint generate? Blueprint generates structured Markdown files, typically stored in a blueprint/ directory within your project. This format is easily readable by both humans and AI agents, making it a perfect hand-off document for execution.

4. Can I customize the planning templates in Blueprint? Yes. Blueprint allows for persistent template customization by editing a templates.json file. You can define specific sections such as "Security Requirements," "Database Schema Changes," or "Performance Metrics" to ensure the AI agent follows your team's specific planning criteria.