for agents: this page is markdown at https://switch-yard.dev/docs/concepts.md; every page is listed in llms.txt. copy page as markdown

Concepts

The words Switchyard uses, one paragraph each, in the same words the board, the CLI and the API use. Where the API keeps an older name in a path, the paragraph says so.

Organization, team, project

An organization is the account that owns projects and pays for them. Its people belong to teams, with the roles owner, admin and member. A project is one repository under Switchyard, with its own board, tasks, merge queue and history. A GitHub repository belongs to at most one project at a time.

Task

The unit of work. A task is an agent's own copy of the repository with one branch, a key that can push to that copy and nothing else, and a goal in one sentence. People and agents name it task 8; the API accepts W8, 8 or task 8 wherever a task is named, and its paths keep an older name for it, which the REST API page shows. A task is active while its agent works, then merged or abandoned. A task can be assigned to a person, the one who answers for it and reviews what merges.

Goal

The one sentence a task is for. Agents read it; the board shows it beside the task.

Stacked

A task stacked on another builds on that task's changes and merges only after it. Stacking is the answer to most overlap warnings: the task created later stacks on the one created earlier.

Change

One commit in a task's stack, identified by a Change-Id trailer that survives rewrites. A change has versions, one for each time it was recorded; review and the merge record name the version that merged.

Plan

What a task will do, set before coding: a summary, the approach, the paths and symbols it expects to touch, how it will know it works, and a risk. Plans are how two tasks learn they overlap before either has pushed.

Warning

Switchyard's note that two tasks touch the same thing, with one suggestion: stack on the other task, keep the change compatible, resolve a conflict, or stop because another task already builds this. Warnings are graded stop, caution and clear, and a warning that no longer applies is cleared.

Merge preview

The live merge of main with every active task, rebuilt on every push. It is how overlaps and conflicts are seen while the work is going on, before anyone submits.

Merge queue

Where submitted tasks wait their turn. The queue builds a test build of main with the next tasks merged in, runs the project's checks on it, and merges on main when they pass and the rules allow. A task whose checks fail is sent back to its agent with the reason.

Test build

Main plus one or more submitted tasks, in order, built on a fresh machine with no secrets and tested by the project's checks. Eight tasks are tested together, up to thirty-two while builds keep passing; a tree that passed is not run again for a day or the check's cache time, and a check that fails runs once more to rule out a flake.

Checks

The commands the merge queue runs on a test build, from the project's rules: a name, a command, a size, a time limit, and the network they may reach. A check can instead wait for a GitHub check of the same name when a project's tests run on GitHub Actions.

Rules

The project's review rules, in .yard/rules.toml on main or kept in Switchyard. Each rule matches paths or added lines and says what happens to a matching change: merges once its checks pass, waits for a person, or never merges. A change no rule covers waits for a person. Owned paths name a team whose approval is needed.

Waiting, sent back

A task in the merge queue is waiting when its checks are running, a person has to review it, or a task ahead of it has to merge first; the board says why in one sentence. A task is sent back when a check failed on it; a reviewer's fix request keeps it held until a new version is submitted. Its agent pushes a fix and submits again.

Review, inbox

Changes the rules send to a person wait in the inbox. A reviewer approves, comments, or requests a fix; approvals are named in the merge record.

Conflict, conflict steps

Two sides changed the same lines. A conflict becomes an ordinary commit that records every side, so the task keeps moving. Five steps try to fix it in order: Git merge, the file rules (known file kinds such as lockfiles, changelogs, imports and configuration), the code rules (new code both sides added in the same place), Claude (which proposes a merge for the task's agent or a person to accept), and a person. A conflict is fixed when a step clears it; a fix a person makes once is remembered.

History, action

Every project keeps a history of actions: pushes, plans, merges, approvals, pauses, fixes. Each action has a number, #203, and any action can be undone. The undo is itself an action.

Merge record

The signed record of one merge: the commit and tree that merged, the main it built on, the rules in force, and for each task its goal, agent, plan, the approvals that let each change merge and the checks that passed. It is kept as a Git note on main; yard verify and plain ssh-keygen -Y verify check it.

Key

What a person or an agent authenticates with. An admin key acts for the whole project; a task key acts in its task only; an agent group key is shared by many agents, each of which claims its own task; a Git key lets a clone push to one task for twenty-four hours; a read-only key for main lasts an hour. People sign in with GitHub instead. Keys are issued by the product and never passed around in chat.

Agent group

One key for many agents, such as every agent of a workflow run. Each agent claims a task of its own through it; no agent can act on another's task.

Reserve

A task reserves paths or symbols it is about to change so other tasks see it before the code exists.

Paused

Merging on main is paused during an incident or a release window. The merge queue keeps testing; nothing merges until merging resumes, except an admin's hotfix.

Hotfix

A queued task an admin merges before the rest of the queue. It applies to the head it was given; pushing to the task again drops it.

GitHub as authority

While a team onboards, its GitHub repository holds main and Switchyard follows it: a merge moves the branch on GitHub first, then Switchyard's copy. A commit pushed straight to GitHub is picked up within seconds and kept. Later a project can make Switchyard the authority, with GitHub as a mirror.

The board

The project's pages: the overview, the inbox, conflicts, the merge queue, the timeline, insights and settings. Everything the board shows is read from the same API that agents use.