How it works Commands Anatomy Editions GitHub Star on GitHub
Inside the .vibeflow/ folder

Anatomy of the
.vibeflow/ folder

What each file is, why it exists, and how the agent uses it. So you know what you can change, and what you should leave alone.

When you run /analyze, Vibeflow creates a .vibeflow/ folder at the root of your project. It is the project knowledge base the agent reads before every spec, implementation, and audit. Four artifacts make up that knowledge base; the other commands add their own folders next to them (PRDs, specs, audits and, with implement --loop, the loop's files).

index.md The map.
What it is
A single file with the project overview: stack, structure, key files, dependencies, suggested budget, known tech debt, the Pattern Registry (a YAML block listing every pattern with its tags and modules), and a Tests and Pitfalls block: the full-suite command, the narrowest affected-tests command with its measured time or unmeasured, and the pitfalls that already cost the project time, each with its source.
Why it exists
Every skill needs to orient itself before doing anything. Without a map, the agent re-discovers the project on every command, which is slow, inconsistent, and easy to drift. The Registry also lets skills load only the relevant patterns instead of all of them.
How the agent uses it
Read by every skill at the start: analyze writes it, discover / gen-spec / implement / audit read it to know the stack, find target files, and resolve patterns via the Registry. analyze records the test commands without running them; only analyze --measure runs each one once and records its time and date.
Do you edit it?
Mostly auto-generated. You can hand-edit notes outside the <!-- vibeflow:patterns:start/end --> markers and the vibeflow:auto markers of the Tests and Pitfalls block, and those survive incremental analyze runs. Inside either set of markers is regenerated.
patterns/ The recurring structural solutions.
What it is
A folder with one markdown file per pattern. Each file documents a solution shape that repeats across the project: what it is, where it lives, the rules, and real code examples lifted from the codebase.
Why it exists
Patterns carry nuance: the what, the why, and the how. They are how the agent writes code that looks like your code, not generic code. Without them, every implementation reinvents structure.
How the agent uses it
gen-spec picks the relevant patterns via the Registry and lists them in the spec. implement reads only those and replicates their structure. audit verifies the implementation followed them. teach can add new ones, including imported from external repos via --from.
Do you edit it?
Yes, but carefully. Content inside <!-- vibeflow:auto:start/end --> is auto-generated; edit outside the markers to add notes that survive re-analysis. Use /teach to add a new pattern instead of dropping a file by hand.
conventions.md The rules.
What it is
A single file with the small, atomic rules of the project: naming, file layout, language/runtime, error handling, delimiters, documentation expectations. Short bullets, no narrative.
Why it exists
Rules without nuance ("do it this way") belong in one flat list, not scattered across pattern docs. This file is what the agent applies on every line of code it writes, regardless of which pattern is in play.
How the agent uses it
Loaded by gen-spec, implement, and audit on every run. Implement applies it line-by-line; audit treats violations as quality failures (the craftsmanship gate).
Do you edit it?
Yes. Use /teach to add or correct a convention in natural language ("we always use named exports"). Direct edits outside <!-- vibeflow:auto:start/end --> are preserved.
decisions.md The architectural memory.
What it is
A reverse-chronological log of architectural decisions: context, options considered, what was chosen, and why. Newest first. Written by the architect during specs and audits, never auto-generated.
Why it exists
Six months later, no one remembers why you picked option B over option A. This file is the trail. It also prevents the agent from re-litigating settled questions on every new spec.
How the agent uses it
Read by gen-spec and audit when a decision is relevant to the current scope. The architect appends new entries when a non-trivial trade-off is resolved.
Do you edit it?
Yes. This one is the most "human". Add entries when you make an architectural call worth remembering. /teach can format it for you.
Folders the loop creates

With implement --loop, .vibeflow/ also gets four working folders:

  • loop/ the ledger of each feature (state, the rounds table that stats reads, decisions, follow-ups, handoff) and config.md.
  • briefings/ one briefing per loop round.
  • progress/ the progress file of the executor and of each fix round.
  • reviews/ the review packages and the PR body.

Commit .vibeflow/ to git except reviews/, which holds working material: the review packages, rewritten on every audit, and the PR body. Add .vibeflow/reviews/ to .gitignore. (The Cursor and Copilot installers already put the whole .vibeflow/ in .gitignore.)

Patterns vs conventions: what is the difference?

They both teach the agent about your project, but at different levels. Conventions are atomic rules ("kebab-case filenames"). Patterns are recurring structural solutions ("how we build i18n components").

conventions.md

  • Atomic rules, one-liners
  • Rarely explain the why
  • Applied on every line of code
  • Think: spelling rules

patterns/*.md

  • Whole solutions, one file each
  • Always explain the why + examples
  • Applied when solving that specific problem
  • Think: essay structure

Convention is how to spell the word. Pattern is how to build the paragraph.

Want the full picture?

The MANUAL covers every command, flag, and workflow in depth.

Read the MANUAL