Models drift when they write into a repo blind. Structural maps give the session landmarks before the agent touches a file.
Dispatch surface: agents, repos, live runs. AGENTS · 040 REPOS · 008 LIVE · LIVE
Real usage · Start here · Session Manager · sessions rail.
§ 02 · THE SURFACE REAL USAGE · VC-FRAME FIG. 02 · DWG VC-002
This is the product .
An operating runtime for multi-agent CLI workflows. Below is the operator cockpit — real frames from vc-frame, not mockups.
Start here · chrome legend First minute: where sessions live, where work happens, how Session Manager attaches. Inventory of rooms — not fleet truth.
Install the runtime
curl -fsSL https://vibecrafted.io/install.sh | bash § 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 · npm · STRUCTURE OP · 01 aicx · npm · MEMORY OP · 02 prview · crates · REVIEW OP · 03 ScreenScribe · PyPI · EARS OP · 04 vc-frame · cockpit · RAIL OP · 05 DoU · GATE
Open the Playground § 05 · THE OPERATOR INSTALL · HAND OFF · OBSERVE · 3.6.0 FIG. 05 · DWG VC-005
Install once. Then pass the baton .
STEP 01
$ curl -fsSL https://vibecrafted.io/install.sh | bash One local bootstrap from the published 3.6.0 artifact — not a private checkout. STEP 02
$ vibecrafted doctor Health check: foundations prebuilt-first, control plane staged, VERSION stamped. STEP 03
$ vibecrafted init claude First-context pass: Loctree map + AICX intent before any agent cuts code. VC-FRAME 0.46 · COCKPIT
Session rail on every dispatch layout .
The operator cockpit ships with the session-manager rail welded into dashboard, marbles, operator, research, and workflow layouts. Tab inventory stays honest; fleet settlement lives on the Mission Control board — not the rail.
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.
- Settlement is canonical. Mission Control f/x/n reads retained control-plane settlement — the same truth as vc-server API and SSR. The rail is inventory; the board is the score.
- Runs leave seals. Delivery-proof kernel: execution envelope, proof contract, reconstructable seal. A completion label is not enough.
- Undone stays visible. DoU and marbles keep 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