Discovery

When to use it

Run $discovery in Codex or /discovery in Claude Code when you want a guided, multi-turn conversation before writing or revising the two Blueprint plans.

Discovery is optional. You can always write detailed plans directly, develop them through any AI conversation, and continue to $overview or /overview. Onboarding never starts Discovery automatically, and Overview never requires it.

The command is included in create-ai-blueprint@0.7.0 and later releases.

How the conversation works

Discovery begins by reading the existing planning files and a small amount of relevant project context. It preserves substantive plan content instead of replacing it with a generic draft.

The agent then asks one focused question at a time. Each answer shapes the next question, so the conversation can follow important decisions instead of moving through a fixed questionnaire. It can explore:

• The problem, desired outcome, and target users
• Primary workflows, MVP scope, non-goals, and later ideas
• Business rules, data, integrations, permissions, and edge cases
• Stack choices, constraints, risks, and technical unknowns
• UI/UX direction, accessibility, monetization, and deployment
• Feature boundaries, dependencies, and build order

There is no fixed question count. Discovery periodically summarizes confirmed decisions, assumptions, open questions, and deferred ideas so a long planning conversation stays coherent.

The plan-writing gate

Discovery does not write either planning file while interviewing you. When you say the project is ready to draft, it first presents complete proposed contents for both files:

• project-plan.md preserves the depth, rationale, constraints, examples, edge cases, and exclusions that should guide later features.
• build-plan.md remains a high-level, numbered checklist of feature-sized outcomes. Detailed implementation belongs in later /feature specs.

Review the drafts and request any changes. The agent writes them only after you explicitly approve the proposed contents. Existing plan decisions and completed build-plan numbering are preserved unless you approve a change.

What it never does

Discovery does not scaffold the application, edit product code, generate the project overview, create a feature spec, commit, merge, push, or deploy. It never makes itself a prerequisite for another Blueprint command.

Next step

Edit or deepen the plans directly for as long as you need. When both files reflect the project you want to build, run $overview or /overview to validate them and generate blueprint/context/project-overview.md.