Key concepts

Everything in OuterLayer hangs off a work item. An issue becomes a work item when it is added to a factory’s Work page. Sessions, pull requests, checks and reviews all attach to the item, not to each other. Because checks attach to the item, a check still counts when one pull request is closed and another opens in its place.

The five words you need first

Factory: one team’s Work page, repositories, keys and policy.
Work page: the factory’s list of work items.
Work item: an issue added to the Work page. It gets a number of its own, so issue 42 might be item 7.
Session: one run of a coding agent. It uploads only when you start it with OUTERLAYER_WORK set to the item’s number.
Runner: the outerlayer runner process that builds items unattended, on a machine you run it on. You need one only for Build, not for a session you start.

The tables below define every other term.

Where work lives

Term	What it is
Organization	Your company’s account. It holds members, roles and billing, and one or more factories.
Factory	One team’s unit of work: its Work page, repositories, keys and policy. `appId` in config files and the API is the factory’s id.
Work page	The factory’s list of work items.
Work item	An issue added to the Work page. It gets a number of its own on the factory: issue 42 might be item 7. Commands and `OUTERLAYER_WORK` take the item number, never the issue number.
Item page	One work item’s page. Its tabs are Activity, Criteria, Findings and Checks, with the item’s sessions and pull requests beside them. See Review and merge.
Control plane	One repository that supplies agent instructions and policy to the factory’s other repositories. Older versions of the dashboard called it the context source. See Share instructions across repositories.

Who does the work

Term	What it is
Session	One run of a coding agent. It uploads only when it was started with `OUTERLAYER_WORK` set to an item number. See Launch a session.
Build	One attempt to turn an item into a pull request, either by a runner or in a session you start yourself.
Runner	One `outerlayer runner` process, with its own config file, runner key and name. It claims the items queued with Build and builds them. A runner on a machine of yours is a self-hosted runner. See Run work on your machines.
Host	A machine that one or more runners run on. Two runners on one host, one for each factory, each need their own name. See Several factories, one machine.
Slot	One build a runner can run at a time. `runner.concurrency` sets how many slots a runner has.
Claim	The hold a runner, or a person’s session, has on an item while it works on it. While it lasts, no runner starts the item. It expires unless it is renewed, so a stopped machine never holds an item for long. Error codes, flags and the CLI call it a lease. A session’s claim lasts 20 minutes, and its hooks renew it while the session works. A runner renews its own while the build runs.
Item key	The key a runner’s build uses in place of the runner’s key. It acts only on the claimed item and stops working when the claim ends. See Item key.
Host key	A signing key the runner makes on its host, at `runner/host-key.pem` beside its config file. The first claim binds it to the runner key. The gateway then refuses that runner key from any other host. See The host key.
Pull request	Joins an item when a session on that item declares it. See Declare a pull request.

How the work is judged

Term	What it is
Policy	`.outerlayer/policy.yaml`, read from each pull request’s base branch. It says which checks run and whether a failing one blocks the merge. See Policy and validators.
Validator	A file in `.outerlayer/validators/` that declares one check: its name, the sentence it shows, and what satisfies it.
Check	One named pass or fail on the item, such as “a code review report is attached”. A check holds across every pull request the item has. The item page’s Checks tab lists them.
Check item	One result inside a check, about one thing the check judged: a criterion, a file or a test. It has its own pass or fail and a reason. A failing check item fails its check. See Check items.
Evidence rows	The item’s checks, one row each. They show on the item page’s Checks tab. When Post session summaries on pull requests is on, they also appear in the evidence comment on each pull request.
Acceptance criteria	The list of what the item must do. The item page’s Criteria tab shows the list recorded with `outerlayer emit criteria`. A criterion missing its declared proof flags the verdict.
Artifact	A file attached as proof. Its file type sets its kind: a screenshot, a video, a report, a log, a test result, or a plain file. See Attach evidence.
Review	A person’s pass or fail on the whole item. A review is not a check. Only a person records one, on the item page or with `outerlayer work comment --pass` or `--fail`. See Review and merge.
Finding	A problem an agent hit in the factory while it worked, such as a flaky test or a wrong instruction. Findings never affect whether the work passes.

Where an item stands

Every item has one status that says whose turn it is, from Not started to Done. The list of statuses and what each means is on Review and merge.

Get started

Connect

Work items

Run builds

Your team

Configure a repository

Privacy

CLI

Files

Tools

Self-host

The five words you need first

Where work lives

Who does the work

How the work is judged

Where an item stands

​The five words you need first

​Where work lives

​Who does the work

​How the work is judged

​Where an item stands

The five words you need first

Where work lives

Who does the work

How the work is judged

Where an item stands