@launchsecure/launch-kit 0.0.33 → 0.0.35

package/scaffolds/ls-marketplace/plugins/kit/skills/deploy-check/SKILL.md

@@ -1,144 +1,151 @@
 ---
-description: Production-readiness check for the current branch — typecheck, lint, build, prisma drift, migration safety, env coverage, and recent LS comms. Read-only; reports a punch list of go/no-go signals before a deploy or merge to a deploy-tracked branch. Does NOT deploy.
+description: Production-readiness check for the current branch — branch freshness, typecheck, lint, build, schema/migration drift, migration safety, env coverage, and recent LS comms. Stack-agnostic: detects the project's toolchain (Node/Python/Go/Rust/Ruby/JVM/.NET/PHP) and migrations tooling at runtime, runs the detected command per check, and skips with a reason where a stack has no equivalent. Read-only; reports a go/no-go punch list. Does NOT deploy.
 ---
 
 # /kit:deploy-check
 
-Audit the current branch for production readiness. Bundles every signal a human would manually check before clicking "deploy" or merging to a deploy-tracked branch (per project convention: `master`). Reports a punch list with ✓ / ⚠ / ✗ per check and a single go/no-go verdict.
+Audit the current branch for production readiness. Bundles every signal a human would manually check before clicking "deploy" or merging to a deploy-tracked branch (default: `master`/`main`). Reports a punch list with ✓ / ⚠ / ✗ per check and a single go/no-go verdict.
+
+This skill ships with `launch-kit init` into **any** project, so it makes **no stack assumptions**. Preflight step 5 detects the toolchain and the migrations tooling once; every check below runs the *detected* command, and any check with no equivalent on this stack is **skipped with a visible reason** rather than failing or running a tool the repo doesn't have.
 
 Parse `$ARGUMENTS`:
