@launchsecure/launch-kit 0.0.34 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "description": "LaunchSecure toolkit — launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",
@@ -56,25 +56,8 @@
     "launch-orbit": "./dist/server/orbit-entry.js",
     "launch-course": "./dist/server/course-entry.js",
     "launch-beacon": "./dist/server/beacon-monitor-entry.js",
-    "launch-rover": "./dist/server/rover-entry.js"
-  },
-  "scripts": {
-    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
-    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
-    "test:beacon": "vitest run --config vite.beacon.config.ts",
-    "test:radar": "vitest run --config vite.radar.config.ts",
-    "test:chart": "vitest run --config vite.chart.test.config.ts",
-    "build:deck-client": "vite build --config vite.deck.config.ts",
-    "build:council-client": "vite build --config vite.council.config.ts",
-    "build:client": "vite build",
-    "build:chart-client": "vite build --config vite.chart.config.ts",
-    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts src/server/launch-radar-entry.ts src/server/rover-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
-    "dev:client": "vite",
-    "dev:deck-serve": "cd ../.. && tsx watch packages/cli/src/server/deck-mcp-entry.ts serve",
-    "dev:chart": "pnpm build:server && pnpm build:chart-client && node dist/server/graph-mcp-entry.js serve",
-    "dev:server": "pnpm build:server && node dist/server/cli.js",
-    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\"",
-    "prepublishOnly": "pnpm build"
+    "launch-rover": "./dist/server/rover-entry.js",
+    "launch-bot": "./dist/server/launch-bot-entry.js"
   },
   "files": [
     "dist",
@@ -96,8 +79,6 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@launchsecure/claude-code-web": "workspace:*",
-    "@launchsecure/ui": "workspace:*",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.11.10",
     "@types/react": "^18.3.12",
@@ -121,6 +102,25 @@
     "react-router-dom": "^6.28.0",
     "tailwindcss": "^3.4.19",
     "vite": "^5.4.11",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "@launchsecure/claude-code-web": "0.0.1",
+    "@launchsecure/ui": "0.0.1"
+  },
+  "scripts": {
+    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
+    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
+    "test:beacon": "vitest run --config vite.beacon.config.ts",
+    "test:radar": "vitest run --config vite.radar.config.ts",
+    "test:chart": "vitest run --config vite.chart.test.config.ts",
+    "build:deck-client": "vite build --config vite.deck.config.ts",
+    "build:council-client": "vite build --config vite.council.config.ts",
+    "build:client": "vite build",
+    "build:chart-client": "vite build --config vite.chart.config.ts",
+    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts src/server/launch-radar-entry.ts src/server/rover-entry.ts src/server/launch-bot-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
+    "dev:client": "vite",
+    "dev:deck-serve": "cd ../.. && tsx watch packages/cli/src/server/deck-mcp-entry.ts serve",
+    "dev:chart": "pnpm build:server && pnpm build:chart-client && node dist/server/graph-mcp-entry.js serve",
+    "dev:server": "pnpm build:server && node dist/server/cli.js",
+    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\""
   }
-}
+}

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

@@ -1,38 +1,55 @@
 ---
-description: Create or update a repo-backed Brief — a long-form idea document committed as a markdown file under doc/ideas/. NOT a Comm Hub / CapCom comment. Use to capture an idea in the repo before promoting it to an Epic.
+description: Create or update a repo-backed Brief — a long-form document committed as a markdown file under doc/<category>/. The server syncs it to a Comm Hub comment; you don't post it yourself. Use to capture a feature, architecture decision, requirement, or playbook in the repo.
 ---
 
 # /kit:brief
 
-A **Brief** is a repo-backed idea document: a long-form description of a problem/opportunity written as a **markdown file committed to the repo** under `doc/ideas/<slug>.md`. It is the structured alternative to a free-form thought when the idea has enough shape to write down. Briefs get promoted to Epics on the Roadmap once they're DECIDED.
+A **Brief** is a structured long-form document that lives **both** as a markdown file in the repo at `doc/<category>/<slug>.md` **and** as a comment in the LaunchSecure Comm Hub. You write the file; the LS server's file-backed sync materializes the matching Comm Hub comment (favoring server → file convergence). See `doc/features/briefs.md`, `doc/playbook/runbooks/write-a-brief.md`, and `architecture/systems/briefs-discovery.md`.
 
