@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/claude/.claude-plugin/marketplace.json

@@ -0,0 +1,56 @@
+{
+  "name": "vesper-marketplace",
+  "owner": {
+    "name": "Vesper Maintainers"
+  },
+  "plugins": [
+    {
+      "name": "vesper",
+      "source": "./",
+      "version": "2.0.0",
+      "description": "Vesper core: the support, review and generic developer/tester specialists plus the catalog skills every project uses. Always enabled."
+    },
+    {
+      "name": "vesper-frontend",
+      "source": "./packs/frontend",
+      "version": "2.0.0",
+      "description": "Vesper frontend pack — React, Next.js, Tailwind and Jest/RTL specialists and skills."
+    },
+    {
+      "name": "vesper-playwright",
+      "source": "./packs/playwright",
+      "version": "2.0.0",
+      "description": "Vesper playwright pack — Playwright end-to-end testing specialists and skills."
+    },
+    {
+      "name": "vesper-backend",
+      "source": "./packs/backend",
+      "version": "2.0.0",
+      "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills."
+    },
+    {
+      "name": "vesper-polyglot",
+      "source": "./packs/polyglot",
+      "version": "2.0.0",
+      "description": "Vesper polyglot pack — Java, Flutter and Google ADK (Python) skills."
+    },
+    {
+      "name": "vesper-docs",
+      "source": "./packs/docs",
+      "version": "2.0.0",
+      "description": "Vesper docs pack — Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
+    },
+    {
+      "name": "vesper-integrations",
+      "source": "./packs/integrations",
+      "version": "2.0.0",
+      "description": "Vesper integrations pack — ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (gitlab-ci-skill, github-actions-to-gitlab-ci)."
+    },
+    {
+      "name": "vesper-styles",
+      "source": "./packs/styles",
+      "version": "2.0.0",
+      "description": "Vesper styles pack — opt-in output styles: i-have-adhd, ponytail (third-party, MIT). Enabled by `vespercli packs enable styles`, which writes the always-on pointer rule that applies them."
+    }
+  ]
+}

package/assets/claude/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "vesper",
+  "displayName": "Vesper",
+  "version": "2.0.0",
+  "description": "Vesper specialist subagent catalog + catalog skills for Claude Code. The orchestrator playbook, team roster, slim project whitepaper, the committed main-thread orchestrator agent, and the four maintenance skills are project-committed (see .claude/rules/, .claude/agents/, .claude/skills/) and are deliberately NOT shipped by this plugin.",
+  "author": {
+    "name": "Vesper Maintainers"
+  },
+  "license": "MIT"
+}

package/assets/claude/agents/code-reviewer.md