-- (empty) — full check on the current branch vs `master` (or repo's default).
+- (empty) — full check on the current branch vs the default branch.
 - **--target=<branch>** — compare against a different deploy-tracked branch.
 - **--skip=<check,…>** — comma-separated checks to skip (e.g. `--skip=lint,build`). Use sparingly; surface skipped checks in the report.
-- **--quick** — skip the build (the slowest check). Still runs typecheck, lint, prisma, env, comms.
+- **--quick** — skip the build (the slowest check). Still runs the rest.
 - **--json** — emit a machine-readable report (per check: ok, detail, durationMs).
 
 Examples:
 - `/kit:deploy-check`
 - `/kit:deploy-check --quick`
 - `/kit:deploy-check --skip=lint`
-- `/kit:deploy-check --target=staging-mirror --json`
+- `/kit:deploy-check --target=staging --json`
 
 ## Preflight
 
 1. Confirm cwd is a git repo (`git rev-parse --is-inside-work-tree`).
-2. Resolve the target branch — `--target=` if given, else default branch (`git symbolic-ref refs/remotes/origin/HEAD --short` → strip `origin/`; fall back to `master`).
-3. Print the scope upfront: `"deploy-check: <current-branch> → <target-branch>"`. The user should never wonder which comparison this is.
-4. Stash check — if `git status --porcelain` shows uncommitted changes, surface this as a `⚠ uncommitted changes in working tree` row at the top of the report. Don't refuse; some workflows want the check to include uncommitted work.
+2. Resolve the target branch — `--target=` if given, else default branch (`git symbolic-ref refs/remotes/origin/HEAD --short` → strip `origin/`; fall back to `master`/`main`).
+3. Print the scope upfront: `"deploy-check: <current-branch> → <target-branch>"`.
+4. Stash check — if `git status --porcelain` shows uncommitted changes, surface a `⚠ uncommitted changes in working tree` row at the top. Don't refuse; some workflows want uncommitted work included.
+5. **Detect the project stack** (this is what makes the skill portable — resolve once, reuse below). Identify the project family from its manifest, then resolve the per-check command. **Always prefer an explicit script/target the repo defines** (a `package.json` script, a `Makefile` target like `build`/`lint`/`test`, a `justfile` recipe) over the language default — a defined script encodes the project's real intent.
+
+   | Family | Marker | typecheck | lint | build | env-ref grep |
+   |---|---|---|---|---|---|
+   | Node | `package.json` (PM from lockfile: pnpm/yarn/bun/npm; `RUN=<pm> run`) | `<RUN> typecheck` else `npx tsc --noEmit` **only if `tsconfig.json`**; else skip | `<RUN> lint` if defined | `<RUN> build` if defined | `process\.env\.[A-Z_]+` in `*.ts,*.tsx,*.js,*.mjs,*.cjs` |
+   | Python | `pyproject.toml`/`requirements.txt`/`setup.py` | `mypy`/`pyright` if configured, else skip | `ruff check`/`flake8` if configured | build script if defined (often none) | `os\.environ\[`, `os\.getenv\(`, `getenv\(` in `*.py` |
+   | Go | `go.mod` | `go vet ./...` | `golangci-lint run` if present | `go build ./...` | `os\.Getenv\(` in `*.go` |
+   | Rust | `Cargo.toml` | `cargo check` | `cargo clippy` | `cargo build --release` | `env::var\(`, `std::env::var` in `*.rs` |
+   | Ruby | `Gemfile` | `srb tc` if sorbet, else skip | `rubocop` if present | build script if defined | `ENV\[` in `*.rb` |
+   | JVM | `pom.xml`/`build.gradle(.kts)` | (compile = build) | checkstyle/ktlint if configured | `mvn -q package` / `gradle build` | `System\.getenv\(` in `*.java,*.kt` |
+   | .NET | `*.csproj`/`*.sln` | (compile = build) | `dotnet format --verify-no-changes` if present | `dotnet build -c Release` | `Environment\.GetEnvironmentVariable\(` in `*.cs` |
+   | PHP | `composer.json` | `phpstan`/`psalm` if present | `php-cs-fixer`/`phpcs` if present | build script if defined | `getenv\(`, `\$_ENV\[` in `*.php` |
+   | unknown | — | skip | skip | skip (look for a `Makefile`/`justfile` `build` target first) | skip env_coverage |
+
+   Also resolve, reusing the same detection `/kit:ship` uses:
+   - **`MIGRATIONS_DIR`** — `prisma/migrations/` · `supabase/migrations/` · `drizzle/` (or a dir with `drizzle/meta/`) · `db/migrate/` (Rails) · `alembic/versions/` · a Django app's `*/migrations/` · `src/main/resources/db/migration/` (Flyway) · a knex/TypeORM/Sequelize dir, or **`none`**. A config-declared `migrationsPath` wins.
+   - **`MIGRATION_TOOL`** — prisma / supabase / drizzle / rails / alembic / django / flyway / knex / typeorm / sequelize / `none`. Drives whether a *drift* command exists (check 5).
+   - **`ENV_EXAMPLE`** — `.env.testing` if it exists, else `.env.example`, else `none`.
+
+   Record the resolved command set and print a one-line `stack: <family> · pm=<pm> · migrations=<tool|none>` so the user can see what was detected.
 
 ## Checks
 
-Run every check in PARALLEL when possible (typecheck/lint/build are independent and slow). Each check returns `{ name, status: "ok"|"warn"|"fail", detail: <one-line>, artifact?: <path or url> }`.
+Run independent checks (typecheck/lint/build) in PARALLEL. Each returns `{ name, status: "ok"|"warn"|"fail"|"skip", detail: <one-line>, artifact?: <path|url> }`. **A check with no detected command is `skip` with a reason — never `fail`.**
 
 ### 1. branch_freshness
 
-How far behind the target branch is the current branch?
-
 ```
 git fetch --quiet origin
 git rev-list --left-right --count <target>...HEAD
 ```
-
 - ✓ `0 commits behind target` → fresh
 - ⚠ `1–10 behind`
 - ✗ `>10 behind` → suggest `git merge origin/<target>` or rebase
 
 ### 2. typecheck
 
-`npx tsc --noEmit` (or the project's `npm run typecheck` if defined in `package.json` scripts — prefer the script).
-
+Run `TYPECHECK_CMD` from Preflight. If none for this stack, `⚠ typecheck skipped — no typecheck configured for <family>`.
 - ✓ `0 errors`
-- ✗ `<N> errors` (sample first 3 file:line:message)
+- ✗ `<N> errors` (sample first 3 `file:line:message`)
 
 ### 3. lint
 
-`npm run lint` if defined in `package.json` scripts; else skip with a `⚠ no lint script defined` row.
-
-- ✓ `0 errors`
-- ⚠ `<N> warnings`
-- ✗ `<N> errors`
+Run `LINT_CMD`. If none defined, `⚠ lint skipped — no lint script/linter detected`.
+- ✓ `0 errors` · ⚠ `<N> warnings` · ✗ `<N> errors`
 
 ### 4. build
 
-`npm run build` (uses the project's actual build pipeline so the check matches what Vercel/CI would do). Skip if `--quick` or `--skip=build`.
+Run `BUILD_CMD` (the project's real build, so the check matches CI). Skip if `--quick` or `--skip=build`. If no build command exists for this stack (common for libraries / scripting projects), `⚠ build skipped — no build step detected`.
+- ✓ `built in <durationMs>ms` · ✗ `build failed` (last 20 lines of stderr as artifact)
 
-- ✓ `built in <durationMs>ms`
-- ✗ `build failed` (last 20 lines of stderr as artifact)
+**DB-safety guard (only when the build touches a DB).** If the detected `BUILD_CMD` runs migrations as part of the build (e.g. a Node build script that chains `prisma migrate deploy`, or any build that applies `MIGRATION_TOOL` migrations — detect by scanning the build script / target), then a prod DB connection string must NOT be used. If the relevant connection env (`DATABASE_URL`, `DB_URL`, etc.) looks production-y (matches `neon.tech`, `rds.amazonaws.com`, `supabase.co`, a `vercel.app` proxy host, etc.), refuse the build step: `⚠ build skipped — build applies migrations and DATABASE_URL looks production-y (<host>); re-run with a dev DB or pass --skip=build`. If the build does NOT touch a DB (most stacks), skip this guard.
 
-Note: this runs the full prod build including prisma generate + migrate deploy. Make sure `DATABASE_URL` is set to a *safe* dev DB before running. If `DATABASE_URL` looks production-y (matches `vercel.app`, `neon.tech`, `rds.amazonaws.com`, etc.), refuse the build step and surface `⚠ build skipped — DATABASE_URL looks production-y (<host>); re-run with a dev DB or pass --skip=build`.
+### 5. schema_drift (only when MIGRATION_TOOL supports it)
 
-### 5. prisma_drift
+Schema-vs-migrations consistency, using the tool's own drift command:
+- **prisma** — `npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-migrations prisma/migrations --shadow-database-url <DEV_SHADOW_URL>`. The diff should be EMPTY (this project hand-authors migrations — see CLAUDE.md). Non-empty = a model change without a migration.
+- **drizzle** — `npx drizzle-kit check` (reports schema/migration mismatch).
+- **rails** — `bin/rails db:abort_if_pending_migrations` against a dev DB (pending = drift).
+- **alembic/django** — `alembic check` / `python manage.py makemigrations --check --dry-run` (a would-be-generated migration = drift).
+- **other / none** — `⚠ schema_drift skipped — no drift command for <tool>` (or skip silently when `MIGRATION_TOOL=none`).
 
-Schema vs migrations consistency:
+- ✓ `schema matches migrations` · ✗ `<N> drift detected` (surface the diff as an artifact; suggest authoring a migration).
+- If a drift command needs a shadow/dev DB and none is available: `⚠ schema_drift skipped — no shadow/dev DB URL`.
 
-```
-npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-migrations prisma/migrations --shadow-database-url <DEV_SHADOW_URL>
-```
+### 6. migration_safety (only when MIGRATIONS_DIR ≠ none)
 
-The project authors migrations by hand (CLAUDE.md: never `prisma db push` or `migrate dev`). So this diff should be EMPTY — any non-empty result means a model field was added without a corresponding hand-written migration.
-
-- ✓ `schema matches migrations`
-- ✗ `<N> drift detected` — surface the diff body as an artifact; suggest authoring a migration per the project's hand-written SQL convention.
-
-If no `DEV_SHADOW_URL` is available, skip this check with `⚠ prisma_drift skipped — no shadow DB URL` and recommend setting one in `.env.local`.
-
-### 6. migration_safety
-
-Recent migrations on the branch — look at every migration file added since divergence from target:
+If `MIGRATIONS_DIR=none`, skip entirely. Otherwise scan every migration added since divergence:
 
 ```
-git diff --name-only <target>...HEAD -- prisma/migrations/
+git diff --name-only <target>...HEAD -- <MIGRATIONS_DIR>
 ```
 
-For each new migration, scan the SQL for risk patterns (per project CLAUDE.md migration safety rules):
+For **SQL-based** migrations (prisma/supabase/flyway/rails-SQL/alembic-SQL), scan the SQL for risk patterns (per the project's migration-safety discipline):
+- ✓ no destructive ops (`DROP COLUMN`, `DROP TABLE`, `ALTER COLUMN ... DROP`, `DELETE FROM` without a backup-matching `WHERE`).
+- ⚠ destructive ops present BUT a sidecar `CREATE TABLE _backup_*` AND an orphan-check (`RAISE EXCEPTION ... orphans remain`) are present in the same file.
+- ✗ destructive ops without backup OR without orphan-check OR expand+contract mixed in one migration.
 
-- ✓ no destructive ops (`DROP COLUMN`, `DROP TABLE`, `ALTER COLUMN ... DROP`, `DELETE FROM` without `WHERE` matching backup) found.
-- ⚠ destructive ops present BUT a sidecar `CREATE TABLE _backup_*` exists in the same file AND an orphan-check (`RAISE EXCEPTION ... orphans remain`) is present.
-- ✗ destructive ops without backup OR without orphan-check OR mixing expand+contract in a single migration.
+For **non-SQL** migration DSLs (Rails Ruby DSL, Django/Alembic Python ops, Drizzle TS), best-effort scan for the tool's destructive ops (`remove_column`, `drop_table`, `op.drop_column`, `.dropColumn`, etc.) and note `partial coverage — non-SQL migration, pattern scan only`.
 
 Each failure cites the exact migration filename + line numbers.
 
-### 7. env_coverage
+### 7. env_coverage (only when ENV_EXAMPLE ≠ none and an env-ref pattern exists)
 
-Compare `.env.example` (or `.env.testing` if it exists) keys against `process.env.*` references in the new code since divergence:
+Compare documented keys in `ENV_EXAMPLE` against env references in new code since divergence, using the stack's `env-ref grep`:
 
 ```
-git diff <target>...HEAD -- '*.ts' '*.tsx' | grep -oE 'process\.env\.[A-Z_][A-Z0-9_]+'
+git diff <target>...HEAD -- <stack source globs> | grep -oE '<ENV_REF_PATTERN>'
 ```
-
-- ✓ every referenced env var is documented in `.env.example`
-- ⚠ `<N> new env vars used but missing from .env.example` (list them)
-- ✗ N/A (always a warn, never a hard fail — env docs are advisory)
+- ✓ every referenced env var is documented in `ENV_EXAMPLE`
+- ⚠ `<N> new env vars used but missing from <ENV_EXAMPLE>` (list them)
+- env docs are advisory — this is never a hard ✗. If `ENV_EXAMPLE=none`, `⚠ env_coverage skipped — no env example file`.
 
 ### 8. recent_comms (LS Comm Hub)
 
-Pull the last 10 comments tagged `release` or `daily_update` via `mcp__launch-secure__communication_read` and surface a one-line: `"<N> release/standup comments in last 7 days — latest: <title> (<author>, <age>)"`. This is informational — it helps the user know if a release note was already drafted or if the team flagged something to ship.
-
-Skip with a `⚠ launch-secure MCP not wired` row if the MCP isn't available; don't fail the whole check.
+Pull the last 10 comments tagged `release` or `daily_update` via `mcp__launch-secure__communication_read`; surface `"<N> release/standup comments in last 7 days — latest: <title> (<author>, <age>)"`. Informational. Skip with `⚠ launch-secure MCP not wired` if unavailable.
 
 ### 9. recall_health
 
-`mcp__launch-recall__recall_status` — ensures the shadow-git backup is alive so a rollback path exists if the deploy goes sideways. Informational only.
-
-- ✓ `recall alive — last snap <X ago>`
-- ⚠ `recall dead — restart before deploy (\`/kit:recall doctor\` for detail)`
+`mcp__launch-recall__recall_status` — confirms the shadow-git backup is alive so a rollback path exists. Informational.
+- ✓ `recall alive — last snap <X ago>` · ⚠ `recall dead — restart before deploy`. Skip if the MCP isn't wired.
 
 ## Report
 
-Render a punch list (plain text, monospace; not markdown table):
+Render a punch list (plain text, monospace; not a markdown table):
 
 ```
 deploy-check: implementation → master
+stack: node · pm=npm · migrations=prisma
 
   ✓ branch_freshness       0 commits behind master
   ✓ typecheck              0 errors (3.2s)
   ⚠ lint                   12 warnings (no errors)
   ✓ build                  built in 47s
-  ✓ prisma_drift           schema matches migrations
+  ✓ schema_drift           schema matches migrations
   ✗ migration_safety       1 destructive op without backup
-                           → prisma/migrations/2026_05_25_drop_legacy_thread/migration.sql:14 (DROP COLUMN legacyThreadId, no _backup_* sidecar)
+                           → prisma/migrations/2026_05_25_drop_legacy/migration.sql:14 (DROP COLUMN, no _backup_* sidecar)
   ⚠ env_coverage           2 new env vars missing from .env.example: FEED_BACKEND_URL, FEED_TIMEOUT_MS
-  ✓ recent_comms           1 release comment in last 7 days — "Comm Hub channels rollout" (prajyot, 2d ago)
+  ✓ recent_comms           1 release comment in last 7 days — "channels rollout" (prajyot, 2d ago)
   ✓ recall_health          alive — last snap 4m ago
 
 verdict: NO-GO — 1 hard fail (migration_safety).
@@ -147,14 +154,16 @@ next: author a backup table + orphan check in the listed migration, then re-run
 
 Verdict rules:
 - Any ✗ → NO-GO with the failing check(s) listed.
-- All ✓ + ⚠ only → GO WITH CAVEATS, list the warnings.
+- All ✓ + ⚠/skip only → GO WITH CAVEATS, list the warnings + skips.
 - All ✓ → GO.
+- **Skips never fail the gate** — but if every code-quality check (typecheck+lint+build) skipped, add a `⚠ note: no typecheck/lint/build ran for this stack — gate is weak` so a green verdict isn't mistaken for thorough.
 
 ## Constraints
 
 - **Read-only.** Never deploy, never push, never auto-fix.
-- **Parallel checks.** Run independent checks concurrently (Bash run_in_background) — sequential bloats the wait time past usefulness.
+- **No stack assumptions.** Every tool-specific command is resolved by detection in Preflight step 5. If detection comes up empty for a check, skip it with a reason — never run a tool the repo doesn't have, never hard-fail for its absence.
+- **Parallel checks.** Run independent checks concurrently — sequential bloats the wait past usefulness.
 - **No silent skips.** Every skipped check appears in the report with a reason.
-- **DB-safe.** Refuse to run `build` against a production-looking DATABASE_URL — the build runs `prisma migrate deploy` against it.
-- **Honest about scope.** This check is what a human would do manually; it is NOT a guarantee. Surface false-negatives readers: `"This check doesn't run e2e tests, doesn't validate runtime config, doesn't sniff for secrets in commits — those are separate skills."`
-- **Use launch-chart only for nice-to-have context (e.g. blast radius of a migration), not for the gate.** The gate is git+npm+prisma+MCP-LS; chart is optional.
+- **DB-safe.** The build DB-safety guard only triggers when the detected build actually applies migrations; when it does, refuse a production-looking connection string.
+- **Honest about scope.** This check is what a human would do manually; it is NOT a guarantee. Surface: `"This check doesn't run e2e tests, doesn't validate runtime config, doesn't sniff for secrets in commits — those are separate skills."`
+- **launch-chart is optional context only** (e.g. blast radius of a migration), never part of the gate. The gate is git + the detected toolchain + the migrations tool + MCP-LS.

package/scaffolds/ls-marketplace/plugins/kit/skills/handoff/SKILL.md

@@ -0,0 +1,132 @@
+---
+description: Refresh the HANDOFF Brief (doc/handoff/HANDOFF.md) from current session state and regenerate the next-session kickoff prompt. Current-state only — per-ship history lives in doc/shipping-logs/ (written by /kit:ship). Does NOT commit or push; run /kit:handoff first, then /kit:ship so the HANDOFF edit rides the ship payload.
+---
+
+# /kit:handoff
+
+Wrap a session: keep `doc/handoff/HANDOFF.md` an accurate **current-state snapshot**, and produce a kickoff prompt the next session can paste in cold.
+
+`doc/handoff/HANDOFF.md` is a **current-state Brief** — it does NOT accumulate per-session "what shipped" writeups. That history lives in `doc/shipping-logs/` (written by `/kit:ship`). Keep HANDOFF lean — if it grows past ~150 lines, the wrong thing is going into it (a cumulative feature list belongs in a roadmap doc; per-ship detail belongs in `doc/shipping-logs/`).
+
+This skill does **NOT commit and does NOT push**. `/kit:ship` does that. The intended order is `/kit:handoff` → `/kit:ship`, so the HANDOFF edit lands inside the slice's ship payload and publishes with it. For a session that won't run `/kit:ship`, see **Edge cases**.
+
+Parse `$ARGUMENTS`:
+
+- (empty) — refresh `doc/handoff/HANDOFF.md` against the current session and regenerate the kickoff prompt.
+- **--dry-run** — build the refreshed HANDOFF + kickoff in a fenced preview block, but do NOT write the file. Useful for "what would the handoff look like right now?".
+- **--next=<text>** — name what's next explicitly (e.g. `--next="F12 webhook retries"`) instead of inferring it from the session. Drives the kickoff prompt's title + context.
+
+## Preflight
+
+1. `git rev-parse --is-inside-work-tree` — abort if not a git repo.
+2. Resolve the **base branch** to diff the session against:
+   - `git symbolic-ref refs/remotes/origin/HEAD --short` (strip `origin/`) → the repo's default branch. Fall back to `origin/main` / `origin/master` if unset.
+   - Use `git log <base>..HEAD` as "what this session/branch added."
+3. Confirm `doc/handoff/` exists. If not, this is the first handoff — create `doc/handoff/HANDOFF.md` from the skeleton in **Step 2** rather than editing.
+
+## Step 1 — Inventory what happened
+
+Survey the session — gather, don't show yet:
+
+- `git log <base>..HEAD --oneline` — what's committed locally this branch.
+- `git status --porcelain` + `git diff --stat` — uncommitted work.
+- Recent `TaskList` (if present) — completed vs deferred.
+- From the conversation: decisions made, scope cuts, schema/migration changes, new env vars, external-service touchpoints, anything paused mid-flight.
+
+Produce a short internal summary (slice/title · what changed · schema/env deltas · deferred items · open threads). This feeds Steps 2–3; do not print it.
+
+## Step 2 — Refresh `doc/handoff/HANDOFF.md`
+
+Update **only** these sections — nothing else belongs in this file:
+
+1. **Intro line** — keep the "refreshed at each `/kit:handoff`" note + the `docs/archive/` pointer (see Archiving).
+2. **Where we are** — the one-block current-state status: what's now feature-complete, what's paused, any new external dependency. Tight.
+3. **What's next** — the next 1–3 things in priority order. If priorities shifted this session, reflect it.
+4. **Open threads** — the short list of genuinely-open items needing attention soon. **Prune anything resolved this session.** Long-horizon "maybe someday" items belong in a deferrals doc, not here.
+5. **Kickoff prompt** — Step 3.
+
+Do NOT add: a "What shipped this session" section (→ `doc/shipping-logs/`), a past-sessions log, or a cumulative feature list (→ a roadmap doc).
+
+First-handoff skeleton (when the file doesn't exist yet):
+
+```markdown
+---
+title: Handoff — Current State
+---
+
+# <Project> — Handoff
+
+_Current-state snapshot, refreshed at each session's `/kit:handoff`. Per-ship "what shipped" history lives in `doc/shipping-logs/`. Older handoff content is archived at `docs/archive/`._
+
+## Where we are
+
+<one-block current state>
+
+## What's next
+
+1. <next thing>
+2. <…>
+
+## Open threads
+
+- <genuinely-open item>
+
+## Kickoff prompt for the next session
+
+> <generated in Step 3>
+```
+
+## Step 3 — Regenerate the kickoff prompt
+
+Replace the "Kickoff prompt for the next session" section at the bottom of `HANDOFF.md`. It must be **specific to whatever's next** (use `--next=` if given), not generic:
+
+```markdown
+## Kickoff prompt for the next session
+
+> Starting **<work item / FNN — Title>**. Read `CLAUDE.md`, then `doc/handoff/HANDOFF.md` and the relevant Briefs under `doc/`. {One-paragraph context: what this work is, why now, what infra is already in place.}
+>
+> Before any code, confirm the design shape:
+>
+> 1. **Surface.** {Where does this live? Closest precedent in the codebase?}
+> 2. **Fields / inputs.** {What does the user/agent provide?}
+> 3. **Eligibility.** {When is the action available? State guards?}
+> 4. **Data path.** {What writes happen, in what order? What events/logs are emitted?}
+> 5. **{Feature-specific question.}**
+> 6. **Out of scope / deferrals.** {What are we explicitly NOT building? Trigger to revisit?}
+>
+> Scope the slice, confirm deferrals, then branch off the default branch. Run `/kit:handoff` then `/kit:ship` at session end.
+```
+
+If `What's next` lists multiple candidates, write the kickoff for the most-likely-next and add a one-line note about the alternative.
+
+## Step 4 — Tell the user
+
+Single short message:
+
+1. **Confirm `HANDOFF.md` is updated** — brief recap of the new current-state + what's-next.
+2. **Show the kickoff prompt** — copy-paste ready, in a fenced block.
+3. **Remind:** start a **new** session for the next slice (one session per feature/branch) and paste the kickoff as the first message.
+4. **Suggest `/kit:ship` next** if there's uncommitted work — there will be, at minimum the HANDOFF edit — so the refresh publishes with the slice.
+
+Do NOT commit. Do NOT push. `/kit:ship` does that.
+
+## Archiving (keep HANDOFF lean)
+
+If `HANDOFF.md` exceeds ~150 lines or the "Where we are" block has accumulated many fully-shipped-and-stable bullets:
+
+- Move the stale, no-longer-active content to `docs/archive/HANDOFF-thru-<YYYY-MM>.md` (append to it if it exists).
+- Leave a one-line pointer in the intro line.
+- The live HANDOFF should read in under a minute. History is recoverable from the archive + `doc/shipping-logs/`; it does not need to live in the active snapshot.
+
+## Edge cases
+
+- **Session shipped code** — `/kit:ship` runs after this and commits the HANDOFF edit along with the slice. The normal path.
+- **Design / planning / process session, no `/kit:ship`** — still refresh HANDOFF (decisions made, deferrals identified, new open threads) and the kickoff. Since no ship will run, either make a small `docs:` commit of the HANDOFF change yourself, or tell the user it's uncommitted and unpublished. Do not silently leave it dangling.
+- **No changes since base** (pure conversation, no code, no decisions) — don't fabricate updates. Refresh only the kickoff prompt and say "no current-state changes; here's the prompt for next session."
+- **Session spanned multiple slices** (rare — violates one-session-per-feature) — each slice already has its own `doc/shipping-logs/` entry from `/kit:ship`; just ensure HANDOFF's current-state reflects all of them.
+
+## Notes for the assistant
+
+- HANDOFF is **current-state only**. The single most common failure is letting it grow into a session journal — that's what `doc/shipping-logs/` is for. When in doubt, cut.
+- This skill never pushes; it respects the same unauthorized-push rules as `/kit:ship`. The HANDOFF edit becomes team-visible only when `/kit:ship` pushes it.
+- If the repo registers a `handoff` doc category in its file-content-sync config (mapping `doc/handoff/**` to the discussion handler, the same mechanism `/kit:ship` uses for `doc/shipping-logs/**`), the HANDOFF Brief materializes as a Comm Hub comment on push. If not, HANDOFF still works as a local cold-start doc — it just isn't mirrored to the Comm Hub. That category registration is a one-time repo/server config, not this skill's job.

package/scaffolds/ls-marketplace/plugins/kit/skills/kickoff/SKILL.md

@@ -0,0 +1,151 @@
+---
+description: Cold-start a session — read the last HANDOFF snapshot, the newest shipping log, the git summary, and (if LS is connected) your open work items, reconcile them, then categorize all pending work (resume in-flight · review/PR feedback · bugs · high-priority · low-hanging fruit · stale/dead · tech-debt/deferred, plus a non-pickable blocked list) and let you choose a list to work from before drilling into a specific item. Read-only; the complement to /kit:handoff. Does NOT branch, commit, or write files unless you confirm a next step.
+---
+
+# /kit:kickoff
+
+Start a session the way `/kit:handoff` ends one. Handoff **writes** the current-state snapshot and a single kickoff prompt at the end of a session; kickoff **reads** that snapshot back at the start of the next one, cross-checks it against git and your work items, and turns "what was I doing / what's next" into a concrete pick.
+
+The loop is: `/kit:handoff` → (new session) → `/kit:kickoff` → choose a slice → work → `/kit:handoff` → `/kit:ship`. One session per feature; kickoff is the first thing you run in the fresh session.
+
+This skill is **read-only by default**. It does not branch, commit, push, or write files. Its output is: a lay-of-the-land board, the pending work **sorted into categorized lists** (resume in-flight · low-hanging fruit · high-priority · stale/dead · tech-debt/deferred), a two-stage choice (pick a *list*, then a *specific item*), and — once you've chosen — a ready-to-use kickoff prompt for that item plus an offer to set up the branch/orbit as a *separate, confirmed* next step.
+
+Parse `$ARGUMENTS`:
+
+- (empty) — full orient: gather all sources, show the board + categorized lists, ask which list to work from, then drill into a specific item.
+- **--brief** — show the lay-of-the-land board + the category headline counts only (e.g. "🍒 Low-hanging: 4 · 🔥 High-priority: 3 · 🪦 Stale: 6"). Skip the interactive choice. For "just remind me where I was."
+- **--list=<name>** — skip the first-stage menu; go straight to the named list (`resume` / `review` / `bugs` / `priority` / `fruit` / `stale` / `debt`) and present its filtered items to pick from.
+- **--pick=&lt;text&gt;** — skip both menus; treat `<text>` as the chosen item and go straight to producing its kickoff prompt + setup offer.
+- **--all** — when assembling work-item candidates, include items not assigned to you (whole-board backlog), not just your own. Default is assigned-to-me.
+
+## Preflight
+
+1. `git rev-parse --is-inside-work-tree` — abort if not a git repo.
+2. Resolve the **base branch** (same logic as `/kit:handoff` and `/kit:ship`):
+   - `git symbolic-ref refs/remotes/origin/HEAD --short` (strip `origin/`). Fall back to `origin/main` / `origin/master` if unset.
+3. Record current branch (`git rev-parse --abbrev-ref HEAD`) and git email (`git config user.email`) — the email is the work-item handle.
+4. Detect LS connectivity: check for `.launch-secure.cred.config` at the repo root. If absent, kickoff still runs — it just **skips the work-items source** and notes "LS not connected; candidates from HANDOFF + git only." Do NOT abort (unlike `/kit:standup`, kickoff is useful offline).
+
+## Step 1 — Gather the sources (don't show yet)
+
+Pull from four layers in parallel. Each is independently optional; a missing one is noted, not fatal.
+
+**1a. The HANDOFF snapshot** — read `doc/handoff/HANDOFF.md` if it exists. Extract its four live sections: **Where we are**, **What's next** (the priority-ordered 1–3), **Open threads**, and the embedded **Kickoff prompt**. This is the human-curated "what's next," highest signal. If the file doesn't exist, note "no HANDOFF yet — first kickoff" and lean on git + work items.
+
+**1b. The last ship** — read the newest file under `doc/shipping-logs/` (date-prefixed `YYYY-MM-DD-…`, so the lexically-last name is newest). This is the authoritative "what was *actually* last updated/shipped" — HANDOFF is current-state only and does not carry per-ship detail. Capture its title + the slice it shipped. If the dir is empty, skip.
+
+**1c. Git summary** — the real on-disk state, to reconcile against what HANDOFF claims:
+- `git log <base>..HEAD --oneline` — commits on this branch not yet in base.
+- `git log -n 8 --oneline <base>` — recent baseline history (what landed lately).
+- `git status --porcelain` — uncommitted work. Filter out generated noise (`.launchsecure/graphs/*.json`, `node_modules`, `dist`, `.next`). What remains is genuine in-flight work — a **"resume this"** candidate.
+- Current branch + whether it's ahead/behind base.
+
+**1d. Work items (only if LS connected)** — build the backlog candidates:
+- `mcp__launch-secure__work_items_list({ assignee_email: "<git email>", status: "IN_PROGRESS" })` — things you already started; strongest "resume" candidates.
+- `mcp__launch-secure__work_items_list({ assignee_email: "<git email>", status: "TODO" })` — your queued backlog.
+- With `--all`, also fetch the same statuses without `assignee_email` to include unassigned/team items.
+- Capture id + title + status for each. Cap at ~8 total; if more, keep the top 8 and note "(N more in LS)".
+
+> Use the hosted `launch-secure` MCP by default. Only use `local-launch-secure` if the active course points there (see `/kit:course`). Don't ask for org/project slugs — the `.mcp.json` headers default to the current project.
+
+## Step 2 — Reconcile + flag drift
+
+Before showing anything, cross-check the sources against each other. This is the honesty pass — the inverse of what `/kit:standup` does for shipped work.
+
+- **Stale "What's next":** if a HANDOFF "What's next" item appears already done in git (matching commits in `<base>..HEAD`, or named in the newest shipping log), flag it: _"HANDOFF lists ‹X› as next, but it appears shipped (commit ‹sha›) — likely stale."_ Don't silently drop it; surface the contradiction.
+- **Dedup across sources:** a HANDOFF "What's next" item and an LS work item often refer to the same slice (match on id like `LS-…`/`#…`, or on title similarity). Collapse them into one candidate that carries both handles.
+- **Resolved open threads:** if an "Open thread" looks addressed by a recent commit, note it as "possibly resolved — confirm."
+- **Branch sanity:** if the current branch already has commits ahead of base AND there's an in-progress work item, the most likely intent is "continue the current branch," not "start something new" — rank accordingly.
+
+## Step 3 — Categorize the pending work into lists
+
+Pool every candidate from the reconciled sources (HANDOFF "What's next" + "Open threads", LS work items, uncommitted git work, follow-up flags grepped from recent commit bodies — same patterns `/kit:standup` uses: `TODO`, `follow-up`, `deferred`, `not patched`, `revert`, `next pass`, plus `broken`/`bug`/`failing`/`blocked`/`waiting on`). Dedup (Step 2).
+
+**First, pull out the blocked items** — anything tagged `blocked`/`waiting`, marked depending on an unfinished item, or whose commit/thread says "waiting on ‹X›". These go to the non-pickable **🚧 Blocked** list (Step 4) so you see *why* they aren't moving; they are removed from all buckets below.
+
+Then sort each remaining item into **one** bucket — most-specific bucket wins, in this precedence:
+
+1. **🔧 Resume in-flight** — uncommitted local work + `IN_PROGRESS` work items. The strongest "continue what you started" signal; always wins if present.
+2. **👀 Review / PR feedback** — work waiting on *your* action on something already in motion: open PRs you authored or are assigned to review, unresolved review comments, `needs-review`/`changes-requested` tags. Time-sensitive (someone's blocked on you), so it outranks fresh work.
+3. **🐛 Bugs / broken** — defects: work items of type `bug` or tagged `bug`/`defect`/`regression`, and `broken`/`failing`/`revert`/`not patched` follow-up flags from commit bodies. Distinct from feature backlog regardless of priority.
+4. **🔥 High-priority** — items the project marks urgent: a work-item priority/severity field at its top value, tags like `p0`/`p1`/`urgent`, **and** everything in HANDOFF "What's next" (human-curated = high priority by definition), minus anything Step 2 flagged stale.
+5. **🍒 Low-hanging fruit** — quick wins: work items with a small estimate/size field or `quick`/`chore`/`good-first`/`small` tags, single-file follow-up flags from commit bodies, and one-line open threads. When no size signal exists, infer from scope words in the title ("rename", "typo", "bump", "add flag", "copy") — but say it's inferred.
+6. **🪦 Stale / dead** — pending too long: `TODO`/`IN_PROGRESS` work items whose `updatedAt` is older than ~30 days (tune to the project's pace), and open threads that have survived multiple handoffs. These are the "why is this still here" items.
+7. **🧹 Tech-debt / deferred** — items tagged `tech-debt`/`debt`/`deferred`/`backlog`, explicit deferrals recorded in HANDOFF, and `deferred`/`rolled back` follow-up flags from commit bodies.
+
+Each item lands in exactly one bucket. Within a bucket, sort by the most relevant key (priority desc, then age; for stale, oldest first; for fruit, smallest first). An empty bucket is simply omitted everywhere downstream.
+
+## Step 4 — Show the lay of the land
+
+One compact block: orientation header, then each **non-empty** bucket with up to **5** items and a `+N more` tail. No preamble.
+
+```
+📍 Where we are
+<HANDOFF "Where we are", trimmed to 2–4 lines. If no HANDOFF: a 1-line synthesis from git.>
+🚢 Last shipped: <newest shipping-log title + date> — <one line>
+⚠️ Drift: <Step 2 flags, one line each. Omit if none.>
+
+🔧 Resume in-flight (N)
+- <item — handle/branch/file · short why>
+  …up to 5… (+N more)
+
+👀 Review / PR feedback (N)
+- <item — PR#/LS-id · what's waiting on you>
+  …up to 5… (+N more)
+
+🐛 Bugs / broken (N)
+- <item — LS-id · short why>
+  …up to 5… (+N more)
+
+🔥 High-priority (N)
+- <item — LS-id · short why>
+  …up to 5… (+N more)
+
+🍒 Low-hanging fruit (N)
+- <item — handle · est/size or "inferred quick">
+  …up to 5… (+N more)
+
+🪦 Stale / dead (N)
+- <item — LS-id · "untouched 47d">
+  …up to 5… (+N more)
+
+🧹 Tech-debt / deferred (N)
+- <item — handle · source>
+  …up to 5… (+N more)
+
+🚧 Blocked (N) — not pickable, shown for awareness
+- <item — handle · waiting on ‹what›>
+  …up to 5… (+N more)
+```
+
+Readable in under a minute. The 🚧 Blocked list is informational only — never offered as a pick. If `--brief`, stop after the headline counts line (don't expand the bucket items).
+
+## Step 5 — Two-stage choice: pick a list, then an item
+
+**Stage A — which list.** Call **AskUserQuestion** ("Which list do you want to work from?"). Options are the **non-empty pickable buckets** (🚧 Blocked is never an option), capped at 4 (the tool's max) — there are up to 7 pickable buckets, so choose the 4 most useful for this session by precedence + item count + freshness, and surface the rest in option descriptions ("…also N stale, N tech-debt — say the word to see them"). Thin slow-moving buckets may be folded into one option ("Stale & deferred"). Each option's description carries the bucket's count + a one-line flavor of what's inside. "Other" (auto-added) lets the user name any list (including a folded/overflow one) or item directly. Skip Stage A if `--list=` was passed.
+
+**Stage B — which item.** Once a list is chosen, show that bucket's **full** filtered list (not just the top 5 — now we're focused on one category, so depth is fine), numbered, each with its handle + the one-line why. Ask the user to pick one (a second `AskUserQuestion` with up to 4 of the top items, or just let them reply with a number/name if the list is long). Skip Stage B if `--pick=` was passed.
+
+## Step 6 — Set up the chosen item
+
+Once a specific item is chosen:
+
+1. **Produce its kickoff prompt.** If the chosen slice matches the one HANDOFF already wrote a "Kickoff prompt for the next session" for, **reuse that verbatim** in a fenced block. Otherwise synthesize one in the **same shape** handoff uses (Starting **‹item — Title›** · read CLAUDE.md + HANDOFF + relevant Briefs · then the 1–6 design-shape questions: Surface, Fields/inputs, Eligibility, Data path, feature-specific, Out-of-scope). Make it specific to the chosen slice, not generic.
+2. **Offer the setup as a confirmed next step — do not do it unprompted.** In one line, offer to: branch off the base (`git checkout <base> && git pull && git checkout -b <slice-branch>`) **or** create an isolated orbit (`/kit:orbit`) if the slice wants a forked DB. Wait for an explicit "yes" / branch name before running any git or orbit command — this is a state mutation and falls under the per-action confirmation rule.
+3. If the chosen slice is a `TODO` work item and the user confirms starting it, offer (don't auto-run) to move it to `IN_PROGRESS` via `mcp__launch-secure__work_item_move` / `work_item_update`.
+
+## Edge cases
+
+- **No HANDOFF.md yet** (first kickoff in a repo) — don't fabricate a "Where we are." Synthesize the board from git + last shipping log + work items, and tell the user "no HANDOFF snapshot yet — run `/kit:handoff` at the end of this session to create one." Kickoff degrades to a git+LS orientation.
+- **LS not connected** — skip Step 1d entirely; candidates come from HANDOFF + git. Note it once on the board.
+- **Clean tree, nothing in flight, empty backlog** — say so plainly ("nothing in flight; HANDOFF's next is ‹X›") and just present HANDOFF's "What's next" as the candidates. Don't invent work.
+- **HANDOFF wildly out of sync with git** (many stale "next" items already shipped) — lead with the drift block and suggest the previous session likely forgot `/kit:handoff`; offer to reconstruct current-state from git, but don't write HANDOFF here (that's `/kit:handoff`'s job).
+- **Mid-branch resume** (current branch already ahead of base) — surface "continue this branch" at the top of the 🔧 Resume in-flight list, and skip the branch-creation offer in Step 6 unless the user picks a different item.
+- **Everything lands in one bucket** (e.g. all candidates are stale) — that's fine; show the single list and skip Stage A (no choice to make), going straight to picking an item.
+
+## Notes for the assistant
+
+- Kickoff is **read + orient + choose**. It is the mirror of `/kit:handoff` (write) — keep the boundary clean: kickoff does not write `HANDOFF.md`, does not commit, does not push. The only mutations it ever performs are the explicitly-confirmed branch/orbit/work-item-move in Step 6.
+- The single most useful thing kickoff adds over just re-reading HANDOFF is **reconciliation** (Step 2): HANDOFF is hand-maintained and goes stale. Always cross-check it against git before presenting its "What's next" as gospel.
+- Prefer commit scopes, work-item ids, and shipping-log titles as candidate handles — they're stable and clickable. Don't pull the full chart/graph for this; kickoff is a fast orientation, not an analysis (`/kit:analyse` is for structure).
+- Respect the course: read/write LS through whichever server the active course points at, never cross prod/local.

package/scaffolds/ls-marketplace/plugins/kit/skills/orbit/SKILL.md

@@ -10,7 +10,8 @@ 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;** — print the path/env for an existing orbit (no shell mutation).
+- **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; --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.
@@ -43,7 +44,18 @@ Examples:
 
 ### switch
 
-`mcp__launch-orbit__orbit_switch(branch)` → print `cd <path>` + `envFile`. Don't run cd.
+`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