@mthanh/vespercli 1.6.0 → 1.7.0

package/assets/skills/vesper-catalog-editing-safety/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: vesper-catalog-editing-safety
+description: Pre-edit safety checklist for touching Vesper's own asset catalog and provisioning code — assets/, scripts/generate-claude-assets.js, src/cli/utils/settings.js, src/cli/utils/claude-target.js. Use before editing any catalog asset (agent, skill, prompt, instruction), the Claude-asset generator, or the Copilot/Claude settings-injection code in this repo. Prevents re-deriving the dual-target distribution model from scratch and catches the generator-boundary and git-hygiene-dual-list traps that have already caused a blocking architecture-review finding and a shipped bug.
+---
+
+# Vesper Catalog Editing Safety
+
+## Overview
+
+This repo (`@mthanh/vespercli`) is self-hosting: it produces the very agent/skill/prompt catalog it installs into itself and every other project. That self-hosting creates footguns that are easy to rediscover the hard way — one already caused a blocking architecture-review finding, another shipped as a real bug. This skill is a **pre-flight checklist**, not the narrative — walk it before touching provisioning code or catalog assets, and follow the links when you need the full story.
+
+Full narrative + citations: [`docs/architecture.md`](../../../docs/architecture.md). Terse always-loaded version: `.claude/vesper/context.md`'s Conventions section. Read this skill first — it tells you *which* parts of those two documents matter for the edit in front of you.
+
+## When to Use This Skill
+
+Load this skill before:
+
+- Editing anything under `assets/` — core, extended, or the generated `assets/claude/` tree
+- Editing `scripts/generate-claude-assets.js`
+- Editing `src/cli/utils/settings.js` or `src/cli/utils/claude-target.js`
+- Planning or reviewing a change that touches how Copilot or Claude Code *discovers* a Vesper asset (settings arrays, plugin install, guard blocks, reinject hooks)
+- Editing `.claude/rules/*.md`, `.vesper/instructions/`, or `.vesper/skills/` override paths
+- Editing `VESPER_GIT_PATHS` (`settings.js`) or `assets/hooks/pre-commit`
+- Reviewing a plan/PR that proposes any of the above — this is a research **and** review-time checklist, not just an implementation-time one
+
+## Instructions
+
+### Step 1 — Route the edit to the right trap
+
+| You're touching...                                                    | Go to        |
+| ----------------------------------------------------------------------- | ------------ |
+| A file under `assets/agents/`, `assets/skills/`, `assets/instructions/`, `assets/prompts/`, or `assets/claude/*` | Checklist A — Dual Asset Tree |
+| `scripts/generate-claude-assets.js` itself                              | Checklist A  |
+| `.vesper/instructions/`, `.vesper/skills/`, or a new `.claude/rules/*.md` | Checklist B — Discovery Wiring |
+| `getCoreAssetEntries()` or `VSCODE_SETTINGS_MAP` in `settings.js`        | Checklist B  |
+| `ensureClaudeMdGuardBlock()` or `VESPER_REINJECT_COMMAND` in `claude-target.js` | Checklist B |
+| `VESPER_GIT_PATHS` in `settings.js`, or `assets/hooks/pre-commit`        | Checklist C — Git-Hygiene Dual List |
+| Anything about which target (Copilot vs Claude) gets what               | Checklist D — Distribution Model (background only) |
+
+Most edits hit exactly one checklist. If unsure, read Checklist D first — it's the model everything else sits on.
+
+### Checklist A — Dual Asset Tree (the highest-value trap)
+
+`scripts/generate-claude-assets.js` has a narrow, explicit remit — verified against its own header comment (`scripts/generate-claude-assets.js:11-14`):
+
+| Copilot source                                        | Claude output                                           |
+| ------------------------------------------------------- | ----------------------------------------------------------- |
+| `assets/agents/<name>/<name>.agent.md`                 | `assets/claude/agents/<name>.md`                          |
+| `assets/prompts/<name>/<name>.prompt.md`               | `assets/claude/commands/<name>.md`                        |
+| `assets/skills/<name>/`                                | `assets/claude/skills/<name>/` (near-verbatim)             |
+| `assets/instructions/<name>/<name>.instructions.md`    | `assets/claude/skills/<name>/SKILL.md` (new skill)         |
+
+**That table is the entire remit.** `assets/core/` is never read by this script, at all — by design, not by omission (the script's own comment: *"the 12 core agents + the orchestrator playbook are hand-authored separately in assets/claude/ and are never touched by this script"*).
+
+- [ ] Is the file under `assets/core/`?
+  - **Yes** → There is no generator step for you. Hand-edit **both** the Copilot source (`assets/core/{agents,skills,instructions,prompts}/...`) **and** its `assets/claude/` twin. Before editing the twin, check it for **Claude-only content that doesn't exist in the Copilot source** and preserve it — e.g. `assets/claude/skills/agent-fundamentals/SKILL.md`'s `## Direct Collaboration (Nested Delegation)` section has no Copilot-side counterpart. Never diff the two sides expecting them to match; they're allowed to diverge by design.
+  - **No** (it's under `assets/agents/`, `assets/skills/`, `assets/instructions/`, or `assets/prompts/`) → Edit the Copilot source only, then run `node scripts/generate-claude-assets.js` to regenerate its Claude twin. **Never hand-edit anything under `assets/claude/`** for a file that came from this table — your edit will be silently clobbered (or drift undetected) the next time the generator runs.
+- [ ] If you're editing `assets/claude/` directly right now — stop and confirm which case above you're actually in. Hand-editing generated output is the single most common way this trap gets tripped.
+- [ ] If your task is planning/reviewing (not implementing) a catalog change: confirm the plan doesn't assume a core-skill/core-agent edit will "just flow through" the generator step. It won't — this exact wrong assumption produced a blocking architecture-review finding (BC-2) and a near-miss self-contradiction in an agent's own file-write rules in a prior session.
+
+### Checklist B — Local Overrides vs. Discovery Wiring (per target)
+
+"A file exists at the right path" and "the target actually discovers it" are two different guarantees — satisfied differently per target.
+
+**Copilot** — `.vesper/instructions/*.instructions.md` and `.vesper/skills/**/SKILL.md` are project-local override paths. They are **inert on their own**.
+
+- [ ] Does `getCoreAssetEntries()` (`src/cli/utils/settings.js:1321-1363`, appending entries around lines 1348-1360) explicitly include a `${workspaceFolder}/.vesper/instructions` and `${workspaceFolder}/.vesper/skills` entry in the arrays it writes into `.vscode/settings.json` (keyed by `VSCODE_SETTINGS_MAP`, `settings.js:70-75`)? If you're adding a *new* override path convention, it needs the equivalent wiring here — a path convention alone is invisible to Copilot without a matching settings-array entry. This exact gap was found and fixed once already.
+
+**Claude Code** — `.claude/skills/{domain}/SKILL.md` needs no wiring; it's natively auto-discovered. `.claude/rules/{name}.md` is different — it has two moving parts, neither of which is native Claude Code behavior:
+
+- [ ] Does `CLAUDE.md` carry an `@.claude/rules/{name}.md` import line **outside** the `<!-- vesper:start -->...<!-- vesper:end -->` guard block? (`ensureClaudeMdGuardBlock()`, `src/cli/utils/claude-target.js:257`.) Inside the guard block, it gets regenerated away on the next `update`/`/reinit`.
+- [ ] Does the rule still need to survive `/clear`? The `SessionStart(clear)` reinject hook (`VESPER_REINJECT_COMMAND`, `claude-target.js:723-753`) dynamically enumerates `.claude/rules/*.md` at hook-fire time — sorted, `.md`-filtered — alongside the three fixed `.claude/vesper/*.md` playbook files. You don't need to register a new rule file anywhere for this to work; a missing `.claude/rules/` directory is swallowed by an outer try/catch (no-op). But if you're changing the *enumeration logic itself*, verify it still globs correctly.
+
+### Checklist C — Git-Hygiene Dual List (no single source of truth)
+
+`VESPER_GIT_PATHS` (`src/cli/utils/settings.js:173-185`) and the `vesper_git_paths` shell string in `assets/hooks/pre-commit:16` describe the same set of "project knowledge that must ride along with any commit touching other work." They are **hand-mirrored**, not generated from one source.
+
+- [ ] Edited one list? Edit the other too, in the **same relative order**. There is no codegen link between them (open technical debt) — nothing will catch a divergence for you.
+- [ ] Every entry is **slash-less** (`.claude/skills`, never `.claude/skills/`). A trailing slash turns the pre-commit hook's match clause (`case "$candidate" in "$p"/*)`) into a pattern with a literal double slash that never matches a real staged path — silently defeating the guardrail for that one entry. This has already shipped as a real bug once.
+
+### Checklist D — Distribution Model (background, read when the trap isn't obvious)
+
+- **Copilot**: nothing is copied into the project. Vesper injects settings entries (`chat.agentFilesLocations` / `chat.instructionsFilesLocations` / `chat.promptFilesLocations` / `chat.agentSkillsLocations`, see `VSCODE_SETTINGS_MAP` at `settings.js:70-75`) into `.vscode/settings.json`, pointing at the installed npm package's `assets/` tree. `getCoreAssetEntries()` (`settings.js:1321-1363`) assembles the full entry list.
+- **Claude Code**: the catalog is a **user-level plugin**, installed once and shared across every project on the machine — `~/.claude/skills/vesper/{agents,commands,skills}/`. `getClaudePluginDir()` (`claude-target.js:36-38`) resolves the path; `installClaudePluginCatalog()` (`claude-target.js:157-171`) performs the install/refresh. Only a small per-project set of files lives in the repo itself: `.claude/vesper/{orchestrator,orchestration,context}.md`, `.mcp.json`, `.claude/settings.json`.
+- Both targets share one on-disk index at `.vesper/index.db`.
+
+If your edit changes *where* either target looks, or *what* gets written into the project vs. the shared install location, this is the model to reason from before touching Checklist A/B.
+
+## Examples
+
+### Example 1: Adding a brand-new skill to the extended catalog
+
+**Input**: "Add a new skill `assets/skills/foo-bar/SKILL.md`."
+
+**Process**:
+1. Checklist A applies (extended tree, not `assets/core/`).
+2. Write `assets/skills/foo-bar/SKILL.md` (+ any `references/`, `scripts/`, `assets/` subfolders) under the Copilot source tree only.
+3. Do **not** hand-write anything under `assets/claude/skills/foo-bar/` — that's the generator's job.
+4. Note in the handoff/PR that `node scripts/generate-claude-assets.js` must be run (by a maintainer or a later pipeline step with Bash access) before the skill exists on the Claude Code target.
+
+### Example 2: Editing a core skill (`assets/core/skills/agent-fundamentals/`)
+
+**Input**: "Add a new rule to `agent-fundamentals`'s Terminal Discipline table."
+
+**Process**:
+1. Checklist A applies, `assets/core/` branch — no generator step exists.
+2. Edit `assets/core/skills/agent-fundamentals/SKILL.md` (Copilot source).
+3. Before editing `assets/claude/skills/agent-fundamentals/SKILL.md`, re-read it fully — it already carries the Claude-only `## Direct Collaboration (Nested Delegation)` section that has no Copilot-side counterpart. Add the new rule to both files without disturbing that section.
+
+### Example 3: Adding a `${workspaceFolder}`-relative override path for a new asset type
+
+**Input**: "Support project-local overrides for prompts, the same way `.vesper/instructions` works today."
+
+**Process**:
+1. Checklist B applies (Copilot branch).
+2. Confirm `getCoreAssetEntries()` in `settings.js` needs a new `${workspaceFolder}/.vesper/prompts`-style entry appended into the `chat.promptFilesLocations` array — the path convention alone will not make Copilot discover it.
+3. Flag in the plan/review that this wiring step is required, not optional — it's the exact class of gap that was found and fixed once already in this repo.
+
+## Edge Cases
+
+**"I'm only touching `assets/claude/` to fix an obvious typo."** Still routes through Checklist A. If the source file is under the extended tree, fix the typo in the Copilot source and regenerate — don't patch the generated copy even for a one-character fix, or the next generator run silently reverts it.
+
+**"The instruction/prompt/agent I'm adding doesn't map cleanly to the generator's table."** `assets/core/instructions/*.instructions.md` files are hand-folded into the orchestrator/rules constructs (Checklist B), not mechanically converted — there is no automatic instructions → Claude-skill path for core instructions the way there is for the extended tree.
+
+**"I can't tell if a file is 'core' or 'extended.'"** Core = anything under `assets/core/`. Extended = `assets/agents/`, `assets/skills/`, `assets/instructions/`, `assets/prompts/` (no `core/` segment). If genuinely ambiguous, check whether an `assets/claude/` twin already exists and whether it looks hand-authored (has Claude-only sections) vs. mechanically generated (near-verbatim mirror) — that's a strong signal of which bucket it's in.
+
+**"I don't have Bash tool access to run the generator."** Note it explicitly in your output/handoff rather than silently skipping it — the change is incomplete on the Claude Code target until a maintainer or a later pipeline step runs `node scripts/generate-claude-assets.js`.
+
+## Related Files
+
+- `assets/` — the Copilot-format source catalog (`core/` hand-authored default install; `agents/`, `skills/`, `instructions/`, `prompts/` extended/opt-in)
+- `assets/claude/` — generated Claude-target twin of the extended tree, plus hand-maintained Claude-only twins of `assets/core/`
+- `scripts/generate-claude-assets.js` — the extended-tree generator; never touches `assets/core/`
+- `src/cli/utils/settings.js` — `VSCODE_SETTINGS_MAP`, `getCoreAssetEntries()`, `VESPER_GIT_PATHS`
+- `src/cli/utils/claude-target.js` — `getClaudePluginDir()`, `installClaudePluginCatalog()`, `ensureClaudeMdGuardBlock()`, `VESPER_REINJECT_COMMAND`
+- `assets/hooks/pre-commit` — the hand-mirrored `vesper_git_paths` shell list
+
+## References
+
+- [`docs/architecture.md`](../../../docs/architecture.md) — full narrative, all four facts, with additional citations and the specific incidents (BC-2 architecture-review finding, the trailing-slash bug) that motivated this checklist.
+- `.claude/vesper/context.md` — terse, always-loaded version of the same conventions, auto-injected into every session in this repo.

package/assets/skills/vesper-catalog-editing-safety/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "vesper-catalog-editing-safety",
+  "version": "1.0.0",
+  "generated": "2026-07-19T18:29:56.208Z",
+  "files": [
+    "SKILL.md"
+  ]
+}

package/assets/skills/vscode-agent-config/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "vscode-agent-config",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.830Z",
+  "generated": "2026-07-19T18:29:56.209Z",
   "files": [
     "SKILL.md"
   ]

package/assets/skills/web-design-guidelines/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "web-design-guidelines",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.831Z",
+  "generated": "2026-07-19T18:29:56.209Z",
   "files": [
     "SKILL.md"
   ]

package/assets/skills/web-frameworks/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "web-frameworks",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.831Z",
+  "generated": "2026-07-19T18:29:56.210Z",
   "files": [
     "SKILL.md",
     "references/nextjs-app-router.md",