@@ -67,6 +67,19 @@ Brief overview of what was reviewed.
 - [x] All planned tasks marked complete in `changes.md` are present in code.
 - [ ] No linting errors (checked via `Bash` running the project's lint command).
 
+**Pipeline trailer** — the LAST lines of your final message, verbatim in this shape. The orchestrator reads ONLY these lines (never the report body): the two yes/no answers decide whether the conditional documentation step and the feature-wrap retrospective run for this tier, so never omit them and never bury them mid-report:
+
+```
+Public surface changed: yes|no
+New pattern learned: yes|no
+Status: DONE | NEED_HELP | BLOCKED
+Summary: <1-2 sentence summary of the verdict>
+Next: <fixes the Developer must make, or "none">
+```
+
+- `Public surface changed` is **yes** when the change touches anything a user or another package can observe: a CLI flag or command, an exported/public API, a config-file format, or user-facing text. Internal refactors, tests and private helpers are **no**.
+- `New pattern learned` is **yes** when the implementation introduced a convention, workaround, or approach worth capturing for future tasks (a reusable pattern, a pitfall, a project-specific rule) — a one-off fix is **no**.
+
 ---
 
 ## Constraints

package/assets/claude/agents/feature-wrap-document.md

@@ -14,6 +14,8 @@ You WILL capture implementation patterns, solutions, and architectural decisions
 
 ## When to Invoke
 
+**Tier rule (Implementation pipeline)**: Vesper delegates to you after every **L**-tier implementation, after an **M**-tier one only when the code reviewer's trailer said `New pattern learned: yes`, and never after an **S**-tier one — the retrospective is conditional, not mandatory. The triggers below describe those invocations and explicit requests.
+
 You WILL activate when:
 
 - **Task completion**: All phases in `.vesper/.tracking/changes/*.md` marked complete `[x]`
@@ -157,7 +159,7 @@ START: Is this a RULE about how to write/modify code in THIS project?
 
 You MUST present ALL proposed updates as a numbered summary, then wait for user to approve by number (partial approval supported).
 
-**Scope of this approval gate (important):** this numbered-approval workflow applies ONLY to genuinely **structural** `.claude/vesper/context.md` edits — the slim core's Big Picture Architecture / Domain Model / Critical Workflows, and the on-demand tier's Conventions / Integrations / Technical Debt files. It does **NOT** cover the trivial, high-frequency `.claude/vesper/context/recent-decisions.md` ring-buffer append after an Implementation completion — that bounded self-healing trim-to-N append is `history-logger`'s job (its Recent-Decisions Ring Buffer responsibility), runs unattended in parallel with the `history.md` append, and must never be routed through this approval loop. Do not propose or apply `recent-decisions.md` line appends here.
+**Scope of this approval gate (important):** this numbered-approval workflow applies ONLY to genuinely **structural** `.claude/vesper/context.md` edits — the slim core's Big Picture Architecture / Domain Model / Critical Workflows, and the on-demand tier's Conventions / Integrations / Technical Debt files. It does **NOT** cover the trivial, high-frequency `.claude/vesper/context/recent-decisions.md` ring-buffer append after an Implementation completion — that bounded self-healing trim-to-N append is your own **Recent-Decisions Ring Buffer** responsibility (see below), runs unattended as part of the wrap, and must never be routed through this approval loop. Do not propose `recent-decisions.md` line appends here; just do them.
 
 ### Step 1: Analyze and Generate All Proposals
 
@@ -306,7 +308,7 @@ You WILL after all approved updates are applied:
 
 ### Project Context (two-tier: slim core + on-demand tier)
 
-**Target routing (avoid slim-core creep):** durable prose lands in the on-demand tier, NOT the auto-injected core. A coding rule/convention → `.claude/vesper/context/conventions.md`; an external dep / integration / dev-standard / CI detail → `.claude/vesper/context/integrations.md`; a known debt/ambiguity → `.claude/vesper/context/technical-debt.md`. Only genuinely **structural** content (Big Picture Architecture / Domain Model / Critical Workflows) belongs in the injected `.claude/vesper/context.md` core — and any such gated structural edit also bumps the core's `Last incremental update` freshness stamp. `recent-decisions.md` is `history-logger`'s ring buffer, never written here.
+**Target routing (avoid slim-core creep):** durable prose lands in the on-demand tier, NOT the auto-injected core. A coding rule/convention → `.claude/vesper/context/conventions.md`; an external dep / integration / dev-standard / CI detail → `.claude/vesper/context/integrations.md`; a known debt/ambiguity → `.claude/vesper/context/technical-debt.md`. Only genuinely **structural** content (Big Picture Architecture / Domain Model / Critical Workflows) belongs in the injected `.claude/vesper/context.md` core — and any such gated structural edit also bumps the core's `Last incremental update` freshness stamp. `recent-decisions.md` is the ring buffer described under **Recent-Decisions Ring Buffer** below — appended, never proposed.
 
 **Characteristics:**
 
@@ -627,7 +629,7 @@ You WILL respond to these user commands:
   - `docs/*.md`
   - `README.md`
 - **FORBIDDEN WRITES**:
-  - `.claude/vesper/context/recent-decisions.md` — `history-logger`'s ring buffer, never written here
+  - `.vesper/.tracking/runs/` — the run ledger is written only by `vespercli log` (the orchestrator's call), never by hand
   - Source code files (unless explicitly requested)
   - Configuration files — **except** the single narrow `CLAUDE.md` `@import`-append carve-out defined under ALLOWED WRITES above
   - Planning/tracking files (`.vesper/.tracking/*`)
@@ -664,12 +666,33 @@ When invoked, you WILL:
 
 Your goal is to ensure **every implementation teaches the next one** by systematically capturing and organizing knowledge.
 
+## 📌 Recent-Decisions Ring Buffer (Implementation completions only)
+
+After every **Implementation pipeline completion**, as the last act of your normal wrap, record one bounded line in `.claude/vesper/context/recent-decisions.md`. This is a **self-healing trim-to-N ring buffer** (N=10): the newest 10 decisions live in the on-demand context tier as a quick human-readable view. The decision itself is also captured in the memory graph by the wrap above (as a `learning`/`workspace_pattern` when durable), so trimming the file never loses knowledge — memory is the record, the file is the view. This append is NOT subject to the numbered-approval gate.
+
+1. Read `.claude/vesper/context/recent-decisions.md` (create it with a `# Recent Decisions` header if missing).
+2. Append the new entry as **one line**: `- YYYY-MM-DD [slug] — <one-sentence summary of what shipped>` (`slug` is the story/task slug the orchestrator gave you).
+3. Count the data lines (exclude the header). If the total exceeds **10**, drop the oldest `(total - 10)` lines from the file — they remain in the memory graph and in the story's `changes/` file.
+4. Rewrite `recent-decisions.md` so it holds only the newest 10 entries (plus its header).
+
+**Why re-trim on every append (not a one-time pop):** `recent-decisions.md` carries `merge=union` in `.gitattributes`, so a concurrent-worktree merge may transiently leave the on-disk file with more than 10 entries — `union` never deletes. This is **expected and self-corrects** on the very next append. Do NOT rely on `union` to enforce the cap, and do NOT treat transient overflow as a bug.
+
+## 🗜️ Tracking Compaction Mode (`/compact-knowledge` only — never the default behavior)
+
+A **separate, explicitly-invoked mode**. Runs when Vesper delegates the tracking side of a `/compact-knowledge` request. Scope: the paper trail only.
+
+1. Move **every** `.vesper/.tracking/stories/completed/*.md` (never `completed/archive/` itself) into `.vesper/.tracking/stories/completed/archive/YYYYMM/` (current month). Unconditional — no age gate.
+2. For each moved story slug, move its correlated `research/`, `plans/`, `details/`, `prompts/`, `changes/` and `issues/` artifacts (matched by slug) into `.vesper/.tracking/archive/YYYYMM/<slug>/`. Idempotent: skip what is already there.
+3. If a slug has no recorded feature-wrap (no learnings in memory and no `changes/` file), create an empty `.unwrapped` marker in its archive folder so `/revalidate-knowledge` re-extracts it.
+4. Never move or trim `.vesper/.tracking/runs/` (the run ledger) or `.vesper/memory.jsonl`. Nothing is deleted — only moved.
+5. Report: stories archived, artifacts moved per slug, slugs flagged `.unwrapped`.
+
 ## 🗜️ Memory Compaction Mode (`/compact-knowledge` only — never the default behavior)
 
-A **separate, explicitly-invoked mode**, distinct from your normal per-task memory-update job above. Runs when Vesper delegates a knowledge-compaction request (triggered by `/compact-knowledge`, or a memory-size/entity-count threshold suggestion the user accepted). `history-logger` handles the `history.md`/tracking-archive side of the same request in parallel — this mode is scoped to the memory graph only.
+A **separate, explicitly-invoked mode**, distinct from your normal per-task memory-update job above. Runs when Vesper delegates a knowledge-compaction request (triggered by `/compact-knowledge`, or a memory-size/entity-count threshold suggestion the user accepted). Tracking Compaction Mode handles the paper-trail side of the same request — this mode is scoped to the memory graph only.
 
 1. `read_graph()` (or `search_nodes` broadly) to see the full set of entities.
-2. Identify **stale, observation-heavy entities** — those tied to stories/tasks already in `.vesper/.tracking/stories/completed/` with no observations added recently and no `current_task`/active relation pointing at them. Never touch an entity named `current_task` or anything with an active relation.
+2. Identify **stale, observation-heavy entities** — those tied to stories/tasks already in `.vesper/.tracking/stories/completed/` with no observations added recently and no active relation pointing at them. Never touch anything with an active relation.
 3. For each stale entity: merge its observations into a single summarized entity per topic/category (e.g. collapse five separate `learning_flow_*` entities about the same recurring pattern into one, keeping the clearest/most complete observation and dropping exact duplicates) — use `add_observations` on a consolidated entity and `delete_entities` for the ones folded in. Preserve `supersedes` relations so history isn't lost, just compacted.
 4. Never delete a `preference` or `workspace_pattern` entity outright — these tend to stay relevant; only dedupe near-identical ones.
 5. Report: entity count before/after, and a short list of what was merged.
@@ -683,7 +706,7 @@ A **separate, explicitly-invoked mode**, distinct from both your normal per-task
 1. `read_graph()` (or `search_nodes` broadly) to see the full set of entities.
 2. Cross-check durable entities (`workspace_pattern`, `preference`, architecture/decision entities) against the current code and `workspace-learner`'s revalidated `.claude/vesper/context.md` core + on-demand tier. Correct observations the code no longer supports; add a `supersedes` relation rather than silently rewriting, so the correction is traceable.
 3. Give priority to knowledge tied to `.unwrapped`-flagged archives (slugs archived without a feature-wrap) — re-extract any durable learning those tracking artifacts still hold into the graph.
-4. Merge/dedupe as in Compaction Mode where entities are now redundant post-revalidation. Never touch `current_task` or anything with an active relation.
+4. Merge/dedupe as in Compaction Mode where entities are now redundant post-revalidation. Never touch anything with an active relation.
 5. Report: entities revalidated, corrected, superseded, and re-extracted from flagged archives.
 
 **Never** perform revalidation as a side effect of a normal feature-wrap invocation — only when explicitly asked via `/revalidate-knowledge`.

package/assets/claude/agents/skill-creator.md

@@ -164,7 +164,7 @@ Create the skill directory and files:
 2. Optionally create `references/`, `scripts/`, `assets/` subdirectories via `Write`/`Bash`
 3. Create supporting `.md` files in `references/` if needed
 
-**Default Location**: `.claude/skills/` in the project, or `~/.claude/skills/vesper/skills/` if this is meant to join the global Vesper catalog (only when explicitly requested — ask before writing outside the project).
+**Default Location**: `.claude/skills/` in the project. Never write user-level (`~/.claude/skills/`); new catalog skills are authored in the Vesper repo's `assets/claude/skills/`.
 
 ### 5. Validation Phase
 

package/assets/claude/agents/workspace-learner.md

@@ -139,7 +139,7 @@ Everything else moves to the **on-demand tier**, each replaced in the core by a
 - `.claude/vesper/context/conventions.md` — project-specific patterns that differ from common practice (was "Conventions").
 - `.claude/vesper/context/integrations.md` — external dependencies, cross-component communication, Development Standards / Verification & CI/CD detail.
 - `.claude/vesper/context/technical-debt.md` — known debt / ambiguities.
-- `.claude/vesper/context/recent-decisions.md` — the bounded (N=10) Recent-Decisions ring buffer appended by `history-logger`; start it with a `# Recent Decisions` header and zero entries.
+- `.claude/vesper/context/recent-decisions.md` — the bounded (N=10) Recent-Decisions ring buffer appended by `feature-wrap-document` after each Implementation completion (every decision is also captured in the memory graph); start it with a `# Recent Decisions` header and zero entries.
 
 **Do NOT add any `.claude/vesper/context/*.md` file to the `CLAUDE.md` guard block** — the guard block imports only `orchestrator.md`, `orchestration.md`, and the slim core `context.md`. The on-demand files are pull, not push.
 
@@ -275,11 +275,13 @@ Before assuming any subagent is available, check whether `~/.claude/skills/vespe
 
 Run `vesper list --target claude` via `Bash` and capture the full output. This lists every subagent, command, and skill currently installed in the plugin catalog.
 
+**Packs.** The catalog is a **core** plugin plus stack **packs** (`frontend`, `playwright`, `backend`, `polyglot`, `docs`, `integrations`), and a pack is enabled per project only when the roster needs it — so the installed listing may show a pack as *disabled*. Pick from the **whole catalog index** regardless: run `vespercli catalog` (the shipped `CATALOG.md`; always complete) and read each entry's `Pack:` line. A packed specialist is delegated to as `vesper-<pack>:<name>`; a packed skill is `/vesper-<pack>:<name>`. You never enable a pack yourself — the orchestrator runs `vespercli packs sync` after you hand off (final step below).
+
 #### Step 2 — Match Team Composition to Catalog
 
 Using your analysis from Phase 2, match the workspace's tech stack to catalog items.
 
-**Core subagents are always installed** by `vesper init --target claude` — do NOT attempt to add them individually. The following are core (installed automatically): `workspace-learner`, `technical-product-manager`, `se-system-architecture-reviewer`, `task-researcher`, `code-planner`, `se-technical-writer`, `code-reviewer`, `principal-software-engineer`, `feature-wrap-document`, `skill-creator`, `history-logger`, `vision-analyst`.
+**Core subagents are always installed** by `vesper init --target claude` — do NOT attempt to add them individually. The following are core (installed automatically): `workspace-learner`, `technical-product-manager`, `se-system-architecture-reviewer`, `task-researcher`, `code-planner`, `se-technical-writer`, `code-reviewer`, `principal-software-engineer`, `feature-wrap-document`, `skill-creator`, `vision-analyst`.
 
 **If any core subagent is missing** from `vesper list --target claude` output, this indicates a CLI issue. Stop installation and ask the user to run `vesper init --force-default --target claude` to repair the setup, then re-invoke Workspace Learner.
 
@@ -338,6 +340,7 @@ Edit `.claude/vesper/orchestration.md` to add/update the **Team Roster** section
 - **Support section is FIXED**: All rows in the template's Support table are mandatory. Copy them verbatim into every generated roster — do NOT omit any Support role regardless of project type or stack.
 - Every role MUST map to an installed subagent (verified in `vesper list --target claude`)
 - Subagent names must be **exact** as they appear in `vesper list --target claude` — the orchestrator uses this to delegate via the `Agent` tool
+- Write the **plugin-namespaced** name: `vesper:<name>` for a core specialist, `vesper-<pack>:<name>` for one whose catalog entry carries `Pack: <pack>` (e.g. `vesper-frontend:expert-react-frontend-engineer`, `vesper-playwright:playwright-tester`). Never write a packed specialist as `vesper:<name>` — that name does not resolve
 - `(fallback)` marker signals this role lacks a dedicated specialist and uses a generic subagent
 - Review and Support sections use core subagents — these are always installed and never need fallback markers
 - Only Implementation and Testing sections may have fallback entries
@@ -348,14 +351,14 @@ Edit `.claude/vesper/orchestration.md` to add/update the **Team Roster** section
 - Match skills to roles by **domain overlap** — e.g., `tailwind-shadcn` and `web-frameworks` → Frontend Developer; `backend-development` and `databases` → Backend Developer
 - A subagent may have **multiple skills** — list them comma-separated (e.g., `tailwind-shadcn, web-frameworks, aesthetic`)
 - A skill may be assigned to **multiple subagents** if relevant (e.g., `code-review` → Code Review + Principal Review)
-- Use `—` for roles that need no skills (e.g., History Logger)
+- Use `—` for roles that need no skills
 - Only assign skills that are **actually installed** (verified in `vesper list --target claude`)
 
 #### Step 6 — Verify Roster Against Installed Catalog
 
 After writing the Team Roster, read back `.claude/vesper/orchestration.md` and verify every subagent name in the Team Roster is real. Cross-check against `vesper list --target claude` output — this is the canonical source. If any subagent name doesn't exist in the catalog or in the known core subagent list, fix the Team Roster before proceeding.
 
-**Known core subagents** (always valid): `workspace-learner`, `technical-product-manager`, `se-system-architecture-reviewer`, `task-researcher`, `code-planner`, `se-technical-writer`, `code-reviewer`, `principal-software-engineer`, `feature-wrap-document`, `skill-creator`, `history-logger`, `vision-analyst`.
+**Known core subagents** (always valid): `workspace-learner`, `technical-product-manager`, `se-system-architecture-reviewer`, `task-researcher`, `code-planner`, `se-technical-writer`, `code-reviewer`, `principal-software-engineer`, `feature-wrap-document`, `skill-creator`, `vision-analyst`.
 
 #### Step 7 — Report Installation
 
@@ -364,14 +367,17 @@ Include in your final report:
 - Number of subagents, commands, and skills installed
 - Any gaps (recommended but not found in catalog)
 - Roster verification result (all valid, or list of subagents that could not be resolved)
+- **Packs the roster needs** — one line per pack, e.g. `frontend (vesper-frontend): expert-react-frontend-engineer, reactjs`; `none (core only)` when every named agent and assigned skill is core. Derive it from the `Pack:` line of each catalog entry you used
 - The full `vesper list --target claude` output
 
+Then tell the orchestrator to run **`vespercli packs sync`** — it enables every pack the roster you just wrote needs (and reports packs enabled but no longer needed; it never disables). You do not run it yourself.
+
 End your response with:
 
 ```
 Status: DONE
-Summary: <what was written/updated and installed>
-Next: none
+Summary: <what was written/updated and installed; the packs the roster needs>
+Next: run `vespercli packs sync` (enables the packs the Team Roster needs), then none
 ```
 
 ## Constraints

package/assets/claude/context.md.tpl

@@ -41,7 +41,7 @@ On-demand tier (create as separate files, reference each by a one-line pointer f
 - .claude/vesper/context/conventions.md — project-specific patterns that differ from common practice.
 - .claude/vesper/context/integrations.md — external deps, cross-component comms, dev standards / CI.
 - .claude/vesper/context/technical-debt.md — known debt / ambiguities (re-validated on regen, not append-only).
-- .claude/vesper/context/recent-decisions.md — bounded (N=10) Recent-Decisions ring buffer (history-logger).
+- .claude/vesper/context/recent-decisions.md — bounded (N=10) Recent-Decisions ring buffer, appended by feature-wrap-document after each Implementation completion; every decision is also captured in the MCP memory graph, so the file is a convenience view, not the record.
 
 Guidelines:
 - Slim and scannable: push depth into the on-demand tier, not the core; verify with `wc -l` <= 200.

package/assets/claude/orchestration.md.tpl

@@ -4,13 +4,15 @@ description: 'Vesper orchestration data — team roster, task management, routin
 
 # Vesper Orchestration
 
-**Source of truth**: this file is the single authority for this project's available specialist subagents, their roles, and their skill assignments. The orchestrator playbook (`vesper-orchestrator.md`, imported above this file in root `CLAUDE.md`) routes purely by the names listed in the **Team Roster** below.
+**Source of truth**: this file is the single authority for this project's available specialist subagents, their roles, and their skill assignments. The orchestrator playbook (the always-on `.claude/rules/vesper-orchestrator.md` rule) routes purely by the names listed in the **Team Roster** below.
+
+**Delegation-name convention (correctness invariant):** every specialist Agent Name in the roster below is the plugin's **namespaced** name — `vesper:<name>` for a core specialist, `vesper-<pack>:<name>` for one shipped by a pack (the catalog index `assets/CATALOG.md` / `vespercli catalog` names each asset's pack) — that is exactly the `subagent_type` the orchestrator must delegate with, since the specialist catalog ships as the `vesper` marketplace plugin plus its packs. The one exception is the committed main-thread persona `vesper-orchestrator` (a project agent, no namespace), used only as the `.claude/settings.json` `agent` key value. `workspace-learner` MUST preserve the plugin prefix on every specialist name it writes here. A packed asset named here (agent or assigned skill) needs its pack enabled for this project: `vespercli packs sync` enables what this roster needs (`init`/`update` run it too; `vespercli doctor` reports a gap as `pack-not-enabled`).
 
 ## Repository Policy
 
 Base branch: `<!-- workspace-learner: fill in with the repo's actual default branch, e.g. via `git symbolic-ref refs/remotes/origin/HEAD` or `git branch --show-current` if no remote yet -->`
 
-Every git worktree for this project is created **from the base branch above** — never from another worktree's branch. `.vesper/.tracking/`, `.vesper/history.md`, and `.vesper/memory.jsonl` are git-tracked and shared by every AI client working this workspace (see the `mcp-memory` skill and the merge-driver setup in `.gitattributes`) — never create a client-specific tracking folder. `.mcp.json`, `.vscode/mcp.json`, `.vesperrc`, and `.vesper/index.db` are local/gitignored and get regenerated automatically for each worktree (SessionStart hook, VS Code folder-open task, and `git post-checkout` hook all call `vespercli worktree bootstrap`).
+Every git worktree for this project is created **from the base branch above** — never from another worktree's branch. `.vesper/.tracking/` (the run ledger `runs/` included) and `.vesper/memory.jsonl` are git-tracked and shared by every AI client working this workspace (see the `mcp-memory` skill and the merge-driver setup in `.gitattributes`) — never create a client-specific tracking folder. `.mcp.json`, `.vscode/mcp.json`, `.vesperrc`, and `.vesper/index.db` are local/gitignored and get regenerated automatically for each worktree (SessionStart hook, VS Code folder-open task, and `git post-checkout` hook all call `vespercli worktree bootstrap`).
 
 ## Task Management
 
@@ -62,26 +64,25 @@ Populated by workspace-learner during setup / re-init. Structure:
 
 | Role             | Agent Name                              | Assigned Skills             |
 | ---------------- | ------------------------------------------ | ---------------------------- |
-| Code Review      | code-reviewer                      | [skills matching this role] |
-| Architecture     | se-system-architecture-reviewer    | [skills matching this role] |
-| Principal Review | principal-software-engineer        | [skills matching this role] |
+| Code Review      | vesper:code-reviewer                      | [skills matching this role] |
+| Architecture     | vesper:se-system-architecture-reviewer    | [skills matching this role] |
+| Principal Review | vesper:principal-software-engineer        | [skills matching this role] |
 
 ### Support (fixed — every row included verbatim, every project)
 
 | Role               | Agent Name                        | Assigned Skills                                 |
 | ------------------- | ------------------------------------ | -------------------------------------------------- |
-| Research           | task-researcher              | [skills matching this role]                         |
-| Planning            | code-planner                 | [skills matching this role]                         |
-| Documentation       | se-technical-writer          | [skills matching this role]                         |
-| Retrospective       | feature-wrap-document        | [skills matching this role]                         |
-| Knowledge Codifier  | skill-creator                | skill-creator, mcp-management, docs-seeker         |
-| History             | history-logger               | —                                                    |
+| Research           | vesper:task-researcher              | [skills matching this role]                         |
+| Planning            | vesper:code-planner                 | [skills matching this role]                         |
+| Documentation       | vesper:se-technical-writer          | [skills matching this role]                         |
+| Retrospective       | vesper:feature-wrap-document        | [skills matching this role]                         |
+| Knowledge Codifier  | vesper:skill-creator                | skill-creator, mcp-builder, docs-seeker            |
 
 Fallback mapping (used ONLY when no specialist subagent is installed for a role):
 
 | Role Category | Fallback Agent                    |
 | ------------- | ------------------------------------ |
-| Developer     | principal-software-engineer  |
-| Tester        | code-reviewer                |
-| Task Agent    | technical-product-manager    |
+| Developer     | vesper:principal-software-engineer  |
+| Tester        | vesper:code-reviewer                |
+| Task Agent    | vesper:technical-product-manager    |
 -->

package/assets/claude/packs/backend/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-backend",
+  "displayName": "Vesper backend pack",
+  "version": "2.0.0",
+  "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
+  "author": {
+    "name": "Vesper Maintainers"
+  },
+  "license": "MIT"
+}

package/assets/claude/packs/backend/skills/agent-fundamentals/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: agent-fundamentals
+description: Universal operating rules for all Vesper subagents — codebase query protocol, terminal discipline, tool usage patterns, and response standards. Use when any subagent needs to search code, run terminal commands, perform file operations, or produce output. This is the baseline skill every Vesper subagent should follow.
+---
+
+# Vesper Agent Fundamentals
+
+Universal operating rules for every subagent in the Vesper ecosystem. These are non-negotiable behaviors — not guidelines.
+
+## Codebase Query Protocol
+
+**PRIMARY**: `vesper-indexing` MCP tools are the first-choice codebase exploration method.
+
+| Tool                                  | Purpose                                               |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `mcp__vesper-indexing__vesper_search`  | Full-text code search → returns snippets + file paths |
+| `mcp__vesper-indexing__vesper_symbols` | Find functions, classes, exports by name + location   |
+| `mcp__vesper-indexing__vesper_status`  | Check index health before querying                    |
+| `mcp__vesper-indexing__vesper_reindex` | Rebuild index if stale or empty                       |
+
+- Results include actual source code — skip `Read` unless you need wider surrounding context.
+- If the index is empty or MCP unavailable → **STOP and report**. Do NOT silently fall back to directory traversals or `find` commands.
+- For broader exploration beyond indexed content: `Grep`, `Glob` are acceptable secondary tools.
+- **Archives are off-limits in normal pipelines**: never read, grep, or search `.vesper/history-archive/` or `.vesper/.tracking/archive/` during ordinary work — they are index-excluded and reachable only via `/revalidate-knowledge`. See [codebase-query.md](references/codebase-query.md).
+
+## Terminal Discipline
+
+See [terminal-discipline.md](references/terminal-discipline.md) for expanded rules and examples.
+
+| Rule                       | Requirement                                                            |
+| --------------------------- | -------------------------------------------------------------------------- |
+| **Timeout**                | Every command gets one. Quick=15s, build=120s, test=300s. Default=30s. |
+| **No foreground blockers** | `tail -f`, `watch`, dev servers → always run with `run_in_background: true`. |
+| **Output cap**             | `\| head -30` if output may exceed 50 lines.                           |
+| **Stderr capture**         | `2>&1 \| head -N` for both stdout and stderr.                          |
+| **No `cd &&` chaining**    | Use `pushd path && command && popd` instead.                           |
+| **Runtime version guard**  | Node commands → check `.nvmrc`/`.node-version`, chain `nvm use` in the same call. Ignore if unavailable. |
+| **Tools-first**            | Never use `Bash` for tasks built-in tools handle.                     |
+
+## Tool Usage Hierarchy
+
+See [tool-usage-patterns.md](references/tool-usage-patterns.md) for comprehensive patterns and anti-patterns.
+
+**Always prefer built-in tools over `Bash` equivalents:**
+
+| Task          | ✅ Correct Tool          | ❌ Never Do This                             |
+| -------------- | -------------------------- | ---------------------------------------------- |
+| Read a file   | `Read`                    | `cat`, `less`, `node -e "fs.readFileSync()"` |
+| Search code   | `Grep`, `mcp__vesper-indexing__vesper_search` | `grep -r`, `find . -exec grep` |
+| Find files    | `Glob`                    | `find .`, `ls -R`, `tree`                    |
+| Create a file | `Write`                   | `echo > file`, `python -c "open().write()"`  |
+| Edit a file   | `Edit`                    | `sed -i`, `node -e "fs.writeFileSync()"`     |
+| Check errors  | `Bash` (the project's own lint/typecheck command) | Manual terminal compilation |
+
+## Secret & Credential Handling
+
+**NEVER write a secret to a file.** No token, API key, password, private key, or connection string carrying an embedded secret may be written into any file you `Write` or `Edit` — regardless of git host, language, or task.
+
+| Trigger                                                          | Required Action                                                                                                                                                        |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A value about to be written looks like a token/credential/secret | **STOP** — do not write it. Require explicit user confirmation before proceeding.                                                                                      |
+| You are a subagent and cannot ask the user directly              | **Escalate, don't write** — surface the blocker and stop (same reflex as the Codebase Query Protocol's "STOP and report"), rather than silently writing the secret. Return `NEED_HELP` to the orchestrator so a human is asked before any write. |
+| The user explicitly approves writing the value                   | Proceed, then **record the approved exception** back into the project's instructions (`CLAUDE.md` or the relevant `.claude/vesper/*.md`) so the same value isn't re-flagged on a later pass. |
+
+- Detection is on the **value**, not the file: a secret-shaped string (a long random token, `ghp_…`/`glpat-…`-style prefixes, a PEM `-----BEGIN … PRIVATE KEY-----` block, a `user:password@host` connection URL) triggers the stop — even inside configs, tests, or docs.
+- Prefer a placeholder or environment-variable reference (`${MY_TOKEN}`) over the literal secret whenever a file genuinely needs the name.
+- When in doubt, halt and surface it — never silently work around it.
+
+## Direct Collaboration (Nested Delegation)
+
+If your toolset includes `Agent`, you may delegate directly to another specialist instead of returning `NEED_HELP` to the orchestrator. This is the preferred path for bounded assists — it saves a full round-trip through the orchestrator.
+
+**Protocol:**
+
+1. **Roster only**: Pick the collaborator from the Team Roster (`.claude/vesper/orchestration.md`) and use its **exact name** as the `subagent_type`. If it's not on the roster, it doesn't exist.
+2. **Depth accounting**: Your delegation prompt includes a `Nesting depth: N` marker (the orchestrator is depth 0; its direct delegates are depth 1). When you delegate, include `Nesting depth: N+1` in the prompt. If no marker was given, assume you are at depth 1.
+3. **Depth budget**: If your depth N ≥ 3, do NOT delegate — end with `Status: NEED_HELP` instead and describe what you need in `Next:`. (The platform maximum is 5; stopping at 3 leaves headroom for your collaborator to make one nested call of its own.)
+4. **Point assists only**: Nested delegation is for a bounded question, review, lookup, or gap-fill — never for executing a whole pipeline step that belongs on the orchestrator's todo list. If the work you need is a pipeline step, return `NEED_HELP`.
+5. **Self-contained prompts**: Same rules the orchestrator follows — include file paths, enough background to act, the expected output, the depth marker, and the requirement to end with the `Status:/Summary:/Next:` footer.
+6. **Fold results in**: Your collaborator's final message returns to YOU, not the orchestrator. Incorporate it into your own artifacts/output, and note the collaboration in your final `Summary:` so the orchestrator has the full picture.
+7. **Fallback is always available**: `Agent` tool missing from your toolset, the call fails, or the depth budget is spent → end with `Status: NEED_HELP` and what you need in `Next:`. The orchestrator will route it.
+
+## Response Standards
+
+- **Be direct**: State findings, don't narrate your process.
+- **Show evidence**: Back claims with file paths, line numbers, or code snippets.
+- **Report blockers immediately**: If MCP tools fail, index is empty, or permissions block you — say so. Don't silently work around it.
+- **No verbose preambles**: Skip "I'll now..." or "Let me..." — just do the work.
+- **Structured output**: Use Markdown tables, bullet lists, and code blocks. Walls of text = failure.

package/assets/claude/packs/backend/skills/agent-fundamentals/references/codebase-query.md

@@ -0,0 +1,95 @@
+# Codebase Query Protocol
+
+How Vesper subagents should explore and understand any codebase.
+
+## Priority Order
+
+```
+1. vesper-indexing MCP tools       (PRIMARY — always try first)
+2. Grep                            (SECONDARY — when index lacks coverage)
+3. Glob + Read                     (TERTIARY — targeted file inspection)
+4. Bash                            (LAST RESORT — only for operations with no built-in equivalent)
+```
+
+## Archive Exclusion (normal pipelines)
+
+Archived knowledge directories — `.vesper/history-archive/`, `.vesper/.tracking/archive/`, and `.vesper/.tracking/stories/completed/archive/` — are **excluded from all normal-pipeline reads, greps, and searches**. They are also excluded from the `vesper-indexing` index (`DEFAULT_EXCLUDES`), so `vesper_search`/`vesper_symbols` never surface their contents. Do NOT `Grep`, `Read`, or otherwise crawl these paths during ordinary research, planning, implementation, or review work. They hold intentionally retired material (rotated history, archived tracking artifacts) and are reachable **only** through the explicit `/revalidate-knowledge` flow, which re-validates archived knowledge against current code. If you think you need something from an archive, that is a signal to surface `/revalidate-knowledge` to the user — not to read the archive directly.
+
+## vesper-indexing MCP Tools
+
+### mcp__vesper-indexing__vesper_search
+
+Full-text code search across the indexed workspace. Returns matching code snippets with file paths and line ranges.
+
+```
+Use for: Finding specific code patterns, function calls, variable usage,
+         string literals, error messages, configuration values
+```
+
+**Key behavior**: Results include actual source code. In most cases, you DO NOT need a follow-up `Read` unless you need wider context beyond the returned snippet.
+
+### mcp__vesper-indexing__vesper_symbols
+
+Find functions, classes, exports, and other symbols by name. Returns symbol type, location, and surrounding code.
+
+```
+Use for: Finding function definitions, class declarations, exported modules,
+         understanding module interfaces, locating entry points
+```
+
+### mcp__vesper-indexing__vesper_status
+
+Check the health and state of the search index.
+
+```
+Use for: Verifying the index is populated before querying,
+         checking if a reindex is needed after major file changes
+```
+
+### mcp__vesper-indexing__vesper_reindex
+
+Force a rebuild of the search index.
+
+```
+Use for: After bulk file operations, when vesper_status reports stale data,
+         when search results seem incomplete
+```
+
+## Index Failure Protocol
+
+If vesper-indexing tools fail or return empty results:
+
+1. **STOP** — do not silently fall back
+2. **Report** the failure to the user: "vesper-indexing MCP is unavailable/empty"
+3. **Fall back explicitly** to `Grep` with a note
+4. **Never** start crawling directories with `find`, `ls -R`, or `tree` as a hidden workaround
+
+## Secondary Tools
+
+### Grep
+
+Best for exact text matches, regex patterns, filtering by file type.
+
+```
+Use when:
+- You know the exact string or pattern
+- You need regex matching
+- You want to scope to specific files (glob filter)
+```
+
+### Glob
+
+Best for finding files by name or path pattern.
+
+```
+Use when:
+- You know the filename but not the location
+- You need all files matching a glob (e.g., **/*.test.ts)
+- You're looking for configuration files
+```
+
+## Exploration Efficiency
+
+- **Batch when possible**: Multiple `Grep` calls with regex alternation (`pattern1|pattern2`) instead of sequential single-pattern searches
+- **Read targeted ranges**: Use `Read` with a specific `offset`/`limit`, not the entire file
+- **Use subagents for deep exploration**: For complex multi-step searches, delegate to a specialist subagent (from the Team Roster) via the `Agent` tool instead of manually chaining 10+ search calls. Specialist agents own their own discovery — never invoke a subagent that bypasses the roster.

package/assets/claude/packs/backend/skills/agent-fundamentals/references/terminal-discipline.md

@@ -0,0 +1,94 @@
+# Terminal Discipline — Expanded Rules
+
+Non-negotiable rules for every `Bash` command a subagent executes.
+
+## Timeout Requirements
+
+| Command Type       | Timeout  | Examples                                               |
+| -------------------- | ---------- | ---------------------------------------------------------- |
+| Quick              | 15s      | `ls`, `cat`, `echo`, `which`, `git status`             |
+| Package management | 60s      | `npm install`, `pip install`, `brew install`            |
+| Build              | 120s     | `npm run build`, `tsc`, `esbuild`, `webpack`           |
+| Test               | 300s     | `npm test`, `vitest run`, `pytest`, `playwright test`  |
+| Default            | 30s      | Anything not in the above categories                   |
+
+**Every command gets a timeout. No exceptions.**
+
+## Background Processes
+
+Commands that never terminate must be run with `run_in_background: true`:
+
+- Dev servers: `npm run dev`, `next dev`, `vite dev`
+- Watch modes: `tsc --watch`, `vitest --watch`, `nodemon`
+- Log tailing: `tail -f`, `docker logs -f`
+- Containers: `docker compose up`
+- Any long-running process the subagent doesn't need to wait for
+
+After starting a background process, check its output via the harness's background-task output mechanism rather than blocking on it.
+
+## Output Control
+
+```bash
+# Cap output to prevent context overflow
+command | head -30
+
+# Capture both stdout and stderr
+command 2>&1 | head -30
+
+# Count lines before displaying
+command | wc -l    # check size first, then decide head limit
+
+# Git: always limit
+git log --oneline -20
+git diff --stat
+
+# Grep: files-only when appropriate
+grep -rl "pattern" src/
+```
+
+**Never** let unbounded output flood the context window. If output might exceed 50 lines, pipe through `head`.
+
+## Directory Navigation
+
+```bash
+# ❌ WRONG — breaks permission-prompt matching (matching starts from `cd`)
+cd /some/path && npm run build
+
+# ✅ CORRECT — preserves working directory, approval matches `npm`
+pushd /some/path && npm run build && popd
+
+# ✅ ALSO CORRECT — if already in the right directory
+npm run build
+```
+
+The `cd && command` pattern breaks command-matching for permission prompts because matching starts from `cd`, not the actual command. Always use `pushd`/`popd` for temporary directory changes.
+
+## Runtime Version Guard (Node/nvm)
+
+Projects that pin a Node version via nvm expect every command to run under that version — running under whatever `node` happens to be on PATH can produce misleading build/test failures or silently wrong behavior.
+
+Before running any Node-based command (`npm`, `npx`, `yarn`, `pnpm`, `node`, or project scripts that wrap them):
+
+1. Check the project root for `.nvmrc` or `.node-version`.
+2. If found, chain `nvm use` into the **same** `Bash` call as the actual command — shell state (including nvm's shell function) does not persist between separate tool calls:
+   ```bash
+   nvm use > /dev/null 2>&1; npm test
+   ```
+3. If `nvm` isn't installed, no version file exists, or the switch fails — proceed anyway with whatever `node` is on PATH. **Never block the task on this.**
+
+Do not run `nvm use` as its own command and expect it to carry over to the next one — it won't.
+
+## curl Rules
+
+- Always set `--max-time 5` to prevent hanging on unresponsive hosts
+- Localhost health checks only without explicit user approval
+- Never curl external URLs without user awareness
+
+## Timeout Recovery
+
+When a command times out:
+
+1. **Diagnose first** — `ps aux | grep <process>` to check if it's still running
+2. **Report to user** — Explain what happened and why
+3. **Don't blindly retry** — The same command will likely time out again
+4. **Suggest alternatives** — Smaller scope, different approach, or user intervention