Truth-convergence executor. Use when implementation already exists but the codebase still lies: overgenerated surfaces, drift between runtime paths, false certainty from one-shot agent output, or a product that "works" while remaining fragile. Each invocation is isolated: inspect the current tree, find the most dangerous present falsehood or fragility, compress the surface into a more truthful shape, run gates, commit, and emit a machine-diffable round delta report. Do not reconstruct prior marble rounds unless the operator explicitly requests forensics. Trigger phrases: "marbles", "kulki", "stabilize", "stabilizacja", "loop until done", "reduce chaos", "fortify the foundation", "adultification".
Operator enters the framework session through:
vibecrafted start
# or
vc-start
# same default board as: vc-start vibecrafted
Then launch this workflow through the command deck, not raw skills/.../*.sh paths:
vibecrafted <workflow> <agent> \
--<options> <values> \
--<parameters> <values> \
--file '/path/to/plan.md'
vc-<workflow> <agent> \
--<options> <values> \
--<parameters> <values> \
--prompt '<prompt>'
If vc-<workflow> <agent> is invoked outside Zellij, the framework will attach
or create the operator session and run that workflow in a new tab. Replace
<workflow> with this skill's name. vc-marbles also has a natural
surface; keep the same launcher contract and prefer the most truthful input form.
--depthSingle convergence round with a prompt:
vibecrafted marbles codex --prompt 'Fix the 3 failing portable tests'
vc-marbles codex --prompt 'Harden the installer shell surface'
Multiple rounds (convergence loop — the runtime orchestrator script spawns the new agent N times):
vibecrafted marbles codex --count 5 \
--prompt 'Stabilize until P0=0'
vc-marbles claude --count 8 \
--prompt 'Refactor the 1500 LOC monoliths across the project'
From a plan file:
vibecrafted marbles codex --file ~/.vibecrafted/artifacts/VetCoders/vibecrafted/2026_0407/plans/marbles-plan.md
vc-marbles gemini --count 2 --file /path/to/plan.md
This is NOT the same as vibecrafted codex implement <plan>.
implement is how code appears. marbles is what happens after code exists but
still needs to be made truthful, legible, operable, and shippable. The mechanism
wraps the agent in a convergence loop: each round re-perceives the live tree,
attacks the biggest present lie, compresses the surface toward one coherent
runtime truth, commits, and reports. The --count flag controls how many rounds
the outer loop runs.
The worker sees the tree, not the factory. One round. One truth-forcing cut. One report. Then leave.
vc-marbles is not a mini-task implementer.
It is the executor of truth in an already-generated codebase.
It begins after implementation is already in.
Its job is to take the naturally overgenerated output of agentic coding and pack it into shape:
A marble worker is intentionally blind to prior marble history. It works against the current workspace state and the current evidence surface only.
The loop exists outside the worker. The worker must not try to model, narrate, or optimize the loop. The worker exists to force the present tree to tell the truth.
Context weight kills quality. An agent that has been working for 90 minutes on a complex refactor will make worse decisions in minute 91 than a fresh agent would in minute 1. The accumulated context becomes a lens that distorts perception — the agent starts defending its own sunk cost instead of seeing the tree clearly.
Marbles exist to exploit this. Every round gets a fresh mind. The fresh mind does
vc-init, perceives the project through live instruments (loctree, aicx-steer,
semgrep), and sees the codebase as it actually is — not as the previous worker
left it in their mental model.
This is not a workaround. This is the design.
And there is a second reason this works:
agentic code generation naturally overproduces. It leaves duplicate surfaces, parallel contracts, half-finished abstractions, "helpful" wrappers, fallback paths, and uncollapsed naming. Marbles exists to metabolize that excess. It does not merely fix bugs. It distills the codebase until one runtime truth starts to win.
The orchestrating agent (partner, operator) prepares the plan. The implementing agent receives it as a plain task. The framing matters:
The worker enters with a mission, not a maintenance ticket.
Good framing:
Bad framing:
The worker should feel like the best person for the job walking into a project that needs them — not like cog #4 on a conveyor belt.
Why-matrix is a map of styles, not a hierarchy of worth.
vc-initEvery round begins with vc-init. No exceptions.
The agent must perceive the project through live instruments before touching code:
This is perception, not research. The agent is not building a mental model of the project's history — it is seeing what exists now.
Without vc-init, the agent invents its own reality. With it, the agent works
from evidence.
Instruments (loctree, semgrep, aicx-steer) go at the beginning. They direct where to look. They are prosecution — accusing the tree with evidence.
Tests (pytest, cargo test, build checks) go at the end. They verify the fix. They are the gate — confirming the fortification holds.
If the agent runs tests first, its field of vision collapses to "what fails" instead of "what is fragile." Red tests scream loudest, but the real structural weakness is often silent. Instruments find the silent ones. Tests confirm the fix.
One invocation of vc-marbles performs one bounded truth-convergence round:
This is not "pick one tiny task and implement it."
The round may be small in surface area, but its purpose is large: reduce uncertainty in the codebase and move the system toward one stable model of itself.
Do not:
If the operator explicitly asks for historical comparison or forensics, that is a different task.
Default vc-marbles execution is blind.
When the round ends, the worker leaves.
Only these outputs survive the round:
Everything else is disposable.
Allowed inputs:
Not allowed as implicit inputs:
These are lenses, not a fixed staircase. Use the one that matches the weakest live surface.
A round may touch one lens or a tightly coupled cluster. Do not force a pillar order if the evidence says otherwise.
Tools = Prosecution
They accuse the fragile surface with evidence.
Use:
vc-loctreeAgent = Fortifier
You do not guess. You do not theorize first. You fortify where the evidence is loudest.
Execution backend:
vc-agents as the default first choice whenever the task benefits from model-specific strengths.vc-delegate only when the task is small, bounded, and model-agnostic.Other marbles may exist in parallel. They are not your context.
Do not:
Work only inside your assigned tree, worktree, or lane.
HARD RULE: Never change branches. Never create branches in the user's repo-root.
The operator chose the current branch. That decision is not yours to revisit.
If the current path is unusable, create or use a git worktree.
The repo-root branch is sacred because concurrent work may depend on it.
vc-marbles is allowed to commit.
One round = one commit.
No partial commits. No squashing across multiple marble rounds. No mining git history to decide your subject line.