git:20260816.9f77a90 to git:20260816.ed1331b

- description: Entry point for Orbit — tool invocation surfaces, task lifecycle, and routing to the per-topic skills. Also covers first-time setup and orientation when `.orbit/` is absent.

- Durable operations go through the registered Orbit tool surface — never direct lifecycle subcommands, never a rebuild from source. Lifecycle and authoring detail lives in the per-topic skills listed at the bottom.

- If `.orbit/` is absent, or the user is still deciding whether to adopt Orbit, read [references/guide.md](references/guide.md) and follow it end-to-end. Once the workspace is initialized, the rest of this skill applies.

- | **MCP** — Claude Code with the orbit plugin, or any client connected to `orbit mcp serve` | `orbit_task_add({...})` |

- **Mapping rule:** `orbit.<group>.<action>` ↔ `orbit_<group>_<action>` — every dot becomes an underscore, so `orbit.task.artifact.put` is `orbit_task_artifact_put`. A gateway fronting the MCP mirrors this surface exactly; it may add an optional `workspace` routing param and tools of its own, documented by that gateway rather than here.

-

- **Always include `model`** in the JSON — `codex`, `claude`, `gemini`, or `grok` — so Orbit attributes the call. Full model strings auto-normalize; the family is the persisted identity. This holds for every `orbit.*` call in every skill.

-

- `orbit tool list` (CLI) or `tools/list` (MCP) is the authoritative surface; never guess a tool name. Two gaps worth knowing up front:

-

- - **CLI-only:** `orbit semantic`, `orbit.state.*`, and the routine/sweep/job commands — they need direct process access.

- - **No query surface at all:** code structure (callers, refs, symbols, implementors). Inspect files with the provider-native file-read tool, or `rg` with shell access. Task-to-commit lookup is `git log --grep '[T<task-id>]'`, not a graph query.

- Some CLI flags have no MCP counterpart because they are already the MCP default: `orbit tool run orbit.task.show --full` is plain `orbit_task_show({"id": "<id>"})`. Pass `field` or `fields` to project instead — valid values are `comments`, `plan`, `execution_summary`, `description`, `acceptance_criteria`, `history`, `context_files`, `artifacts`. `orbit.task.list` also accepts `path`, returning tasks whose `context_files` selectors cover that path.

- If an activity already injected `task` into the execution envelope, read that snapshot instead of calling `orbit.task.show` again.

- ## Common Mistakes — DO NOT

- | Mistake | Why it fails | Correct form |

- |---------|-------------|--------------|

- | `cargo run -- tool run ...` | Rebuilds from source instead of using the installed binary | `orbit tool run ...` |

- | `orbit task show <id>` | Direct CLI subcommands skip agent provenance tracking | `orbit tool run orbit.task.show --input '{"id":"<id>"}'` |

- Use `blocked` when execution cannot safely continue. Provenance follows the surface: `orbit tool run ...` is agent-driven, bare `orbit task ...` is human-driven.

- ## Skill Selection

- - `orbit-task`: create, execute, and review tasks through the lifecycle; file self-reported tooling and skill-guidance friction.

- - `orbit-workflow`: task-pilot preflight, jobs, activities, routines, `orbit sweep`, and `orbit run`; diagnosing failed, stuck, or cancelled runs.

- - `orbit-search`: find tasks, docs, and frictions by topic; docs-corpus admin. Decision records are searched as docs.