idea-to-blueprint

An agent skill for Claude Code, Codex and claude.ai

Tell it once.
Build it right.

Two paragraphs of raw idea go in. One evidence-backed build blueprint comes out. Then your coding agent ships it, epic by epic, without guessing.

Get the skill View on GitHub

Numbers from a real run. Read the full output ›

Your agent isn't hallucinating.
It's guessing.

A coding agent starts every session knowing exactly two things: your repo and your prompt. Everything you left out, it fills with something plausible. Each guess looks fine on its own. Together they add up to a product nobody designed.

GUESS 01

It guesses the stack.

Whatever it reaches for first. A version from its training data. An API that was renamed a year ago.

GUESS 02

It guesses the spec.

What happens when the payment fails twice? When two people edit at once? You never said. So it decided.

GUESS 03

It guesses the words.

Every button, every error, every empty state, improvised on the spot. A different voice on every screen.

So we asked a different question.

What if it never
had to guess?

Introducing idea-to-blueprint

A researcher. An architect. A product manager.

These are not three hires.
This is one command.

❯/idea-to-blueprint
01 · RESEARCHER

It reads the web so your agent doesn't have to remember it.

Live research before a single decision is made.

  • 20 to 60 searches per product
  • 5 to 10 competitors, benchmarked
  • Versions verified and pinned
  • Every source logged with a date
02 · ARCHITECT

It decides. It doesn't hedge.

"Use X or Y" hands the decision to an agent with less context than you have now.

  • Ranked, measurable architecture drivers
  • Shape first, tools second
  • Every choice names its runner-up
  • One deterministic check gate
03 · PRODUCT MANAGER

It writes down everything. Everything.

Nothing is left for a build session to infer.

  • Personas, flows, every screen
  • Every user-facing string, by ID
  • Epics → stories → Given / When / Then
  • Tests and a Definition of Done per epic

How it works

Four steps.
Idea to production.

STEP 01

Say it.

Two lines or two pages, in your own words and your own language. The skill does a quick warm-up search, then asks one batch of questions. Every question has a default. Answer defaults and move on.

❯ /idea-to-blueprint a QR menu for restaurants.
  guests order from the table and pay online.

Before I research, 8 quick questions.
Reply "defaults" to accept them all.

1. Who pays you: the restaurant or the guest?
   default: restaurant, monthly
2. I found three products in this space.
   Which is closest to what you mean? …
STEP 02

Sign off.

After the research you get a one-screen decision brief: how it read your idea, the personas, the architecture, the locked stack, the epic list. Reply go, or correct any line. Then it writes the blueprint, section by section, and lints it.

## Decision brief
Drivers   AD-1 order placed in under 3 taps
          AD-2 works on a weak connection
Shape     modular monolith
          beat: microservices. revisit at AD-4
Stack     locked, versions pinned, verified
Epics     E00 Foundation · E01 Menu · E02 …

Reply "go" to write the full blueprint.
STEP 03

See it.

Before any production code, have a frontier model turn the blueprint into a single clickable .jsx prototype. Every screen. Every flow. The real copy. If something feels wrong, you fix the blueprint, not the code.

❯ Read docs/BLUEPRINT.md. Build ONE file,
  prototype/Prototype.jsx: a clickable
  prototype of the whole product.

  Every screen SCR-nn. Every flow F-nn.
  Exact strings from the copy tables CP-*.
  Mock data inline. No backend.
STEP 04

Ship it.

Open a fresh session. Type five words. The agent orients itself from the repo, plans, writes the tests first, builds story by story, reviews its own diff, and hands off in writing. Close the session. Open a new one. Next epic.

❯ plan then build epic 0

✓ Orient    preconditions met, check green
✓ Plan      5 stories, 23 tests
✓ Build     tests first, one commit per story
✓ Verify    gate green, DoD walked with evidence
✓ Handoff   PROGRESS.md updated

Safe to terminate this session.

Inside the blueprint

One file.
The product's only memory.

It isn't a PRD in the loose sense. It's the single document shared by you, the research, and every future build session. A hundred pages is normal. Every line has an ID, so a fresh session finds anything by search.

22
sections, from research to session prompts
21
categories of edge cases, checked per story
20–60
live web searches behind a full product
0
facts written from memory and passed off as true
### E03-S02 — Request OTP by phone
Persona P1   Flow F-02   Screen SCR-04

AC-1  Given a valid phone number
      When P1 taps CP-SCR04-2
      Then an OTP is sent within 10 s and SCR-05 opens
AC-2  Given 3 requests within 10 minutes
      When P1 requests a 4th
      Then the request is refused with CP-SCR04-7

Edge cases  EC-AUTH-03 · EC-MSG-01 · EC-NET-02
Tests       T-E03S02-1 … T-E03S02-5   (must fail before the code exists)
[VERIFIED — S-14, 2026-09-18]

Checked today, with a source.

Versions, competitors, prices, service availability. If it's a claim about the outside world, it carries a receipt.

[ASSUMED — why]

An assumption, labelled as one.

Every question you skipped becomes a row in the Assumptions table. You can see exactly what was decided for you.

[UNKNOWN → OQ-07]

Not known. Not invented.

Routed to Open Questions with an owner. The linter fails the document if an unknown has nowhere to go.

"I don't know" is always an acceptable answer. A confident wrong one never is.

Why it works

Think once.
Build many.

Yes, it's waterfall. On purpose. For humans, big upfront design is slow to write. For agents, writing is nearly free, and ambiguity is the expensive part: an agent never pushes back on a vague spec. It just guesses. So all the thinking happens once, with full context, in the strongest model you have. After that, every session has one job: execute one well-specified epic.

Orient→Plan→Build→Verify→Handoff→Terminate

One epic per fresh session. Long sessions drift. The repo doesn't.

Vibe coding is a conversation.
Agentic engineering is a contract.

Vibe coding
With a blueprint
Source of truth
The chat history
The repo: BLUEPRINT, PROGRESS, DECISIONS
Unknown facts
Filled with something plausible
Tagged verified, assumed or unknown
The stack
Whatever the model reaches for
Derived from drivers, verified, pinned
"Done" means
It seems to work
Evidence per criterion, gate green, diff reviewed
UI text
Improvised per screen
Copied by ID from the copy tables
A wrong spec
Silently worked around
A logged amendment. Never a silent change

One more thing.

See the whole product before you build any of it.

Because the blueprint already contains every screen, every flow and every word, a frontier model can turn it into one clickable file in a single pass. You hold the product in your hands on day one. Changing your mind here costs minutes. In epic six, it costs days.

3 epics.
One day.

That's the author's own pace, working from a blueprint this skill produced, with Claude Code and Codex, one fresh session per epic. Yours depends on epic size and the model you run.

Get started

One line to install.

npx skills add iniesohidham/idea-to-blueprint -g

Installs for Claude Code, Codex, Cursor and every other agent the skills CLI finds on your machine.

Turn web search on.

The skill verifies versions, competitors and services live. Without web access it will tell you it can't meet its own bar.

Use your strongest model.

Highest effort setting, for the blueprint and for the build sessions. The blueprint is where model quality pays off most.

Stop prompting.
Start specifying.

Get it on GitHub Read the docs