Blueprint

What is Blueprint?

Blueprint is a planning copilot for coding agents. It helps an agent ask the right questions before writing code, then produces a markdown plan the agent can execute in one pass.

The tool is designed to be agent-agnostic and uses Q&A-driven planning: it explores a codebase and asks multiple-choice questions meant to be easy to answer. The output is meant to surface issues and decisions you might not have considered, structured as a reusable spec/plan.

Key Features

• Q&A planning before code: Blueprint slows down execution just enough to clarify requirements, then generates a structured plan.
• Codebase exploration: It reads your workspace/codebase and uses that context to drive the questions it asks.
• Multiple-choice questions: Questions are formatted so you can answer quickly, while still covering important ambiguities.
• Markdown plan output: The result is a markdown file intended for direct handoff to coding agents.
• Agent-agnostic skills (compatible with skills.sh): Blueprint is packaged as skills compatible with multiple coding-agent harnesses.
• Built-in templates with open-questions sections: Includes default planning templates that define sections like overview, expected behavior, implementation phases, testing strategy, and open questions.

How to Use Blueprint

1. Install the skill using the npx command shown in the repository: npx skills add imbue-ai/blueprint.
2. Start a planning session by invoking the skill in your coding agent with a short task description (e.g., /blueprint Add a caching layer to reduce API calls).
3. Pick a template when prompted. Blueprint explores your codebase and begins asking questions.
4. Answer the questions until Blueprint determines enough ground has been covered.
5. Generate the plan using /blueprint-generate. The plan is written to a path formatted as blueprint/<slug>/plan-<slug>.md.
6. Refine in chat if needed and ask for open questions (e.g., “what are the open questions?”) before handing the plan to your coding agent.

Use Cases

• Greenfield projects / new features: Plan a large new feature while ensuring requirements, expected behavior, and testing strategy are explicitly covered before implementation.
• Incremental change that needs coordination: When a change is big enough to require a careful spec (not just a quick edit), Blueprint can help structure decisions and phases.
• Research and experiments: For new models, systems, or subsystems, Blueprint’s Q&A flow can capture assumptions and unknowns as a plan with open questions.
• Working on an unfamiliar codebase: Blueprint can explore the workspace and ask clarifying questions based on what it finds, reducing the chance of missing key constraints.
• Reducing execution mistakes in agent workflows: If an agent would otherwise “rush to code,” Blueprint provides an explicit plan file the agent can execute after the planning phase.

FAQ

• Which coding-agent harnesses are supported? The repository states it’s compatible with harnesses such as Claude Code, Codex CLI, Gemini CLI, Pi agent, and other compatible harnesses.

• Where does the generated plan get saved? The plan is written to blueprint/<slug>/plan-<slug>.md after running /blueprint-generate.

• What templates does Blueprint include? It ships with two built-in templates by default: Default (sections including overview, expected behavior, implementation plan/phases, testing strategy, and open questions) and Concise (sections including overview, expected behavior, and changes).

• Can I customize the plan structure? Yes. The repository indicates you can describe a custom template inline when prompted, and you can also persistently add/edit templates via templates.json so the two Blueprint skills stay in sync.

• Is Blueprint limited to front-end work? The README’s guidance suggests it’s less ideal for frontends where most decisions are visual, and more suitable for greenfield projects, large new features, and research or subsystem planning.

Alternatives

• Spec or document generators (manual-review style): Tools that produce long specs after the agent makes its own choices can differ from Blueprint by reversing the workflow—Blueprint seeks your input first via Q&A.
• Agent “plan mode” workflows from coding-agent tools: Some agent platforms include their own planning modes; Blueprint is positioned specifically as a planning copilot that generates an agent-executable markdown plan and asks short, requirement-focused questions.
• Generic codebase review assistants: Alternatives may summarize or analyze repositories, but Blueprint’s distinguishing output is a structured markdown plan with defined sections and open questions meant for execution.
• VS Code sidebar workflow using a planning extension: If you prefer editor-integrated tooling, Blueprint is also available as a VS Code extension that works in VS Code, Cursor, and Windsurf, which may differ from purely chat-driven agent setups.