⚡ 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

• Click to see video: Idea to Roadmap — The Concept (10-Phase Framework)
• Click to see video: Zero to Build-Ready — The Walkthrough

---

What's in this repo

---

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:

1. Brain-dump the idea, unfiltered
2. State your real constraints out loud, early
3. Ground it in reality before designing further
4. Let the core mechanism emerge, then formalize it
5. Go deep, one layer at a time
6. Periodically zoom out and stress-test the whole thing
7. Steer, don't just accept
8. Bring in real outside artifacts and cross-check them
9. Consolidate into a small number of durable reference documents
10. 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):

1. 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).
2. Diff — check the inventory against what each output doc needs; sort gaps into Critical vs Minor.
3. 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.
4. Write — generate each file from the inventory using the bundled templates, so the same fact never drifts between files.
5. Flag — mark minor assumptions inline with a consistent marker:
   hljs language-css

   Copy

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

6. 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

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.