heyspex 0.2.3 → 0.2.5

package/.claude-plugin/marketplace.json

@@ -8,7 +8,8 @@
     {
       "name": "heyspex",
       "source": "./plugins/heyspex",
-      "description": "SpexCode plugin (for Claude Code and GitHub Copilot CLI): HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+      "displayName": "HeySpex",
+      "description": "HeySpex plugin for Claude Code and GitHub Copilot CLI: vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
     }
   ]
 }

package/README.md

@@ -10,6 +10,7 @@ HeySpex sits between "I have an idea" and "an AI agent writes code" - it distill
 npm install heyspex
 npx heyspex setup copilot          # registers the plugin with the Copilot CLI
 npx heyspex setup copilot --check  # confirm; exit 0 = installed
+npx heyspex setup copilot --statusline  # optional: HeySpex status line in Copilot's settings.json (--uninstall to remove)
 ```
 
 Prerequisite: the GitHub Copilot CLI. Either install the GitHub Copilot app (its bundled CLI at `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` is auto-detected, newest version wins), or `npm install -g @github/copilot`, or `winget install GitHub.Copilot`. If none is found, `setup copilot` installs nothing and exits non-zero. `COPILOT_HOME` is honoured. Full guide: [docs/copilot-plugin-install.md](docs/copilot-plugin-install.md).

package/bin/hs.mjs

@@ -1077,7 +1077,7 @@ function main(argv) {
         `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` +
           "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
           "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
-          "  hs setup copilot [--check|--uninstall|--print|--hooks]   GitHub Copilot (plugin; --hooks for the cloud agent)\n",
+          "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n",
       );
       process.exit(2);
     }
@@ -1089,7 +1089,7 @@ function main(argv) {
       setupFlags.length = 0;
       for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
-        if (["--check", "--uninstall", "--print", "--hooks", "--json"].includes(a)) setupFlags.push(a);
+        if (["--check", "--uninstall", "--print", "--hooks", "--json", "--statusline", "--force"].includes(a)) setupFlags.push(a);
         else if (a === "--target" && rest[i + 1]) setupFlags.push(a, rest[++i]);
         else if (a.startsWith("--target=")) setupFlags.push(a);
       }

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

@@ -20,7 +20,7 @@ Admin/dev-only — resolves paths via `dev-factory/watch-dev-log.mjs`, then watc
 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 ...`.
+   - Multiple paths (e.g. `companion`'s 3 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.
 

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

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

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

@@ -24,7 +24,7 @@ Admin/dev-only — resolves paths via `dev-factory/watch-dev-log.mjs`, then watc
 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 ...`.
+   - Multiple paths (e.g. `companion`'s 3 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.
 

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

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

package/docs/copilot-plugin-install.md

@@ -187,3 +187,14 @@ The install commands come from GitHub's plugin reference, and the hook behaviour
 replaying Copilot-shaped payloads through the registered commands, not by a live Copilot session.
 The first agent that completes section 4 is the real test. Fix history: diagnose HS-20SW and
 capture HS-HNO1 (2026-10-16).
+
+## Optional: HeySpex status line
+
+Opt in with `npx heyspex setup copilot --statusline`. It merges a `statusLine` block into `<COPILOT_HOME or ~/.copilot>/settings.json`
+(other keys are kept; the first change leaves `settings.json.heyspex-bak`). The command is `node "<installed heyspex>/scripts/copilot-statusline.mjs"`,
+so run it from a project that has `heyspex` installed, not from the npx cache. A non-HeySpex `statusLine` is never overwritten unless you pass `--force`.
+`npx heyspex setup copilot --statusline --uninstall` removes only the HeySpex one; `--check` reports its state.
+
+The line shows `Auto · 12% used | repo > branch | [HS] <pinned epic> | [HS] <pillar> > <claimed spec>`, reusing the Claude Code renderer.
+It is plain text (no font needed), refreshes every 30 s (`refreshInterval`) plus on Copilot events, never waits on the network, and prints a bare `HeySpex`
+if anything fails. `hs mode off` / `HEYSPEX_MODE=off` blanks it. Copilot renders it in interactive sessions only.