heyspex 0.2.6 → 0.2.7

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

@@ -1,91 +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`
+---
+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-backfill.md

@@ -7,25 +7,25 @@ description: Retroactively backfill completed work into the vault (creates epic
 
 **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.
+> **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

@@ -7,59 +7,59 @@ description: Fast brain-offload capture — open/resume a capture, or route a na
 
 **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.
+> **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

@@ -7,26 +7,26 @@ description: Defer remaining work on the claimed task — file a split child wit
 
 **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]].
+> **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-ground.md

@@ -7,27 +7,27 @@ description: Pre-plan grounding — a single bounded (~2k-token) report (Scope
 
 **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.
+> **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-next.md

@@ -7,26 +7,26 @@ description: Pull the next on-deck execution prompt from the HeySpex roadmap (fo
 
 **Usage:** `/hs-next [handheld|assist|auto] [HS-XXXX-EPIC | HS-XXXX] [--include-horizon] [--ignore-focus] [--claim]`
 
-> **SaaS-safety note:** this file is a thin shim — the workflow orchestration (claim question wording, reply→action mapping, failure-mode handling) lives in `vendor/heyspex-mcp/cli.mjs` (`composeAgentOrchestration`) and is delivered to you as the structured `agent_dispatch` object. **Do not add orchestration prose here.** If a workflow detail needs to change, change it in the MCP server so customer workspaces can't corrupt it. See [[HS-CCKM-J6CD-RES-migrate-slash-command-orchestration-from]] and [[workflow-orchestration-belongs-in-mcp-not-claude-commands]].
-
-## What to do
-
-1. **Parse `$ARGUMENTS`** (all optional, order-flexible):
-   - **Run front** (default `handheld`): `handheld` · `assist` | `assisted` · `auto` | `autonomous` → canonical `front` for MCP (`handheld` | `assisted` | `autonomous`; omit when handheld/default)
-   - bare token `HS-EPIC-*` or `HS-*` → `spec_id`
-   - bare token `HS-ROADMAP-*` → `roadmap_id`
-   - `--include-horizon` → `include_horizon: true`
-   - `--ignore-focus` → `ignore_focus: true`
-   - `--claim` | `--auto-claim` → `auto_claim: true`. Skips the yes/proceed/confirm handshake and claims immediately — same mechanism `autonomous` front already triggers automatically (`shouldAutoClaimOnDeck` in `run-front.mjs`), just usable standalone at any front. `/hs-next HS-IUQO --claim` claims and starts handheld work with no ask; `/hs-next HS-IUQO assisted --claim` does the same at assisted supervision. (Redundant, never conflicting, with `autonomous` front, which already implies it.)
-
-2. **Call** `heyspex_next_on_deck` with `summary: true` plus the parsed args (including `front` when not handheld/default, and `auto_claim: true` when `--claim`/`--auto-claim` was passed).
-
-3. **Output the `user_prompt_markdown` field verbatim** to the user. Do not summarize, paraphrase, or trim. **Do NOT echo the `agent_dispatch` field** — it is a structured routing object you decode, not prose you print. (The @deprecated `prompt_markdown` field mirrors `user_prompt_markdown`; either is safe to print, but prefer `user_prompt_markdown`.) Schema: `specs/schemas/agent-dispatch.schema.json`.
-
-4. **On the user's reply**, decode `agent_dispatch`:
-   - Match the reply against each entry's `tokens` array under `on_user_reply` (or `drift_resolution_menu`, when present).
-   - If the matching entry has `actions`, invoke each `{ tool, args }` in order. If `execute_after: true`, begin executing the work in the same turn — no second permission ask. All listed tools (`heyspex_claim_spec`, `heyspex_record_alignment`, `heyspex_next_on_deck`, `heyspex_release_spec`) are pre-allowlisted.
-   - If the matching entry has `reply`, respond with that string verbatim.
-   - If the `default` entry is `"respond_to_user_question"`, treat the reply as a redirect: answer the user's actual question instead of claiming.
-   - For any tool error, look up its code in `agent_dispatch.failure_modes` and apply the named `handling` only when that error code was **returned by the tool call** — failure_modes are conditional, not a statement that the console is down. Trust `console_status.reachable` on the brief. Never hand-write vault files when `heyspex_file_spec` fails.
-   - On session hand-off, run the `on_handoff` actions (typically `heyspex_release_spec`).
+> **SaaS-safety note:** this file is a thin shim — the workflow orchestration (claim question wording, reply→action mapping, failure-mode handling) lives in `vendor/heyspex-mcp/cli.mjs` (`composeAgentOrchestration`) and is delivered to you as the structured `agent_dispatch` object. **Do not add orchestration prose here.** If a workflow detail needs to change, change it in the MCP server so customer workspaces can't corrupt it. See [[HS-CCKM-J6CD-RES-migrate-slash-command-orchestration-from]] and [[workflow-orchestration-belongs-in-mcp-not-claude-commands]].
+
+## What to do
+
+1. **Parse `$ARGUMENTS`** (all optional, order-flexible):
+   - **Run front** (default `handheld`): `handheld` · `assist` | `assisted` · `auto` | `autonomous` → canonical `front` for MCP (`handheld` | `assisted` | `autonomous`; omit when handheld/default)
+   - bare token `HS-EPIC-*` or `HS-*` → `spec_id`
+   - bare token `HS-ROADMAP-*` → `roadmap_id`
+   - `--include-horizon` → `include_horizon: true`
+   - `--ignore-focus` → `ignore_focus: true`
+   - `--claim` | `--auto-claim` → `auto_claim: true`. Skips the yes/proceed/confirm handshake and claims immediately — same mechanism `autonomous` front already triggers automatically (`shouldAutoClaimOnDeck` in `run-front.mjs`), just usable standalone at any front. `/hs-next HS-IUQO --claim` claims and starts handheld work with no ask; `/hs-next HS-IUQO assisted --claim` does the same at assisted supervision. (Redundant, never conflicting, with `autonomous` front, which already implies it.)
+
+2. **Call** `heyspex_next_on_deck` with `summary: true` plus the parsed args (including `front` when not handheld/default, and `auto_claim: true` when `--claim`/`--auto-claim` was passed).
+
+3. **Output the `user_prompt_markdown` field verbatim** to the user. Do not summarize, paraphrase, or trim. **Do NOT echo the `agent_dispatch` field** — it is a structured routing object you decode, not prose you print. (The @deprecated `prompt_markdown` field mirrors `user_prompt_markdown`; either is safe to print, but prefer `user_prompt_markdown`.) Schema: `specs/schemas/agent-dispatch.schema.json`.
+
+4. **On the user's reply**, decode `agent_dispatch`:
+   - Match the reply against each entry's `tokens` array under `on_user_reply` (or `drift_resolution_menu`, when present).
+   - If the matching entry has `actions`, invoke each `{ tool, args }` in order. If `execute_after: true`, begin executing the work in the same turn — no second permission ask. All listed tools (`heyspex_claim_spec`, `heyspex_record_alignment`, `heyspex_next_on_deck`, `heyspex_release_spec`) are pre-allowlisted.
+   - If the matching entry has `reply`, respond with that string verbatim.
+   - If the `default` entry is `"respond_to_user_question"`, treat the reply as a redirect: answer the user's actual question instead of claiming.
+   - For any tool error, look up its code in `agent_dispatch.failure_modes` and apply the named `handling` only when that error code was **returned by the tool call** — failure_modes are conditional, not a statement that the console is down. Trust `console_status.reachable` on the brief. Never hand-write vault files when `heyspex_file_spec` fails.
+   - On session hand-off, run the `on_handoff` actions (typically `heyspex_release_spec`).