heyspex 0.1.0 → 0.2.1

package/dist/cli-templates/harness-commands/claude/hs-res.md

@@ -0,0 +1,63 @@
+---
+description: Confidence-ladder research method's entrypoint — SpexCrawl via the Companion (search/gather) is PRIMARY + DeepSeek (synthesis); self-hosted Firecrawl is an AUTOMATIC fallback (no permission needed, owner ruling 2026-08-22), zero Claude/Anthropic involvement.
+argument-hint: "[research question/topic]"
+---
+
+# Research (`/hs-res`)
+
+> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
+
+## What to do
+
+1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
+   console doc-toolbar Promote pin via `heyspex_active_research`
+   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
+   capture body as the question. Either way, restate the scope and confirm with the user.
+
+2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
+   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
+   for research"). Decompose into a few independent search angles, then per angle:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
+   searches AND returns the cleaned pages of the top results. Specific extra URLs:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
+   Prerequisites: the Companion running and paired to the console. LAN mode
+   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
+   machine than the console — since HS-V9WH the Companion polls loopback consoles too
+   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
+   misdocumented as a requirement). When missing, the CLI exits 3 with
+   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
+   running or not polling this console.
+
+   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
+   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
+   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
+   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
+   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
+   prefer other reachable machines over the one the orchestrating session runs on; check
+   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
+   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
+   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
+   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
+
+3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
+   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
+   instructions to a temp prompt file.
+
+4. **Synthesize via DeepSeek** —
+   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
+   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
+   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
+   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
+   with `SYNTHESIZE_UNAVAILABLE`).
+
+5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
+   pipeline), with `sources` populated from the gathered URLs.
+
+**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
+`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
+`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
+permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
+user's explicit per-run permission, every time. If a CLI reports unavailable
+(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
+**stop** and tell the user — never silently substitute another backend. Full method,
+escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.

package/dist/cli-templates/harness-commands/claude/hs-resolve.md

@@ -0,0 +1,23 @@
+---
+description: Pull the top open item from the HeySpex Resolution lane (conflicts, dangling refs, cycles, prerequisites, validation/stale-index) with a fix brief. Replaces the old conflict-only prompt.
+argument-hint: "[HS-XXXX-EPIC | <item-key> | --ignore-focus]"
+allowed-tools: mcp__heyspex__heyspex_next_resolution
+---
+
+Invoke the `mcp__heyspex__heyspex_next_resolution` MCP tool to fetch the top open resolution item from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user can act on the fix brief.
+
+Argument parsing for `$ARGUMENTS` (all optional; if empty, call the tool with no parameters):
+
+- A token containing `:` (e.g. `dangling_ref:hs-epic-x:hs-task-y`) → pass as `item_key` (fetch that specific item's brief; bypasses the focus pin).
+- A bare spec id matching `HS-EPIC-*` / `HS-TASK-*` / `HS-MIL-*` / `HS-*-*` → pass as `scope` (deck-aware: restrict detection to that spec so its gating prerequisite/conflicts surface). This is what the On-Deck `resolve_command: /hs-resolve <epic-id>` passes.
+- `--ignore-focus` → set `ignore_focus: true` (skip the Neon resolution focus pin; lead with the top-ranked open item).
+
+Resolution precedence (built into the tool — do not re-implement): `item_key` → `scope`/`ignore_focus` (top-ranked of the open list) → the Neon focus pin (server-applied) → top-ranked open item. Items are ordered with **gating** and **errors first** (`orderResolutionItems`).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source} · {item.kind} · {item.key}_`. Do not summarize, paraphrase, or start executing actions from the brief without the user's go-ahead.
+
+This is the surviving `/hs-resolve` (the legacy conflict-only prompt that errored **"Not an Epic"** on a milestone has been retired — the resolver is item-centric and never type-checks the target). Authority from the brief's resolution menu: **Re-scan / clear** is agent-autonomous; **Switch to this**, **Defer**, **edge removal**, and **override** require explicit user confirmation. `stale_index` items expose **only** re-scan/clear — never an edge-mutating action.
+
+Detection is HTTP-only (the tool reads the console aggregator — the one detection path — it does not re-detect). If the tool errors with `CONSOLE_UNREACHABLE`, tell the user to **start the console dev server (port 3000, or run `hs server status` to see which port it actually bound)** — this only happens on a dev machine; SaaS console is always up. On `CONSOLE_TIMEOUT`, suggest retrying shortly (the server may be cold-compiling). On `ITEM_NOT_FOUND`, the `item_key` is not in the open set — list items with `/hs-resolve` (no args).
+
+This skill does NOT claim or build anything; it presents the fix brief. Sibling skills: `/hs-next` (build pipeline), `/hs-review` (review pipeline), `/hs-resolve` (this — resolution lane). See [[HS-0EJ6-RMCP-EPIC-hs-resolve-mcp-tool-and-skill]] and [[HS-I8FM-RSRF-EPIC-resolution-surface-api-and-pin]].

package/dist/cli-templates/harness-commands/claude/hs-review.md

@@ -0,0 +1,23 @@
+---
+description: Pull the next review-ready spec from the HeySpex review queue (review-focus.yaml → manifest traversal of `status: in_review` with HS-REV companion → folder scan).
+argument-hint: "[HS-XXXX-TASK | HS-XXXX-EPIC] [--ignore-focus]"
+allowed-tools: mcp__heyspex__heyspex_next_review
+---
+
+Invoke the `mcp__heyspex__heyspex_next_review` MCP tool to fetch the next review-ready spec from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user (reviewer) can walk acceptance against the parent spec + HS-REV companion.
+
+Argument parsing for `$ARGUMENTS` (all optional; if `$ARGUMENTS` is empty, call the tool with no parameters):
+
+- A bare token matching `HS-TASK-*` / `HS-EPIC-*` / `HS-*-*` → pass as `spec_id`.
+- A bare token matching `HS-ROADMAP-*` → pass as `roadmap_id`.
+- `--ignore-focus` → set `ignore_focus: true`.
+
+Resolution precedence (built into the tool, do not re-implement here): `args.spec_id` → `.heyspex/review-focus.yaml` pin → manifest traversal for `status: in_review` specs with an `HS-REV-<suffix>-*.md` companion → folder scan as fallback. Sorted by `updated:` ascending (oldest first).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source_kind} · {spec_id} · phase {phase_id} · age {age_in_review_days}d_`. Do not summarize, paraphrase, or start executing the returned prompt.
+
+This skill does NOT claim the spec. Reviewing is a human-in-loop activity by design (CLAUDE.md §Session Completion); the reviewer walks the four sections of the HS-REV companion (`## Acceptance verification`, `## Reviewer notes`, `## Memory candidates`, `## Decision: close or reopen`) and decides pass/reopen. Memory candidates are scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) — the prompt body includes the rubric and the conflict-check instruction.
+
+If the tool errors with `NO_REVIEW_READY`, tell the user the review queue is empty (no specs at `status: in_review` with an HS-REV companion) and suggest checking `specs/reviews/` for stale companions or filing the missing review doc. If `SPEC_NOT_IN_REVIEW`, surface the spec's actual status so the user can pick the right `/hs-review HS-XXXX` target. If `NO_REVIEW_DOC`, the parent spec is `in_review` but has no `HS-REV-<suffix>-*.md` companion — point the user at CLAUDE.md §Session Completion §3 for the four-section template.
+
+Cross-reference: [[HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review]] (spec), [[HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture]] §J17 (downstream Review surface that will call this tool from the "Copy `/hs-review`" affordance).

