orbit

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; runtime kinds report failed or stuck runs and possibly stale claims (Operator capability required); ci_red reports a red base branch and friction_untriaged lists open friction records; host_unhealthy reports failing doctor checks and, across registered hosts, hosts that cannot be read. Read degraded before interpreting an empty result. See Attention 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>"}'. Provenance comes from the session, not a model argument. 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, use its read-only open and inspect actions 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
Prepare configured agent-filled pull request sections	Agent-filled PR sections
Set dependencies, relations or validation tools	Task fields
Create or revise a task	Task authoring
Review a delivered diff	Task review
Find prior tasks or frictions	Search
Run and interpret task-flow analytics	Task-flow analytics
Record a concrete recurring obstacle	Friction
Record and inspect repeated capability costs	Evolution records
Resolve tool transport, permissions or workspace routing	Tool surface
Understand Orbit nouns	Concepts
Act as a manager for resident mandates	Manager
Run one resident cycle for a mandate	Resident cycle
Single-owner distributed drain setup or claimed-attempt recovery	Distributed drain

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. orbit task archive <id> and the UI archive action are not table moves: they archive a task in any status, including done and rejected, through internal authority. The transition table governs task update --status instead, which refuses an off-table move to archived. 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 action 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.

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.