> ## 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.

# Work commands

> Start, remove and read what the factory is working on.

These commands start, remove and read work items, the issues on the factory's Work page. None of them sends session content.

Every command takes `--json`, plus `--url` and `--app-id` when your config lacks them. A failed command prints the reason and exits `1`.

## outerlayer work build

Start work on an item. A host builds it, or with `--local` you do.

```bash theme={"system"}
outerlayer work build --issue <n> [--repo <owner/name>] [--note <text>]
outerlayer work build --issue ENG-123 [--tracker linear|jira] [--repo <owner/name>]
outerlayer work build --item <number> [--note <text>]
outerlayer work build --issue <n> --local [--repo <owner/name>]
# every form also takes [--session-id <id>] [--retry <count>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--issue <n>` | none | Issue number, or a Linear or Jira key like `ENG-123`. Adds the item to Work if needed. |
| `--tracker <linear\|jira>` | none | The key's tracker. Needed only when both are connected. |
| `--item <number>` | none | An item already on Work. Not with `--local`. |
| `--local` | off | You build it. No host takes it. |
| `--repo <owner/name>` | checkout's remote | The repository. A Linear or Jira key never uses the remote: pass `--repo` to attach one. |
| `--note <text>` | none | A note stored with the request. |
| `--session-id <id>` | detected | Session id to record as-is. |
| `--retry <count>` | `0` | Resend up to 4 times after a 5xx or 429, never after a network error. A non-integer means no retries. A build request is not idempotent, so a retry can record it twice. |

```bash theme={"system"}
outerlayer work build --issue 42           # a host builds it
outerlayer work build --issue 42 --local   # you build it
```

Without `--local`, the command records a build request naming who asked. A host takes the item when it has a free slot. Only a build request makes an item startable for a host. The command never links your session or takes a claim. A failed build never retries itself: run `work build` again.

With `--local`, the item goes on Work with no build request, so no host takes it. The command prints:

```text theme={"system"}
branch: outerlayer/acme-factory/7
start your session with: OUTERLAYER_WORK=7 claude
```

With `--json`, these are the `branch` and `launchCommand` fields. That session links itself and holds the item's claim. An item already on Work needs no `--local`: start a session with `OUTERLAYER_WORK=<number>`.

A Linear or Jira key must belong to a team or project the factory connected, and the tracker must be able to read it.

| Refusal | What to do |
| - | - |
| `--local takes --issue, not --item` | Start a session with `OUTERLAYER_WORK=<number>`. |
| `repository_not_connected` | Connect the repository, or fix `--repo`. |
| `tracker_not_connected` | Connect the tracker, or check the key. |
| `tracker_ambiguous` | Pass `--tracker`. |
| `work_item_not_found` | Check the `--item` number. |
| Warning: a container host will fail this build | Ask again with a member's own key or login, not a host key. |

See also: [Launch a session](/launch-a-session), [Run work on your machines](/run-work-on-your-machines), [Connect a tracker](/connect-a-tracker).

## outerlayer work link-session

Link the calling session to an existing item. The session hooks run this for you.

```bash theme={"system"}
outerlayer work link-session <number> [--session-id <id>] [--retry <count>] [--no-lease] [--ended]
```

| Flag | Default | What it does |
| - | - | - |
| `<number>` | required | The item's number. |
| `--session-id <id>` | detected | The session to link. |
| `--retry <count>` | `0` | Resend up to 4 times after a network error, 5xx or 429. Linking is idempotent, so a retry is always safe. |
| `--no-lease` | off | Link only, with no claim. A host's own build uses it. |
| `--ended` | off | Release the session's claim instead. |

```bash theme={"system"}
outerlayer work link-session 7
```

It also takes or renews the session's 20-minute [claim](/concepts) on the item. If a host or another session holds one, the output names the holder and no claim is taken. Linking twice is a no-op.

| Refusal | What to do |
| - | - |
| `no session id detected` | Run it from a live session, or pass `--session-id`. |
| `work_item_not_found` | Check the number, or create the item with `work build --local`. |
| `work_item_withdrawn` | Add the issue again with `work build`. |

See also: [Launch a session](/launch-a-session).

## outerlayer work remove

Withdraw your own addition of an item, recording why. Nothing is deleted.

```bash theme={"system"}
outerlayer work remove (--item <number> | --issue <n> [--repo <owner/name>]) --reason <text>
```

| Flag | Default | What it does |
| - | - | - |
| `--item <number>` | none | The item's number. |
| `--issue <n>` | none | The issue number in `--repo`. |
| `--repo <owner/name>` | checkout's remote | The repository for `--issue`. |
| `--reason <text>` | required | Why. |

```bash theme={"system"}
outerlayer work remove --item 7 --reason "done"
```

The item leaves Work once no live addition remains. Removing again succeeds and changes nothing.

