Models drift when they write into a repo blind. Structural maps give the session landmarks before the agent touches a file.
Β§ 01 Β· THE PROBLEM OBSERVED 2024β2026 FIG. 01
Agent-built apps can look complete.
Auth, data, payments, and deploy are still fragile .
After the first user it usually turns out that a demo is not a product. The truth surfaces on the first install on someone else's machine, the first Stripe webhook, the first security review, or a new developer on the team β they show you what no prompt ever truly took on.
Security review
The app works. Auth has two roles: admin and user β but seven profiles run in prod, and nobody mapped them. Tokens live wherever they end up: localStorage sometimes, HTTP-only cookie sometimes, both at once sometimes. First thing in an audit: nobody can tell who has access to what. Second: when someone leaves the team, the keys stay.
Money path
Stripe works. Until it does not. A webhook fails once β no retry, no dead letter queue, no alert. The customer notices the missing service before the system does. The founder hears about it on the support Discord, not from the dashboard.
Β§ 02 Β· ENGINEERING AXIOMS Β· METHOD FIG. 02 Β· DWG VC-002
Less magic
More inspectable work .
The vocabulary can stay vivid, as long as the system remains inspectable: context before edits, evidence after runs, and a release surface that says what is still uncertain.
Code generation is noisy. The Marbles loop gives that noise a place to show up: small loops, counterexamples, and visible unresolved work.
Structured Human-AI collaborative engineering. The craft is in the handoff: humans keep scope, taste, and irreversible decisions; agents do fieldwork with evidence attached.
Β§ 03 Β· THE SHIFT VIBES β VECTORS FIG. 03 Β· DWG VC-003
Most AI coding sessions leave fragments.
Vibecrafted gives the work coordinates..
Without a board
Context evaporates.
The next session may inherit a diff, but not the reason behind it. The repo has changes; the work has no memory.
Retry becomes the method.
A green build starts to feel like proof. It is useful signal, but not enough to know whether the product is safe.
Done stays blurry.
Artifacts collect in comments, branches, notes, and screenshots. A future agent can see pieces, but not the shape.
With a board
The contract is visible.
Scope, owner, evidence, and next action sit on the same surface before the agent starts cutting.
The trail survives.
Reports and artifacts stay attached to the repo, so the next session can continue from evidence instead of mood.
Convergence is inspectable.
The board does not declare victory. It shows what landed, what moved, and what still asks for a decision.
05 PHASES
06 OPERATORS
01 SHARED BOARD
00 LOST CONTEXT
Β§ 04 Β· THE FRAMEWORK SCAFFOLD β RELEASE FIG. 04 Β· DWG VC-004
Not a rewrite. A cadence.
Every write earns a read .
Eleven stages alternate Read and Write. Every write β implement, marbles, polarize β is immediately falsified by a read β review, audit, DoU. Marbles raises entropy to fill the cracks; Polarize cuts it back to one truth. Each stage runs its leg and hands the baton to the next, so nothing ships unchecked.
01
Scaffold
read Β· map before the cut
02
Implement
write Β· agents deliver
03
Review
read Β· falsify the write
04
Converge
write Β· marbles β¬ polarize β¬
05
Release
write Β· ship for strangers
%%{init: {
"theme": "base",
"themeVariables": {
"background": "#07111f",
"primaryColor": "#0c1626",
"primaryTextColor": "#f3efe7",
"primaryBorderColor": "#2d3b56",
"lineColor": "#d8894b",
"secondaryColor": "#101b2d",
"tertiaryColor": "#0d1728",
"fontFamily": "Inter, ui-sans-serif, system-ui, sans-serif",
"fontSize": "16px"
},
"flowchart": {
"curve": "basis",
"htmlLabels": true,
"nodeSpacing": 32,
"rankSpacing": 46,
"padding": 14
}
} }%%
flowchart LR
S["Scaffold Β· R"] --> I["Implement Β· W"]
I --> RV["Review Β· R"]
RV --> WF["Workflow Β· W"]
WF --> FU["Follow-up Β· R"]
FU --> MA{{"Marbles Β· W β¬"}}
MA --> AU["Audit Β· R"]
AU --> PO{{"Polarize Β· W β¬"}}
PO --> DU["DoU Β· R"]
DU --> HY["Hydrate Β· W"]
HY --> RE["Release Β· W"]
classDef read fill:#0d1728,stroke:#3b6ea5,color:#dbe7f3,stroke-width:1.3px;
classDef write fill:#1a1410,stroke:#d8894b,color:#ffd9bd,stroke-width:1.6px;
classDef core fill:#1a1110,stroke:#e2935a,color:#ffd9bd,stroke-width:2.4px;
class S,RV,FU,AU,DU read;
class I,WF,HY,RE write;
class MA,PO core;How the pass runs .
Each workflow has one job. Read the repo, make the cut, test the real path, or audit what is still not ready. Names come later; the evidence comes first.
OP Β· 00 loctree Β· STRUCTURE OP Β· 01 aicx Β· MEMORY OP Β· 02 prview Β· REVIEW OP Β· 03 ScreenScribe Β· RUNTIME OP Β· 04 DoU Β· GATE OP Β· 05 Review Β· CLOSING
Open the Playground Β§ 05 Β· THE OPERATOR INSTALL Β· HAND OFF Β· OBSERVE FIG. 05 Β· DWG VC-005
Install once. Then pass the baton .
STEP 01
$ curl -fsSL vibecrafted.io/install.sh | bash One local bootstrap. It installs the commands and opens the guided launcher. STEP 02
$ vibecrafted doctor A quick health check before agents touch the repo. STEP 03
$ vibecrafted init claude A first-context pass with a real agent inside a real repository. The repo gets a shared surface .
A session can end without disappearing. The operator is an agent: it runs the relay, and each leg hands the baton to the next runner β the next agent inherits reports, decisions, and open questions, not a cold prompt. You stay the founder β scope, taste, the hard transitions, the feel of the project β you never run the legs yourself.
- State has a place. Artifacts live under $VIBECRAFTED_ROOT/. Not in the memory of whichever tab happened to be open.
- Runs leave evidence. Each agent run leaves prompt, report, metadata, and the decision it was meant to back up.
- Undone stays visible. DoU and marbles keep the unresolved pieces on the board until somebody decides what they mean.
N# PHASE MARBLES COVERAGE % STATE
00 scaffold 03 100 CONVERGED
01 implement 08 100 CONVERGED
02 review 05 100 CONVERGED
03 workflow 06 072 ACTIVE
04 follow-up 03 058 ACTIVE
05 marbles 12 048 ACTIVE
06 audit 02 000 WAITING
07 polarize 00 000 WAITING
08 doU 00 000 WAITING
09 hydrate 00 000 BLOCKED
10 release 00 000 BLOCKED
Fig. 04a β Board state as observed at t=14:04:48, after twelve throws across stages 00β05.
HOW THE RELAY HOLDS ONE REPO, ONE SURFACECONTRACT BEFORE PROMPTEVIDENCE OVER MOODUNRESOLVED STAYS VISIBLE
Β§ 06 Β· QUICKSTART INIT β SHIP Β· SIX THROWS FIG. 06 Β· DWG VC-006
Start with the first useful signal .
Check the local surface.
Start with the boring signal: does the launcher know where it is, what is installed, and what needs attention?
$ vibecrafted doctor LANDS: INSTALL HEALTHΒ· FOUNDATION CHECKΒ· LAUNCHER TRUTH
000% CONVERGE
Let an agent read first.
Init may surface repo shape, recent context, and the first risks before any edit starts.
$ vibecrafted init claude LANDS: REPO MAPΒ· FIRST CONTEXTΒ· NEXT MOVE
030% CONVERGE
Choose a lane.
Workflow helps when the task needs a little ceremony: examine the surface, research the gap, then implement the cut.
$ vibecrafted workflow claude --prompt "Plan and implement <task>" LANDS: PLANΒ· IMPLEMENTATION LANEΒ· REPORT TRAIL
060% CONVERGE
Look for what still bites.
Marbles runs small counterexample loops. It may find an edge case, a false assumption, or simply a place that needs a human decision.
$ vibecrafted marbles codex --count 3 --depth 3 LANDS: COUNTEREXAMPLESΒ· FIX LOOPSΒ· CONVERGENCE SIGNAL
075% CONVERGE
Name the unfinished parts.
DoU is the moment to stop pretending. It asks what is missing across install, docs, runtime, trust, and release.
$ vibecrafted dou claude --prompt "Audit launch readiness" LANDS: UNDONE LISTΒ· SHIP RISKSΒ· PRODUCT TRUTH
090% CONVERGE
Prepare the handoff.
Release gathers the outward work: artifacts, deployment notes, docs, and the next human-readable step.
$ vibecrafted release codex --prompt "Prepare release steps" LANDS: RELEASE PLANΒ· ARTIFACT CHECKΒ· NEXT STEPS
100% CONVERGE
Β§ 07 Β· REFERENCES RESEARCH Β· FIELD NOTES FIG. 07 Β· DWG VC-007
What we read before we built .
The convergence framework is the synthesis of research on agent handoffs, release gates, and runtime contracts. Sources below β consult before adopting.
REF Β· 01 The Mythical Man-Month. Addison-Wesley, 1975 The original observation that adding throw-power without coordination makes things worse, not faster. Convergence is the answer to that math. REF Β· 02 A Philosophy of Software Design. Yaknyam Press, 2018 Deep modules over shallow APIs β the principle behind why each operator owns one sharp protocol, not a thousand prompts. REF Β· 03 Model Cards for Model Reporting. FAccT 2019 Documenting what a system can and cannot do before it ships. DoU is this idea, applied to a build instead of a model. REF Β· 04 Datasheets for Datasets. Communications of the ACM, 2021 Every input declares its scope upfront. The board makes the same demand of every throw β declare contract before code. REF Β· 05 On the Dangers of Stochastic Parrots. FAccT 2021 Why scaling alone doesn't yield understanding β surface fluency without grounded truth doesn't ship. REF Β· 06 The Hardware Lottery. Communications of the ACM, 2021 Runtime substrate decides which ideas survive. Convergence systems need predictable execution, not just smart prompts.
Β§ 08 Β· EVIDENCE FROM THE WILD Β· PATTERNS OBSERVED FIG. 08 Β· DWG VC-008
The vibe hangover in the wild .
A few field notes from the wild β from agent-built products and our own release lanes. Anonymized, because the pattern says more than the name.
PATTERN Β· 01 RELEASE MIRROR
Two checkouts, two truths.
The upstream framework was already fixed, but the public landing repo still served older installer truth. Everyone was right inside their own checkout; the user saw drift.
FIELD NOTE Β· representative repo release lane PATTERN Β· 02 HELPER DRIFT
The runtime moved. The docs did not.
A helper script kept yesterday's path assumptions after the main runtime flow was repaired. The product worked, until an operator followed the stale trail.
FIELD NOTE Β· helper surface audit PATTERN Β· 03 SILENT FAILURES
The webhook that never retried.
A checkout path looked healthy until activation moved into claim and webhook truth. The sale happened; the entitlement story still needed a witness.
OBSERVED Β· real founder (redacted) PATTERN Β· 04 DEPLOY AND PRAY
Friday afternoon migration runs four times.
No staging, no smoke tests, no rollback. The migration deadlocks on a lock table. Support tickets spike while the founder tries to remember which tab ran last.
OBSERVED Β· field reports