package/dist/cli-templates/harness-commands/claude/hs-view.md

@@ -0,0 +1,28 @@
+---
+description: Open one console surface in a chromeless app-mode browser window (solo console gauge) — the inspector's Pipeline tab first; follows the focus pin when no doc id is given. Thin wrapper over `hs view`.
+argument-hint: "[surface] [doc id] [--width N] [--height N] [--browser edge|chrome]"
+---
+
+# HeySpex solo-surface viewer (`/hs-view`)
+
+> Parity: `.commandcode/skills/hs-view/SKILL.md` · `.cursor/skills/hs-view/SKILL.md` · `.agents/skills/hs-view/SKILL.md`
+
+Optional macro over the one core ([[capability-three-faces-no-per-capability-slash]]): shell to `hs view`, never reimplement it. Design: [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]].
+
+## What to do
+
+1. **Resolve `$ARGUMENTS` by smart first-token detection** — grammar is positional, token-identical with the CLI:
+   - First token is not a surface slug → it is the doc id, in any form (`hlfj`, `hs-hlfj`, `HS-HLFJ`, a full basename); opens the inspector on its Pipeline tab. Pass it through as typed — the CLI normalises it.
+   - First token is a surface slug (`inspector`, `docs`, `whats-next`, `captures`, `session-log`, `settings`) → second token, if present, is the doc id (anchors `inspector` and `docs` only).
+   - `pipeline` is accepted but is not its own window: it is the inspector on its Pipeline tab.
+   - `docs` opens two panes: the doc beside the inspector on its Pipeline tab.
+   - No arguments → the inspector on its Pipeline tab, anchored on the focus pin (live-follow).
+   - Pass `--width` / `--height` / `--browser edge|chrome` through unchanged.
+2. **Run it yourself** from the repo root:
+   ```bash
+   node bin/hs.mjs view [<surface>] [<doc-id>] [flags]
+   ```
+3. The verb probes ground-truth dev-server status first — if the console is down, relay its message and offer `npm run dev` (don't start the server unprompted).
+4. Relay the one-line result (URL + window size); closing the window closes it, re-running reopens it.
+
+Never hand-build `msedge --app=…` invocations — the CLI verb owns server probing, URL resolution, and browser mechanics.

package/dist/cli-templates/harness-commands/claude/kill-ports.md

@@ -0,0 +1,32 @@
+---
+description: Kill every process listening on a TCP port in the range 3000–5999 (clears stuck dev servers).
+argument-hint: "(no arguments)"
+allowed-tools: PowerShell
+---
+
+**Always use the PowerShell tool for this command — never the Bash tool.** Bash routes to a POSIX shell in this environment and the PowerShell syntax below will fail there.
+
+Kill all processes that are **listening** on TCP ports in the range **3000–5999** inclusive. This clears orphaned dev servers (Next.js, console, companion bridges, etc.) that are holding ports.
+
+Run this single command via the **PowerShell** tool. It discovers the listening connections in range, reports each `port → pid (process name)` it is about to kill, then force-kills the unique owning PIDs and confirms:
+
+```powershell
+$conns = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
+  Where-Object { $_.LocalPort -ge 3000 -and $_.LocalPort -le 5999 }
+if (-not $conns) { Write-Output 'No listeners on ports 3000-5999. Nothing to kill.'; return }
+$pids = $conns | Select-Object -ExpandProperty OwningProcess -Unique
+foreach ($c in $conns) {
+  $p = Get-Process -Id $c.OwningProcess -ErrorAction SilentlyContinue
+  $name = if ($p) { $p.ProcessName } else { '?' }
+  Write-Output ("port {0,-5} -> pid {1} ({2})" -f $c.LocalPort, $c.OwningProcess, $name)
+}
+foreach ($procId in $pids) {
+  try { Stop-Process -Id $procId -Force -ErrorAction Stop; Write-Output ("killed pid {0}" -f $procId) }
+  catch { Write-Output ("could not kill pid {0}: {1}" -f $procId, $_.Exception.Message) }
+}
+```
+
+Notes:
+- Only TCP **listeners** are targeted, so client/outbound connections in that range are left alone.
+- If `Stop-Process` fails on a PID (e.g. a Windows system process like `svchost`, which needs admin and shouldn't be killed anyway, or a process that already exited), report the `Access is denied` / error and continue with the rest — do not abort the whole run.
+- After running, briefly summarize how many ports were freed.

package/dist/cli-templates/harness-commands/claude/prototype.md

@@ -0,0 +1,91 @@
+---
+description: Build an HTML/frontend prototype for the HeySpex Console. Files MUST land in spex-console/public/design-previews/<slug>-v<N>[-<variant>].html with a sibling .meta.json that validates against specs/schemas/prototype-meta.schema.json. Use this any time the user asks to "build a prototype", "mock up a UI", or invokes /frontend-design in this repo.
+argument-hint: "<slug> [--from-spec HS-XXXX] [--bump] [--variant <name>]"
+---
+
+This skill is the **implementation** of `specs/protocols/prototype-lifecycle-protocol.md`. The protocol is the SSOT — when they conflict, the protocol wins and this skill is the bug. Fetch it with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })` when you need the full rules.
+
+It applies to:
+
+- explicit `/prototype` invocation
+- any natural-language "build me an HTML prototype / mock / preview / canvas" ask
+- `/frontend-design` invocations in this repo (the plugin builds the artifact; this skill governs placement)
+
+## The contract — no exceptions
+
+**Required output paths** (both files, same commit):
+
+1. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html` — the self-contained prototype.
+2. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].meta.json` — the sidecar.
+
+Anything outside this folder — including a stray top-level `prototypes/` directory — is **invisible** to the console. The route at `spex-console/src/app/api/ui-design/prototypes/route.ts` reads this folder flat (no recursion, no nested folders). A prototype that doesn't show up in the Prototypes surface does not exist for the user.
+
+## Naming
+
+- **`<slug>`** (lineage slug) — kebab-case, describes the surface (`capture-canvas`, `shipped-surface`, `review-inbox`). May contain hyphens. **Match an existing lineage if you're iterating on a known surface** — grep `spex-console/public/design-previews/` before inventing a new slug.
+- **`-v<N>`** — version, starts at `-v1`. **Bump rather than overwrite.** The console groups versions into a lineage with full history. If `--bump`, increment from the highest existing `-v<N>` for that slug.
+- **`-<variant>`** (optional) — sibling variant within a version (e.g. `-v2-alt`, `-v2-minimal`, `-v2-terminal`). May contain hyphens. The console nests variants under their parent version and shows a `+N variants at vK` chip on the lineage card. Variants are for "A/B explorations of the same version", not new lineages.
+- **No `index.html`, no nested folders, no dated filenames.** Just `<slug>-v<N>[-<variant>].html`.
+
+## meta.json schema
+
+Validate against `specs/schemas/prototype-meta.schema.json`. Required: `title` + `status`. Always set `surface_area` and 1–4 `tags` on new sidecars (the console's filter rail depends on them — leaving them empty makes the prototype harder to find).
+
+```json
+{
+  "title": "Human-readable name (e.g. 'Capture canvas v2')",
+  "description": "One-paragraph summary: what it demonstrates, key interactions, aesthetic direction, technical notes. The console hides this on the card and shows it in the drawer Notes tab — write for that context.",
+  "status": "draft",
+  "surface_area": "capture | on-deck | preloader | shell | review | roadmap | other",
+  "tags": ["kebab-case", "1-to-4"],
+  "updated_at": "2026-06-03T18:17:00.000Z",
+  "design_doc": "specs/ui/<slug>-design.md  (optional but required for promotion to accepted)",
+  "linked_specs": [
+    "HS-XXXX-CAP-...",
+    "HS-XXXX-EPIC-..."
+  ],
+  "parent": "<slug>-v<N-1>.html  (optional, when this iterates on a prior version)",
+  "embeds": ["other-prototype-slug  (optional)"]
+}
+```
+
+- **`status` MUST be `"draft"` at create time.** Promotion to `"accepted"` runs through the console's `/api/ui-design/prototypes/<slug>/promote` route and requires both a linked `design_doc` AND a review entry under `specs/reviews/`. The skill does not write `accepted` — refuse if the user asks. (`"archived"` is for superseded versions; usually set later, not at create time.)
+- **Compute `updated_at` as `new Date().toISOString()`** at write time.
+- **`linked_specs`** accepts vault basenames (no `.md` extension) and `HS-*` IDs. Always include the capture/epic/task the prototype embodies. Pull from `--from-spec` if provided. Never invent IDs.
+- Reference siblings in this folder for examples — `shipped-surface-v1.meta.json` (thorough) or `on-deck-v2.meta.json` (minimal).
+
+## Workflow
+
+When this skill is invoked or matched:
+
+1. **Resolve lineage slug.** Match an existing slug if iterating on a known surface; otherwise pick a new kebab-case slug.
+2. **Resolve version.** Default `-v1`. If a file with the same slug already exists, default to bumping to the next integer; honour explicit `--bump`. **Never silently overwrite** — if the target file exists and `--bump` was not passed, surface the conflict and ask.
+3. **Resolve variant.** `--variant <name>` produces `<slug>-v<N>-<name>.html`. Without it, you produce the base variant.
+4. **Pull source spec context.** If `--from-spec HS-XXXX` is passed or the user references a spec, Read it first so the prototype reflects real content, not invented filler.
+5. **Aesthetic.** Defer to the user's brief (e.g. "Claude-in-PowerShell terminal aesthetic" overrides defaults). Otherwise honour console design-system tokens — fetch via `heyspex_design_*` MCP tools, do not grep `spex-console/DESIGN.md`. Recall UI memories first: `heyspex_recall_memories({ tags: ["ui", "console", "design-system"] })`.
+6. **Decide `surface_area` and `tags`.** Pick `surface_area` from the enum based on what the prototype shows. Pick 1–4 lowercase kebab-case `tags` covering the dominant patterns (e.g. `empty-state`, `dark-mode`, `keyboard-nav`).
+7. **Write both files in the same commit.** HTML at `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html`, sidecar at the matching `.meta.json` path. Single self-contained HTML file (inline CSS/JS).
+8. **Validate the sidecar shape** against the schema before saving. Required: `title` + `status`. `status` MUST be `"draft"`. `tags` MUST match `^[a-z0-9-]+$`. `surface_area` MUST be in the enum. `linked_specs[]` items MUST match `^HS-[A-Z0-9]+-` (family keys contain digits, e.g. `HS-9HVY-CAP`). Fix and re-write if any fail.
+9. **Confirm.** After writing, report the gallery URL (`/design-previews/<slug>-v<N>[-<variant>].html`). The console's UI-Design → Prototypes surface picks it up via `/api/ui-design/prototypes` and groups it into the matching lineage automatically.
+
+## Anti-patterns — do not do these
+
+- Do **not** create a new `prototypes/` folder at the repo root.
+- Do **not** nest as `<slug>/index.html`.
+- Do **not** overwrite an existing `<slug>-v<N>[-<variant>].html` — bump or use a new variant.
+- Do **not** ship without a sibling sidecar.
+- Do **not** write `status: "accepted"` from this skill — promotion runs through the console's `/promote` route only.
+- Do **not** invent linked specs. Only reference `HS-*` IDs that exist in the vault.
+- Do **not** leave `surface_area` and `tags` empty on new sidecars — the console's filter rail depends on them.
+- Do **not** Read `spex-console/DESIGN.md` for token lookups; use `heyspex_design_get_token` / `heyspex_design_get_pattern` MCP tools.
+
+## Reference
+
+- **Protocol (SSOT):** `specs/protocols/prototype-lifecycle-protocol.md` — fetch with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })`
+- **Schema (SSOT):** `specs/schemas/prototype-meta.schema.json`
+- **Discovery route:** `spex-console/src/app/api/ui-design/prototypes/route.ts`
+- **Surface component:** `spex-console/src/components/surfaces/ui-design-surface.tsx`
+- **Lineage parser:** `spex-console/src/lib/prototype-lineage.ts`
+- **Folder:** `spex-console/public/design-previews/`
+- **Thorough sidecar example:** `shipped-surface-v1.meta.json`
+- **Minimal sidecar example:** `on-deck-v2.meta.json`