| Refusal | What to do |
| - | - |
| `not_your_addition` | Withdrawing someone else's addition needs **Withdraw others' work**. |
| `no live item for <repo>#<n>` | Check `--issue` and `--repo`, or use `--item`. |

## outerlayer work status

Print one item's stage, section, gate results, linked pull requests and sessions, and additions, as JSON. The output is indented; with `--json` it is one line.

```bash theme={"system"}
outerlayer work status (--item <number> | --issue <n> [--repo <owner/name>])
```

| Flag | Default | What it does |
| - | - | - |
| `--item <number>` | none | The item's number. |
| `--issue <n>` | none | The issue number in `--repo`. |
| `--repo <owner/name>` | checkout's remote | The repository for `--issue`. |

```bash theme={"system"}
outerlayer work status --item 7
```

`no live item for <repo>#<n>`: check `--issue` and `--repo`.

## outerlayer work list

List live work items.

```bash theme={"system"}
outerlayer work list [--repo <owner/name>] [--stage spec|build|review]
                     [--section attention|waiting|flowing]
                     [--unclaimed] [--claimed] [--startable] [--needs amend]
```

| Flag | Default | What it does |
| - | - | - |
| `--repo <owner/name>` | checkout's remote, else all | The repository to list. |
| `--stage` | all | `spec`, `build` or `review`. |
| `--section` | all | `attention`, `waiting` or `flowing`. |
| `--unclaimed` | off | No live claim, a host's or a session's. |
| `--claimed` | off | A live claim. Each line names the claim's host, kind, start time and expiry, or the member for a local session. With `--json`, each row carries the `claim` object. |
| `--startable` | off | An unused build request and no live claim. The [runner](/reference/cli-runner) takes work from this. |
| `--needs amend` | off | An open pull request, a person's unanswered `fail` on the general thread, and no live claim. Each row's `threads` names the thread waiting. |

```bash theme={"system"}
outerlayer work list --claimed
```

`--claimed` with `--unclaimed` is refused (`invalid_query`). Linked sessions and pull requests never block an item.

## outerlayer work comment

Post one comment on an item's general thread, or on one criterion's thread.

```bash theme={"system"}
outerlayer work comment --item <n> [--criterion <id>] --body <text>
                        [--artifact <id>] [--pass|--fail|--attach|--ready]
                        [--session-id <id>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--item <n>` | required | The item's number. |
| `--criterion <id>` | general thread | The criterion thread to post on. |
| `--body <text>` | empty | The text. |
| `--pass`, `--fail` | off | A person's verdict on the whole item, on the general thread. |
| `--attach` | off | Make `--artifact` the criterion's current proof. Needs `--criterion`. |
| `--artifact <id>` | none | The artifact to attach. Only with `--attach`. |
| `--ready` | off | An agent hands the thread back to a person after answering a fail. |
| `--session-id <id>` | detected | The posting session. It only narrows what the comment may do. |

Give at most one of `--pass`, `--fail`, `--attach`, `--ready`.

```bash theme={"system"}
outerlayer work comment --item 7 --criterion AC-9-01 --body "fixed" --artifact 3f2a1c9d --attach
```

A verdict naming a criterion is refused with `verdict_on_criterion` and nothing is stored. A plain comment starts no agent: only a person's `fail` on the general thread does.

| Code | What to do |
| - | - |
| `verdict_on_criterion` | Drop `--criterion`. Note a criterion with a plain comment. |
| `verdict_needs_person` | An agent session or a factory key cannot record a verdict. Run it yourself, outside the session, with your own login, or record it on the work item page. |
| `not_reviewable` | Nothing is evaluated yet. Wait for the first evaluation. |
| `artifact_needs_attach` | Add `--attach`, or drop `--artifact`. |
| `attach_needs_criterion` | Name the criterion. |
| `artifact_not_found` | The artifact is unknown, superseded, or not on this item. Emit it for this item. |
| `artifact_criterion_mismatch` | Attach it on the criterion it was emitted for. |
| `ready_needs_agent` | Only an agent posts `--ready`. |
| `comment_conflict` | Post it again as a new comment. |

See also: [Review and merge](/review-the-work).

## outerlayer work threads

Print an item's general thread, then each criterion thread with proof or a comment, and who each waits on.

```bash theme={"system"}
outerlayer work threads --item <n>
```

| Flag | Default | What it does |
| - | - | - |
| `--item <n>` | required | The item's number. |

See also: [Review and merge](/review-the-work).

## outerlayer work pr

Declare that a pull request belongs to this session's work item. Running it twice is a no-op.

```bash theme={"system"}
outerlayer work pr <number> [--repo <owner/name>] [--session-id <id>]
```

| Flag | Default | What it does |
| - | - | - |
| `<number>` | required | The pull request number. |
| `--repo <owner/name>` | checkout's remote | Its repository. |
| `--session-id <id>` | detected | The session declaring it. |

```bash theme={"system"}
outerlayer work pr 481
```

