---
description: Create an isolated worktree, run pre-merge gates, or merge an orbit into its target — using launch-orbit MCP tools with launch-chart layer detection in the pre-flight. Encodes the project's orbit standards (database fork by profile, gate enforcement, post-merge cleanup) so every orbit gets created and merged the same way.
---

# /kit:orbit

Drive a launch-orbit worktree through its lifecycle: create → work → check_mergeable → merge → drop. Wraps the MCP tools with sensible defaults and a layer-aware pre-flight so the operator doesn't forget the project's conventions.

Parse `$ARGUMENTS` — first token is the subcommand:

- **create &lt;branch&gt;** — `[--base=<ref>] [--profile=<name>]` — fork resources per `orbit.json`, return path + envFile.
- **list** — list every orbit registered on this machine.
- **switch &lt;branch&gt;** — activate an orbit: atomically repoint the `current` anchor at its worktree, then operate under that anchor.
- **deactivate** — clear the `current` anchor so work targets the main checkout again.
- **doctor** — surface registry inconsistencies.
- **check &lt;branch&gt;** — `[--all] [--deep] [--base=<ref>] [--json]` — orbit **cleanliness** report: DROP-SAFE + HEALTHY verdicts, recommendation + concrete actions. (Different from `check-merge` — this is "is it safe to delete / sane to keep working in", not "will it merge".)
- **check-merge &lt;branch&gt; --target=&lt;target-branch&gt;** — run pre-merge gates WITHOUT merging.
- **merge &lt;branch&gt; --target=&lt;target-branch&gt;** — `[--cleanup=full|none] [--skip-gate=<id>,…]` — run gates + merge.
- **drop &lt;branch&gt;** — `[--no-backup] [--force]` — tear down (drop-safety guard, then backup, drop DB, remove worktree, deregister).

Examples:
- `/kit:orbit create feat-channel-rename --profile=fe`
- `/kit:orbit check feat-channel-rename` · `/kit:orbit check --all`
- `/kit:orbit check-merge feat-channel-rename --target=implementation`
- `/kit:orbit merge feat-channel-rename --target=implementation`
- `/kit:orbit doctor`

## Preflight (runs on create / check-merge / merge)

1. Confirm `mcp__launch-orbit__orbit_doctor` returns no critical inconsistencies for THIS project. If it does, surface them and stop — the operator probably wants `/kit:orbit drop <stale-branch>` first.
2. Confirm `orbit.json` exists at the repo root. If missing, tell the user to add one (point at the orbit docs) and stop.
3. Run `mcp__launch-chart__detect_project_stack` and print the detected layers as part of the pre-flight log. This is the project's "what's in scope" surface — surface it before any branch op so the operator sees if the chart misses a layer that orbit.json's gates reference (e.g. orbit.json's build-lint gate runs against the api layer but chart doesn't see api).
4. For **merge**: confirm `--target=` is set. Default is NOT `master` — explicit target only.

## Per-subcommand behavior

### create

1. `mcp__launch-orbit__orbit_create` with `branch`, `baseRef` (if `--base`), `profile` (if `--profile`).
2. On success, surface the returned `nextAction` (`cd <path>`) verbatim and the `envFile` path. Don't auto-cd — the operator's shell is theirs to drive.
3. Remind: in the new worktree, `npx launch-kit refresh` will rewire MCPs against the worktree's `.launch-secure.cred.config` symlink if needed.

### list

`mcp__launch-orbit__orbit_list` → one row per orbit: `slug  branch  age  path  resources`.

### switch

`mcp__launch-orbit__orbit_switch(branch)` **activates** the orbit — it atomically repoints `<project>/.launchsecure/orbit/current` at the orbit's worktree and writes `active.json`, then returns `anchor` + `nextAction`. This is a real, deterministic switch: one stable path now resolves into the active orbit.

After switching, target the anchor for everything (this is the whole point — one path, not the raw worktree path):
- **files**: Read / Edit / Write under `.launchsecure/orbit/current/<path>`.
- **chart**: pass `project_root: ".launchsecure/orbit/current"`.
- **commands**: run the returned `nextAction` (`cd ".launchsecure/orbit/current"`) once, then all Bash runs in the orbit.

