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.

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

For dispatch, backlog supervision and failed runs, use
orbit-orchestrate. For machine, repository,
MCP, automation or upgrade configuration, use orbit-setup.

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.