package/dist/cli-templates/harness-commands/cursor/hs-auto.md

@@ -0,0 +1,40 @@
+---
+name: hs-auto
+description: Autonomous COO — route a filename or spec into dev-factory (pre-flight + dispatch).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-auto.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-auto [filename]`
+
+# Autonomous COO mode (`/hs-auto`)
+
+> Parity: `.commandcode/skills/hs-auto/SKILL.md` · `.cursor/skills/hs-auto/SKILL.md` · `.agents/skills/hs-auto/SKILL.md`
+
+## What to do
+
+1. **Parse `$ARGUMENTS`** — optional `filename` (spec id, spec `.md` path, or source file path). Bare token only; no flags required. **All prose before/after the command is the COO brief** (scope, slice, constraints) — not permission to implement in this session.
+
+2. **Resolve** — one shell call:
+
+   ```bash
+   node bin/hs.mjs auto [FILENAME] --json
+   ```
+
+3. On `error`, report and **stop**. (`source_plan` is **not** an error — proceed to step 5.)
+
+4. Run **pre-flight** commands from the `preflight` array in the JSON.
+
+5. Branch on `mode` (follow `coo_contract` in JSON when present):
+   - `source_plan` → diagnose/research with no dispatchable work yet: file remediation epic (no milestone required) → fleet decompose → file tasks with `target:` → re-resolve same source id → `dispatch`
+   - `discover` → `discover_command`
+   - `breakdown` → `breakdown_command` (review before filing)
+   - `dispatch` → `dispatch_command`
+
+6. Summarize results for the user (spec, target, gate, checkpoint).
+
+## COO contract
+
+**Do not write product code in this session** when `/hs-auto` was invoked. Delegate to the local fleet first. Follow fleet rules in `.commandcode/skills/hs-auto/SKILL.md` (Night Action builder ban, budget caps, bias constraint). Implement yourself only if the fleet gate fails after retries.
+
+Diagnose (`HS-…-DIAG-…`) and research (`HS-…-RES-…`) specs use the same source pipeline as capture/research in Phase 1 — they are planning inputs until a remediation epic + tasks with `target:` exist.

package/dist/cli-templates/harness-commands/cursor/hs-backfill.md

@@ -0,0 +1,31 @@
+---
+name: hs-backfill
+description: Retroactively backfill completed work into the vault (creates epic + child tasks at status:in_review, with an auto-generated review doc). Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-backfill.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-backfill <epic name> [<one-line summary>]`
+
+> **Platform asymmetry — read this, it is load-bearing.** Claude Code delivers only the **first whitespace token** of an MCP prompt's argument (GitHub [#14210](https://github.com/anthropics/claude-code/issues/14210), closed *not planned*), so the namespaced MCP prompt `/hs-backfill` can carry at most a single token — never a title plus a summary. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`.
+
+## What to do
+
+**1. Parse `$ARGUMENTS`:** leading text up to the first sentence break / newline → `epic_name` (required — ask if missing). Remainder of the string → a `summary` hint; the tool still requires a full plain-language `summary` per spec-summary-authoring, so expand/refine a terse arg using the conversation.
+
+**2. Gather from the conversation and/or `git log`/`git diff`:**
+- `plan_markdown` — what was actually done + which acceptance criteria were met.
+- `children` — each completed task as `{ name, summary }` (summary required per child).
+- `files_changed` — paths touched.
+- `kind` / `effort` / `tags` / `related` — optional classification.
+
+**3. Call** `heyspex_backfill_epic({ epic_name, summary, plan_markdown, children, files_changed, kind?, effort?, tags?, related? })`. All resulting specs land at `status: in_review` with an auto-generated review doc. This is for work done **outside** the normal `/hs-next` flow — never a substitute for it going forward.
+
+**4. Roadmap registration** defaults to `HS-ROADMAP-PRODUCT` phase `P0` (Review column) unless the call passes `skip_roadmap_registration: true`.
+
+**5. Report** the created epic id + task ids, and remind the user this does not commit or push — they still need to do that themselves.
+
+## Hard prohibitions
+
+- **Never** use this for work that hasn't actually happened — it documents DONE work retroactively; `/hs-push` is for planning work not yet started.
+- **Never** commit or push git.

