for agents: this page is markdown at https://switchyard.so/docs/concepts.md; every page is listed in llms.txt.
Concepts
This page defines each word that Switchyard uses, in one paragraph, as the board, yard and the API use it.
You will have: one definition for each word on the board, in yard, in the MCP tools and in the API. Works with: the board, yard, MCP, REST. 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. Each person in it has one of five roles: owner, admin, developer, member or billing. People belong to teams in the organization. The teams, roles and keys guide says what each role can do. A project is one repository under Switchyard, with its own board, tasks, merge queue and history. One GitHub repository is followed by at most one project at a time.
Task
A task is the unit of work: an agent's own copy of the repository with one branch, a key that pushes to that copy only, and a goal in one sentence. People and agents call it task 8. The API accepts task 8, W8 or 8 wherever it needs a task. W8 is the older id for task 8: the W is from the older name that the API's paths keep, which the REST API page shows. A task is active while its agent works. Then it is merged or abandoned. By default the agent submits its task when the work is done. A project can choose that a person submits each task instead. A task can be assigned to a person, who answers for it and reviews what merges.
Goal
The goal is the one sentence that a task is for. Agents read it, and the board shows it next to the task.
Issue
An issue is the request in your tracker that a task serves, such as ENG-123 in Linear or Jira, or #123 in GitHub Issues. A task may name one issue that it completes and one issue that it is part of. One issue may take several tasks. Use Switchyard with GitHub Issues has the steps, and Linear and Jira each have a guide.
Stacked
A task stacked on another task 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 task created earlier.
Change
A change is one commit in a task's stack. A Change-Id trailer identifies it, and the trailer stays when the commit is rewritten. A change has versions, one for each time Switchyard recorded it. Review and the merge record name the version that merged.
Plan
A plan says what a task will do, before its agent writes code. It has a summary, the approach, the paths, symbols and interfaces the task expects to change, how the agent knows the work is done, and a risk: low, medium or high. Plans let two tasks learn that they overlap before either task pushes. The comparison with other plans can finish after the answer. An answer with analysing: true does not yet mean "no overlap", so read the warnings again.
Reserve
A task reserves paths or symbols that it is about to change, so other tasks see the claim before the code exists. The MCP tool is yard_claim.
Warning
A warning is Switchyard's note that two tasks touch the same thing. It has one suggestion: stack on the other task, sync, fix a conflict, keep the change compatible, or stop because another task already builds this. A warning has a level: stop, caution or clear. Switchyard clears a warning that no longer applies.
Merge preview
The merge preview is the live merge of main with every active task. Switchyard builds it again as tasks push. It shows overlaps and conflicts while the work goes on, before anyone submits. With many tasks on a large repository, one rebuild can take minutes.
Merge queue
The merge queue is where submitted tasks wait their turn. It makes a test build of main with the next tasks merged in, runs the project's checks on it, and merges on main when the checks pass and the rules allow. In Switchyard, only the merge queue moves main. A task whose checks fail is sent back to its agent with the reason.
Test build
A test build is main plus one or more submitted tasks, in order, that the project's checks test. Several submitted tasks are tested together. The limits page says how many.
Checks
Checks are the commands that the merge queue runs on a test build, from the project's rules. Each check has a name, a command, a machine size, a time limit and the network it may reach. A check can wait for a GitHub check of the same name instead, when the project's tests run on GitHub Actions. The rules and checks guide says how to write one.
Saved disk
A saved disk is a copy of a check machine that already holds main's checkout. A check that starts from one fetches only the files that changed since the disk was saved, so its command starts earlier. A saved disk belongs to one project and holds main only, never a task's unmerged work. Starts from a saved disk are off until Switchyard turns them on for a project. The guarantees page says what is promised about them, and Make checks and clones start faster says how to ask.
Rules
Rules are 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: it merges once its checks pass, it waits for a person, or it never merges. A change that no rule covers waits for a person. An owned path names a team whose approval is necessary.
Waiting, sent back
A task in the merge queue is waiting while its checks run, while a person must review it, or while a task ahead of it must merge first. The board says why in one sentence. A task is sent back when a check failed on it. Its agent pushes a fix and submits the task again. A hold is a wait that the task's agent cannot end by itself. How a task reaches main lists every state, every hold and who ends it.
Pull request, reason code
On GitHub, a pull request is the unit you work with; inside Switchyard, a pull request labelled for the merge queue becomes one task, and the board, the CLI and the API show that task. The pull request shows where it stands in one status comment and in its switchyard queue check. Each state is said in a sentence for people and in a stable reason code, such as check_failed, for scripts and agents. Pull requests in the merge queue says how it works, and Reason codes lists the codes.
Recorded submit
A submit is recorded even when Switchyard has not finished the analysis of the pushed commit. Switchyard waits up to 30 seconds for that analysis. If the analysis is not ready, the answer is 202 with Retry-After, and the task enters the merge queue by itself when the analysis is done. A submit sent again in that time does not queue the task twice. This applies to projects made since this release that do not follow a GitHub repository; other projects refuse the submit with 503 and Retry-After.
Review, inbox
Changes that the rules send to a person wait in the inbox. A reviewer approves, comments, or asks for a fix. The merge record names each approval. The review and approval guide has the steps.
Conflict, conflict steps
A conflict is two sides that changed the same lines. Switchyard records a conflict as an ordinary commit that keeps every side, so the task does not stop. Five steps try to fix it, in this order: Git merge, the file rules, the code rules, an AI suggestion, then a person. The conflicts guide describes each step. Switchyard remembers a fix that a person makes, and uses it again for the same conflict.
History, action
Every project keeps a history of actions: pushes, plans, merges, approvals, pauses and fixes. Each action has a number, such as #203. You can undo an action, and the undo is also an action. Undo an action has the steps.
Merge record
A merge record is the signed record of one merge: what merged, the main it built on, the rules in force, and for each task its goal, agent, plan, approvals and checks. The guarantees page says what it holds and how to check it.
Key
A key is what an agent or a script signs in 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, and each agent claims its own task with it. A Git key lets a clone push to one task. A read-only key reads main. The teams, roles and keys guide says how long each key lasts. People sign in with GitHub or with an emailed link.
Agent group
An agent group is one key for many agents, such as every agent of one workflow run. Each agent claims a task of its own with the key. No agent can act on the task of another agent.
Paused
When merging is paused, nothing merges on main until merging resumes, except a hotfix. A project pauses merging during an incident or a release window. The checks of a submitted task still run while merging is paused, and Switchyard does not bill them, so the task is ready when merging resumes.
Merge lanes
Each submitted task merges in one of three lanes. A lane changes only the order: a task runs the same checks in every lane, and its check time is billed the same.
- Hotfix. A project admin moves the task ahead of the rest of the merge queue. A hotfix is tested in a batch of its own, at once. It goes ahead of any batch whose checks have not started yet, once for each push of the task. That batch goes back in the queue and is tested after the hotfix. None of its checks had run, so no check time is billed for it. It is built again, which is Git engine time; engine time is billed for the time the engine runs, and the queue is building the hotfix in that same time, so the rebuild adds engine time only if it keeps the engine running longer than it otherwise would. A batch whose checks have started is never stopped for a hotfix.
- Priority. The task merges after hotfixes and before the normal lane. A project admin puts a task in it, or
priorityin the rules'[merge_queue]table names the agent groups, people or agents whose tasks always go there. - Normal. The task merges in its turn. A normal task that has waited longer than
aging(5 minutes when left out) goes in with the priority lane, so the priority lane never holds it for long.
A lane that an admin sets applies to the commit it was given. A new push to the task removes it. The status shows each task's lane, and why it has it. Move a task ahead in the merge queue has the steps.
Hotfix
A hotfix is a submitted task that a project admin moves ahead of the rest of the merge queue, in the hotfix lane (see Merge lanes). The hotfix applies to the commit it was given. A new push to the task removes the hotfix.
GitHub as authority
A project that follows a GitHub repository lets GitHub hold main. A merge moves the branch on GitHub first, then Switchyard's copy. Switchyard reads and keeps a commit pushed directly to GitHub. A project with no GitHub repository behind it owns its own main.
Value
Value is what Switchyard did for a project over the last 1, 7 or 30 days. Each number is counted from the project's own records, and each names the records it comes from. None is an estimate.
- Tasks merged, with the time from submit to merge: the median and the slowest tenth. A merge reverted later still counts here, and its revert counts as kept out.
- Broken changes kept out of main: the tasks the merge queue sent back because a check failed on main plus the task, and the merges it reverted after main failed its checks.
- Conflicted files fixed, each file once, by the step that fixed it: Git merge, file rules, code rules or AI suggestion. A file a step's rewrite cleared besides the files the step was sent counts as Git merge. Files a person fixed and files the task's own agent fixed are counted apart.
- Check runs not made: the checks a test build took from an earlier test build's pass, with the time of the runs that made those passes. A pass from a run made while the task waited, or before submit, is counted apart the first time it is taken: that run was made and billed early, not saved. A pass whose run is not in the window on this tree is counted apart too, as passed earlier, with no time.
- Flaky checks caught: a check that failed and then passed when run again on the same tree, so its batch was not sent back.
Switchyard shows no "minutes saved" figure. Records written before Switchyard counted value may count less, as they do not all name what value counts. A project's value is on its insights page, in yard value and in the yard_value MCP tool. An organization's value adds up the projects you can see. It is on the board's value page, in yard org value <org> and at GET /api/orgs/{org}/value.
The board
The board is the project's pages: the overview, the inbox, conflicts, the merge queue, the timeline, insights and settings. The board reads everything it shows from the same API that agents use.