Concepts

This is the single nomenclature reference for how work is organized in YOLO Studio. Every other page in these docs uses the terms defined here and links back rather than redefining them.

The model is small on purpose. There is one place work is described (a ), one kind of work item (a ), one kind of relationship between items (a ), and one place the truth about what happened is recorded (an ).

The shape of it

Two ideas carry most of the weight:

Admission is intent; completion is truth. Where a card sits is a statement about what should happen. What a card produced is a separate, system-written fact. A column may carry the first and must never carry the second.
A board is a queue, not a run. It has no terminal success state. Work is added and drained continuously; “nothing is eligible right now” is not “the objective is met”.

The primitives

Board

The kanban board — the mutable, realtime record of intent: what should happen and in what order.

A board owns:

its columns, one of which is the drainable column
the cards on it, and their order within each column
board-level settings

Boards and cards live in their own collections. The kanban tile you see in a workspace is a view of the board, not the board itself — closing the tile changes nothing about the board or any work in flight.

Both humans and the root orchestrator edit a board. That is the point: intent is expected to change while work is running.

Card

One unit of work, with a prompt. This is the only work type — there are no step modes.

A card owns:

a prompt describing the work
acceptance criteria — what would make it checkably done
its dependencies (see below)
its column and position within that column
its , once it has run

Verification is not a different kind of thing. A review, a test run, a check on someone else’s work — each is a card that depends on another card.

Sizing a card is a question of statability: if you cannot write checkable acceptance criteria for it, it is too big or too vague. Split it until you can.

Dependency edge

The only edge type: a card’s “blocked by” list. The structure is cycle-safe.

A dependency expresses necessity, never ordering. The test to apply before adding one:

Could this card start and produce something useful if the other had not run?

If the answer is yes, there is no edge — even if you would prefer one to go first. Preference is ordering, and ordering is expressed by card order within a column.

Over-drawn dependency edges are the common failure: they serialize work that could have run in parallel, and they do it invisibly.

Drainable column and admission

Exactly one column is drainable — it is a setting, not a property of a card. Cards sitting there are admitted: “this may be picked up”.

You choose the column in the Background Runner’s settings, or from its board picker when you start it. A board created with To do / Doing / Done columns has To do filled in as the drainable column, so connecting it is one step. Nothing drains until a board is connected, and a column’s name alone never makes it drainable.

Admission does not make a card ready. Dependencies still decide eligibility; a card can sit admitted for a long time because something it is blocked by has not produced a successful outcome yet.

There is exactly one drainable column because two would require an arbitration rule between them — and an arbitration rule is scheduling policy, which is the thing this model is trying not to accumulate.

Outcome pointer

The system-written record of what a card actually produced: the lane it ran in, its exit status, the artifact, the commit SHA, and when this was observed.

Three rules about it, and they are the load-bearing part of the whole model:

It is system-written only. Never written by a human, never declared by the agent that did the work.
Readiness reads the outcome pointer, never a column. A card dragged into a “done” column with no successful outcome pointer does not unblock the cards that depend on it. Moving a card is a statement of intent, and intent cannot make something true.
The record comes before teardown. Writing the pointer is what releases the lane. The lane is reclaimed only after that, once nothing in it would be lost.

In practice, this is the card’s outcome field, written by the system when a Background Runner lane exits. Commit-backed dependencies additionally require the outcome’s commit to have landed on its target branch.

Lane

The execution vehicle for a card: git clone <workspace> ~/lanes/<name> — a full clone with its own index, in the same pod on the same volume as the workspace.

That makes a lane git-state isolation only. It is not resource isolation and it is not a security boundary: agents in different lanes share the pod’s CPU, memory and filesystem. What they do not share is a git index, which is what makes parallel work on the same repo safe.

A lane is not the unit of work. The card is the unit of work; the lane is where it happens.

Worker and scout

A is an agent dispatched to execute one card. It gets the card, a lane, a claim on that card, and — when it finishes — an outcome pointer written on its behalf. A worker is dispatched; it never selects its own work.

A is read-only and ephemeral. It has no lane and no card. It looks something up and reports back.

The dividing line is write access: a spawn that can write is a worker, and a worker needs a card. If you find yourself wanting an agent to “just quickly change one thing” without a card, that is a worker without a card, and the outcome of its work will not be recorded anywhere the board can read.

Artifact

A work product whose existence and content are observable facts — a file at a path the card’s acceptance criteria named, or a commit.

Distinguish an artifact from a result declaration: the worker’s own account of how it went. The declaration may be useful to read, but it is opinion, and nothing schedules off opinion. When a card claims success, what makes that actionable is the artifact, not the claim.

Root orchestrator

The agent that curates intent and interprets results: it decomposes an objective into cards, authors their prompts, reads outcomes, and proposes follow-up work.

What it does not do: compute readiness, hold a lease, or dispatch. Those are mechanical and belong to the system.

A root orchestrator must be disposable. Kill it mid-flight and a fresh one reconstructs everything it needs by reading the board — because the board, not the orchestrator’s memory, is where intent lives.

Tile

A tile is a view of an entity, never the entity itself. A kanban tile shows a board; an agent tile shows a running agent; a preview tile shows a served port.

Closing a tile never cancels the underlying work. A running agent keeps running when its tile is closed, and a closed tile can be reopened and re-attached.

Dispatch: the drain tick

The dispatch step is deliberately boring and deliberately singular. One call handles one card:

find one ready card — admitted, and with every dependency satisfied by a successful outcome pointer
claim it exactly once
create its lane
spawn its agent

It returns one of three things: spawned, at-capacity, or idle.

In practice, this is the step the Background Runner repeats on each scheduler pass. The runner’s lifecycle modes — “drain-once” (the default: turn off once every source is empty and nothing is running) and “standing” — decide what happens when a tick returns idle; they do not change the tick itself.

Continuous drain

A board is drained continuously. There is no terminal success state, and no surface reports “complete” at board level.

idle means nothing is eligible right now. It does not mean the objective is met — only a human reading the outcomes can say that. This is why a board is never called a “run”: a run is a thing that finishes, and a queue is not.

Worked example

Picture a delivery effort: an auth migration, then a credential layer that needs the migration in place, then an agent resolver that needs both — and a review of each before it counts.

On a board that is:

Six cards, not three. Each piece of work is a card, and each review is a separate card that depends on the work card. Verification is not a mode; it is a dependency.
The credential card is blocked by the migration card, because it genuinely could not produce anything useful first. The resolver card is blocked by the credential card for the same reason. Nothing else gets an edge — the two review cards depend only on the work they review, so review of the migration can run while the credential work is still going.
Each card carries acceptance criteria concrete enough to check: not “migration works”, but the path of the file that must exist and the command that must exit zero.
All six cards are moved into the drainable column, which admits them. Admission alone does not start a card — the migration card starts immediately because it is blocked by nothing, and the credential card waits until the migration card has a successful outcome pointer, not until someone drags the migration card to “Done”.
When the resolver card finishes, its outcome pointer records the lane, the exit status, the commit SHA and the artifact. Whether that commit is merged is decided by the workspace’s landing mode: left for you, opened as a PR for review, or merged automatically within your repository’s checks and review settings.

Naming

Plain nouns, no prefix family. A card is a card, a board is a board.

Lane, Runner, Tile and Desktop are infrastructure details. They describe where and how work runs, not what the work is.

Where to read next

Workspaces — what a workspace contains and how tiles fit together
Workspace MCP Server — the tools agents use to read and change a board
Glossary — every term on one page
Background Runner — dispatches cards into isolated agent lanes
Loops — iterate an agent toward exit checks