Switching to a *different* orbit just repoints the anchor — re-run `nextAction` afterward, because a shell that already `cd`'d resolved the old target at cd-time (files and chart follow the symlink live; only the shell needs the re-cd).

### deactivate

`mcp__launch-orbit__orbit_deactivate()` removes the `current` anchor + `active.json` for this project. Use when done in the orbit so subsequent work targets the main checkout. No-op if nothing is active. (Dropping the active orbit clears the anchor automatically.)

### doctor

`mcp__launch-orbit__orbit_doctor` → list every issue with a one-line fix (e.g. `orphan-registration` → `/kit:orbit drop <branch>`).

### check (cleanliness)

`mcp__launch-orbit__orbit_check(branch)` (or `all: true` to sweep this repo's orbits; `deep: true` adds the prisma schema-drift check) → render the two-verdict report:

```
orbit feat-channel-rename [feat-channel-rename]   DROP-SAFE: NO   HEALTHY: YES
  recommendation: KEEP — unmerged or uncommitted work would be lost on drop.
  Drop-safety:  ✗ uncommitted changes · ✗ 3 commits ahead · ✓ no orbit-only rows
  Working-health: ✓ registry · ⚠ env drift · ✓ DB reachable · ✓ ports free
  Actions:
    → Commit or stash the uncommitted changes …
    → Merge feat-channel-rename into implementation …
```

Use it to answer "can I drop this / is it sane to keep working in" — e.g. before cleaning up stale orbits, or at session start. The report carries a `recommendation` + `actions[]`; surface those verbatim. DB checks skip gracefully if the cluster is down.

### check-merge (pre-merge gates)

`mcp__launch-orbit__orbit_check_mergeable(branch, target)` → render the gate report:

```
orbit feat-channel-rename → implementation
  ✓ builtin/mergeability           (no textual conflicts)
  ✗ builtin/build-lint             (tsc: 3 errors, see <artifact>)
  ✓ launchsecure/migration-safety  (no destructive migrations)

result: BLOCKED — fix build-lint then retry.
```

### merge

1. Run `check-merge` first (same report). If `passed: false`, stop with the report — don't attempt the merge.
2. If `passed: true`, call `mcp__launch-orbit__orbit_merge(branch, target, cleanup, skipGates)` and surface the result.
3. Default `cleanup: "full"` (orbit is dropped post-merge after pg_dump). The operator must pass `--cleanup=none` to keep the orbit around.
4. After a successful merge, recommend `/kit:standup` to surface the change in the next standup, and `/kit:diagram` if it touched the schema.

### drop

`mcp__launch-orbit__orbit_drop(branch, backup: !args.noBackup)` → idempotent. Surface `backups[]` paths.

**Drop-safety guard (default on).** `orbit_drop` runs the drop-safety checks first and THROWS if the orbit still has uncommitted/unmerged work or orbit-only DB data. When that happens, surface the blockers and DON'T pass `force: true` reflexively — relay the verdict, let the operator decide. Only pass `force: true` after they explicitly confirm "drop anyway, I'll lose that work". (Tip: run `/kit:orbit check <branch>` first to see the full report and the recommended actions.)

## Conventions encoded here

- **No bare `--target=master`.** Default merge target is `implementation` per project CLAUDE.md ("implementation branch is parent for all impl branches"). If the operator types `--target=master`, double-check by asking once.
- **No `--skip-gate` without a reason in the next message.** Surface a banner: `"Skipping gates: <ids>. Reason?"` — let the operator answer in chat; do NOT proceed silently.
- **Always run `check-merge` before `merge`.** The skill enforces this — even if the operator runs `merge` directly, the skill runs `check-merge` first.
- **Layer awareness.** Pre-flight always prints `detect_project_stack` layers so the operator sees parity (or absence) between chart layers and orbit gate scope.

## Constraints

- **MCP-first.** Never shell out to `git worktree`, `git merge`, `pg_dump` directly — orbit's tools own these.
- **Idempotent.** All subcommands are safe to retry. Drop especially — it handles partial-state gracefully.
- **Surface, don't hide.** If a gate fails, print the artifact path; if the doctor finds inconsistency, print the exact slug.
