@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/copilot/skills/task-implementation/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: task-implementation
+description: Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai. Use when working with task change-record files under .vesper/.tracking/changes/.
+---
+
+# Task Plan Implementation Instructions
+
+You will implement your specific task plan located in `.vesper/.tracking/plans/**` and `.vesper/.tracking/details/**`. Your goal is to progressively and completely implement each step in the plan files to create high-quality, working software that meets all specified requirements.
+
+Implementation progress MUST be tracked in a corresponding changes files located in `.vesper/.tracking/changes/**`.
+
+## Pre-Implementation Validation
+
+**CRITICAL - MUST COMPLETE BEFORE ANY IMPLEMENTATION:**
+
+1. **Verify Planning Completeness:**
+   - Search `.vesper/.tracking/research/` for most recent research file
+   - Search `.vesper/.tracking/plans/` for corresponding plan file
+   - Search `.vesper/.tracking/details/` for corresponding details file
+   - Search `.vesper/.tracking/prompts/` for implementation prompt file
+
+2. **If ANY file is missing:**
+   - STOP immediately
+   - Report: "❌ Planning incomplete. Missing: [list missing files]"
+   - Suggest: "Please complete planning first using Thanh Junior Agent"
+   - DO NOT proceed with implementation
+
+3. **If all files exist:**
+   - Proceed to Core Implementation Process
+
+
+## Core Implementation Process
+
+### 1. Plan Analysis and Preparation
+
+**MUST complete before starting implementation:**
+
+- **MANDATORY**: Read and fully understand the complete plan file including scope, objectives, all phases, and every checklist item
+- **MANDATORY**: Read and fully understand the corresponding changes file completely - if any parts are missing from context, read the entire file back in using `Read`
+- **MANDATORY**: Identify all referenced files mentioned in the plan and examine them for context
+- **MANDATORY**: Understand current project structure and conventions
+
+### 2. Systematic Implementation Process
+
+**Implement each task in the plan systematically:**
+
+1. **Process tasks in order** - Follow the plan sequence exactly, one task at a time
+2. **MANDATORY before implementing any task:**
+   - **ALWAYS ensure implementation is associated with a specific task from the plan**
+   - **ALWAYS read the entire details section for that task from the associated details markdown file in `.vesper/.tracking/details/**`\*\*
+   - **FULLY understand all implementation details before proceeding**
+   - Gather any additional required context as needed
+
+3. **Implement the task completely with working code:**
+   - Follow existing code patterns and conventions from the workspace
+   - Create working functionality that meets all task requirements specified in the details
+   - Include proper error handling, documentation, and follow best practices
+
+4. **Mark task complete and update changes tracking:**
+   - Update plan file: change `[ ]` to `[x]` for completed task
+   - **MANDATORY after completing EVERY task**: Update the changes file by appending to the appropriate Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
+   - **MANDATORY**: If any changes diverge from the task plan and details, specifically call out within the relevant section that the change was made outside of the plan and include the specific reason
+   - If ALL tasks in a phase are complete `[x]`, mark the phase header as complete `[x]`
+
+### 3. Implementation Quality Standards
+
+**Every implementation MUST:**
+
+- Follow existing workspace patterns and conventions (check `copilot/` folder for standards)
+- Implement complete, working functionality that meets all task requirements
+- Include appropriate error handling and validation
+- Use consistent naming conventions and code structure from the workspace
+- Add necessary documentation and comments for complex logic
+- Ensure compatibility with existing systems and dependencies
+
+### 4. Continuous Progress and Validation
+
+**After implementing each task:**
+
+1. Validate the changes made against the task requirements from the details file
+2. Fix any problems before moving to the next task
+3. **MANDATORY**: Update the plan file to mark completed tasks `[x]`
+4. **MANDATORY after EVERY task completion**: Update the changes file by appending to Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
+5. Continue to the next unchecked task
+
+**Continue until:**
+
+- All tasks in the plan are marked complete `[x]`
+- All specified files have been created or updated with working code
+- All success criteria from the plan have been verified
+
+### 5. Reference Gathering Guidelines
+
+**When gathering external references:**
+
+- Focus on practical implementation examples over theoretical documentation
+- Validate that external sources contain actual usable patterns
+- Adapt external patterns to match workspace conventions and standards
+
+**When implementing from references:**
+
+- Follow workspace patterns and conventions first, external patterns second
+- Implement complete, working functionality rather than just examples
+- Ensure all dependencies and configurations are properly integrated
+- Ensure implementations work within the existing project structure
+
+### 6. Completion and Documentation
+
+**Implementation is complete when:**
+
+- All plan tasks are marked complete `[x]`
+- All specified files exist with working code
+- All success criteria from the plan are verified
+- No implementation errors remain
+
+**Final step - update changes file with release summary:**
+
+- Add Release Summary section only after ALL phases are marked complete `[x]`
+- Document complete file inventory and overall implementation summary for release documentation
+
+### 7. Problem Resolution
+
+**When encountering implementation issues:**
+
+- Document the specific problem clearly
+- Try alternative approaches or search terms
+- Use workspace patterns as fallback when external references fail
+- Continue with available information rather than stopping completely
+- Note any unresolved issues in the plan file for future reference
+
+## Implementation Workflow
+
+```
+1. Read and fully understand plan file and all checklists completely
+2. Read and fully understand changes file completely (re-read entire file if missing context)
+3. For each unchecked task:
+   a. Read entire details section for that task from details markdown file
+   b. Fully understand all implementation requirements
+   c. Implement task with working code following workspace patterns
+   d. Validate implementation meets task requirements
+   e. Mark task complete [x] in plan file
+   f. Update changes file with Added, Modified, or Removed entries
+   g. Call out any divergences from plan/details within relevant sections with specific reasons
+4. Repeat until all tasks complete
+5. Only after ALL phases are complete [x]: Add final Release Summary to changes file
+```
+
+## Success Criteria
+
+Implementation is complete when:
+
+- ✅ All plan tasks are marked complete `[x]`
+- ✅ All specified files contain working code
+- ✅ Code follows workspace patterns and conventions
+- ✅ All functionality works as expected within the project
+- ✅ Changes file is updated after every task completion with Added, Modified, or Removed entries
+- ✅ Changes file documents all phases with detailed release-ready documentation and final release summary
+
+## Template Changes File
+
+Use the following as a template for the changes file that tracks implementation progress for releases.
+Replace `{{ }}` with appropriate values. Create this file in `./.vesper/.tracking/changes/` with filename: `YYYYMMDD-task-description-changes.md`
+
+**IMPORTANT**: Update this file after EVERY task completion by appending to Added, Modified, or Removed sections.
+**MANDATORY**: Always include the following at the top of the changes file: `<!-- markdownlint-disable-file -->`
+
+<!-- <changes-template> -->
+
+```markdown
+<!-- markdownlint-disable-file -->
+
+# Release Changes: {{task name}}
+
+**Related Plan**: {{plan-file-name}}
+**Implementation Date**: {{YYYY-MM-DD}}
+
+## Summary
+
+{{Brief description of the overall changes made for this release}}
+
+## Changes
+
+### Added
+
+- {{relative-file-path}} - {{one sentence summary of what was implemented}}
+
+### Modified
+
+- {{relative-file-path}} - {{one sentence summary of what was changed}}
+
+### Removed
+
+- {{relative-file-path}} - {{one sentence summary of what was removed}}
+
+## Release Summary
+
+**Total Files Affected**: {{number}}
+
+### Files Created ({{count}})
+
+- {{file-path}} - {{purpose}}
+
+### Files Modified ({{count}})
+
+- {{file-path}} - {{changes-made}}
+
+### Files Removed ({{count}})
+
+- {{file-path}} - {{reason}}
+
+### Dependencies & Infrastructure
+
+- **New Dependencies**: {{list-of-new-dependencies}}
+- **Updated Dependencies**: {{list-of-updated-dependencies}}
+- **Infrastructure Changes**: {{infrastructure-updates}}
+- **Configuration Updates**: {{configuration-changes}}
+
+### Deployment Notes
+
+{{Any specific deployment considerations or steps}}
+```
+
+<!-- </changes-template> -->

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

