⚡ Vibe Coding Blueprint

From a messy idea in your head → a build-ready roadmap your AI coding tool can actually execute.

A reusable, repeatable system for turning any idea into a build-ready software roadmap — using an AI collaborator as a thinking partner, not just a code generator.

Stop vibe-coding blind. 10 phases + a skill that turns your messy AI chat into PRDs, tech stacks, and prompts that don't lie to you.

This repo contains the framework, its walkthrough, and a ready-to-use skill for generating project documentation.

Watch the videos

What's in this repo

File	What it is
`01-idea-to-roadmap-concept.md`	Text transcript of the concept video (the 10-phase framework)
`vibe-project-docs.skill`	A Claude/OpenCode skill that generates your project docs (PRD, tech stack, brand guide, prompts, etc.)

How to follow this (recommended order)

1. Read the framework

Start with 01-idea-to-roadmap-concept.md. It lays out the 10 phases of turning an idea into a roadmap:

Brain-dump the idea, unfiltered
State your real constraints out loud, early
Ground it in reality before designing further
Let the core mechanism emerge, then formalize it
Go deep, one layer at a time
Periodically zoom out and stress-test the whole thing
Steer, don't just accept
Bring in real outside artifacts and cross-check them
Consolidate into a small number of durable reference documents
Make the final output actually actionable

Remember: these phases are a loop, not a strict waterfall. You'll revisit earlier phases as you build.

2. Watch the walkthrough

Open the walkthrough video on YouTube and follow along with a real project. Pause and apply each phase to your own idea as you go.

3. Install the skill

The vibe-project-docs.skill file automates the documentation step (Phase 9). To use it:

Copy/rename vibe-project-docs.skill to a .zip and extract it, or place the file in your agent's skills directory (e.g. ~/.claude/skills/ or your OpenCode skills folder) as vibe-project-docs/.
A readable copy of the skill's instructions is also included as vibe-project-docs_skill.md in this repo.

What the skill does

It turns a freeform "vibe coding" conversation into a complete, consistent set of project docs — prd.md, tech-stack.md, brand-guide.md, prompts.md, and others as warranted — meant to be dropped into a repo as context for Claude Code, Cursor, or Windsurf.

Its core rule is extract, then check, then write (never write straight from memory of a long conversation):

Extract — re-read the whole conversation and pull every concrete decision into a scratch _inventory.md (buckets: Product, Tech stack, Architecture & data, Design & brand, Coding conventions, Constraints, Contradictions, Open questions).
Diff — check the inventory against what each output doc needs; sort gaps into Critical vs Minor.
Ask — if there are critical gaps, ask about them once, batched (max 3), via the ask_user_input tool. Don't ask about minor gaps.
Write — generate each file from the inventory using the bundled templates, so the same fact never drifts between files.

Flag — mark minor assumptions inline with a consistent marker:

**[TODO: exact secondary color not specified — assumed a neutral gray-500]**

Format — favor scannable structure (bullets, bolded terms, a "Quick reference" summary per file). If 3+ files are generated, also write a docs-index.md.

Which files it generates

File	When
`prd.md`	Almost always — any product/feature discussion happened
`tech-stack.md`	Almost always — any stack/framework/infra discussion happened
`brand-guide.md`	Only if design/branding/tone was discussed, or asked for
`prompts.md`	Only if coding-agent behavior / conventions were discussed, or asked for
`data-model.md`, `roadmap.md`, `api-spec.md`	Only if that content came up in real detail (`references/optional-docs.md`)

After writing, the skill summarizes what was generated and reports the total count of [TODO: ...] markers left to decide.

4. Build your own

Run through the phases with your idea. By the end you should have:

A clear set of constraints
A named core mechanism
A layered, stress-tested plan
A small set of focused reference documents
An actionable, step-by-step build sequence

Quick start checklist

I can state my constraints in one breath (cost, audience, what it will never do)
I know what already exists and why I'm not just using it
My biggest named risk isn't the one I started with
My reference documents don't repeat each other
I can hand Phase 1 to someone else and they know when it's done

Help it spread

If this helped you ship with AI, give the repo a ⭐ and share it with other Claude Code, Cursor, or Windsurf users.

Turn messy software ideas into production-ready roadmaps with AI: 10-phase vibe coding framework + Claude skill for consistent project docs (PRD, tech stack, prompts & more).

Find it via these topics: ai · ai-agents · claude-code · cursor · vibe-coding · developer-tools · llm · prompt-engineering · indie-hacker · agentic-coding · workflows

Share-ready blurb:

Stop vibe-coding blind. vibe-coding-blueprint = 10 phases + a skill that turns your messy AI chat into PRDs, tech stacks, and prompts that don't lie to you.

License

Licensed under the MIT License. This material is shared for learning and reuse — feel free to fork, adapt, and build on it.