package/dist/cli-templates/harness-commands/cursor/hs-capture.md

@@ -0,0 +1,65 @@
+---
+name: hs-capture
+description: Fast brain-offload capture — open/resume a capture, or route a named capture straight to promote. Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-capture.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-capture [HS-CAP-XXXX | HS-IDEA-XXXX] [promote]`
+
+> **Platform asymmetry — read this, it is load-bearing.** Claude Code delivers only the **first whitespace token** of an MCP prompt's argument (GitHub [#14210](https://github.com/anthropics/claude-code/issues/14210), closed *not planned*), so the namespaced MCP prompt `/hs-capture` can carry **at most a single capture id** — never an intent word. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`/`$1 $2`, so it is the only place `HS-CAP-1234 promote to research` can be parsed. The two surfaces are intentionally **not** identical; do not try to "make them match" — they cannot. Diagnosis + code anchors: [[HS-UIYC-34KP-RES-hs-capture-arg-routing-capture-id-and-pr]]. Owning epic: [[HS-7IOM-QKEF-EPIC-hs-capture-command-parity-resume-aware-s]].
+
+## What to do
+
+**1. Parse `$ARGUMENTS`** (both optional, order within the string is: id first, then intent words):
+- Leading token matching `HS-(CAP|IDEA|DRAFT)-[A-Z0-9-]{3,}` (case-insensitive) → `capture_id`. `DRAFT` is tolerated here for a stray/manual `HS-DRAFT-*` id (e.g. pasted by hand) — the auto-launch bridge ([[HS-I6NU]]) resolves every companion draft to a real `HS-CAP-*` id before ever invoking this command, so a `DRAFT` id should not normally reach here.
+- Remaining words containing `promote` (case-insensitive) → **promote intent**.
+- Neither → the no-arg path.
+
+If the capture tools are not already available in this session, call `heyspex_load_tools` first so `heyspex_active_capture` / `heyspex_promote_capture` / `heyspex_promote_capture_to_diagnose` are callable.
+
+**2. Route on what you parsed:**
+
+- **`capture_id` + promote intent** → route **straight to the promote exit**, bypassing the capture loop (do not run capture or ground=expand). Follow `/hs-promote`'s **§A. Capture → research** section verbatim (same tools, same two-phase confirm rule, same bug-fix→diagnose branch) — do **not** re-derive or fork that logic here; this command and `/hs-promote` share one promote implementation, this is just a second entrypoint into it.
+
+- **`capture_id`, no promote** → **attach/resume that exact capture**: call `heyspex_active_capture({ spec_id: capture_id })`. The server honors the explicit id (resolves that capture DB-first, disk fallback) and, when it already has a Core Idea + Summary, returns it as a **resume**. Then follow the beats below. A non-existent id returns a clear "no such capture" error — surface it; **never** silently start a fresh capture under a near-miss id.
+
+- **No arguments** → call `heyspex_active_capture({})`. It attaches to the capture on deck, or auto-creates a fresh `HS-CAP-*` when none is pinned. Then follow the beats below.
+
+**3. Run the beats** (the capture protocol — source of truth is `.cursor/skills/hs-capture/SKILL.md` and the MCP prompt markdown; do not re-derive them). Grounding and expanding are the **same act** — three beats, not four:
+
+| # | Action | Confirm? |
+|---|--------|----------|
+| 1 | **Capture** — every turn (including the user's answers to your questions), call `heyspex_update_capture` with `user_quote` = verbatim text. If Core Idea is empty, also pass `core_idea` + `summary` in the same call. | No |
+| 2 | **Ground = Expand + sufficiency check** — chat-only, peer-level grounding (technical co-founder). The grounding output IS the Expanded Concept: write it to `agent_expansion` via `heyspex_update_capture` in the same pass, automatically. No offer, no user confirmation. Every `heyspex_update_capture` response carries a `sufficiency` verdict (the same scorer `heyspex_promote_capture` runs) — while it fails, elicit the listed missing elements (`example` / `done_when` / a considered `kind`) from the user and write them in this same pass. | No |
+| 3 | **Promote** — the only exit, **gated**: only offered once the sufficiency verdict passes AND the owner has confirmed satisfaction with the enhanced capture. `heyspex_promote_capture` (research), or `heyspex_promote_capture_to_diagnose` for `kind: bug-fix`. The promote-time gate stays as defense-in-depth. **`heyspex_promote_capture` creates an outline, not a finished hand-off** — the response's `research_still_stub`/`next_step` fields say so when the research doc still has unfilled `_TBD — fill in this section._` placeholders; run `/hs-res` against it before `heyspex_promote_research` (which refuses stubs with `RESEARCH_STILL_STUB` as a backstop). | Yes |
+
+After beat 2, the two choices depend on the sufficiency verdict ([[HS-X8GS-T9T6-EPIC-capture-sufficiency-gate-grounding-time]]):
+- **Verdict fails** → present **iterate** and **enhance to readiness** (elicit the missing elements; never invent content to pass the gate). Do **not** present "promote to research" as a live option — an explicit owner instruction to promote anyway still wins.
+- **Verdict passes** → show the enhanced capture and ask if the owner is satisfied with it; on that yes, present exactly two choices: **promote to research** (or promote-to-diagnose for `kind: bug-fix`) or **iterate**. A promote call is spent only after the owner's confirmation (confirm-before-offer + confirm-before-spend).
+
+Never present "do you want to expand" as a choice — expansion already happened.
+
+**Open-the-doc offer (agent captures only, owner ruling 2026-08-11):** Companion / Chrome-extension captures auto-open the solo window; agent captures must **not**. When `heyspex_update_capture` returns `offer_open_viewer` (first materialization) — or the first time the capture doc exists on disk — print that offer verbatim alongside promote/iterate (or right after the first "captured" ack):
+
+> Want to see `HS-…-CAP`? Say **yes** / **open** / **show** and I'll open the doc.
+
+On `yes` / `open` / `show`, immediately run `node bin/hs.mjs view docs <spec_id>` from the repo root. Do not ask twice, do not open unprompted, do not nag on later iterates.
+
+**Iterate is the default continuation (owner ruling 2026-07-12).** While the capture sits at that choice, the user's next prose that isn't an explicit "promote" or "discard" IS the iterate move — even when it reads like a new idea or a work order ("please add …"), and even though the user never says "iterate". Append it to the SAME capture: `heyspex_update_capture` with the **explicit `spec_id`** of the capture in flow (never no-arg `heyspex_active_capture({})`, which can mint a fresh capture), re-ground into `agent_expansion`, and re-present the two choices. Only open a new capture when the prose is clearly a separate idea with no thread back — say so in one line first.
+
+**Kind suggestion (during beat 2, HS-RZQO):** when the content signals a non-default kind — bug/error/broken/regression language → `bug-fix`; a bare URL/link-only body → `clip`; a pointer to a doc/resource → `reference`; an open question → `question` — offer it in the same reply ("this reads like a bug-fix capture — reclassify?") and on the user's yes pass `kind` in the next `heyspex_update_capture` call. Suggest once, never auto-apply, never nag.
+
+**Model routing & thread split/spawn (owner ruling 2026-08-11):** settings at `.heyspex/config.yaml` → `agent_behaviors.capture_on_idea.{default_model, model_switch_mode, thread_split_mode}`; full table in `capture-guardrails.md` §"Capture model routing & thread split/spawn" and `.cursor/skills/hs-capture/SKILL.md`. On a first/only-turn capture, offer or silently delegate a model switch per `model_switch_mode` (`ask`\|`silent_delegate`\|`off`) — never a live silent switch, that's not possible. When new mid-thread prose isn't a continuation, judge whether it benefits from this thread's context: benefits → split (`Agent(subagent_type:"fork")` on a new capture id); doesn't → spawn (fresh `Agent()`); genuinely unsure and `thread_split_mode: ask` → `AskUserQuestion` with exactly those two options.
+
+On a **resume** (capture already has Core Idea + Summary), skip re-capturing: greet with what's already there and offer the two resume moves — **iterate** (refine with new verbatim input) or **promote**. Expansion is automatic during grounding, not a menu item — there is **no** separate `/hs-expand` command or skill.
+
+## Hard prohibitions
+
+- **Never** offer to file epics, tasks, or implementation plans — promote-to-research (or promote-to-diagnose) is the only exit.
+- **Never** implement the captured idea straight from the capture — its only road to code is promote-to-research → `/hs-promote <research-id>` + `/hs-next <resulting-id> [front]`. Milestone/epic/task filing is never skipped; front mode (handheld/assisted/autonomous) controls supervision, never whether that filing happens. The old permission-gated direct-implementation bypass is retired (research-capture-protocol §"From research to code — always through milestone/epic/task (no bypass)").
+- **Never** ask the user whether to expand — Ground=Expand auto-writes `agent_expansion` every time, with no confirmation gate.
+- **Never** auto-open a browser / solo window for an agent-originated capture — offer once (`yes`/`open`/`show`) and only then run `hs view docs <id>`.
+- **Never** alter words inside a `## Notes` quote (format-wrapping is fine; word substitution is not).
+- **Never** create a `type: research` doc without beat-3 (or promote-intent) confirmation.
+- **Never** commit or push.

package/dist/cli-templates/harness-commands/cursor/hs-defer.md

@@ -0,0 +1,32 @@
+---
+name: hs-defer
+description: Defer remaining work on the claimed task — file a split child with handoff envelope and route it on-deck for the next agent.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-defer.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-defer [HS-XXXX-TASK] (optional — defaults to the task you are working)`
+
+> **SaaS-safety note:** orchestration lives in `vendor/heyspex-mcp/cli.mjs` (`heyspex_defer_spec` → `POST /api/specs/:id/defer`). Do not re-implement the defer write path here.
+
+## What to do
+
+When the user sends `/hs-defer` (optionally with a bare `HS-TASK-*` id):
+
+1. **Identify the parent task** — the optional arg, else the spec you currently hold a claim on.
+
+2. **Author the handoff envelope** from session context (do not ask the user to paste a handoff prompt):
+   - `reason` — why you are deferring (context budget, blocked, lane hand-off, …)
+   - `summary_done` — verified work completed this session
+   - `remaining` — actionable items for whoever picks it up
+   - `success_criteria` — how the reviewer knows the deferred work is done
+
+3. **Call** `heyspex_defer_spec` with `{ spec_id, reason, summary_done, remaining, success_criteria }` plus optional `parent_status` (`in_review` default, or `in_progress` when the parent is not independently reviewable), `effort`, `child_name`.
+
+4. **Tell the user** the returned `child_id` and that they can open a fresh window and run `/hs-next` to continue. The tool pins the child on-deck, releases the parent claim, and records WIP on the epic.
+
+## Not this command
+
+- `hs defer` / `hs undefer` — time-shifts a spec via `defer_until` ([[HS-ZZBN]]), not delegation split-child defer.
+
+Cross-reference: [[HS-MS3T-1U0Z-TASK-hs-defer-mcp-tool-and-slash-command]], [[HS-DTL1-CX5K-CAP-task-split-handoff-when-context-runs-low]], [[HS-HXE2-YQ5A-EPIC-delegation-defer-work-from-one-agent-to]].

package/dist/cli-templates/harness-commands/cursor/hs-dev.md

@@ -0,0 +1,24 @@
+---
+name: hs-dev
+description: Show or switch the HeySpex dev/prod mode and dev-mode reliance (local vs cloud) — which console, read tier, and write mode everything points at.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-dev.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-dev [mode:local|mode:cloud|mode:prod]`
+
+# HeySpex dev/prod mode (`/hs-dev`)
+
+> Parity: `.commandcode/skills/hs-dev/SKILL.md` · `.cursor/skills/hs-dev/SKILL.md` · `.agents/skills/hs-dev/SKILL.md`
+
+Admin/dev-only. Empty `$ARGUMENTS` → status; `mode:local` / `mode:cloud` / `mode:prod` (or bare `local|cloud|prod`) → switch. `mode:local`/`mode:cloud` imply dev mode with that reliance.
+
+## What to do
+
+1. **Call the MCP tool** (primary): `heyspex_dev_mode({ action: "get" })` for status, or `heyspex_dev_mode({ action: "set", mode: "<target>" })` to switch. Fallback when the `heyspex_*` tools are missing: `node bin/hs.mjs dev [mode:<target>]`.
+2. **Report** the resolved mode / reliance / console URL / read tier / write mode WITH the source of each value. Flag a stale local override (`localOverride.staleAgainstCloud`) explicitly — `~/.heyspex/dev-mode.json` wins over the cloud setting on this machine.
+3. On a switch, confirm what was written (`~/.heyspex/dev-mode.json`, `console_url` in `~/.heyspex/credentials.yaml`) and whether the cloud admin setting updated; an unreachable console never blocks the local switch — relay `cloud.error` plainly.
+
+Semantics: `prod` and `dev+cloud` → cloud console (app.heyspex.com), Neon reads, cloud writes; `dev+local` → localhost:3000, disk reads, local writes.
+
+Full method: `.commandcode/skills/hs-dev/SKILL.md`.

package/dist/cli-templates/harness-commands/cursor/hs-doctor.md

@@ -0,0 +1,36 @@
+---
+name: hs-doctor
+description: Diagnose + repair the HeySpex install surfaces (MCP, hooks, skills, git hooks, deps) — the fallback when heyspex_* MCP tools are missing or broken.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-doctor.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-doctor (no arguments)`
+
+# HeySpex doctor (`/hs-doctor`)
+
+> Parity: `.commandcode/skills/hs-doctor/SKILL.md` · `.cursor/skills/hs-doctor/SKILL.md` · `.agents/skills/hs-doctor/SKILL.md`
+
+Works even when the `heyspex` MCP server is down — it shells out to the in-repo doctor script, no MCP tools required. **Run the commands yourself.**
+
+## What to do
+
+1. **Diagnose (read-only)** — parse per-surface status:
+   ```bash
+   node scripts/heyspex-doctor.mjs --json
+   ```
+   (Same as `npm run doctor` / `hs doctor --json`.) Result: `{ mode, ok, results: [{ id, label, status, detail, fix, human }] }` — `status` ∈ `ok | warn | fail`.
+
+2. **Repair the fixable gaps** — if any surface is `fail` (or a `warn` you want cleared) with a `fix` array:
+   ```bash
+   node scripts/heyspex-doctor.mjs --fix
+   ```
+   (Same as `npm run setup` / `hs doctor --fix`.) Idempotent. **Do not run while the spex-console dev server is live** — check `hs server status` first.
+
+3. **Hand un-fixable items to the human** — surfaces with a `human` field and no `fix` need a person: `deps` → `npm install`; `console-env` → copy `.env.example` to `.env.local` + fill `DATABASE_URL`/Clerk keys (ask owner); `node`/`git` → install the tool. Report each verbatim.
+
+4. **Reconnect for MCP** — if any `mcp-*` surface or `node_modules` was just fixed, the `heyspex_*` tools won't appear until the session restarts (Claude Code reads MCP once at startup). Tell the human to reconnect, then confirm `/mcp` + `/hs-next`.
+
+5. **Report** a short table: surface · status · fixed-or-needs-you, blockers first, then the reconnect reminder.
+
+Full method: `.commandcode/skills/hs-doctor/SKILL.md`.

package/dist/cli-templates/harness-commands/cursor/hs-ground.md

@@ -0,0 +1,33 @@
+---
+name: hs-ground
+description: Pre-plan grounding — a single bounded (~2k-token) report (Scope · Relevant specs · Relevant code · Graph hints · Conflicts · Gaps) assembled from the vault via lexical retrieval. You are the reranker; do not re-read the vault.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-ground.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-ground [topic words] [--summary <text>] [--areas a,b] [--tags x,y] [--max-tokens N]`
+
+> **Thin trigger.** Retrieval, scoring, conflict detection, caps, and report assembly all live in the MCP server (`vendor/heyspex-mcp/plan-ground.mjs`, `report:true` path). Do not re-implement grounding logic here, and do not turn the report into a vault-reading scaffold — that is the exact failure this command replaces ([[hs-ground-as-built-mcp-failure-modes]], [[HS-BZTV-G7R2-EPIC-hs-ground-three-tier-grounding-report]]).
+
+## What to do
+
+1. **Parse `$ARGUMENTS`** (topic is required — the bare words are the topic):
+   - free text → `topic` (and reuse as `summary` if no `--summary`)
+   - `--summary <text>` → `summary`
+   - `--areas a,b` → `areas` (subset of: console, companion, mcp, vault, indexer)
+   - `--tags x,y` → `tags`
+   - `--max-tokens N` → `max_tokens` (default 2000)
+
+2. **Call** `heyspex_ground_plan` with **`report: true`** plus the parsed args (and `check_conflicts: true`). The tool returns the bounded report as markdown directly.
+
+3. **Output the returned report verbatim.** It is already capped and cited. Then **stop and act on it** — do **NOT** open the discovered specs, run broad `rg`, or read whole files. The report's "Relevant specs" list is a wide lexical-recall window and **you are the reranker**: open *only* the one or two specs you judge directly relevant to the task, if any.
+
+4. **If the footer / report shows blocking conflicts** (`conflicts: N (BLOCKING …)`), resolve them via `/hs-resolve` before treating any conflicted spec as authoritative; re-run `/hs-ground` after resolution.
+
+5. **Heed the Conflicts caveat.** The conflict detector is claim-level and blind to design-supersession / identifier drift — for substrate/decision questions, check the design-vs-decision axis yourself ([[drift-is-two-axes-as-built-and-design-supersession]]).
+
+6. *(Optional)* If the task needs durable context, call `heyspex_recall_memories` with the report's `recall_memories_hint` tags — once, `limit: 10`.
+
+Sibling skills: `/hs-next` (build pipeline), `/hs-resolve` (resolution lane), `/hs-review` (review pipeline). Hand off a grounded plan to `/hs-push`.
+
+7. **When grounding a capture on deck, record it** (HS-KNJ8). Once the report is read and you have judged what is already built / already decided / the owner's own working reference / the residual delta, run `node scripts/record-grounding.mjs --capture <HS-CAP-id> --built "..." --decided "..." --reference "..." --delta "..."`. It writes `.heyspex/research-grounding.json` (the shape the deep-research gate reads) and marks the capture expanded. Until it runs, the capture-execution gate refuses research gathers, paid-model synthesis and routing-edit sub-agents for that capture.

package/dist/cli-templates/harness-commands/cursor/hs-handoff.md

@@ -0,0 +1,37 @@
+---
+name: hs-handoff
+description: Chat-surface form of `hs handoff` — resolves a short-code lane and resumes the spec it names, or (no code) runs close-out and hands back a fresh code + launch command.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-handoff.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-handoff [<CODE>]`
+
+# HeySpex handoff (`/hs-handoff`)
+
+> Parity: `.commandcode/skills/hs-handoff/SKILL.md` · `.cursor/skills/hs-handoff/SKILL.md` · `.agents/skills/hs-handoff/SKILL.md`
+
+Chat harnesses intercept `/hs` before the agent sees it and split on the space in `/hs handoff <CODE>`, so the terminal-only CLI form is unreachable from chat. This command is that fix, one word — same contract, no new engine code. `hs handoff`, `heyspex_record_wip`, and `hs export-events` already exist.
+
+Full contract: [[handoff-request-contract-close-out]] (vault decision) and `docs/admin/workflow/handoff.md`. Follow them; don't restate or reinvent them.
+
+## What to do
+
+1. **Parse `$ARGUMENTS`.** First token is a bare, non-flag string → resume flow, code = it. Empty → create flow.
+
+2. **Resume flow (`$ARGUMENTS` = `<CODE>`):**
+   ```bash
+   hs handoff load --lane <CODE>
+   ```
+   Spelled-out `load --lane` form, NOT the bare shorthand — as of [[HS-RVKN]] (owner ruling 2026-09-01) `hs handoff <CODE>` LAUNCHES a new terminal session by default, and this command's resume flow must stay a read inside the current chat session.
+   - **Hit**: prints `lane <CODE> · spec <ID> · phase <label> · <time>`. Show that to the human, then continue from it the standard way — run `/hs-next <ID>` (same steps as that command: call `heyspex_next_on_deck`, print `user_prompt_markdown` verbatim, decode `agent_dispatch` on the reply). The human already asked for the handoff; don't ask again before pulling the brief.
+   - **Miss** (`(no current handoff context)`): the lane is empty or expired — say so, then ask which spec to resume instead of guessing.
+
+3. **Create flow (no code)** — owner-locked contract, verbatim, do not invent steps or reorder them:
+   1. Close out first, automatically: `heyspex_record_wip` per worked epic, change-log rows + HS-REV companion at the review grain, `heyspex_release_spec` on open claims, then `hs export-events`. Skip silently anything already current.
+   2. Do NOT pick a code — it is MINTED. Owner ruling 2026-09-01: keys are minted, never invented (a hand-picked one once landed as `FLEET`).
+   3. Record the lane, minting the code in the same call: `hs handoff record --new-code --spec <next-target> --phase "<label>" --link <worked-epic-id...> --blocker "<open items, one line>"`. It prints `Handoff code: <CODE>` — that is the code you hand back.
+   4. Hand the human both forms, always: `/hs-handoff <CODE>` and `cd C:\dev-projects\heyspex-specs && claude "/hs-next <next-spec-id>"`.
+   5. Never treat the session as over — the human decides whether to continue here or launch the next one.
+
+Full method: `.commandcode/skills/hs-handoff/SKILL.md`.