Models get worse when they write into a repo blind. Structural maps give the session landmarks before it starts editing.
Β§ 01 Β· THE PROBLEM OBSERVED 2024β2026 FIG. 01
Agent-built apps can look done
while auth, data, payments, and deploy are still fragile .
Code generation gets you to a demo. Real users, money, security reviews, and the next developer expose the parts no prompt ever owned.
Security review
The app works, but auth is admin/user only, tokens live in the wrong place, and nobody can prove who may touch which data.
Money path
Stripe works until it does not. A webhook fails once, there is no retry, and the customer finds the missing service before the system does.
Β§ 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 compile pass starts to feel like proof. It is useful signal, just 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 stabilization sprint
Find the weak seams, then close them .
Vibecrafted keeps the momentum from AI-built software and adds the missing release discipline: map the repo, assign the next cut, verify runtime truth, and leave evidence for the next session.
01
Scaffold
prepare the surface
02
Craft
shape with agents
03
Convergence
collapse unresolveds
04
DoU
find what is still undone
05
Release
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
A["Scaffold"] --> B["Init"]
B --> C["Workflow"]
C --> D["Follow-up"]
D --> E{{"Marbles Loop"}}
E --> F["DoU"]
F --> G["Decorate"]
G --> H["Hydrate"]
H --> I["Release"]
classDef stage fill:#0d1728,stroke:#31415d,color:#f3efe7,stroke-width:1.3px;
classDef core fill:#1a1110,stroke:#d8894b,color:#ffd9bd,stroke-width:2.2px;
class A,B,C,D,F,G,H,I stage;
class E 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 Β· RUN Β· OBSERVE FIG. 05 Β· DWG VC-005
Install it locally
Let every run leave a trail .
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 next agent may inherit reports, decisions, and open questions instead of a cold prompt.
- 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 can carry prompt, report, metadata, and the decision it was meant to support.
- 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 04 100 CONVERGED
01 craft 12 078 ACTIVE
02 convergence 07 042 ACTIVE
03 doU 03 000 WAITING
04 release 00 000 BLOCKED
Fig. 04a β Board state as observed at t=14:04:48, after six throws across phases 00β02.
OPERATOR HABITS 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 .
Β§ 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 agent-built products and our own release lanes. Anonymized, because the pattern matters 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