heyspex 0.2.5 → 0.2.7

package/dist/cli-templates/customer-vault/specs/protocols/spec-summary-authoring.md

@@ -1,83 +1,83 @@
----
-id: HS-PROTO-spec-summary-authoring
-name: Spec summary authoring — the plain-language `summary:` frontmatter contract
-type: protocol
-status: open
-priority: 1
-scope: vault
-owner: TODO — your name/handle
-created: 2026-06-18
-updated: 2026-06-18
-tags:
-  - protocol
-  - spec-filing
-  - frontmatter
-  - summary
-  - plain-language
-  - agent-experience
-triggers:
-  - author_summary
-  - file_milestone
-  - file_epic
-  - file_task
-  - file_protocol
-related:
-  - "[[entity-model]]"
-  - "[[spec-hierarchy]]"
-  - "[[canonical-frontmatter-templates]]"
-summary: |
-  Contract for the summary: frontmatter field: plain language readable by someone unfamiliar with the project, one opening sentence of 160 characters or fewer authored at filing time, with an optional second sentence for nuance.
-
----
-
-# Spec summary authoring — the plain-language `summary:` frontmatter contract
-
-This is the single source of truth for how to write a spec's `summary:` frontmatter field. The `summary:` is a short, plain-language description that explains what a spec is about to someone who has never heard of this project. Cards and list rows render only the opening sentence; drawers and search previews render the whole thing. This procedure is what the "fill in missing summary" prompt (in the console detail drawers and the `/hs-next` brief) hands a coding agent, and what a human should follow when authoring one by hand.
-
-
-## The contract
-
-- The **opening sentence** must be ONE complete, standalone sentence (target ≤160 chars) — list rows and cards render only this sentence.
-- **If this spec has a parent** (a task's parent epic, an epic's parent milestone): the opening sentence must convey two things in one plain sentence — what THIS spec delivers (the *what*) AND the parent's goal it serves (the *why*). A reader should grasp both from that one sentence. Put them in whichever order reads naturally when you say it out loud — often the easiest is the plain action first, then the goal it serves. Do NOT use a rigid "So that …, this …" template, and do NOT stack a long purpose clause in front of the subject before the reader knows what the thing is.
-- **If this spec has no parent** (a top-level milestone): the opening sentence is a standalone, plain-language summary of the spec itself.
-- The **full value** may add a sentence or two of nuance/context after the opening (target ≤400 chars total).
-- Write the WHOLE summary in plain, everyday language a twelve-year-old who has never heard of this project could understand — including the parent's goal. No project-invented jargon anywhere; no metaphor-as-terminology — the banned word list is **seam, wedge, moat, fuse, firehose, grain (noun), lane, spine, zombie, knob, plumbing, rollup (noun), ladder** (use plain replacements: "review level," "entry point," "defensibility," "auto-expiry," etc.); no examples, metaphors, or analogies. No non-standard abbreviations either — spell out project-internal shorthand ("acceptance criteria," not "AC"); only industry-standard acronyms a newcomer would recognize (SEO, API, CLI, MVP) are allowed. Only reach for a technical or project term when there is genuinely no plain word for the thing.
-- Write it as a YAML block scalar (`summary: |`) so multi-line prose stays readable.
-- Derive this spec's contribution from its own body and the parent's goal from the parent context provided — do not invent scope that isn't in the files.
-
-## Why these rules
-
-Every spec is read by people and by coding agents who may know nothing about the rest of the project. The summary is the one place that has to make sense on its own, with no surrounding context. A reader who is about twelve years old and has never heard of the project should still understand what the spec is about. That is why the language stays plain in every sentence, why made-up words are banned, and why the opening sentence has to stand completely on its own — many surfaces show only that one line.
-
-## Not the same thing as `## Explain Like I'm 12`
-
-Milestones and epics also carry a required `## Explain Like I'm 12` body section ([[spec-hierarchy]] §Explain Like I'm 12). The two share a voice and do **different jobs** — never write one as a paraphrase of the other. If the summary can be pasted into the section, or the section's first paragraph can be trimmed into the summary, one of them is wrong.
-
-| | `summary:` (frontmatter) | `## Explain Like I'm 12` (body) |
-|---|---|---|
-| **Answers** | What this spec delivers, and the parent goal it serves | What this work is FOR, and what changes when it ships |
-| **Length** | One standalone sentence, ≤400 chars total | Several short paragraphs |
-| **Kinds** | Milestone, epic, task, protocol | Milestone and epic only |
-| **Rendered** | Cards, list rows, drawers, search, the `/hs-next` brief | The spec body, read first |
-| **Assumes** | Nothing about the project, but compresses the WORK | Nothing about the project, and explains the PURPOSE before the work |
-
-The plain-language rules here (no invented jargon, no metaphor-as-terminology, no non-standard abbreviations) are the shared floor. The section adds six more properties on top — purpose before mechanism, name what it replaces, comparisons to real named products only, one idea per paragraph, no ids or file paths, end on the consequence. Those live in [[spec-hierarchy]].
-
-## Where it shows up
-
-- **List rows and cards** render the opening sentence alone (≤160 chars target).
-- **Detail drawers and search previews** render the full value (≤400 chars target).
-- The **`/hs-next` brief** prefers an authored `summary:` over a body-derived fallback when handing an agent its on-deck work.
-
-## When to author it
-
-`summary:` is always written **at the same time** as the rest of the spec is authored — a normal step of filing, like giving the spec a name. **Milestones and epics are never authored together with tasks** — they belong to different phases:
-
-| Phase | Kinds | Normal authoring moment |
-|---|---|---|
-| **Planning** | Milestone + Epic | Plan ingest, research promotion, milestone→epic breakdown — milestones and epics are filed in this wave only |
-| **Execution** | Task | What's Next → **Launch** → `/hs-next` breakdown only — tasks are never filed during plan ingest or alongside epics |
-
-`heyspex_push_plan` files epics only (`children: []`). Tasks come from the on-deck `/hs-next` breakdown via `heyspex_file_spec`. `heyspex_file_spec` **refuses** to create a milestone, epic, or task without a `summary` (returns `summary_required`). POST `/api/specs` still accepts the write but returns a soft `summary_missing` warning — prefer the MCP tool for agent filing. The `/hs-next` **author-then-claim** path remains a recovery surface for legacy specs filed before this enforcement, not the primary authoring path.
-
-It is optional on captures, research, memory, and ADRs. **Protocols require it** — `summary:` is the field the procedure catalog and `heyspex_get_procedure` surface to agents before they fetch the full body; a protocol without one forces body-text extraction, which is noisier and less precise. See [[entity-model]] §Universal fields and [[spec-hierarchy]] §Frontmatter requirements → "Author `summary:` at file time".
+---
+id: HS-PROTO-spec-summary-authoring
+name: Spec summary authoring — the plain-language `summary:` frontmatter contract
+type: protocol
+status: open
+priority: 1
+scope: vault
+owner: TODO — your name/handle
+created: 2026-06-18
+updated: 2026-06-18
+tags:
+  - protocol
+  - spec-filing
+  - frontmatter
+  - summary
+  - plain-language
+  - agent-experience
+triggers:
+  - author_summary
+  - file_milestone
+  - file_epic
+  - file_task
+  - file_protocol
+related:
+  - "[[entity-model]]"
+  - "[[spec-hierarchy]]"
+  - "[[canonical-frontmatter-templates]]"
+summary: |
+  Contract for the summary: frontmatter field: plain language readable by someone unfamiliar with the project, one opening sentence of 160 characters or fewer authored at filing time, with an optional second sentence for nuance.
+
+---
+
+# Spec summary authoring — the plain-language `summary:` frontmatter contract
+
+This is the single source of truth for how to write a spec's `summary:` frontmatter field. The `summary:` is a short, plain-language description that explains what a spec is about to someone who has never heard of this project. Cards and list rows render only the opening sentence; drawers and search previews render the whole thing. This procedure is what the "fill in missing summary" prompt (in the console detail drawers and the `/hs-next` brief) hands a coding agent, and what a human should follow when authoring one by hand.
+
+
+## The contract
+
+- The **opening sentence** must be ONE complete, standalone sentence (target ≤160 chars) — list rows and cards render only this sentence.
+- **If this spec has a parent** (a task's parent epic, an epic's parent milestone): the opening sentence must convey two things in one plain sentence — what THIS spec delivers (the *what*) AND the parent's goal it serves (the *why*). A reader should grasp both from that one sentence. Put them in whichever order reads naturally when you say it out loud — often the easiest is the plain action first, then the goal it serves. Do NOT use a rigid "So that …, this …" template, and do NOT stack a long purpose clause in front of the subject before the reader knows what the thing is.
+- **If this spec has no parent** (a top-level milestone): the opening sentence is a standalone, plain-language summary of the spec itself.
+- The **full value** may add a sentence or two of nuance/context after the opening (target ≤400 chars total).
+- Write the WHOLE summary in plain, everyday language a twelve-year-old who has never heard of this project could understand — including the parent's goal. No project-invented jargon anywhere; no metaphor-as-terminology — the banned word list is **seam, wedge, moat, fuse, firehose, grain (noun), lane, spine, zombie, knob, plumbing, rollup (noun), ladder** (use plain replacements: "review level," "entry point," "defensibility," "auto-expiry," etc.); no examples, metaphors, or analogies. No non-standard abbreviations either — spell out project-internal shorthand ("acceptance criteria," not "AC"); only industry-standard acronyms a newcomer would recognize (SEO, API, CLI, MVP) are allowed. Only reach for a technical or project term when there is genuinely no plain word for the thing.
+- Write it as a YAML block scalar (`summary: |`) so multi-line prose stays readable.
+- Derive this spec's contribution from its own body and the parent's goal from the parent context provided — do not invent scope that isn't in the files.
+
+## Why these rules
+
+Every spec is read by people and by coding agents who may know nothing about the rest of the project. The summary is the one place that has to make sense on its own, with no surrounding context. A reader who is about twelve years old and has never heard of the project should still understand what the spec is about. That is why the language stays plain in every sentence, why made-up words are banned, and why the opening sentence has to stand completely on its own — many surfaces show only that one line.
+
+## Not the same thing as `## Explain Like I'm 12`
+
+Milestones and epics also carry a required `## Explain Like I'm 12` body section ([[spec-hierarchy]] §Explain Like I'm 12). The two share a voice and do **different jobs** — never write one as a paraphrase of the other. If the summary can be pasted into the section, or the section's first paragraph can be trimmed into the summary, one of them is wrong.
+
+| | `summary:` (frontmatter) | `## Explain Like I'm 12` (body) |
+|---|---|---|
+| **Answers** | What this spec delivers, and the parent goal it serves | What this work is FOR, and what changes when it ships |
+| **Length** | One standalone sentence, ≤400 chars total | Several short paragraphs |
+| **Kinds** | Milestone, epic, task, protocol | Milestone and epic only |
+| **Rendered** | Cards, list rows, drawers, search, the `/hs-next` brief | The spec body, read first |
+| **Assumes** | Nothing about the project, but compresses the WORK | Nothing about the project, and explains the PURPOSE before the work |
+
+The plain-language rules here (no invented jargon, no metaphor-as-terminology, no non-standard abbreviations) are the shared floor. The section adds six more properties on top — purpose before mechanism, name what it replaces, comparisons to real named products only, one idea per paragraph, no ids or file paths, end on the consequence. Those live in [[spec-hierarchy]].
+
+## Where it shows up
+
+- **List rows and cards** render the opening sentence alone (≤160 chars target).
+- **Detail drawers and search previews** render the full value (≤400 chars target).
+- The **`/hs-next` brief** prefers an authored `summary:` over a body-derived fallback when handing an agent its on-deck work.
+
+## When to author it
+
+`summary:` is always written **at the same time** as the rest of the spec is authored — a normal step of filing, like giving the spec a name. **Milestones and epics are never authored together with tasks** — they belong to different phases:
+
+| Phase | Kinds | Normal authoring moment |
+|---|---|---|
+| **Planning** | Milestone + Epic | Plan ingest, research promotion, milestone→epic breakdown — milestones and epics are filed in this wave only |
+| **Execution** | Task | What's Next → **Launch** → `/hs-next` breakdown only — tasks are never filed during plan ingest or alongside epics |
+
+`heyspex_push_plan` files epics only (`children: []`). Tasks come from the on-deck `/hs-next` breakdown via `heyspex_file_spec`. `heyspex_file_spec` **refuses** to create a milestone, epic, or task without a `summary` (returns `summary_required`). POST `/api/specs` still accepts the write but returns a soft `summary_missing` warning — prefer the MCP tool for agent filing. The `/hs-next` **author-then-claim** path remains a recovery surface for legacy specs filed before this enforcement, not the primary authoring path.
+
+It is optional on captures, research, memory, and ADRs. **Protocols require it** — `summary:` is the field the procedure catalog and `heyspex_get_procedure` surface to agents before they fetch the full body; a protocol without one forces body-text extraction, which is noisier and less precise. See [[entity-model]] §Universal fields and [[spec-hierarchy]] §Frontmatter requirements → "Author `summary:` at file time".

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

@@ -1,28 +1,28 @@
----
-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).
-argument-hint: "<epic name> [<one-line summary>]"
-allowed-tools: mcp__heyspex__heyspex_backfill_epic
----
-
-> **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 `/mcp__heyspex__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.
+---
+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).
+argument-hint: "<epic name> [<one-line summary>]"
+allowed-tools: mcp__heyspex__heyspex_backfill_epic
+---
+
+> **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 `/mcp__heyspex__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/claude/hs-capture.md

@@ -1,62 +1,62 @@
----
-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).
-argument-hint: "[HS-CAP-XXXX | HS-IDEA-XXXX] [promote]"
-allowed-tools: mcp__heyspex__heyspex_active_capture, mcp__heyspex__heyspex_update_capture, mcp__heyspex__heyspex_promote_capture, mcp__heyspex__heyspex_promote_capture_to_diagnose, mcp__heyspex__heyspex_load_tools
----
-
-> **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 `/mcp__heyspex__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.
+---
+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).
+argument-hint: "[HS-CAP-XXXX | HS-IDEA-XXXX] [promote]"
+allowed-tools: mcp__heyspex__heyspex_active_capture, mcp__heyspex__heyspex_update_capture, mcp__heyspex__heyspex_promote_capture, mcp__heyspex__heyspex_promote_capture_to_diagnose, mcp__heyspex__heyspex_load_tools
+---
+
+> **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 `/mcp__heyspex__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/claude/hs-defer.md

