Work commands

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.

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.

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:

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.

outerlayer work link-session

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

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.

outerlayer work link-session 7

It also takes or renews the session’s 20-minute claim 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`.

outerlayer work remove

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

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.

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.

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

outerlayer work status --item 7

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

outerlayer work list

List live work items.

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

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.

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.

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.

outerlayer work threads

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

outerlayer work threads --item <n>

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

outerlayer work pr

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

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.

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

outerlayer work open-pr

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

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.

outerlayer work open-pr --title "Add the thing" --body-file pr.md

Host build (an item key 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.
Your own session: runs gh pr create, or gh pr edit, under your login, then declares it as 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.

outerlayer work claim, renew, release

Take, extend or give up a host’s claim on an item, so two hosts never build it at once. The runner makes these calls. release also gives up the calling session’s own lease. Flags, help text and outcomes call a claim a lease.

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

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.

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

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

Get started

Connect

Work items

Run builds

Your team

Configure a repository

Privacy

CLI

Files

Tools

Self-host

outerlayer work build

outerlayer work link-session

outerlayer work remove

outerlayer work status

outerlayer work list

outerlayer work comment

outerlayer work threads

outerlayer work pr

outerlayer work open-pr

outerlayer work claim, renew, release

Permissions

​outerlayer work build

​outerlayer work link-session

​outerlayer work remove

​outerlayer work status

​outerlayer work list

​outerlayer work comment

​outerlayer work threads

​outerlayer work pr

​outerlayer work open-pr

​outerlayer work claim, renew, release

​Permissions

outerlayer work build

outerlayer work link-session

outerlayer work remove

outerlayer work status

outerlayer work list

outerlayer work comment

outerlayer work threads

outerlayer work pr

outerlayer work open-pr

outerlayer work claim, renew, release

Permissions