| Refusal | What to do |
| - | - |
| `no active session detected` | Run it in the session that opened the pull request, or pass `--session-id`. |
| `this session is not launched on a work item` | Start the session with `OUTERLAYER_WORK=<number>`. |
| `<repo> is not a workpiece of this factory` | Connect the repository, or fix `--repo`. |

See also: [Declare a pull request](/declare-a-pull-request).

## outerlayer work open-pr

Open this session's pull request, or edit the one already open on its branch.

```bash theme={"system"}
outerlayer work open-pr --title <text> --body-file <path> [--repo <owner/name>] [--session-id <id>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--title <text>` | required | The title. |
| `--body-file <path>` | required | A file holding the description. |
| `--repo <owner/name>` | checkout's remote | The repository, on the `gh` path. |
| `--session-id <id>` | detected | The declaring session, on the `gh` path. |
| `--json` | off | Prints `{ repository, number, url, created }`. `created` is `false` for an edit. |

```bash theme={"system"}
outerlayer work open-pr --title "Add the thing" --body-file pr.md
```

* **Host build** (an [item key](/concepts) is the credential): the gateway opens or edits it as the factory's GitHub App, from the claim's branch. No `gh` runs. `OUTERLAYER_WORK` must be set. Refusals: [Opening the pull request](/reference/cli-runner#opening-the-pull-request).
* **Your own session**: runs `gh pr create`, or `gh pr edit`, under your login, then declares it as [`work pr`](#outerlayer-work-pr) does. If declaring fails, run `work pr <number>`.

Run it again after changing the title or description.

See also: [Declare a pull request](/declare-a-pull-request).

## outerlayer work claim, renew, release

Take, extend or give up a host's [claim](/concepts) on an item, so two hosts never build it at once. The [runner](/reference/cli-runner) makes these calls. `release` also gives up the calling session's own lease. Flags, help text and outcomes call a claim a *lease*.

```bash theme={"system"}
outerlayer work claim --item <n> --kind implement|amend [--host <name>] [--seconds <n>]
outerlayer work renew --item <n> [--host <name>] [--seconds <n>]
outerlayer work release --item <n> [--host <name>] [--session-id <id>] [--outcome <outcome>]
```

| Flag | Default | What it does |
| - | - | - |
| `--item <n>` or `--issue <n>` | one required | The item, or the issue in `--repo`. |
| `--repo <owner/name>` | checkout's remote | The repository for `--issue`. |
| `--kind` | required on `claim` | `implement` or `amend`. |
| `--host <name>` | this machine's hostname | A label. The key that took the claim holds it. On `release`, giving it keeps the release to a host's claim. |
| `--session-id <id>` | detected | On `release`: the session whose lease to release, when it cannot be detected. |
| `--seconds <n>` | `900` | Claim length, capped at 900. |
| `--outcome` | none | On `release`: `ok`, `incomplete`, `failed`, `timed_out`, `idle`, `lease_lost`, `interrupted` or `stopped`. |

```bash theme={"system"}
outerlayer work claim --item 7 --kind implement
```

Claiming again with the same key extends the claim. Releasing twice returns the recorded release time and outcome both times. A release with an outcome shows as an attempt on the item's page.

`outerlayer work release` also releases the calling session's own lease. A session that names an item holds a lease on it, and the item's review stays closed until that lease ends. Run inside a session with no `--host`, the command releases that session's lease, so review opens without closing the session. It never releases another session's lease, and `--outcome` applies only to a host's claim. Releasing a session's lease needs `work.insert`, not `work.claim`. A later tool call in the same session takes the lease again. The `build` skill runs this as its last step in a local session.

```bash theme={"system"}
outerlayer work release --item 7
```

| Code | What to do |
| - | - |
| `work_item_claimed` | Another host or session holds it. Wait for release or expiry. |
| `claim_not_held` | A different key holds it. Use the key that took it. |
| `work_item_not_requested` | `implement`: run `outerlayer work build` first. `amend`: no thread waits on an agent since the last attempt. |
| `claim_expired` | `renew` found no live claim. Claim again. |
| `work_item_withdrawn` | Add the issue again with `work build`. |
| `runner_upgrade_required` | Upgrade `@outerlayer/cli`. |

See also: [Run work on your machines](/run-work-on-your-machines).

## Permissions

| Command | Needs |
| - | - |
| `build`, `link-session`, `pr`, `open-pr` on your own login, `comment` (plain or `ready`) | Add work |
| `comment --attach` | Emit evidence |
| `status`, `list`, `threads` | View the Work page |
| `remove` | Add work, plus View the Work page with `--issue`, plus Withdraw others' work for someone else's addition. |
| `claim`, `renew`, `release` of a host's claim | Claim work items. No dashboard role has it: a claim belongs to a host. |
| `release` of the calling session's own lease | Add work, the permission `link-session` needs. |
| `comment --pass`/`--fail` | Record a review. Your own login or dashboard session carries it. A factory key or an agent session is refused with `verdict_needs_person`. |


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