- 1. Philosophy: Structured Vibe Coding
- 2. The Blueprint Method
- 3. Vibe Coding Tools
- 4. Workflow Examples
- 5. FAQ
- 6. License & Contributions
This tool is designed for software engineers who feel better with a command-line interface.
- Chat‑only workflow: AI changes lightning-fast; locking in to any model or tool is not good.
- Requirements, design, and coding: AI is similar to a human; you will need to confirm at the requirements, design, and coding/test stages.
- Git & diff: AI is similar to a human. We need to communicate with the AI using git history & diffs so it can reason over the exact context you see.
If you are implementing large features, asking an AI to design architecture and write code at the same time can lead to hallucinations and context drift. For complex tasks, we recommend The Blueprint Method: a three-phase methodology that shifts AI from a guessing machine to a precise execution engine.
- The Blueprint Method: A methodology to get confirmation at each step: requirement-design-coding. Humans and AI get on the same page fast, with minimal back‑and‑forth.
Move your design, requirement, and test documents into Markdown format in the repository if you have any.
VS Code is great for rendering Markdown into Word or Google Doc-like documents if you do the following:
- Export Google Docs to HTML ZIP, then use PanDoc to convert the HTML into an md file.
pandoc GoogleDocExport.html --wrap=none --markdown-headings=atx -f html-native_divs-native_spans -t gfm-smart --extract-media=. -o CleanedExport.md
- Use Mermaid sequenceDiagram to generate inline flow charts.
- Use Mermaid graph TD for inline diagrams.
- Use drawio for diagrams, then export to svg, and embed them inline in the md file.
- GitHub Flavored Markdown (GFM) for tables.
- Markdown All-in-one for section numbers and Table of Contents.
Feed the AI your requirements and ask it to audit them for edge cases before any code is written.
Audit this `requirement_prompt.md` for clarity, missing edge cases, and logical gaps. Rewrite it into strict Given-When-Then acceptance criteria and wait for my approval before writing code. Do not include details already implemented in the codebase in the `requirement_prompt.md`. The Ground Truth Principle: Treat the codebase as the absolute source of truth. Design markdown files are historic intent. If they clash, the code wins.
Have the AI map out how the requirements integrate into the codebase by updating your markdown design docs or Mermaid diagrams first.
Based on the approved `requirement_prompt.md` and the codebase context, update our design.md files. Then, generate a strict step-by-step `coding_prompt.md` for execution. Wait for my approval. Do not include details already implemented in the codebase in the `coding_prompt.md`. The Ground Truth Principle: Treat your codebase as the absolute source of truth. Design docs are historic intent. If they clash, the code wins.
Feed the AI the generated coding_prompt.md and force it to code incrementally.
Execute step 1 of the `coding_prompt.md`. Write complete, production-ready code with no placeholders. Stop and wait for me to verify the tests pass before moving to step 2.
Keep it simple. These tiny scripts package the right text or code so you can drop a single file or a folder or a type of files into a coding chat AI. No lock‑in to any AI model or tool.
python3 -m venv venv && source venv/bin/activate
# run any tool with: python3 <tool>.py [args]If you are implementing small features, you don't need to use 'The Blueprint Method'. Start with the vibe tool
- Run a tool below to generate a single text file.
- Attach or paste that file into your coding chat.
- Prompt the AI with what you want (review, refactor, tests, bug fix, or a Blueprint Method phase).
Snapshot all text files in a repo
What: Recursively collects text‑like files (e.g., .py, .md, .json, etc.), skips noisy folders (.git/, node_modules/, dist/, etc.), and writes one bundle with headers per file.
Why: Share the whole project context in chat without zipping.
Use it
python3 concatenate_text_files.py path/to/project
# → creates ./<project>.txt containing all included files with headersThe script supports --code-only and --py-only options to reduce the number of files included in the package.
Bundle a script plus its local imports
What: Traces local Python imports starting from one or more entry scripts and concatenates those files into a single text artifact.
Why: Give AI the exact Python dependency closure it needs for reasoning, without external packages.
Use it
python3 concatenate_python_files.py project_root/ path/to/main.py [another.py ...]
# → writes project_root_concatenated.txtPackage the changed files for a commit or range
What: Finds files changed in one commit (or between two commits) and writes their contents to a single text file with commit headers.
Why: Share focused diffs for targeted reviews or debugging.
Use it
# Single commit
python3 save_commits.py --this f9e8d7c
# Range (base..this)
python3 save_commits.py --base a1b2c3d --this f9e8d7c
# → writes <this>.txt or base-this.txtQuick repo inventory
What: Scans a directory, groups by file type, totals sizes, and shows a small table (count, total size, example largest file). No bundle output—just fast insight.
Why: Decide what to package (and what to ignore) before chatting.
Use it
python3 analyze_folder.py # analyze current folder
python3 analyze_folder.py path/to/dir # analyze a specific directoryconcatenate_text_files.py ./myapp→myapp.txt- Attach
myapp.txtin chat. - Ask: “Review for structure, add tests for X, and propose a minimal refactor.”
concatenate_python_files.py ./tools ./tools/runner.py→tools_concatenated.txt- Attach; ask: “There’s a crash when input is empty. Fix and add doctests.”
save_commits.py --base abc123 --this def456→abc123-def456.txt- Attach; ask: “Explain risk, edge cases, and missing tests in this change.”
concatenate_text_files.py ./myapp --code-only → myapp_code.txt
Attach myapp_code.txt along with your requirement_prompt.md.
Follow the Phase 1, 2, and 3 prompts outlined in the Blueprint section above to design and execute without context drift.
Why text instead of zip? Text is immediately visible/searchable in chat, avoids unzip friction, and keeps you and AI tightly in sync.
Does this include third‑party deps? No—these tools focus on your source and local imports. Mention external packages in your prompt or attach requirements.txt.
Use at your own risk; PRs welcome. Keep changes tiny, logs clear, and defaults sensible.