@@ -0,0 +1,172 @@
+---
+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 or skill), the Copilot-asset generator, or the Copilot/Claude settings-injection code in this repo. Prevents re-deriving the one-host-per-workspace 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) (rewritten for 2.0) and the user-facing model in [`README.md`](../../../README.md). Terse always-loaded version: the project whitepaper's Conventions section. Read this skill first — it tells you *which* parts of those documents matter for the edit in front of you.
+
+> **Stale-marker note.** A reference anywhere to `assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/` or `assets/skills/`, to a committed Claude catalog under `.claude/{agents,commands,skills}`, to `@import`ed `.vesper/instructions/vesper-*.instructions.md` playbook files, or to the `SessionStart(clear)` reinject hook describes the retired 1.x layout. Flag it; don't follow it.
+
+## When to Use This Skill
+
+Load this skill before:
+
+- Editing anything under `assets/` — the canonical `assets/claude/` + `assets/claude-committed/` trees, or the generated `assets/copilot/` output root
+- 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 declaration, `.vesper/instructions/`, the `CLAUDE.md` pointer)
+- Editing `.vesper/instructions/*.instructions.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/claude/*`, `assets/claude-committed/*`, or `assets/copilot/*` | Checklist A — Dual Asset Tree |
+| `scripts/generate-claude-assets.js` itself                              | Checklist A  |
+| `.vesper/instructions/`, `.vesper/skills/`, or a new `.vesper/instructions/*.instructions.md` | Checklist B — Discovery Wiring |
+| `getCoreAssetEntries()` or `VSCODE_SETTINGS_MAP` in `settings.js`        | Checklist B  |
+| `ensureClaudeMdGuardBlock()`, `installClaudeProjectFiles()` or `configureClaudeSettings()` 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 host (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)
+
+**Direction of travel (Vesper 2.0): Claude-format is the hand-authored source; Copilot-format is generated output.** This is the reverse of the 1.x model — if you remember it the other way round, you are remembering a retired layout. The old hand-authored Copilot-format trees (`assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/`, `assets/skills/`) **no longer exist**; do not look for them, do not re-create them.
+
+There are exactly **two canonical authored roots**, and `scripts/generate-claude-assets.js` scans them to emit **one** generated root:
+
+| Canonical source (hand-authored)                                              | Generated Copilot output (never hand-edited)             |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `assets/claude/agents/<name>.md`                                              | `assets/copilot/agents/<name>.agent.md` (`user-invocable: false`) |
+| `assets/claude/skills/<name>/`                                                | `assets/copilot/skills/<name>/` (every `.md` rendered by `src/cli/utils/copilot-render.js`) |
+| `assets/claude/skills/<name>/SKILL.md` carrying `copilot-apply-to` + `copilot-instructions-tier: core` | *also* `assets/copilot/instructions/<name>.instructions.md` (injected for every project) |
+| `assets/claude/skills/<name>/SKILL.md` carrying `copilot-apply-to` + `copilot-instructions-tier: extended` | *also* `assets/copilot/instructions-extended/<name>/<name>.instructions.md` (opt-in per project) |
+| `assets/claude-committed/skills/<name>/` carrying `disable-model-invocation: true` | `assets/copilot/prompts/<name>.prompt.md`              |
+
+**That table is the entire remit.** Everything else under the two roots is **explicitly excluded** from the scan (`EXCLUDED_SOURCE_PATHS` / `isExcludedSource()` in the generator): `assets/claude/.claude-plugin/`, `assets/claude/commands/`, the three root files `assets/claude/{vesper-orchestrator.md, orchestration.md.tpl, context.md.tpl}`, and `assets/claude-committed/agents/`. `assets/hooks/` and `assets/legacy/` are excluded too — git-hook assets and the 1.x proof table live outside the scan roots on purpose. **Third-party skills** (`gitlab-ci-skill`, `github-actions-to-gitlab-ci` in `packs/integrations`; `i-have-adhd`, `ponytail` in the opt-in `packs/styles`) ARE under a scan root, but each carries an `UPSTREAM.json` beside its `SKILL.md`, which makes it third-party to the generator: copied verbatim into the Copilot mirror (`UPSTREAM.json` and `LICENSE` included), never rendered, never residue-scanned. Never hand-edit one: its bytes are upstream's, refreshed only by `npm run vendor:sync [name]` (`scripts/vendor-sync.js`, which rewrites `UPSTREAM.json`); a hand edit is silently undone by the next sync.
+
+- [ ] Is the file under `assets/copilot/`?
+  - **Yes** → **Stop. That is generated output.** Find the canonical source in the table above, edit *that*, and regenerate. Your edit here will be silently clobbered — the generator rebuilds the whole output root from the canonical sources on every run (atomically: temp dir, then rename). Hand-editing generated output is the single most common way this trap gets tripped.
+  - **No** (it's under `assets/claude/` or `assets/claude-committed/`) → This is hand-authored canonical source. Edit it directly, then regenerate (see the run order below).
+- [ ] **One command.** `node scripts/generate-claude-assets.js` rebuilds `assets/copilot/` AND `assets/manifest.json` (no timestamp, no per-skill manifests). It is STRICT — any bad source (missing/unsafe frontmatter, a committed skill without its marker, a plugin skill with it, an unmapped tool or model, Claude-host residue) fails the run and writes nothing — so fix the reported source rather than working around it. `scripts/generate-manifests.js` still exists but only rewrites the global manifest.
+- [ ] **All Copilot renaming lives in ONE pure module**, `src/cli/utils/copilot-render.js` (path homes, the single roster/whitepaper path, `vesper:` namespace stripping). The generator and the runtime Copilot provisioning both import it. Never add a Copilot inversion anywhere else, and never import from `scripts/` under `src/` (a test enforces it — the CLI bundle once inlined the generator and regenerated the installed assets mid-command).
+- [ ] The generated output root is **committed**, not gitignored — that is deliberate (it keeps `init` offline-capable and the injected Copilot settings paths resolvable before any build step). So a regeneration shows up as a real file diff in your PR. That diff is expected; an *absent* diff after a source edit means you forgot to regenerate.
+- [ ] The two canonical roots are **not** twins of each other and must never be diffed expecting a match. `assets/claude/` is the marketplace **plugin** catalog; `assets/claude-committed/` is the **project-committed** partition (see Checklist D). A name appearing in both is a real bug, not a mirror.
+- [ ] The maintenance-skill discriminator (`disable-model-invocation: true`) is **not globally unique** — the third-party `assets/claude/packs/styles/skills/i-have-adhd/SKILL.md` also carries it (allowed there because the skill is third-party). The single-key rule is safe *only* because prompt emission is scan-scoped to `assets/claude-committed/skills/`. If you change the scan roots, you can silently start emitting prompts from third-party or plugin content. Tree location is the signal, not the key alone.
+- [ ] If your task is planning/reviewing (not implementing) a catalog change: confirm the plan doesn't assume the 1.x direction (Copilot source → Claude output). It is inverted. The 1.x-shaped 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; the same class of error now looks like "edit `assets/copilot/` and expect it to stick."
+
+### Checklist B — Local Overrides vs. Discovery Wiring (per host)
+
+"A file exists at the right path" and "the host actually discovers it" are two different guarantees — satisfied differently per host. A workspace runs exactly **one** host (`.vesperrc.host`); a Copilot workspace never gets a `.claude/*` file and a Claude workspace never gets Copilot settings, apart from the cross-host guard trigger.
+
+**Copilot** — the per-project brain (`.vesper/agents/vesper-orchestrator.agent.md`, `.vesper/instructions/vesper-*.instructions.md`, `.vesper/context/`) and the override paths `.vesper/instructions/*.instructions.md` / `.vesper/skills/**/SKILL.md` are **inert on their own**.
+
+- [ ] Does `getCoreAssetEntries()` (`src/cli/utils/settings.js`) include the `${workspaceFolder}/.vesper/{agents,instructions,skills}` entries it writes into `.vscode/settings.json` (keyed by `VSCODE_SETTINGS_MAP` in the same file), next to the package's `assets/copilot/` folders? A *new* project-local path convention needs the equivalent wiring here — a path alone is invisible to Copilot without a matching `chat.*Locations` entry. This exact gap was found and fixed once already.
+- [ ] Is `${workspaceFolder}/.vesper/agents` still written? It is also a Copilot **fingerprint** (`fingerprints.js`): the checked-out tree resolves the host from it. Renaming or dropping it changes host resolution, not just discovery.
+
+**Claude Code** — `.vesper/skills/{name}/SKILL.md` and `.vesper/instructions/*.instructions.md` are both **natively** discovered; no settings wiring and no `@import`.
+
+- [ ] The always-on playbook, roster and slim whitepaper are `.vesper/instructions/vesper-{orchestrator,orchestration,context}.md` (`installClaudeProjectFiles()`). A new always-on Vesper rule goes in `.vesper/instructions/` too — never an `@import` in `CLAUDE.md`, which would double-load it.
+- [ ] The `CLAUDE.md` guard block (`<!-- vesper:start -->…<!-- vesper:end -->`, `ensureClaudeMdGuardBlock()`) is a **prose pointer only**. Don't add `@import` lines to it; it is regenerated on every `init`/`update`.
+- [ ] Vesper writes **no** `CLAUDE.md` `@import` at all any more (the pre-epic-J opt-in styles' marker-scoped blocks are stripped by `init` / `reset`). The one always-on file a pack writes is the `styles` pack's pointer rule `.vesper/instructions/vesper-styles.instructions.md` (`pack-rules.js`), a Vesper-authored ~10-line file, never third-party text.
+- [ ] The plugin is **declared, not copied**: `configureClaudeSettings()` writes `enabledPlugins["vesper@vesper-marketplace"]` and `agent: "vesper-orchestrator"` into the committed `.claude/settings.json`; `configureClaudeMarketplaceLocal()` writes the machine-local marketplace `source` into the gitignored `.claude/settings.local.json`. Both committed keys are Claude **fingerprints** — the same resolution caveat as Copilot's `.vesper/agents`.
+- [ ] There is no `SessionStart(clear)` reinject hook in 2.0 (rules survive `/clear` natively). The one Vesper `SessionStart` entry is the host guard (`VESPER_CLAUDE_GUARD_COMMAND`).
+
+### Checklist C — Git-Hygiene Dual List (no single source of truth)
+
+`VESPER_GIT_PATHS` (`src/cli/utils/settings.js`) and the `vesper_git_paths` shell string in `assets/hooks/pre-commit` 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** (`.vesper/skills`, never `.vesper/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.
+- [ ] The sweep is for **human** commits. `VESPER_NO_SWEEP=1` (set by agents, which stage by path) skips it: nothing is staged, and one line names the dirty paths left out. Changing what the block does? `doctor`'s `git-hook-outdated` check keys on marker strings in the installed block (`vesper.hooks`, and `VESPER_NO_SWEEP` for pre-commit) — add a marker when older installed blocks must be flagged; `worktree bootstrap` rewrites any block that differs.
+
+### Checklist D — Distribution Model (background, read when the trap isn't obvious)
+
+**One host per workspace.** `.vesperrc.host` is `claude` or `copilot`, never both; the checked-out tree decides it from Vesper-only keys in git-visible files (`host-authority.js#resolveCheckoutHost`). `.vesperrc` is a gitignored per-worktree **ledger**, not evidence. 1.x "targets" and `getInstalledTargets()` survive only as the 1.x record recogniser (it returns `[]` for any v2 ledger) — never derive a 2.0 decision from them.
+
+- **Copilot**: the generated catalog stays **package-resident**. `getCoreAssetEntries()` injects the installed package's `assets/copilot/{agents,prompts,skills}` folders and core `instructions/`, plus the project's `${workspaceFolder}/.vesper/{agents,instructions,skills}` into `chat.{agent,instructions,prompt,agentSkills}FilesLocations` in `.vscode/settings.json`. That is why `assets/copilot/` is committed: the paths must resolve straight out of an npm install. The per-project brain is rendered under `.vesper/` by `copilot-target.js` (through `copilot-render.js`). Nothing is written to `.github/` or `.claude/`.
+- **Claude Code**: delivery is **two-part**, and conflating the halves is the highest-value mistake here.
+  1. **The marketplace plugin (referenced, never copied).** `assets/claude/` *is* the plugin root (`.claude-plugin/`, `agents/`, `skills/`), declared in the committed `.claude/settings.json` and sourced from the gitignored `.claude/settings.local.json` (Checklist B). Specialists resolve as `<name>`. Nothing is written under `~/.claude` except what Claude Code itself writes in `~/.claude/plugins/`; `NEVER_WRITE_USER_PATHS` refuses the rest.
+  2. **The committed fallback (rendered into the repo, tracked in git).** `installClaudePluginCatalog()` writes `.vesper/agents/vesper-orchestrator.agent.md` and the four maintenance skills from `assets/claude-committed/`; `installClaudeProjectFiles()` writes `.vesper/instructions/vesper-*.instructions.md` and the `CLAUDE.md` pointer. This keeps a working orchestrator where the plugin doesn't resolve (cloud, headless: degraded mode). If you find yourself adding the playbook, roster, whitepaper, orchestrator agent or a maintenance skill to `assets/claude/agents/` or `assets/claude/skills/`, you are creating a competing duplicate of something that already has a committed home.
+- **Every write is recorded** in the `.vesperrc` v2 manifest (`ownership.js`: whole file + sha256, or region/key), and **removal needs proof** (`proven-removal.js`: recorded hash or pinned 1.x digest). Directories go through `removeProvenDirectory`, file by file, only when empty — a user file beside a Vesper file always survives. Never delete on name, location or a manifest entry alone (both shipped as real data loss in epic (d)).
+- **`.vesper/skills/` (Claude) and `.vesper/skills/` (Copilot) are shared namespaces**: Vesper maintenance skills (Claude only), `--override` pins, and agent-authored project skills. Every prune and `reset` (`resetClaudeProjectFiles`, `removeCopilotTarget`) is manifest-scoped; there is never an enumerate-and-delete or `rm -r`.
+  - **Third-party skills are pack content, never project content (epic J).** `gitlab-ci-skill` and `github-actions-to-gitlab-ci` ship in `packs/integrations`, `i-have-adhd` and `ponytail` in the opt-in `packs/styles`, each with an `UPSTREAM.json` (`third-party.js`). Nothing installs them into a project, there is no consent prompt or flag, and `vespercli packs enable styles` is the consent for the styles — it writes the Vesper-authored pointer rule (`pack-rules.js`), recorded as `pack-rule` and removed by `packs disable` / `reset` / a host clean. `vespercli packs upstream` (and an attended `update`) only WARN about a newer upstream (`upstream.js`); `npm run vendor:sync` is the maintainer refresh.
+  - **The copies an older build placed** (`.vesper/skills/<name>`, `.vesper/skills/<name>`, the rules, the `CLAUDE.md` blocks) are retired by `init` through `third-party-migration.js`, proof-first (shipped snapshot, the legacy `vendored-body` row's hashes, the pinned 1.x digests); an edited copy is kept and reported once. Never reintroduce a writer for those paths.
+- **Shared by both hosts**: `.vesper/.tracking/` (run ledger `runs/` included), `.vesper/memory.jsonl`, the read-only `.vesper/history-archive/` and the code index `.vesper/index.db`. No host switch, reset or migration touches them.
+
+If your edit changes *where* either host 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 catalog
+
+**Input**: "Add a new skill `foo-bar`."
+
+**Process**:
+1. Checklist A applies. Decide which canonical root it belongs to: an ordinary model-invocable catalog skill goes in the **plugin** tree, `assets/claude/skills/foo-bar/`. It belongs in `assets/claude-committed/skills/` only if it is a project-committed maintenance workflow (and then it carries `disable-model-invocation: true`).
+2. Write `assets/claude/skills/foo-bar/SKILL.md` (+ any `references/`, `scripts/` subfolders) under the canonical tree only.
+3. Do **not** hand-write anything under `assets/copilot/skills/foo-bar/` — that's the generator's job, and the next run would clobber it anyway.
+4. If the skill should *also* surface to Copilot as an auto-applied instructions file, add a `copilot-apply-to` glob key AND a `copilot-instructions-tier:` key (`extended` = opt-in per project, the default choice for anything stack-specific; `core` = injected for every project, which counts against the 80 KB always-on budget). That is the only lossless way to get an `.instructions.md` emitted; there is no separate instructions source tree any more.
+5. Run `node scripts/generate-claude-assets.js` and commit the resulting `assets/copilot/` diff. If you lack Bash access, say so explicitly in the handoff — the change is incomplete on the Copilot host until a maintainer runs it.
+
+### Example 2: Editing a shared skill with by-design divergence (`agent-fundamentals`)
+
+**Input**: "Add a new rule to `agent-fundamentals`'s Terminal Discipline table."
+
+**Process**:
+1. Checklist A applies. There is exactly **one** authored copy now: `assets/claude/skills/agent-fundamentals/SKILL.md`. Edit it.
+2. Note that this skill carries Claude-specific content — e.g. its `## Direct Collaboration (Nested Delegation)` section — which in the 1.x layout had no Copilot-side counterpart and had to be hand-preserved across two files. That hazard is gone: there is no second authored copy to keep in sync, and the generator carries the body across through the shared render.
+3. Regenerate (Example 1, step 5). If the section genuinely should not reach Copilot, that is a generator-transform question — raise it, don't solve it by hand-editing the output.
+
+### 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/copilot/` to fix an obvious typo."** Still routes through Checklist A. Fix the typo in the canonical source and regenerate — don't patch the generated copy even for a one-character fix, or the next generator run silently reverts it.
+
+**"I'm looking for `assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/` or `assets/skills/` and they're not there."** Correct — those five hand-authored Copilot-format trees were retired in 2.0. Every one of their assets has a home in `assets/claude/` or `assets/claude-committed/` (or a recorded retirement decision). Do not re-create them; find the canonical home instead. If you are reading a doc or comment that still references them, that doc is stale — flag it, don't follow it.
+
+**"The asset I'm adding doesn't map cleanly to the generator's table."** The table is exhaustive for the two scan roots. Everything else under them — the plugin manifest dir, `commands/`, the root template files, `claude-committed/agents/` — is explicitly excluded and is provisioned by the Claude target code, not the generator. If your asset needs to land somewhere outside the table, that is a provisioning change (`claude-target.js` / the Copilot provisioning module), not a generator change.
+
+**"I can't tell which canonical root a file belongs to."** Plugin tree (`assets/claude/`) = shipped to every project by reference, model-invocable, not committed into the workspace. Committed partition (`assets/claude-committed/`) = rendered into the project's own `.claude/`, tracked in git, and for skills carries `disable-model-invocation: true`. If it is the orchestrator playbook, roster, whitepaper, main-thread orchestrator agent, or one of the four maintenance skills, it is committed — `plugin.json`'s description names them explicitly.
+
+**"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 Copilot host until a maintainer or a later pipeline step runs `node scripts/generate-claude-assets.js`.
+
+## Related Files
+
+- `assets/claude/` — **canonical hand-authored source**, and simultaneously the `vesper` marketplace plugin root (`.claude-plugin/`, `agents/`, `skills/`, plus the excluded `commands/` and root template files)
+- `assets/claude-committed/` — **canonical hand-authored source** for the project-committed partition (`agents/vesper-orchestrator.md`, the four maintenance skills)
+- `assets/copilot/` — **generated output**, committed but never hand-edited; the Copilot settings entries point here
+- `assets/claude/packs/<pack>/skills/<name>/UPSTREAM.json` — the provenance record that marks a pack skill third-party (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`, `i-have-adhd`, `ponytail`); copied verbatim by the generator, refreshed only by `scripts/vendor-sync.js`
+- `scripts/generate-claude-assets.js` — the Copilot-output generator (name predates the 2.0 flip); scans the two canonical roots, wipes and rebuilds `assets/copilot/`
+- `scripts/generate-manifests.js` — rewrites only `assets/manifest.json` (the generator already writes it); no run-order constraint
+- `src/cli/utils/settings.js` — `VSCODE_SETTINGS_MAP`, `getCoreAssetEntries()`, `VESPER_GIT_PATHS`
+- `src/cli/utils/claude-target.js` — `installClaudePluginCatalog()`, `installClaudeProjectFiles()`, `ensureClaudeMdGuardBlock()`, `configureClaudeSettings()`, `configureClaudeMarketplaceLocal()`
+- `src/cli/utils/packs.js`, `pack-rules.js`, `third-party.js`, `upstream.js`, `third-party-migration.js` — the packs, the `styles` pointer rule, the third-party registry, the upstream check and the migration of pre-J copies
+- `src/cli/utils/copilot-target.js` / `copilot-render.js` — the Copilot per-project brain and all Copilot path renaming
+- `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.
+- [`README.md`](../../../README.md) — the user-facing 2.0 model: what each host writes, git hooks, `doctor`, migration.
+- The project whitepaper (`.vesper/instructions/vesper-context.instructions.md` on a 2.0 Claude workspace) — terse, always-loaded version of the same conventions.

package/assets/copilot/skills/vesper-orchestration/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: vesper-orchestration
+description: Detailed step-by-step orchestration pipelines used by the Vesper super-orchestrator to delegate multi-step work to the specialist team — research & plan, implementation, QA/E2E testing, and re-initialization, including the bug-fix and skill-creation context overrides. Use when running or resuming a Vesper purpose pipeline and you need the per-step delegation prompts, tracking-file naming, output contracts, or the bug-fix overrides that the orchestrator playbook defers to.
+---
+
+# Vesper Orchestration Pipelines
+
+Detailed orchestration workflows for delegating multi-step tasks to the specialist team.
+
+The always-on orchestrator playbook (`.vesper/instructions/vesper-orchestrator.instructions.md`) is the authority for
+**routing** — which purpose a request belongs to, which agent fills which role, and the global
+rules (delegation law, loop limits, concurrency limits, context discipline). This skill carries the
+**step-level detail** the playbook defers to: the per-step delegation prompts, the tracking-file
+contracts, and the bug-fix / skill-creation overrides.
+
+Where the two ever disagree, the playbook wins.
+
+## Pipelines
+
+| Pipeline              | When to use                                                 | Reference                                                         |
+| --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Research & Plan**   | Steps 1-3: task fetch, research, architect validation (M: 1-2) | [research-plan-pipeline.md](references/research-plan-pipeline.md) |
+| **Implementation**    | Steps 4-11: validation, coding, review, gate, testing, docs, wrap | [implement-pipeline.md](references/implement-pipeline.md)       |
+| **Multi-Task Dispatch** | Several tasks at once: per-task tier, phases, cross-task check | [multi-task-dispatch.md](references/multi-task-dispatch.md)     |
+| **QA / E2E Testing**  | Post-implementation or standalone test requests             | [qa-e2e-pipeline.md](references/qa-e2e-pipeline.md)               |
+| **Re-initialization** | "Re-vesperize", "refresh workspace setup", `/reinit`        | [reinit-pipeline.md](references/reinit-pipeline.md)               |
+
+## Scope tiers
+
+The playbook's **tier table** (section *2. Implementation* → *Scope tiers*) is the single
+definition of which steps run for a given change: **S** (implement → `vespercli gate` → log),
+**M** (research → plan → implement → one review → gate → conditional docs/wrap → log) and **L**
+(the full step table). These references describe the *steps* and never restate the tiers — when a
+step below says "L only" or "conditional", the tier table is what decides. `vespercli gate` is the
+orchestrator's own CLI call (exit code + headline only), never a delegation.
+
+## Routing
+
+- **Implementation request** → the orchestrator has already chosen the tier. **S**: skip both
+  references' planning steps and use the playbook's S delegation directly. **M**: read
+  `research-plan-pipeline.md` (Steps 1-2), then `implement-pipeline.md` (Steps 5-7, 9-10 conditional,
+  11). **L**: `research-plan-pipeline.md` (Steps 1-3), then `implement-pipeline.md` (Steps 4-11)
+- **Bug fix** → same pipeline; the research-plan and implement references carry the bug-fix overrides
+- **Skill creation** → same pipeline; the same two references carry the skill-creation overrides
+- **Testing request** → read `qa-e2e-pipeline.md` (Mode B for standalone, Mode A for post-implementation — auto-triggered after L only)
+- **Re-initialization** → read `reinit-pipeline.md`
+
+## File Naming Convention
+
+All tracking output uses `YYYYMMDD-[slug]-<type>.md`, where `[slug]` is a short task identifier
+(3-5 words, kebab-case). When the orchestrator delegates with a `Task slug: [slug]` directive, use
+that exact slug — it is what isolates artifacts when several tasks run in parallel.
+
+## Shared Rules
+
+- Delegation prompts pass **file paths** — never embed file content.
+- Subagents write outputs to `.vesper/.tracking/` — never to the plugin or global install location.
+- Every delegation prompt carries `Nesting depth: 1` so delegates can track their own nesting budget.
+- Every delegated subagent ends its final message with the `Status:` / `Summary:` / `Next:` handoff block.
+- Loop limits, concurrency limits, and the delegation law live in the orchestrator playbook —
+  these pipelines reference them and never override them.
+- Specialists are delegated to by their namespaced plugin names (`<name>`) exactly as the
+  Team Roster in `.vesper/instructions/vesper-orchestration.instructions.md` writes them. The committed maintenance
+  skills are invoked unqualified (`/reinit`, `/compact-knowledge`, `/revalidate-knowledge`,
+  `/revalidate-team`).
+- Memory integration: subagents use the MCP `memory` server's tools per the `mcp-memory` skill.
+
+> **Note on two similarly-named files.** This skill is `vesper-orchestration` — the pipeline
+> detail. `.vesper/instructions/vesper-orchestration.instructions.md` is a *different* artifact: the generated
+> per-project **Team Roster + task-management config**. References to that path throughout these
+> pipelines mean the roster file, not this skill.