heyspex 0.1.0 → 0.2.1

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

@@ -0,0 +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".

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

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

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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]].

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

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

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

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

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

@@ -0,0 +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.

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

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

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

@@ -0,0 +1,27 @@
+---
+description: Watch a dev-time log live (spex-console, companion, or a generic `devlog`-captured process) instead of asking the human to paste terminal output. Filters to errors/warnings/failed-request lines by default.
+argument-hint: "[console|companion|<name>] [--raw]"
+---
+
+# HeySpex live log watch (`/hs-log`)
+
+> Parity: `.commandcode/skills/hs-log/SKILL.md` · `.cursor/skills/hs-log/SKILL.md` · `.agents/skills/hs-log/SKILL.md`
+
+Admin/dev-only — resolves paths via `dev-factory/watch-dev-log.mjs`, then watches with the harness's own background-process tooling. **Run the commands yourself.**
+
+## What to do
+
+1. **Resolve the target.** Default to `console` if `$ARGUMENTS` is empty; otherwise the first token is the target (`console`, `companion`, or any other name — treated as the generic `devlog` pwsh-helper convention).
+   ```bash
+   node dev-factory/watch-dev-log.mjs <target>
+   ```
+   If it reports `missing`, tell the human how to start it (`npm run console:log` for `console`; the companion tray host self-logs once running; a generic target needs `devlog <cmd>` in their own terminal) and stop — don't start a dev server yourself unprompted.
+
+2. **Watch it.** Start a background `tail -f` over the resolved path(s) and stream it:
+   - Default: filtered to signal only — `grep -E --line-buffered -i "error|warn|exception|fatal|crash| 4[0-9][0-9] | 5[0-9][0-9] "` — so routine 200-OK request logs stay silent and only real problems surface.
+   - `--raw` in `$ARGUMENTS`: skip the filter, stream everything (useful for a first look, like the very first time this was set up).
+   - Multiple paths (e.g. `companion`'s 4 files) can be tailed together: `tail -n 0 -f path1 path2 ...`.
+
+3. **Report** the resolved path(s) and whether you're running filtered or raw, then stay quiet until something actually worth flagging comes through — don't narrate routine matched lines individually if they're clearly benign.
+
+Full method: `.commandcode/skills/hs-log/SKILL.md`.

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

@@ -0,0 +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`).

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

@@ -0,0 +1,70 @@
+---
+description: Promote whatever doc you hand it to its next stage — a capture (HS-CAP-*) to research, or a research doc (HS-RES-*) to a milestone with AI-assisted epic stubs. One verb, inferred by id prefix. Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token).
+argument-hint: "<HS-CAP-XXXX[,HS-CAP-YYYY...] | HS-RES-XXXX> [rest of args depend on which — see below]"
+allowed-tools: mcp__heyspex__heyspex_active_capture, mcp__heyspex__heyspex_promote_capture, mcp__heyspex__heyspex_promote_capture_to_diagnose, mcp__heyspex__heyspex_promote_research, 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 prompts (`/mcp__heyspex__hs-promote-capture`, `/mcp__heyspex__hs-promote-research`) can each carry at most a single token. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`.
+>
+> **Why one command instead of two.** `/hs-promote-capture` and `/hs-promote-research` used to be separate commands — which meant typing the word "promote" twice (`/hs-promote-capture HS-CAP-XXXX promote`) when the command name already said what it does. There's exactly one verb here — *promote whatever doc you hand it to its next stage* — so there's one command. The **id prefix alone** tells you which flow applies (`HS-CAP-*` vs `HS-RES-*` are mutually exclusive and mechanical to detect); the two flows underneath are otherwise unrelated (different tools, different payload shapes, different two-phase mechanics) and stay fully separate below — only the entrypoint is shared.
+
+## Step 0 — identify the doc
+
+Read the **leading token** of `$ARGUMENTS` (case-insensitive; captures may be a comma/whitespace-separated list):
+- Contains `-CAP` as its type label (legacy `HS-CAP-XXXX` or era-3 `HS-<fileKey>-<familyKey>-CAP-<slug>`) → go to **§A. Capture → research**.
+- Contains `-RES` the same way → go to **§A2. Research → milestone**.
+- **Era-3 short/display forms carry NO type label** — `HS-XV4W` (short id) and `HS-XV4W-HV6H` (file key + family key, the form humans see rendered) name a spec without saying its kind. Resolve the kind by fetching it: `heyspex_active_capture({ spec_id })` succeeding → it's a capture, §A. Otherwise treat it as research and try §A2. The tools accept any of these forms and collapse them to the stored short id themselves — never tell the user their id is wrong just because it carries (or lacks) the family key.
+- None of the above → ask the user which doc they mean (don't guess).
+
+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.
+
+---
+
+## §A. Capture → research (`HS-CAP-*`)
+
+**1. Parse the rest of `$ARGUMENTS`:**
+- Leading token(s) matching `HS-CAP-[A-Z0-9-]{3,}` (comma- and/or whitespace-separated) → `capture_ids` (1 or more).
+- Next token: `HS-RES-[A-Z0-9-]{3,}` → `target_research` = that id. Or the literal word `new`/`NEW` (also the default when this token is omitted entirely) → `target_research = "NEW"`; any remaining words up to an `enhances:` token → `new_research_name`.
+- A token shaped `enhances:HS-MIL-XXXX` anywhere in the string → `enhances`.
+
+**2. Route by kind:**
+- For each `capture_id`, read its `kind:` via `heyspex_active_capture({ spec_id: capture_id })`.
+- Exactly one capture_id AND its `kind: bug-fix` → `heyspex_promote_capture_to_diagnose({ capture_id })` (creates `HS-DIAG-*`). Never mix a bug-fix capture into a multi-capture research promote.
+- Otherwise → `heyspex_promote_capture({ capture_ids, target_research, new_research_name?, enhances? })`:
+  - `target_research === "NEW"` is **two-phase**: first call **omits** `accepted_outline` — it returns a proposed `{ name, outline, tags, enhances_suggestion }`. **Show it to the user and confirm** before calling again with the same args plus `accepted_outline` (Phase 2 performs the writes). Never skip straight to Phase 2.
+  - An existing `target_research` id is single-phase (direct, idempotent append) — no outline confirm needed.
+  - A `CAPTURE_INSUFFICIENT` error names the missing elements (core-idea, example, done-criteria, kind, user-stories) — the correct response is to elicit that detail from the user and improve the capture, not to pass `force_promote: true` unless the human explicitly says to promote anyway.
+  - **Check the outline against the capture's own Notes before presenting it.** Before showing `proposed_outline` (AI-proposed or agent-authored) to the user, walk every verbatim quote in the capture's `## Notes` and state plainly whether the outline addresses it. If a quote asks for something the outline doesn't cover, add a section for it or say so before asking for confirm — a missed verbatim quote is exactly what got two real items dropped from a milestone in this vault's own history ([[HS-GDT5-F16L-DIAG-promote-flow-drafts-research-and-stubs]]).
+  - **Outline confirm ≠ research done.** Phase 2 only writes the research **stub** — every section body is the literal placeholder `_TBD — fill in this section._`. Confirming the outline approves its *shape* (section headings), not its findings. As the very next step after Phase 2 creates the file, fill in every section with real content **by running the `/hs-res` method** (SpexCrawl gather via the Companion + DeepSeek synthesis — see `.claude/commands/hs-res.md`); **never author the research yourself in the main session** — main-session self-research skips the routed research seats and burns the expensive model on work the fleet owns. Do not report the research as complete, and do not move on to `/hs-promote-research`, until the TBD placeholders are gone. (`heyspex_promote_research` mechanically refuses with `RESEARCH_STILL_STUB` while any remain, but don't rely on that gate — write the research because it's the point of the flow, not because a check will otherwise fail.)
+
+**3. Report the result** — the research id (created or extended) or diagnose id created, and confirm the capture(s)' `promoted_to` now points at it.
+
+---
+
+## §A2. Research → milestone (`HS-RES-*`)
+
+**1. Parse the rest of `$ARGUMENTS`:**
+- `research_id` is the leading `HS-RES-*` token (already identified in Step 0).
+- Next word matching `spawn|augment|both` → `intent`. Default `spawn` when omitted.
+- Next token: `HS-MIL-[A-Z0-9-]{3,}` → `target_milestone` = that id. Or the literal word `new`/`NEW` (also the default when this token is omitted entirely) → `target_milestone = "NEW"`; remaining words → `new_milestone_name`.
+- If `intent` includes `augment`, any remaining `HS-EPIC-[A-Z0-9-]{3,}` tokens → `augment_epic_ids` (required in that case — ask for them if `augment` was requested but none were given).
+
+**2. Default policy:** `target_milestone: "NEW"` unless the user names an **existing `status: open`** milestone that clearly extends the same thesis. Spawning into an `in_progress` milestone is blocked unless the owner explicitly passes `attach_to_in_progress_milestone: true` + `attach_override_reason` (≥40 chars audit trail) — never default to this path or infer the override on the agent's own judgment.
+
+**3. Phase 1 — proposal.** Call `heyspex_promote_research({ research_id, target_milestone, new_milestone_name?, intent, spawn_epic_count?, augment_epic_ids? })` **without** `accepted_stubs`. Show the user the returned `proposed_stubs[]` and let them edit/remove/approve.
+   - **If `ai_proposal.ok === false` (e.g. `reason: "no_api_key"`), `proposed_stubs` comes back empty — the agent must author the stubs itself.** This is NOT a shortcut to skip the confirm step; it makes the confirm step *more* necessary, not less, because nothing upstream has vetted these stubs yet. Author them from the research doc's actual content, present them to the user exactly as you would an AI proposal (name/kind/effort/rationale per stub), and wait for a real approval turn before calling Phase 2. **Do not call Phase 2 in the same turn you authored the stubs in** — that is precisely the failure this line exists to prevent (observed 2026-08-12: an agent self-authored 3 epic stubs and executed `accepted_stubs` in the same tool-call batch with no human turn in between).
+   - **Check the stubs against the SOURCE CAPTURE's own Notes before presenting them.** Before showing `proposed_stubs` (AI-proposed or agent-authored) to the user, walk every verbatim quote in the source capture's `## Notes` — the capture(s) named in the research doc's `sources_captures`, not just the research doc's own prose, since a two-hop drift can lose fidelity the research doc's text won't show — and confirm each is addressed by a stub or explicitly named as out of scope. This check caught two real gaps missed by an agent-authored stub list in this vault's own history ([[HS-GDT5-F16L-DIAG-promote-flow-drafts-research-and-stubs]]).
+
+**4. Phase 2 — execute (after human confirms).** Call again with the same args plus `accepted_stubs: [...]` (the confirmed, possibly-edited subset) to perform the transactional write.
+
+**5. Report the result** — the milestone id (new or existing) plus spawned epic ids, or the augmented epic ids. Note that research stays `status: open` (research is evergreen) — only its `enhances:`/`spawned_epics:` links change.
+
+---
+
+## Hard prohibitions
+
+- **Never** execute a Phase-2 write (`accepted_outline` or `accepted_stubs`) without the human having seen and confirmed the Phase-1 proposal. For `accepted_stubs` the tool now refuses this mechanically: the proposal turn leaves a marker keyed on the research id, and an execute turn without one returns `STUB_REVIEW_REQUIRED`. If the human replaced every proposed stub, pass `stub_edit_note` (≥40 chars) saying what they changed — otherwise a fully-drifted execute returns `STUB_REVIEW_DRIFT`. As with `RESEARCH_STILL_STUB`, treat the mechanical refusal as the backstop, not the first line of defense.
+- **Never** call `heyspex_promote_research` against a research doc that still carries `_TBD — fill in this section._` placeholders — fill it in via the `/hs-res` method first (§A step 2 above), never by authoring the research yourself in the main session. The tool refuses this mechanically (`RESEARCH_STILL_STUB`) but the agent should never rely on that as the first line of defense.
+- **Never** route a bug-fix capture through `heyspex_promote_capture` — it goes to `heyspex_promote_capture_to_diagnose` instead.
+- **Never** attach a research promote to an `in_progress` milestone without an explicit owner override (`attach_to_in_progress_milestone` + `attach_override_reason`).
+- **Never** commit or push.

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

@@ -0,0 +1,35 @@
+---
+description: Push an epic implementation plan into the HeySpex vault, optionally pinning it on deck in the same call. Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token). Consolidates the former hs-push / hs-push-next split into one command + flag.
+argument-hint: "[<epic name>] [--next] [--reason <focus reason>]"
+allowed-tools: mcp__heyspex__heyspex_push_plan
+---
+
+> **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 prompts `/mcp__heyspex__hs-push` / `/mcp__heyspex__hs-push-next` can each carry at most a single token — never an epic name plus a `--next` flag plus a focus reason together. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`. It also **consolidates** the old two-prompt split (`hs-push` vs `hs-push-next`) into one command: both ultimately call the same `heyspex_push_plan` tool with only `on_deck` differing, so there is no behavior lost by merging them here — just one flag instead of two command names.
+
+## What to do
+
+**1. Parse `$ARGUMENTS`:**
+- `--next` (anywhere, case-insensitive) → `on_deck = true`. Absent → `on_deck = false` (file the epic without pinning focus).
+- `--reason <text>` → `focus_reason` (only meaningful when `on_deck` is true; rest of that flag's value up to the next `--` flag or end of string).
+- Remaining leading, non-flag text → an `epic_name` hint. Optional — if omitted, derive the title from the plan under discussion in chat.
+
+**2. Gather the rest of the payload from the conversation** (a Cursor/proprietary `.plan.md` the user pasted or referenced, or a plan already discussed in chat):
+- `summary` — required plain-language frontmatter summary (spec-summary-authoring contract).
+- `plan_markdown` — epic body markdown (goal, phases, acceptance criteria).
+- `milestone` — **required**: the parent `HS-MIL-*` wikilink. Ask the user if it isn't obvious from context; the tool call fails without it.
+- `source_plan_paths` — any `.plan.md` file paths referenced (auto-detected from `plan_markdown` too).
+- `kind` / `effort` / `tags` / `related` — optional scheduler/classification fields.
+
+**3. Call** `heyspex_push_plan({ epic_name, summary, plan_markdown, milestone, on_deck, focus_reason?, source_plan_paths?, kind?, effort?, tags?, related? })`. This writes the epic **only** — `children: []`; tasks are never filed here, only later via `/hs-next` breakdown.
+
+**4. After the call:**
+- `on_deck: true` → the epic is set `in_progress`, `.heyspex/focus.yaml` is written, and a NEXT STEP block is added. Tell the user to run `/hs-next` next.
+- `on_deck: false` → tell the user to re-run `/hs-push --next` (or `/hs-next <the new epic id>`) when ready to start work.
+
+**5. Conflict handling:** if the tool returns a behavioral-conflict block against `related` specs and `on_deck` was requested, the write is blocked by default (no files written, no focus pinned). Surface the conflicts to the user — only pass `skip_conflict_check: true` on their explicit say-so, and note a `conflict_override` should be recorded afterward.
+
+## Hard prohibitions
+
+- **Never** file tasks here — epics only (`children: []`); tasks are just-in-time via `/hs-next` breakdown.
+- **Never** silently bypass a conflict block — surface it and let the human decide.
+- **Never** commit or push git.

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

@@ -0,0 +1,27 @@
+---
+description: Post-plan QC gut-check — stress-test a drafted plan before executing it (the plan→execute gate). Reason through the gut-check questions, launch explorers to fill gaps, fold findings into the plan, then record Proof-of-Use.
+argument-hint: "[--plan <path>]  (defaults to the most recent plan)"
+allowed-tools: Task, AskQuestion, mcp__heyspex__heyspex_plan_qc, mcp__heyspex__heyspex_ground_plan, mcp__heyspex__heyspex_plan_review, mcp__heyspex__heyspex_recall_memories, Read, Grep, Glob, WebSearch, WebFetch
+---
+
+> **Where this sits.** `/hs-ground` (pre-plan) → draft → `heyspex_plan_review` → **`/hs-qc`** → `ExitPlanMode`. Both plan-review + QC markers required ([[HS-R4OY]]).
+
+## What to do
+
+**0. Mandatory drift passes** — Axis A (as-built code) + Axis B (design supersession per [[drift-is-two-axes-as-built-and-design-supersession]]). Re-run `heyspex_plan_review`; read `axis_b_drift`. Do not trust parent epic AC over newer memory decisions.
+
+**0b. When `axis_b_drift` is non-empty — ask the user before recording QC:**
+
+Present each conflict. **Default (Recommended):** re-scope the plan (remove dead work). **Override:** user explicitly confirms proceed anyway → `heyspex_plan_qc({ axis_b_user_confirmed: true, axis_b_confirmation_note: "…" })`. Tool returns `QC_AXIS_B_DRIFT` until resolved or user-confirmed. **The override is currently broken** per [[HS-EP8E-C1L2-DIAG-heyspex-plan-qc-override-path-ignores-ax]] (reproduced twice) — until fixed, `HEYSPEX_PLAN_QC_GATE_OFF=1` is the only working escape, and its use should be reported to the owner.
+
+**1. Run the gut-check (verbatim — the owner's standard).**
+
+Wonderful work! Can you please do a quality check and a gut-check? … *(full questions unchanged)*
+
+**2. Act on what you find.** Fold findings into the plan; re-run `heyspex_plan_review` if material.
+
+**3. Record Proof-of-Use.** `heyspex_plan_qc` with substantive `findings_summary` including **`Axis B:`** line.
+
+**4. Then `ExitPlanMode`.**
+
+(Break-glass: `HEYSPEX_PLAN_QC_GATE_OFF=1`.)