> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The Work page

> Add an issue to the Work page, start its build, and find work items by status, label or text.

The Work page lists the factory's work items. Use it to add an issue, start a build and find the items that wait on you. Select a row to open the item's page, where you review the work. See [Review and merge](https://docs.outerlayer.ai/review-the-work.md).

## Add work

Add an issue to the Work page to make it a work item and start its build.

To start work that has no issue yet, see [Draft a spec on a work item](https://docs.outerlayer.ai/draft-a-spec.md).

You need the **Add work** permission. The button is off until the factory has a connected repository. A build needs a runner. See [Set up a host](https://docs.outerlayer.ai/set-up-a-host.md) or [Run the runner in a container](https://docs.outerlayer.ai/run-the-runner-in-a-container.md).

1. Choose **Add work**.
2. If the factory has more than one source, pick one in **Source**. A source is a repository, a Linear team or a Jira project.
3. In **Find an issue**, type the issue's key, its URL, or words from its title or a label.
4. To list only the issues with a label, choose **Label** and pick one.
5. Choose **Build** beside the issue.
6. If **Run this build on** shows, pick **Managed runners** or **Self-hosted runners**.
7. Write **Instructions for the agent** if you want. See [Give a build instructions](#give-a-build-instructions).
8. Choose **Build**.

![The Add work dialog for the repository acme/web: a Find an issue box, a Label menu, and two open issues, each with Build locally and Build](https://mintcdn.com/outer-layer/vHQEixgdCuVgMGb1/images/add-work-dialog.png?fit=max\&auto=format\&n=vHQEixgdCuVgMGb1\&q=85\&s=2b9106cfac0daf4f2e07c1043f6de07c)

The Add work dialog lists the open issues of a source.

The item's page opens. A runner claims the item and builds it.

**Run this build on** shows only when the factory can use managed runners, which OuterLayer runs. See [Managed runners](https://docs.outerlayer.ai/build-security.md#managed-runners).

An issue that is already on the Work page shows **Already added**. To build an issue in a session of your own, choose **Build locally** instead of **Build**. See [Debug a build in your own session](https://docs.outerlayer.ai/launch-a-session.md).

## Give a build instructions

Instructions are text for the agent that runs one build, up to 2,000 characters. The agent reads them as guidance from you. They never change which issue is built or which checks run. The issue's criteria win if the two disagree.

You can give instructions in four places:

* **Add work.** Write them in **Instructions for the agent**, in the second step.
* **The first build of an item that is not started.** Write them in the note field beside **Build** on the item page. See [Build an item that is not started](#build-an-item-that-is-not-started).
* **A rerun.** Write them in the rerun dialog on the item page. See [Rerun a Stuck item](https://docs.outerlayer.ai/review-the-work.md#rerun-a-stuck-item).
* **The CLI.** Pass `--instructions <text>` to [`outerlayer work build`](https://docs.outerlayer.ai/reference/cli-work#outerlayer-work-build).

Instructions belong to one build request. You cannot edit them after you send the request, and a later rerun does not reuse them. The **Activity** section of the item page shows them with the request.

A rerun of an item with an open pull request is an amend. An amend does not use instructions, and the dialog says so.

## Start a build with a label

Add the label `outerlayer-build` to an issue in GitHub, Linear or Jira. OuterLayer adds the issue to the Work page if needed and starts a build for you. You do not open the dashboard or a terminal.

The build belongs to the person who added the label. OuterLayer matches that tracker user to a member:

* **GitHub:** your GitHub account must be the one you signed in to OuterLayer with.
* **Linear and Jira:** the email on your tracker account must equal your OuterLayer sign-in email. In Jira, your profile must show your email.

You also need the **Add work** permission.

Only adding the label starts a build. Removing it, adding another label or editing the issue starts nothing. The label matches in any letter case. If the issue's item has an open pull request, the label starts a rerun. It starts nothing when no review waits on an agent.

OuterLayer replies with one comment on the issue. The comment links to the work item, or says why no build started. A reply needs a tracker connection that can write. See [Replies need a write grant](https://docs.outerlayer.ai/connect-a-tracker.md#replies-need-a-write-grant). The build starts with or without the reply.

An item has at most one build queued or running. If you add the label again during a build, no second build starts. A label on an issue in a repository, team or project that the factory does not read starts nothing.

### Change the label or turn it off

You need the **Edit factory settings** permission.

1. Open **Settings**, then **Automations**.
2. Under **Issues**, choose **Start a build from a label**.
3. To stop labels starting builds, turn the switch off.
4. To change the label, choose **Edit**, enter the label and choose **Save**.

The label has 1 to 50 characters and no spaces. It applies to every repository, Linear team and Jira project of the factory.

The same page shows the run log: each time someone added the label, and what OuterLayer did. See [Read the run log of a built-in automation](https://docs.outerlayer.ai/automations.md#read-the-run-log-of-a-built-in-automation). To act on new or labelled issues with rules of your own, see [Automations](https://docs.outerlayer.ai/automations.md).

## Build an item that is not started

Some items are on the Work page with no build. An [automation](https://docs.outerlayer.ai/automations.md) adds one when its issue must wait for a member. **Build locally** adds one for a session of your own. Such an item reads **Not started**.

Read the issue before you build it. You need the **Add work** permission to start the build.

1. Open the item from the Work list.
2. To give the agent instructions, write them in the note field at the foot of the page.
3. Choose **Build** at the foot of the page.

![A work item page that reads Not started. A card says that nobody has asked for a build yet. The bar at the foot of the page has a note field and the Build button](https://mintcdn.com/outer-layer/vHQEixgdCuVgMGb1/images/item-not-started-build.png?fit=max\&auto=format\&n=vHQEixgdCuVgMGb1\&q=85\&s=cb006754177fc59603b9739a16f6e660)

A Not started item, with Build at the foot of the page.

The foot of the page then says that the build is queued, and who asked for it. A runner takes the item as it takes any other build. If no runner can take it, the item reads **Not picked up**. See [When nothing is building an item](https://docs.outerlayer.ai/troubleshoot-builds.md#when-nothing-is-building-an-item).

You can also start the build in one of these ways:

* Run `outerlayer work build --item <number>`. The number is the one before the item's title on the Work page. See [`outerlayer work build`](https://docs.outerlayer.ai/reference/cli-work#outerlayer-work-build).
* Add the build label to the issue. See [Start a build with a label](#start-a-build-with-a-label).

## The Work list

The list has two tabs. **Open** groups its items by status, with the items that wait on a person first. **Closed** holds every item that shipped or whose issue closed, the most recently closed first. Each tab shows 25 items on a page.

![The Work page on its Open tab: five items grouped under Ready for review, Build failed, Approved, Building and Not started, with columns for criteria, build, pull request, sessions, comments, cost and age](https://mintcdn.com/outer-layer/vHQEixgdCuVgMGb1/images/work-list.png?fit=max\&auto=format\&n=vHQEixgdCuVgMGb1\&q=85\&s=bc1debbb073af7058fac0e448641876e)

The Open tab groups items by status.

### Filter the list

The box above the list holds the whole filter as text, such as `is:open status:stuck sort:cost`. Type in it, or use the **Status**, **Repository**, **Label**, **Builder**, **Asked by** and **Sort** menus beside it. Each menu writes its choice into the box.

The filter is in the page address. Bookmark a filtered view, or send its address to someone.

| Qualifier | Values | Matches |
| - | - | - |
| `is:` | `open`, `closed` | The tab. The default is `is:open`. |
| `status:` | The words for a status you read: `needs-you`, `review`, `approved`, `failed`, `attention`, `in-progress`, `draft`, `not-started`, `no-change`. The words that also look at checks and reviews: `building`, `stuck`, `ready`, `with-agent`, `back`, `merging`, `shipped`. | The item's status. See [Find an item by its status](#find-an-item-by-its-status). |
| `repo:` | A repository, such as `acme/web-app` | The repository of the item's issue. |
| `builder:` | `local`, or a runner's name such as `build-01` | The runner that builds the item now. `local` is a session on a person's machine. |
| `by:` | `me`, or a person's name with each space written as `-`, such as `sam-rivera` | The person whose build or session works on the item now. |
| `label:` | A tracker label, such as `bug`. Write a space as `-`: `label:needs-design` matches "Needs design". | A label on the issue in GitHub, Linear or Jira. Case does not matter. |
| `sort:` | `newest` (the default), `oldest`, `cost` | The row order. `cost` puts the highest cost first. Open shows one list, not groups, under `oldest` and `cost`. |

* A comma means OR within one qualifier: `status:stuck,back`.
* Different qualifiers combine with AND. Two `label:` qualifiers also mean AND: `label:bug label:ui` matches only an item with both.
* Any other word matches the item's title, its number, its issue key or one of its labels. Every word must match.
* `builder:` and `by:` match only an item that someone builds now, so they match nothing on Closed.
* On Closed, `status:` matches only `shipped`.

### Saved filters

The **Saved filters** menu, beside **Add work**, replaces the text in the box with one of five filters:

| Filter | Query |
| - | - |
| Everything open | `is:open` |
| Waiting on me | `is:open status:ready,back` |
| Stuck | `is:open status:stuck` |
| Asked by me | `is:open by:me` |
| Most expensive | `is:open sort:cost` |

**Waiting on me** leaves out an item with a failing check. To see every item that waits on a person, choose **Needs you** in the **Status** menu.

To remove a filter, choose **Clear current filters** under the box.

### What a row shows

| Column | What it shows |
| - | - |
| Title | The status icon, the item's number, the title and up to three labels. Hover the icon for the status name. Select a label to filter by it. |
| Criteria | A bar and a count. *2/5* means two of five criteria are proven. Hover the bar for what the others need. |
| Build | The runner and how long the build has run. After a failed build, *failed on* and the runner's name. |
| Pull request | The item's pull request numbers. On an open item, an icon shows the state of the GitHub checks. |
| Sessions | The number of sessions on the item. |
| Comments | The number of review comments. |
| Cost | The item's total session cost. See [Cost and throughput](https://docs.outerlayer.ai/cost-and-throughput.md). |
| Opened | How long ago the item was added, such as *21h* or *2d*. On Closed, when the item closed. |

A row whose pull request changes a file under `.outerlayer/` says that it changes the repository's rules. See [Require a person's review of rules changes](https://docs.outerlayer.ai/review-the-work.md#require-a-persons-review-of-rules-changes).

Press J and K to move between rows, and Enter to open the selected row.

## Statuses

Each item has one status, on its row and on its page. The status says whose turn it is.

| Status | What it means | What you do |
| - | - | - |
| **Draft** | The item holds a spec and has no issue yet. | Write the spec and approve it. See [Draft a spec on a work item](https://docs.outerlayer.ai/draft-a-spec.md). |
| **Not started** | Nobody has asked for a build. | Start the build. See [Build an item that is not started](#build-an-item-that-is-not-started). |
| **Queued** | A build, or your review notes, wait for a runner. | Wait. |
| **Not picked up** | A build, or your review notes, wait, and no runner can take them. | Read the reason under the item's title. See [When nothing is building an item](https://docs.outerlayer.ai/troubleshoot-builds.md#when-nothing-is-building-an-item). |
| **With agent** | An agent works on the item. | Wait. |
| **Ready for review** | The agent is done and a pull request is open. | Review the item. You can send the work back while checks run or fail. Approve waits for the checks and every proof. |
| **Approved** | A person approved the item. | Merge its pull requests. |
| **Needs attention** | The last build stopped, or work started and no pull request is open. After a failed build, the status reads **Build failed**. | Read the reason under the item's title. Then rerun the item or remove it. See [Rerun a Stuck item](https://docs.outerlayer.ai/review-the-work.md#rerun-a-stuck-item). |
| **No change needed** | The newest build found that nothing needs to change, and it opened no pull request. | Read the build's reason on the item page. Then close the issue, or choose **Build again**. See [When a build finds no change is needed](https://docs.outerlayer.ai/troubleshoot-builds.md#when-a-build-finds-no-change-is-needed). |
| **Done** | Every linked pull request merged. The item is on Closed. | Nothing. |
| **Done, unverified** | A pull request merged while a check was unproven, or after a person requested changes. The item is on Closed. | Read the line under the item's title for what was unproven. |
| **Closed, not shipped** | The issue closed with nothing merged. The item is on Closed. | Nothing. Close a pull request that is still open. |

An item moves to Closed when its issue closes in the tracker. Each tracker has its own rule for a closed issue. See [Connect an issue tracker](https://docs.outerlayer.ai/connect-a-tracker.md).

### Find an item by its status

To filter by a status you read, use the **Status** menu or one of these words:

| Word | Finds |
| - | - |
| `needs-you` | Every item that waits on a person: **Ready for review**, **Approved**, **Build failed** and **Needs attention**. |
| `review` | **Ready for review** |
| `approved` | **Approved** |
| `failed` | **Build failed** |
| `attention` | **Needs attention** for any other reason |
| `in-progress` | **With agent**, **Queued** and **Not picked up** |
| `draft` | **Draft** |
| `not-started` | **Not started** |
| `no-change` | **No change needed** |

The saved filters use a second set of words. These words also look at the item's checks and reviews. Each item matches one word, the first of these that applies:

1. `shipped`: on Closed, every linked pull request merged.
2. `stuck`: the last build or amend failed or timed out, and nobody has asked again.
3. `building`: no pull request is open, a check has not passed, or a declared proof is missing.
4. `with-agent`: an agent holds the item, or a review waits for an agent's answer.
5. `merging`: a person approved the latest push.
6. `back`: a person reviewed the item, and it is your turn again.
7. `ready`: nobody has reviewed the item yet.

The two sets do not match one to one. An item that reads **Ready for review** while a check fails matches `status:building`, not `status:ready`.

## Remove an item from Work

Remove an item when nobody will build it, such as a duplicate issue or a dropped idea. Removing deletes nothing and does not close the issue. The item leaves the Open tab, and its history, sessions and cost stay. To bring the item back, add the issue again with **Add work**.

> [!WARNING]
>
> Removing an item stops its runner build. Work that the build has not pushed is lost.

1. Open the item.
2. Select **Remove from Work** at the top right.
3. Read what the dialog says the removal stops.
4. To leave an open pull request open on GitHub, clear its **Close … on GitHub** box.
5. Enter a reason.
6. Select the button. It reads **Remove from Work**, **Stop build and remove** or **Close pull request and remove**.

OuterLayer records who removed the item, with the reason. If GitHub refuses to close a pull request, the dialog names it and the item stays on Work.

You cannot remove an item that is already on Closed.

You need the **Add work** permission to remove an item that you added. You need **Withdraw others' work** when someone else added the item, or when it has a running build or an open pull request. See [Roles and permissions](https://docs.outerlayer.ai/roles-and-permissions.md).

To remove an item from a terminal, see [`outerlayer work remove`](https://docs.outerlayer.ai/reference/cli-work#outerlayer-work-remove).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.