-**A Brief is a FILE, not a comment.** Do NOT post Briefs to the LaunchSecure Comm Hub / CapCom via `communication_write`. Briefs live in the repo and travel through git like any other source artefact. (An earlier version of this skill posted Briefs as Comm Hub comments — that was wrong; Briefs are file commits.)
+**You write the file, the server does the sync.** Do NOT call `communication_write` / `communication_update` yourself — the brief becomes a Comm Hub comment automatically via the `discussion` handler once the file lands on the default branch (stamped with the category's `docCategory`, icon, and color). The only allowed Comm Hub touch from this skill is reading a `--from` discussion seed, and that's read-only.
+
+## Categories
+
+A Brief is **category-scoped** — the category determines its folder, icon, color, and where readers find it. Pick the one matching the question the reader is asking:
+
+| Reader is asking… | Category | Folder |
+|---|---|---|
+| "What are we building / what does LS offer?" | `features` | `doc/features/` |
+| "How does this system work / why built this way?" | `architecture` | `doc/architecture/` |
+| "What rule must I follow?" | `requirement` | `doc/requirement/` |
+| "How do I do X?" | `playbook` | `doc/playbook/` |
+| "Something happened, I want to remember" | `incident` | `doc/incident/` |
+| "Half-formed personal thought" | `ideas` | `doc/ideas/` (personal — see below) |
+
+`features`, `architecture`, `requirement`, `playbook`, `shipping-logs` are framework defaults; `ideas` and `incident` are this project's custom categories (`.launch-secure.config`). Other projects may differ — read `.launch-secure.config` `docCategories[]` if unsure. **Do not default to `ideas`** — that's the personal-scratch category, not a dumping ground for real briefs. Shipping-log briefs are written by `/kit:ship`, not this skill.
 
 Parse `$ARGUMENTS`:
 - **subcommand** (required) — `new` | `update` | `list` | `show`.
-- For **new**: `<title>` (required), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the default `doc/ideas/` location.
+- For **new**: `<title>` (required), `--category=<name>` (the category from the table; if omitted, infer from the title/intent and confirm before writing), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the resolved folder.
 - For **update**: `<slug-or-path>` and either a body description (re-generates body) or `--append=<text>` to add a section.
-- For **list**: `[--dir=<path>]` — defaults to listing `doc/ideas/`.
+- For **list**: `[--category=<name>]` to filter to one category, else lists briefs across all category folders. `[--dir=<path>]` to scan a specific dir.
 - For **show**: `<slug-or-path>`.
 
 Examples:
-- `/kit:brief new "Channels for Comm Hub"`
-- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123`
+- `/kit:brief new "Comm Hub channels" --category=features`
+- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123 --category=architecture`
 - `/kit:brief list`
+- `/kit:brief list --category=requirement`
 - `/kit:brief show launch-watch`
-- `/kit:brief update launch-watch --append="Resolved: use the Slack metaphor not Teams."`
+- `/kit:brief update comm-hub-channels --append="Resolved: use the Slack metaphor not Teams."`
 
 ## Location
 
-- **Default directory**: `doc/ideas/` at the repo root.
+- **Folder**: `doc/<category>/` at the repo root, where `<category>` is resolved from `--category` (or inferred + confirmed).
 - **Filename**: `<slug>.md`, where the slug is the kebab-cased title (e.g. "launch-watch — unified monitor" → `launch-watch.md`; keep it short — derive from the leading words, drop the subtitle after an em-dash).
-- Override with `--dir=<path>` only if the user asks.
+- Override the folder with `--dir=<path>` only if the user asks.
 
 ## Preflight
 
 1. Resolve the repo root (the working directory is the repo root in this project).
-2. For **new**, check `doc/ideas/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently.
-3. No MCP, no network, no Comm Hub calls. This skill only touches the filesystem + git.
+2. Resolve the category (from `--category`, or infer from the title and confirm with the user). Map it to `doc/<category>/`.
+3. For **new**, check `doc/<category>/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently. Also check the slug isn't already used under a *different* category before creating a duplicate.
+4. No `communication_write`. This skill writes the filesystem (+ optionally reads a `--from` seed); the server handles the Comm Hub side.
 
 ## Body template
 
@@ -74,31 +91,45 @@ When generating a NEW brief, write this skeleton as the file contents (plain mar
 
 ### new
 
-1. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `mcp__launch-secure__communication_read` and weave the relevant points into Problem / Proposed-direction; reading a seed discussion is fine, but the Brief itself is still written to a file, never posted back).
-2. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
-3. **Write the file** to `doc/ideas/<slug>.md` with the Write tool.
-4. Print the path written. Do NOT commit or push unless the user explicitly asks — leave it as a working-tree change for them to review and commit.
+1. Resolve the category and folder (see Preflight).
+2. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `mcp__launch-secure__communication_read` and weave the relevant points into Problem / Proposed-direction; reading a seed discussion is fine, but the Brief itself is still written as a file, never posted back).
+3. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
+4. **Write the file** to `doc/<category>/<slug>.md` with the Write tool.
+5. Print the path written and remind the user it materializes as a Comm Hub comment on the next default-branch push. Do NOT commit or push unless the user explicitly asks — leave it as a working-tree change for them to review and commit.
 
 ### update
 
