Development is comprehension. Compile it.
vibedecoding is a software development framework. It puts two artifacts around your code repo: a private engineering wiki that holds what your system means, and a dependency-aware issue tracker that holds what happens next. Agents maintain both. Builds verify both. Nothing is allowed to rot.
READING IS THE JOB
Most of software development is not typing — it is working out what the system is and why. That understanding is the most expensive artifact your team produces. It is also the only one you throw away.
Agents comprehend from scratch
Every session starts blind. The agent greps, reads, and re-derives your architecture — then the session ends and the comprehension dies with it.
DERIVED DAILY, SAVED NEVERCode answers what, never why
Search over a codebase finds what is — not what should be, what was rejected, or what that strange lock is actually protecting.
WRONG QUESTIONDocs and backlogs rot
Team wikis drift from reality the day they're written. Backlogs mix real work with wishes until nobody trusts the queue.
TRUTH DECAYSCOMPREHENSION, COMPILED
Treat understanding as a build artifact: compile it once, keep it current, and make everything downstream — including your agents — consume the compiled form instead of re-reading the sources.
The Wiki — what it means
- Design pages and decision records: the why that code can't say
- Curated and cross-linked, never appended-to; contradictions get flagged
- Plain markdown — authored in Obsidian, rendered as a private site
The Tracker — what's next
- Dependency-aware issues: blockers, parents, provenance
- Ideas parked from birth; work gated by refinement
- The ready queue is correct by construction
- Runs on Beads: a local, git-synced issue database behind the bd command
A Hard Boundary
The wiki is a private repo beside your source. That source is a codebase you already have: an agent compiles the first design pages from it, and the loop drives every change back into it after that. Understanding stays in; nothing crosses out but opaque issue IDs — and a pre-push guard greps every outgoing commit to keep it that way. Open-source the code if you want to. Keep the comprehension either way.
THE LOOP
One lifecycle from passing thought to distilled knowledge. Every stage is enforced by structure, not discipline.
Ideas are parked. Work is gated. Closes are audited. None of it depends on anyone remembering to care.
WHAT LIVES IN THE WIKI
Five kinds of pages, one link graph, and a build that refuses to render anything broken.
Design Pages & ADRs
Why the system is shaped like this. Decision records survive the refactors that erase their evidence from the code.
Work Pages
Rendered from the tracker at every build and hash-stamped — a hand-edit fails the build. There is nothing to keep in sync.
Tests as Pages
Each test case is a markdown file linked to the work it covers. A coverage matrix flags anything closed but never verified.
Diagrams by Style Guide
A palette and conventions that agents read each session. Consistency comes from a style guide plus lint, not a generator.
Prompts, Versioned
Refine, triage, close-audit, ingest, implement — the judgment work of the process lives as reviewable files, not tribal knowledge.
The Link Graph
Wikilinks resolve in the editor and on the site; issue and test IDs are link targets too. One broken link fails the build.
| A team wiki | vibedecoding | |
|---|---|---|
| Kept honest by | Good intentions | A failing build |
| Work tracking | A separate tool that drifts | The tracker is the source; pages are generated |
| Written for | Humans only | Humans and agents, same files |
| After each change | Drift | Mandatory distillation at close |
| Understanding lives | In heads and threads | In a repo, compiled |
THE ENGINE
The framework is built as an engine: one package, a CLI, and a template. Every project's wiki is an instance; the machinery is developed in exactly one place.
A full workspace in one command: private wiki, issue tracker, agent prompts, boundary guard, and a private site.
Regenerate from the tracker → lint the link graph → check coverage → render. If the wiki is wrong, it doesn't build.
Template improvements flow to existing instances: pristine files re-stamped, customized files flagged — never overwritten.
Point an agent at an existing codebase and compile the first design pages, decisions, and a seeded backlog.
The engine runs today — it maintains this framework's own wiki and backlog. It is not released yet. If that changes, it will change here first.
BUILT INSIDE ITSELF
vibedecoding is developed as a vibedecoding project. Its own wiki holds the framework's design; its own backlog holds the framework's roadmap. Every papercut found in any instance is filed upstream and triaged like everything else.
THE META PROJECT
The framework's design pages, decision records, and tests — the first instance of its own engine. Every change is dogfooded here before any project sees it.
THE INSTANCES
One private wiki per project, scaffolded in a command, running on the shared engine, feeding discoveries back upstream as parked ideas.
The system tracks its own growth: tooling needs are ideas, ideas are triaged, and the framework improves through the same gate as everything it manages.
PRINCIPLES
THE QUEUE CANNOT LIE
Readiness is dependency math, not opinion. Unrefined work is structurally blocked.
GENERATED MEANS GENERATED
Derived pages are hash-stamped. A hand-edit fails the build, so drift is impossible.
A FAILING BUILD IS THE GATE
No CI, no process police. A broken wiki simply refuses to render.
IDEAS ARE NOT WORK
Parked from birth, triaged on schedule, pruned without guilt.
CLOSE MEANS DISTILL
Every close updates the design pages or states “no design impact” — on the record.
PLAIN MARKDOWN FOREVER
Obsidian to write, a static site to read, grep at worst. No lock-in, ever.
THE BOUNDARY IS STRUCTURAL
Private wiki, public code, and a guard that greps every push. Leaks are hard by design.
AGENTS ARE CHEAP; ROT IS NOT
Maintenance is delegated to agents. Honesty is enforced by the build.