@@ -1,29 +1,29 @@
----
-description: Defer remaining work on the claimed task — file a split child with handoff envelope and route it on-deck for the next agent.
-argument-hint: "[HS-XXXX-TASK] (optional — defaults to the task you are working)"
-allowed-tools: mcp__heyspex__heyspex_defer_spec, mcp__heyspex__heyspex_next_on_deck
----
-
-> **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** `mcp__heyspex__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]].
+---
+description: Defer remaining work on the claimed task — file a split child with handoff envelope and route it on-deck for the next agent.
+argument-hint: "[HS-XXXX-TASK] (optional — defaults to the task you are working)"
+allowed-tools: mcp__heyspex__heyspex_defer_spec, mcp__heyspex__heyspex_next_on_deck
+---
+
+> **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** `mcp__heyspex__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/claude/hs-ground.md

@@ -1,30 +1,30 @@
----
-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.
-argument-hint: "[topic words] [--summary <text>] [--areas a,b] [--tags x,y] [--max-tokens N]"
-allowed-tools: mcp__heyspex__heyspex_ground_plan, mcp__heyspex__heyspex_recall_memories
----
-
-> **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** `mcp__heyspex__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.
+---
+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.
+argument-hint: "[topic words] [--summary <text>] [--areas a,b] [--tags x,y] [--max-tokens N]"
+allowed-tools: mcp__heyspex__heyspex_ground_plan, mcp__heyspex__heyspex_recall_memories
+---
+
+> **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** `mcp__heyspex__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/claude/hs-next.md

@@ -1,29 +1,29 @@
----
-description: Pull the next on-deck execution prompt from the HeySpex roadmap (focus.yaml → in_progress → open).
-argument-hint: "[handheld|assist|auto] [HS-XXXX-EPIC | HS-XXXX] [--include-horizon] [--ignore-focus] [--claim]"
-allowed-tools: mcp__heyspex__heyspex_next_on_deck, mcp__heyspex__heyspex_claim_spec, mcp__heyspex__heyspex_release_spec, mcp__heyspex__heyspex_record_alignment
----
-
-> **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** `mcp__heyspex__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`).
+---
+description: Pull the next on-deck execution prompt from the HeySpex roadmap (focus.yaml → in_progress → open).
+argument-hint: "[handheld|assist|auto] [HS-XXXX-EPIC | HS-XXXX] [--include-horizon] [--ignore-focus] [--claim]"
+allowed-tools: mcp__heyspex__heyspex_next_on_deck, mcp__heyspex__heyspex_claim_spec, mcp__heyspex__heyspex_release_spec, mcp__heyspex__heyspex_record_alignment
+---
+
+> **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** `mcp__heyspex__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`).