orbit git:20261102.cf303d7A

Immutable. This exact content never changes and is served at /api/v1/blob/b1f05e8bce64729f.

---
name: orbit
description: Creates, executes and reviews Orbit tasks; searches task history and friction records; records evidence. Use for an assigned task or task ID, task authoring, `orbit.task`/`orbit.search` MCP tools, `orbit tool run`, task records under `.orbit/`, or friction. Use orbit-orchestrate for `orbit run` dispatch, drains and failed `jrun-*` runs, and orbit-setup for installing or configuring a machine.
---

# Orbit

Work through the authoritative task record and leave verifiable results.
Read only the reference needed for the current action; this is not a reading
checklist. An injected task snapshot is your starting context.

## Operator attention

Start an orchestrator or on-call inspection with `orbit attention --json` or the read-only `orbit.attention` tool. Task-level kinds report pilot warnings and holds, human-waiting blocks, open decisions and settled reviews; `host_unhealthy` reports failing doctor checks and, across registered hosts, hosts that cannot be read. Read `degraded` before interpreting an empty result. See [Attention](references/attention.md) for filters, local scopes, suggested actions and the delta cursor.

## Connect and act

- With MCP, discover its tools. In a managed activity, use the injected task
  and inherited workspace binding; `orbit.workspace.list` may be outside the
  activity allowlist. In an unbound session, call `orbit_workspace_list` and
  copy the returned selector, including host qualification when federated.
  For a CLI-only installation, inspect `orbit workspace list/show` on the
  intended host and use that registered workspace. Never substitute another
  host or shadow store.
- Use registered tools: MCP `orbit_task_show`, or the installed CLI's
  `orbit tool run orbit.task.show --input '{"id":"<task-id>","model":"<agent-family>"}'`.
  Include your agent family in `model` where supported. Use `fields` for compact
  reads. The advertised schema decides which inputs and tools are available.
- Update task state through tools, not files under `.orbit/`. Creating a task
  does not authorize dispatch or completion. In a managed activity, implement
  the assigned work; the pipeline owns delivery and lifecycle transitions.
- Verify artifacts, task/run state, diffs and checks. Agent messages are
  advisory. Do not report skipped validation as passing or merged as deployed.
- To check a UI change in a browser, use the host's headless browser kit:
  when it is verified, your environment carries `PLAYWRIGHT_MODULE`,
  `PLAYWRIGHT_BROWSERS_PATH` and `ORBIT_BROWSER_KIT_ENV`. Source
  `"$ORBIT_BROWSER_KIT_ENV"` in the shell that runs the check
  ([Task execution](references/task-execution.md#checking-a-ui-in-a-browser)).
- Use the installed `orbit` binary, never `cargo run -- ...`. Bare
  `orbit task ...` subcommands are the human surface and skip agent
  provenance; agents call `orbit tool run orbit.task.*`. Task IDs come from
  `orbit.task.add`; never invent one. Only a human can force an off-table
  transition (`orbit task update --force` or the dashboard); `orbit.task.update`
  and MCP have no `force`.

## Desktop navigation

When the connected client advertises `orbit_ui_open` / `orbit_ui_inspect`, use
those read-only entrypoints to open the control center or a selected task/run.
Discover workspaces first and copy the exact returned selector; pass `workspace`
and public `id` together, with `kind: run` for a run. Keep ordinary task tools
available when the client cannot render the UI.

The panel can capture proposed tasks, edit allowed fields, comment and record
reviews through separately guarded desktop tools. A click or conversation
reference grants no operator authority. Reread authoritative task state before
acting on a copied reference. Keep the same request ID/payload when a write's
outcome is unknown; only a definite refusal permits a corrected fresh request.
Native support depends on the actual desktop build and connection; an installed
plugin or passing protocol test alone does not prove rendering/context delivery.

## Choose the reference

| Need | Read |
|---|---|
| Implement an assigned task | [Task execution](references/task-execution.md) |
| Prepare configured agent-filled pull request sections | [Agent-filled PR sections](references/task-execution.md#agent-filled-pr-sections) |
| Set dependencies, relations or validation tools | [Task fields](references/task-fields.md) |
| Create or revise a task | [Task authoring](references/task-authoring.md) |
| Review a delivered diff | [Task review](references/task-review.md) |
| Find prior tasks or frictions | [Search](references/search.md) |
| Run and interpret task-flow analytics | [Task-flow analytics](references/concepts.md#task-flow-analytics) |
| Record a concrete recurring obstacle | [Friction](references/friction.md) |
| Resolve tool transport, permissions or workspace routing | [Tool surface](references/tool-surface.md) |
| Understand Orbit nouns | [Concepts](references/concepts.md) |
| Single-owner distributed drain setup or claimed-attempt recovery | [Distributed drain](references/setup/distributed-drain.md) |

For dispatch, backlog supervision and failed runs, use
[orbit-orchestrate](../orbit-orchestrate/SKILL.md). For machine, repository,
MCP, automation or upgrade configuration, use [orbit-setup](../orbit-setup/SKILL.md).

## Lifecycle essentials

Normal delivery is `proposed → backlog → in-progress → review → done`.
Moving to `in-progress` requires a plan from every status except `backlog`;
starting `proposed`, `someday`, or `blocked` work also needs authorization.
`done` is reachable only from `review` and needs completion evidence. The
lifecycle table does not reopen `done` or `archived`; file a regression as a
new task with a `regression_from` relation. Only an operator's
`orbit task update <id> --status <status> --force` restores them, and
`orbit task archive <id>` is that table's move to `archived` (`done` and
`rejected` are not sources). `rejected` returns to `backlog` or
`in-progress`. Follow supported transitions and the assigned workflow; agents
have no lifecycle force override. A task assigned to a human crew
(`[crews.<name>] kind = "human"`) is operator work: the operator's own
`orbit task update --status` or dashboard status control sets any status from
`proposed` to `done` with no plan, review, evidence or `--force`, and task
history records it as a `forced` entry naming the human-crew bypass. Agents and
MCP stay on the normal lifecycle for that task, and leaving `done` or
`archived` still needs `--force`.

When you need a person to choose between known options, such as a sign-off, a
price or a policy fork, raise `orbit.decision.raise` on a human-crew task you
filed instead of writing a free-text human task: a question, two to four options
(one-line label and consequence, exactly one `recommended`), and a `topic` when
a corpus rule should be able to match the request exactly. The operator answers,
or a current corpus rule the operator marked `auto` answers an exact topic or
rule id and records that answer as precedent. Either way the answer is in the
task's history, completes the task and unblocks its `blocked_by` dependents.
Free text stays for open-ended asks. Raw decision history is not authority.
Only a merged `current` rule may be cited, and only while its review date has
not passed and its `depends_on` digests still match. A stale or superseded
rule is not cited and does not answer. You cannot set `auto`. An answer that
changes lasting behaviour or policy must be carried into the doc, config or
code that owns it, in the PR of the task it unblocks.
Details: [Tool surface](references/tool-surface.md#raising-a-decision).

When you work a task directly in an interactive session instead of through a
drain, set its `context_files` to the files the work will touch as you claim
it, and keep them current as the change grows. Drains schedule around a
task's `context_files`, so an interactive claim without them collides with
queued work.
Set the task's `crew` to the registered crew that actually does the work
(for example `opus`), replacing whatever filing assigned. Crew analytics
attribute outcomes by that field.