-1. Resolve `<slug-or-path>` to a file under `doc/ideas/` (or the `--dir` override). If nothing matches, list candidates and stop.
-2. If `--append=<text>`, Read the file, append the text under a `## Update <ISO-date>` heading, and Write it back.
+1. Resolve `<slug-or-path>` with `node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug>` (it prints the resolved path on its `── <path> ──` header, or exits non-zero with candidates / an ambiguity list). If nothing matches, surface the candidates and stop; if ambiguous, ask which category.
+2. If `--append=<text>`, Read the resolved file, append the text under a `## Update <ISO-date>` heading, and Write it back.
 3. If a fresh description was passed, regenerate the body from the template + new description, show the user the diff briefly, then Write it back on confirmation.
 
 ### list
 
-List `doc/ideas/*.md` (or `--dir`). Render one line per brief: `slug  status  title` — read each file's `# Title` and `**Status**:` line to fill those columns.
+Run the bundled scanner — do NOT open and parse the brief files yourself:
+
+```
+node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" list [category]
+```
+
+It walks every `doc/<category>/` folder once and prints an aligned `CATEGORY  SLUG  STATUS  TITLE` table (pass a category to filter). Surface its output as-is; only read individual files if the user then asks to `show` one.
 
 ### show
 
-Read the file and print its contents as-is, no transformation.
+Run the bundled scanner — it resolves the slug across all category folders and prints the file with a `── <path> ──` header:
+
+```
+node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug-or-path>
+```
+
+Exit 1 = no match (it prints near-matches), exit 2 = ambiguous across categories (it lists them — re-run with the full path). Don't hand-glob `doc/` for the file.
 
 ## Constraints
 
-- **A Brief is a file, never a Comm Hub comment.** Do NOT call `communication_write` / `communication_update` to create or store a Brief. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
+- **You write a file; the server creates the comment.** Do NOT call `communication_write` / `communication_update`. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
+- **Pick the right category.** The folder, icon, and color all follow from it. Don't default to `ideas`.
 - **Plain markdown.** No HTML, no emojis unless the user wrote them.
 - **One brief, one file.** Don't fragment a brief across multiple files — append via `--append` to keep the document continuous.
 - **Don't commit or push on your own.** Write the file to the working tree and stop; committing/pushing is the user's call (per project conventions on no unauthorized pushes).
-- **`doc/ideas/` is the user's personal scratch.** Write the brief the user asked for, but do NOT reorganize, reclassify, or migrate other files in that directory. Promotion out of `doc/ideas/` is user-driven only.
+- **`doc/ideas/` is the user's personal scratch.** Write an `ideas` brief there only when the user explicitly asks for one, and do NOT reorganize, reclassify, or migrate other files in that directory. Promotion out of `doc/ideas/` is user-driven only.
 - **Cite real code.** Use launch-chart node ids in the References section — don't invent file paths.
 - **Don't auto-promote to Epic.** A Brief → Epic is a deliberate human action. Surface a hint at the end: "When DECIDED, promote this to an Epic on the Roadmap."

