goldengrape/vibe-coding-skill/vibe-coding-skill

Vibe Coding Skill

Use this skill when a user has a new software idea and wants to use an AI coding assistant to build it from scratch without drifting, overbuilding, or losing track of decisions.

The public promise is simple:

Turn a rough idea into a clear, testable project map for safer vibe coding.

The user does not need to know SDD, URD, ADD, MDD, TDD, RMD, axiomatic design, or coupling analysis. Those terms are internal machinery. When talking to beginners, use friendly names first and technical names only when useful.

Beginner-facing names

Use these names in normal conversation:

The technical names may remain in file names because they are compact and stable. Do not force the user to learn the acronyms before they can use the skill.

Directory layout

pyproject.toml       # for Python projects, managed with uv
.gitignore
README.md
src/ or app/
tests/
 
docs/
  URD.md   # Idea Brief / User Requirement Document
  ADD.md   # Design Split / Axiomatic Design Document
  MDD.md   # Building Blocks / Module Design Document
  TDD.md   # Check Plan / Test-Driven Document
  RMD.md   # Build Path / Route/Runbook/Execution Map Document
  TRACE.md
  CHANGELOG.md
  PARKING_LOT.md
 
okf/
  index.md
  log.md
  terms/
  requirements/
  decisions/
  modules/
  interfaces/
  tests/
  paths/
  issues/
  references/
 
.vibe/
  trace.json
  doc_state.json
  coupling_history.json
  update_log.json

docs/ is the source of truth. okf/ is a derived AI-readable knowledge layer. .vibe/ contains machine-readable state and trace files.

This skill is optimized for new projects. If the project already has a substantial codebase, say so and treat reverse-engineering existing code as a separate task.

Core behavior

0. Operating guardrails

Use these guardrails in every mode. They prevent the AI from moving from planning to coding too early.

🔴 CHECKPOINT moments

Pause and show the user the current decision before continuing when any of these happen:

🛑 STOP conditions

Stop the current action and route the issue back to the right document when any condition below is true:

Failure handling table

Anti-pattern blacklist

Do not do these things when this skill is active:

1. Do not start feature implementation before the Idea Brief and Check Plan have enough facts to define success.
2. Do not turn OKF pages into copies of docs/ pages.
3. Do not invent requirements, libraries, external services, users, or constraints to make the plan look complete.
4. Do not split modules into meaningless pieces only to make the ADD matrix diagonal.
5. Do not hide accepted coupling; record it with guard tests.
6. Do not commit secrets, .env, virtual environments, local databases, caches, or generated artifacts.
7. Do not push, merge, delete, or overwrite real project files without explicit approval.
8. Do not regenerate every document when a local update is enough.
9. Do not create IDs that are never referenced by TRACE or OKF.
10. Do not claim tests passed unless the exact command ran successfully; if not run, say so.

1. Start with a plain-language explanation when needed

If the user is a beginner, non-programmer, or seems unsure what the process means, first explain the workflow in 5–8 short sentences.

Do not start with acronyms. Say something like:

Before coding, we will make a small project plan.
First, we clarify what you want and what should be left out.
Then we split the project into parts that can be built separately.
Then we write down how to check whether each part works.
Finally, we give the AI a build order so it does not jump around randomly.

When the user asks “why are you asking this?”, explain the immediate reason:

• “This affects what we test.”
• “This changes which data we need to store.”
• “This decides whether we need login.”
• “This prevents the AI from building a feature you do not want.”

Do not lecture. Keep explanations short, concrete, and tied to the current question.

2. Discuss the idea before design

In the Idea Brief phase, do not jump directly to architecture or implementation.

Ask questions only when the answer affects design, testing, or scope. Offer concrete options when helpful.

Ask when any of these are unclear:

• who will use the project
• what the user mainly wants to do
• what a successful result looks like
• what is in scope
• what is out of scope
• whether login, permissions, payments, private data, or external services are involved
• where the project should run
• whether speed, cost, privacy, reliability, or simplicity matters most
• whether requirements conflict

Do not ask endlessly. If an uncertainty does not block the next step, record it as an assumption or open question.

The Idea Brief may move to Design Split only after the first 🔴 CHECKPOINT and when all of these are present:

• at least one target user or user role
• at least one core user task
• at least one measurable success criterion
• explicit in-scope and out-of-scope lists
• main constraints
• assumptions and open questions separated from confirmed requirements

3. Apply Ockham's razor to all documents

The document set must stay small. More documents are not better; clearer decisions are better.

Do not write content unless it directly helps one of these tasks:

• confirm user intent
• reduce ambiguity
• preserve a design decision
• reduce coupling
• define a module, interface, or contract
• define a test oracle
• order development tasks
• help an AI retrieve the correct context later

Avoid these forms of document bloat:

• repeating the same idea in every document
• writing future features into the current version
• adding generic architecture lessons
• adding implementation detail before it is needed
• turning OKF concept pages into copies of docs pages
• creating IDs that are never referenced
• keeping stale assumptions after the user has answered them

If something is interesting but not needed for the current version, move it to docs/PARKING_LOT.md.

After every generation or update, run this check:

For each newly added paragraph:
1. Does it serve the current phase?
2. Is it linked to a requirement, design part, module, interface, test, task, or OKF concept page?
3. Is it repeated elsewhere?
4. Does it describe a future feature rather than current scope?
5. Could it be derived reliably from another document?
 
If the answer shows low value, delete, merge, shorten, or move it to PARKING_LOT.

4. Use Design Split to reduce coupling, but do not fake zero coupling

Internally, Design Split uses Functional Requirements (FRs), Design Parameters (DPs), and a design matrix.

For beginners, explain it this way:

We are checking whether each user need can be built by one clear part of the system.
If one part accidentally affects many unrelated needs, the AI is more likely to create messy code.

Matrix interpretation:

• diagonal matrix: uncoupled design
• triangular matrix: decoupled design with an execution order
• dense or irregular matrix: coupled design

When Design Split detects coupling, retry the design decomposition before accepting it. If the retry loop fails, trigger the ADD coupling 🛑 STOP condition.

Coupling retry loop:

1. Try to split broad user needs into smaller independent needs.
2. Try to redefine design parts so each part satisfies one need.
3. Try to introduce explicit interfaces, events, adapters, pure data structures, or contract boundaries.
4. Try to move responsibility between modules.
5. Repeat for up to 3 structural retries.
6. If coupling remains, record it as Accepted Coupling.

For each retry, record what changed and why.

For accepted coupling, record:

• coupled requirements and design parts
• why the coupling is necessary or temporarily accepted
• affected modules
• risks
• tests required to guard the coupling
• future condition that would justify refactoring

Do not split the system into meaningless pieces just to make a pretty matrix. That violates Ockham's razor.

5. Keep docs authoritative and OKF derived