package/scaffolds/ls-marketplace/plugins/kit/skills/brief/briefs.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// briefs.mjs — list/show repo-backed Briefs without the agent reading every file.
+//
+// A Brief is a markdown file at doc/<category>/<slug>.md (see the /kit:brief
+// SKILL.md). This script scans the doc/ tree once and emits structured output so
+// the skill never has to open + parse N files itself.
+//
+// Usage (run from the repo root — process.cwd() must contain doc/):
+//   node briefs.mjs list [category]          # table: CATEGORY  SLUG  STATUS  TITLE
+//   node briefs.mjs show <slug-or-path>      # print one brief's contents
+//
+// Exit codes: 0 ok · 1 not found · 2 ambiguous · 3 usage error.
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, relative, basename, sep } from 'node:path';
+
+const DOC_ROOT = join(process.cwd(), 'doc');
+
+/** Recursively collect every *.md under doc/, tagged with its top-level category. */
+function collectBriefs(filterCategory) {
+  if (!existsSync(DOC_ROOT)) {
+    return { error: `no doc/ directory at ${DOC_ROOT}` };
+  }
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const rel = relative(DOC_ROOT, full); // e.g. features/foo.md, playbook/runbooks/bar.md
+        const category = rel.split(sep)[0];
+        if (filterCategory && category !== filterCategory) continue;
+        out.push({ category, slug: basename(entry.name, '.md'), rel, full });
+      }
+    }
+  };
+  walk(DOC_ROOT);
+  out.sort((a, b) => a.category.localeCompare(b.category) || a.slug.localeCompare(b.slug));
+  return { briefs: out };
+}
+
+/**
+ * Pull a brief's title + status without loading it into the model. Looks in both
+ * YAML frontmatter (`title:` / `status:`, used by the PUBLISHED briefs) and the
+ * markdown body (`# Title` / `**Status**:`, used by template-generated ones).
+ * Frontmatter wins for the title; the `**Status**:` line wins for status.
+ */
+function parseMeta(file) {
+  let fmTitle = '', fmStatus = '', h1 = '', bodyStatus = '';
+  try {
+    const lines = readFileSync(file, 'utf8').split('\n');
+    let inFm = false, fmDone = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (i === 0 && line.trim() === '---') { inFm = true; continue; }
+      if (inFm) {
+        if (line.trim() === '---') { inFm = false; fmDone = true; continue; }
+        const t = line.match(/^title:\s*(.+?)\s*$/i);
+        if (t && !fmTitle) fmTitle = t[1].replace(/^["']|["']$/g, '');
+        const s = line.match(/^status:\s*(.+?)\s*$/i);
+        if (s && !fmStatus) fmStatus = s[1].replace(/^["']|["']$/g, '');
+        continue;
+      }
+      if (!h1) {
+        const m = line.match(/^#\s+(.+?)\s*$/);
+        if (m) { h1 = m[1]; continue; }
+      }
+      if (!bodyStatus) {
+        const m = line.match(/^\*\*Status\*\*:\s*(.+?)\s*$/i);
+        if (m) bodyStatus = m[1];
+      }
+      if ((fmTitle || h1) && (fmStatus || bodyStatus) && fmDone) break;
+    }
+  } catch { /* unreadable → fall through to defaults */ }
+  return {
+    title: fmTitle || h1 || '(untitled)',
+    status: bodyStatus || fmStatus || '-',
+  };
+}
+
+/** First clause of a status, capped — keeps the table aligned when a file writes a sentence. */
+function shortStatus(s) {
+  const first = s.split(/[.(—]/)[0].trim() || s.trim();
+  return first.length > 18 ? first.slice(0, 17) + '…' : first;
+}
+
+function pad(s, n) { return s + ' '.repeat(Math.max(0, n - s.length)); }
+
+function cmdList(category) {
+  const { error, briefs } = collectBriefs(category);
+  if (error) { console.error(error); process.exit(1); }
+  if (briefs.length === 0) {
+    console.log(category ? `(no briefs in doc/${category}/)` : '(no briefs under doc/)');
+    return;
+  }
+  const rows = briefs.map((b) => {
+    const { title, status } = parseMeta(b.full);
+    return { category: b.category, slug: b.slug, status: shortStatus(status), title };
+  });
+  const w = (k) => Math.max(k.length, ...rows.map((r) => r[k].length));
+  const wc = w('category'), ws = w('slug'), wst = w('status');
+  console.log(`${pad('CATEGORY', wc)}  ${pad('SLUG', ws)}  ${pad('STATUS', wst)}  TITLE`);
+  for (const r of rows) {
+    console.log(`${pad(r.category, wc)}  ${pad(r.slug, ws)}  ${pad(r.status, wst)}  ${r.title}`);
+  }
+  console.log(`\n${rows.length} brief${rows.length === 1 ? '' : 's'}.`);
+}
+
+function cmdShow(target) {
+  if (!target) { console.error('show: need a <slug-or-path>'); process.exit(3); }
+  // Direct path hit (relative to cwd or absolute).
+  for (const p of [target, join(process.cwd(), target)]) {
+    if (existsSync(p) && statSync(p).isFile()) {
+      console.log(`── ${relative(process.cwd(), p) || p} ──\n`);
+      console.log(readFileSync(p, 'utf8'));
+      return;
+    }
+  }
+  // Otherwise resolve a slug across categories.
+  const { error, briefs } = collectBriefs();
+  if (error) { console.error(error); process.exit(1); }
+  const slug = basename(target, '.md');
+  const matches = briefs.filter((b) => b.slug === slug);
+  if (matches.length === 0) {
+    console.error(`no brief matching "${slug}".`);
+    const near = briefs.filter((b) => b.slug.includes(slug)).slice(0, 8);
+    if (near.length) {
+      console.error('did you mean:');
+      for (const n of near) console.error(`  ${n.category}/${n.slug}`);
+    }
+    process.exit(1);
+  }
+  if (matches.length > 1) {
+    console.error(`"${slug}" is ambiguous — matches ${matches.length} briefs:`);
+    for (const m of matches) console.error(`  ${m.rel}`);
+    console.error('re-run show with the full path.');
+    process.exit(2);
+  }
+  const hit = matches[0];
+  console.log(`── ${hit.rel} ──\n`);
+  console.log(readFileSync(hit.full, 'utf8'));
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case 'list': cmdList(rest[0]); break;
+  case 'show': cmdShow(rest[0]); break;
+  default:
+    console.error('usage: node briefs.mjs list [category] | show <slug-or-path>');
+    process.exit(3);
+}

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