@mthanh/vespercli 1.5.1 → 1.6.0

package/README.md

@@ -2,7 +2,65 @@
 
 CLI tool to manage AI agents, prompts, instructions, and skills for your workspace — for GitHub Copilot Chat in VS Code, and for Claude Code.
 
-**Vesper** is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. Everything below describes the default (Copilot) target; see [Claude Code target](#claude-code-target) for the second target.
+**Vesper** is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. It supports two platforms — **GitHub Copilot** (VS Code) and **Claude Code** — chosen via a multi-select during `vespercli init`; a single workspace can run both at once, sharing the same `.vesper/` tracking state.
+
+## The Vesper Lifecycle
+
+Vesper is a **pure orchestrator** — it routes, gates, and approves every hand-off, but never does the work itself. Each task travels one revolution of the cycle: the violet **delivery loop** ships it (specialist subagents research, plan, implement, review, and test, with every step reading and writing tracking documents under `.vesper/.tracking/`), and the amber **learning loop** mines what just happened — comparing plan vs. actual, then minting skills, instructions, and knowledge-graph memory that are re-injected into the next task.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/lifecycle-ring-dark.svg">
+  <img src="docs/images/lifecycle-ring-light.svg" alt="Vesper lifecycle ring: Research, Plan, Validate, Implement, Review + Test (delivery), then Retrospect, Store, Re-inject (learning), with Vesper orchestrating at the center" width="760">
+</picture>
+
+Every revolution leaves the system smarter: divergences from plan become glob-scoped instructions, repeated patterns become skills, and task context survives interruption — across sessions and across both client targets.
+
+### Tracking documents — the paper trail
+
+Delegation prompts pass **paths, never contents**. Each document has one writer and defined readers, so a fresh-context subagent can pick up mid-pipeline — even a subagent on the *other client* (Copilot ↔ Claude Code share `.vesper/` by design).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-ledger-dark.svg">
+  <img src="docs/images/panel-ledger-light.svg" alt="Tracking-documents ledger: research, plans, details, prompts, changes, issues, and stories files — each with one writer and defined consumers; story folders carry status: refining, backlog, inprogress, inreview, completed" width="920">
+</picture>
+
+### Implementation runs on prompts, not vibes
+
+The planner doesn't just plan — it writes the *executable brief* each developer will follow:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-chain-dark.svg">
+  <img src="docs/images/panel-chain-light.svg" alt="Prompt chain: planner emits plan, details, and one prompt file per track; Vesper's blocking gate verifies all planning files exist; developers execute the prompt exactly in parallel; divergences from plan are logged in the changes file as the retrospective's raw material" width="920">
+</picture>
+
+### Task tracker — board is the source of truth
+
+The Task Management section of the orchestration file names the system (ClickUp, Jira, …) and its Task Agent; the pipeline never talks to a board directly. **Local mode** works with zero configuration — the story folders alone carry status.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-tracker-dark.svg">
+  <img src="docs/images/panel-tracker-light.svg" alt="Task tracker: ClickUp, Jira, or Local; status flow REFINED to IN PROGRESS to IN REVIEW to DONE with routing guards (never re-refine, re-assign, or re-implement); board wins discrepancies; Case A fetches a referenced task, Case B auto-creates one after refinement" width="920">
+</picture>
+
+### The retrospective engine — where skills are born
+
+After every implementation, the Feature Wrap agent compares what was planned against what actually happened, then routes each learning through a decision tree:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-retro-dark.svg">
+  <img src="docs/images/panel-retro-light.svg" alt="Retrospective engine: mines changes, plans, details, research, and git diffs; patterns in 3+ files become skills, structures in 5+ files become instructions; decision tree routes learnings to INSTRUCTION, SKILL, DOCUMENTATION, or the MEMORY GRAPH, behind Vesper's approval filter" width="920">
+</picture>
+
+### Where learning re-enters the pipeline
+
+Capture is worthless without injection — every knowledge output has a named consumer at a named step:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-reentry-dark.svg">
+  <img src="docs/images/panel-reentry-light.svg" alt="Four re-entry points: memory search before research, current_task recall before planning, roster skill injection on every delegation, and glob-bound instruction auto-apply on every matching edit" width="920">
+</picture>
+
+The design optimizes for compounding: mistakes convert to rules, workflows convert to skills, and state survives interruption, `/clear`, and even a client switch. When a fix loop caps out (10 iterations), unresolved issues are written to `issues/` and the pipeline continues — dead ends become documents, not lost context.
 
 ## Installation
 
@@ -17,29 +75,24 @@ npx @mthanh/vespercli <command>
 ## Quick Start
 
 ```bash
-# Initialize Vesper in your project
-# (multi-select which platform(s) to set up — GitHub Copilot and/or Claude Code;
-#  pass --target copilot,claude or --target all to skip the prompt)
+# Initialize Vesper in your project — multi-select GitHub Copilot and/or Claude Code
+# (pass --target copilot,claude or --target all to skip the prompt)
 vespercli init
+```
 
-# (Optional) Add local overrides to customize specific assets
-vespercli add --agent code-reviewer code-planner
-
-# Add skills (as local overrides)
-vespercli add --skill aesthetic tailwind-shadcn
+Then say hello:
 
-# List local overrides
-vespercli list
+- **GitHub Copilot** — reload VS Code (`Developer: Reload Window`), open Copilot Chat, select **Vesper** from the agent dropdown, and prompt `Vesperize` — Vesper scans the workspace and assembles your team.
+- **Claude Code** — start a session and prompt `init` — Vesper detects the missing Team Roster and runs the full workspace setup automatically.
 
-# Update local overrides
-vespercli update
-```
+## Settings-based Asset Injection
 
-## Settings-based Asset Injection (New)
+Vesper integrates by **pointing your AI client at the packaged catalog** instead of copying assets into your repo — VS Code workspace settings for Copilot, a user-level plugin for Claude Code. Only project-specific files (roster, context, tracking) live in the workspace.
 
-Vesper now integrates with VS Code by **configuring workspace settings** instead of copying the full asset catalog into your repo.
+<details>
+<summary><b>GitHub Copilot</b> — VS Code settings + MCP servers</summary>
 
-### What `vespercli init` does
+`vespercli init` (with Copilot selected):
 
 - Creates/updates `.vscode/settings.json` to point Copilot Chat at Vesper's packaged assets.
 - Configures core MCP servers in `.vscode/mcp.json`:
@@ -79,7 +132,27 @@ Example (illustrative):
 }
 ```
 
-### Local overrides (still supported)
+</details>
+
+<details>
+<summary><b>Claude Code</b> — user-level plugin + project orchestrator files</summary>
+
+Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting, so the specialist catalog is distributed as a **user-level plugin** instead: `vespercli init` (with Claude Code selected) installs it once to `~/.claude/skills/vesper/`, making it available in **every** Claude Code project on the machine. In the current project it creates only:
+
+- `CLAUDE.md` — a small guarded `@import` block pointing at the three files below (never touches the rest of your `CLAUDE.md`)
+- `.claude/vesper/orchestrator.md` — the orchestration playbook (routing rules, delegation), refreshed on every `init`/`update`
+- `.claude/vesper/orchestration.md` — this project's Team Roster + Task Management config
+- `.claude/vesper/context.md` — this project's architecture/stack/conventions
+- `.mcp.json` and `.claude/settings.json` — the `vesper-indexing` MCP server + its tool permissions
+
+No editor dependency — these files are read by the Claude Code engine itself, so the same install works from the terminal CLI, VS Code extension, JetBrains, or the desktop app. During install you're asked once whether to prefix catalog names with `vesper-` to avoid collisions with other Claude Code kits.
+
+A single project can have both targets installed at once — `.vesper/` (code index, story tracking, `history.md`) is shared and cross-client by design, so a story researched under Copilot can be implemented under Claude Code, or vice versa.
+
+</details>
+
+<details>
+<summary><b>Local overrides</b> — customize specific assets</summary>
 
 If you want to customize a specific agent/prompt/instruction/skill, use `vespercli add`.
 
@@ -87,16 +160,12 @@ If you want to customize a specific agent/prompt/instruction/skill, use `vesperc
 - Local copies in `.vesper/` take precedence over the settings-based (package) assets.
 - This is the recommended way to make small, intentional customizations without vendoring everything.
 
-### Migration from legacy `.vesper/` installs
-
-If Vesper detects a legacy install that previously copied assets into `.vesper/`, `vespercli init` will offer to migrate you to the settings-based approach.
-
-- After migrating, you can keep any locally customized files as overrides.
-- Everything else is discovered directly from the Vesper package.
+</details>
 
 ## Commands
 
-### `vespercli init`
+<details>
+<summary><b><code>vespercli init</code></b> — initialize platform(s) in your workspace</summary>
 
 Initialize Vesper in your workspace. Pick one or more platforms (GitHub Copilot
 and/or Claude Code) via a multi-select prompt; the CLI lays down the base setup
@@ -116,7 +185,10 @@ vespercli init --target claude -y       # Non-interactive: Claude with default s
 vespercli init --path /my/project       # Specify workspace path
 ```
 
-### `vespercli add`
+</details>
+
+<details>
+<summary><b><code>vespercli add</code></b> — add local overrides</summary>
 
 Add local overrides (copies) for agents, prompts, instructions, or skills into `.vesper/`.
 
@@ -136,9 +208,15 @@ vespercli add -i nextjs reactjs
 # Add skills
 vespercli add --skill <name> [name2...]
 vespercli add -s aesthetic backend-development
+
+# For Claude Code, adds go to the shared plugin catalog instead
+vespercli add agents code-reviewer --target claude
 ```
 
-### `vespercli list`
+</details>
+
+<details>
+<summary><b><code>vespercli list</code></b> — list local overrides</summary>
 
 List local override assets in `.vesper/`.
 
@@ -149,7 +227,10 @@ vespercli list --type agents      # Filter by type
 vespercli list -t skills          # Short form
 ```
 
-### `vespercli update`
+</details>
+
+<details>
+<summary><b><code>vespercli update</code></b> — refresh local overrides</summary>
 
 Update local override assets from the package to get the latest versions.
 
@@ -158,7 +239,10 @@ vespercli update                  # Interactive confirmation
 vespercli update -y               # Skip confirmation
 ```
 
-### `vespercli reset`
+</details>
+
+<details>
+<summary><b><code>vespercli reset</code></b> — remove configuration and/or overrides</summary>
 
 Remove Vesper configuration and/or local overrides.
 
@@ -170,7 +254,10 @@ vespercli reset --local-only      # Only remove local `.vesper/` folder
 vespercli reset --full            # Remove EVERYTHING including vesper.agent.md (requires typing "YES")
 ```
 
-### `vespercli mcp`
+</details>
+
+<details>
+<summary><b><code>vespercli mcp</code></b> — manage MCP servers</summary>
 
 Manage MCP servers for whichever target(s) are installed here — Copilot (`.vscode/mcp.json`), Claude Code (`.mcp.json`), or both at once. `mcp add`/`mcp remove`/`mcp list` are for **optional catalog servers** (e.g. `clickup`); the three Vesper-core servers (`vesper-indexing`, `sequential-thinking`, `memory`) are managed separately via `mcp enable`/`mcp disable`/`mcp sync` and are never addable/removable through `mcp add`/`mcp remove`.
 
@@ -187,27 +274,21 @@ vespercli mcp sync                         # Re-sync tool auto-approval (Copilot
 vespercli mcp reindex --full               # Clear and rebuild the shared code index
 ```
 
-`mcp add`/`mcp remove`/`mcp list` are fully supported for the Claude Code target — earlier versions silently no-op'd here for anything beyond the 3 core servers.
+</details>
 
-### `vespercli --version`
-
-Display the current version.
+<details>
+<summary><b><code>vespercli --version</code></b> / <b><code>--help</code></b></summary>
 
 ```bash
-vespercli -v
+vespercli -v                      # Display the current version
 vespercli --version
-```
-
-### `vespercli --help`
-
-Display help information.
-
-```bash
-vespercli -h
+vespercli -h                      # Display help information
 vespercli --help
 vespercli <command> --help
 ```
 
+</details>
+
 ## Asset Types
 
 Vesper provides a full catalog via VS Code settings, and supports optional local overrides.
@@ -221,52 +302,10 @@ Vesper provides a full catalog via VS Code settings, and supports optional local
 
 ## After Installation
 
-1. Open VS Code in your workspace
-2. Open GitHub Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`)
-3. Select **Vesper** from the agent dropdown
-4. Start working with an AI agent suite that includes specialized developers, planners, reviewers, and more
-
-## Claude Code target
-
-Vesper also targets **Claude Code**, as a second, fully independent install alongside (or instead of) the Copilot target above — nothing here changes the default behavior of the commands described so far.
-
-Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting (no way to point it at an arbitrary external directory), so the specialist catalog is distributed as a **user-level plugin** instead of referenced in place: `vespercli init --target claude` installs it once to `~/.claude/skills/vesper/`, and it's then available in **every** Claude Code project on the machine, not just this one. Only genuinely project-specific content lives in the repo:
-
-```bash
-vespercli init --target claude          # Install the plugin catalog + this project's orchestrator/roster/context
-```
-
-This creates, in the current project only:
-
-- `CLAUDE.md` — a small guarded `@import` block pointing at the three files below (never touches the rest of your `CLAUDE.md`)
-- `.claude/vesper/orchestrator.md` — the orchestration playbook (routing rules, delegation), refreshed on every `init`/`update`
-- `.claude/vesper/orchestration.md` — this project's Team Roster + Task Management config
-- `.claude/vesper/context.md` — this project's architecture/stack/conventions
-- `.mcp.json` and `.claude/settings.json` — the `vesper-indexing` MCP server + its tool permissions
-
-No `.claude/agents/`, `.claude/commands/`, or `.claude/skills/` appear in the project — the full specialist catalog (subagents, slash commands, skills) lives once in the shared plugin at `~/.claude/skills/vesper/`.
-
-```bash
-vespercli init --target claude                          # Install/refresh everything above
-vespercli add agents code-reviewer --target claude       # Add one subagent to the plugin catalog
-vespercli list --target claude                           # See what's installed
-vespercli update --target claude                         # Refresh the plugin + orchestrator playbook after `npm update`
-vespercli reset --target claude                           # Remove this project's files (leaves the shared plugin catalog alone)
-vespercli mcp status --target claude                      # Check the vesper-indexing MCP server in .mcp.json; also warns on .mcp.json vs .vesperrc drift
-vespercli mcp add clickup --target claude                 # Add an optional catalog MCP server to .mcp.json + record it in .vesperrc
-vespercli mcp remove clickup --target claude              # Remove it (prunes both .mcp.json and .vesperrc)
-vespercli mcp list --target claude                        # List catalog + custom servers configured for this target
-```
-
-Unlike the Copilot target, this one has **no editor dependency** — `~/.claude/...` and a project's `.claude/`/`CLAUDE.md`/`.mcp.json` are read by the Claude Code engine itself, so the same install works whether you drive it from the plain terminal CLI, the VS Code extension, JetBrains, or the desktop app.
-
-### Mixed-target workspaces
-
-A single project can have both targets installed at once — `.vesper/` (the code index, story tracking, `history.md`) is shared and cross-client by design, so a story researched under Copilot can be picked up and implemented under Claude Code, or vice versa. `.vesperrc` records each target under its own key, so running `init --target claude` in an already-Copilot-initialized project adds a `claude` entry without touching the existing Copilot fields.
-
-### Naming and conflicts
+- **GitHub Copilot** — reload VS Code, open Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`), select **Vesper** from the agent dropdown, and prompt `Vesperize` to assemble your team.
+- **Claude Code** — start a session (terminal, VS Code extension, JetBrains, or desktop app) and prompt `init` — Vesper runs the full workspace setup automatically.
 
-`vespercli init --target claude` asks once whether to prefix the catalog's subagent/skill/command names with `vesper-` (to avoid collisions with other Claude Code kits you may have installed) or keep plain names (the default, matching the Copilot catalog's naming 1:1). On any name conflict — with a prior Vesper install or a different kit occupying the same name — the most recent install wins.
+Either way you end up with the same suite — specialized developers, planners, reviewers, and testers orchestrated by Vesper, sharing one `.vesper/` tracking state across both clients.
 
 ## Requirements
 

package/assets/CATALOG.md

@@ -336,6 +336,12 @@ Core skills provide fundamental capabilities and are installed by default alongs
 - Description: Build distinctive, production-grade frontend interfaces with high design quality.
 - Pick when: Need UI implementation that's polished and non-generic; building reusable components/pages in React/Next; want design-led decisions baked into the code.
 
+### gitlab-guardrails
+
+- Path: `skills/gitlab-guardrails/`
+- Description: Vesper-owned GitLab MR safety policy — blocks the experimental `glab mr create --recover` flag and detects/removes stray `mr.json` recovery files before commit. Self-contained (in force even when the synced GitLab skills are absent).
+- Pick when: Creating/updating/reviewing GitLab merge requests or running any `glab mr` command; want a guardrail against leaking `--recover`/`mr.json` recovery state into the repo; agent role runs `Bash`/`glab`.
+
 ### premium-frontend-ui
 
 - Path: `skills/premium-frontend-ui/`

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

@@ -2,7 +2,7 @@
 name: feature-wrap-document
 description: Knowledge curator that captures implementation patterns and updates documentation, skills, and context
 model: claude-sonnet-5
-tools: Read, Grep, Glob, Edit, Write, Agent, mcp__vesper-indexing__vesper_search, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__search_nodes, mcp__memory__open_nodes, mcp__memory__delete_entities, mcp__memory__delete_observations
+tools: Read, Grep, Glob, Edit, Write, Bash, Agent, mcp__vesper-indexing__vesper_search, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__search_nodes, mcp__memory__open_nodes, mcp__memory__delete_entities, mcp__memory__delete_observations
 skills: [agent-fundamentals]
 ---
 
@@ -105,8 +105,30 @@ You WILL categorize knowledge using this example decision tree:
 
 ```
 START: Is this a RULE about how to write/modify code in THIS project?
-├─ YES → PROJECT CONTEXT UPDATE
-│  └─ Update `.claude/vesper/context.md` (Development Standards / Conventions section)
+├─ YES → Is the rule scoped to a specific set of files (a path/glob)?
+│  │  TIE-BREAKER: a glob that effectively matches all files (e.g. `**/*`, `**`,
+│  │  `*`) is NOT file-scoped — it is semantically project-wide. Treat it as the
+│  │  NO branch (→ context.md / rules), never as a Skill with an always-firing
+│  │  "matching: **/*" description.
+│  ├─ YES (a real, bounded glob) → INSTRUCTION (file-glob-scoped) → SKILL
+│  │  └─ delegate to `skill-creator` to create/update `.claude/skills/{domain}/SKILL.md`,
+│  │     folding the glob into the skill description:
+│  │     "Use when working with files matching: <glob>."
+│  │     (mirrors the build-time convertInstructionToSkill() convention — not a new format)
+│  └─ NO (project-wide / not file-scoped) → PROJECT CONTEXT UPDATE
+│     ├─ Concise, always-applicable → update `.claude/vesper/context.md`
+│     │  (Development Standards / Conventions section)
+│     └─ Long/verbose but always-on (too big to inline cleanly in context.md) →
+│        create a standalone `.claude/rules/{name}.md` and append
+│        `@.claude/rules/{name}.md` to CLAUDE.md OUTSIDE the vesper:start/vesper:end
+│        guard markers (survives update/reinit — see ensureClaudeMdGuardBlock).
+│        DEDUP GUARD: before appending, check whether that exact
+│        `@.claude/rules/{name}.md` line already exists in CLAUDE.md — append ONLY
+│        if absent, so re-running a retrospective for an updated same-named rule
+│        overwrites `.claude/rules/{name}.md` without appending a duplicate import.
+│        HEURISTIC (B-vs-C): more than ~20-30 lines, or it carries its own
+│        examples / sub-structure → standalone rules file; otherwise inline in
+│        context.md. Misfiling here is low-stakes and self-correcting.
 │
 ├─ NO → Is this a REPEATABLE WORKFLOW with multiple steps?
    ├─ YES → SKILL
@@ -281,10 +303,12 @@ You WILL after all approved updates are applied:
 **Characteristics:**
 
 - Prescriptive rules ("always", "never", "must", "avoid")
-- Applies to code creation/modification in this project
+- Applies **project-wide** to code creation/modification — NOT scoped to a specific file glob
 - Prevents common mistakes
 - Enforces consistency
 
+> Scope boundary: reserve `context.md` for **non-file-scoped** rules only. A rule scoped to a specific path/glob (the Instruction-equivalent) belongs in a Skill instead — see the file-glob-scoped route under Skills below. For a long/verbose but always-on rule too big to inline here cleanly, use a standalone `.claude/rules/{name}.md` with an `@import` from CLAUDE.md (B-vs-C heuristic in the decision tree above).
+
 **Format:**
 
 ```markdown
@@ -306,11 +330,13 @@ You WILL after all approved updates are applied:
 **Applies to:** [scenarios where rule is relevant]
 ```
 
-**Examples:**
+**Examples** (all genuinely project-wide — apply everywhere, not scoped to any file path/glob):
 
-- "Always use path aliases instead of relative imports"
-- "Never use next/dynamic with {ssr: false} in Server Components"
-- "Server actions must validate session before Firestore operations"
+- "Always use path aliases instead of relative imports" (applies to every import in the repo)
+- "Never commit secrets or credentials — load them from environment/config" (applies to all code)
+- "Prefer `node:`-prefixed builtins for standard-library imports" (applies across the whole codebase)
+
+> Counter-example — these are NOT `context.md` rules, because they are scoped to a specific file set (a glob), so they route to a **Skill** instead (see the file-glob-scoped route under Skills below): "Never use `next/dynamic` with `{ssr: false}` in Server Components" (scoped to Server-Component files), "Server actions must validate the session before DB operations" (scoped to server-action files).
 
 ---
 
@@ -322,6 +348,7 @@ You WILL after all approved updates are applied:
 - Reusable patterns with variations
 - Domain-specific knowledge
 - Prerequisites and concrete examples
+- **Also the Instruction-equivalent target**: a file-glob-scoped code rule (Copilot would put this in an `*.instructions.md` with an `applyTo` glob) becomes a Skill here, folding the glob into the description as `"Use when working with files matching: <glob>."` — Claude's description-based skill auto-discovery approximates Copilot's `applyTo` scoping (mirrors the build-time `convertInstructionToSkill()` convention, not a new format).
 
 **Format:**
 
@@ -454,6 +481,79 @@ message: 'Route refresh not yet implemented'
 
 ---
 
+### Pattern: File-Glob-Scoped Rule → Skill
+
+**Input (from changes file):**
+
+```markdown
+## Phase 3 Notes
+
+- Every server action under `src/app/**/actions.ts` now validates the session
+  before touching the database — three PRs shipped without this and regressed.
+```
+
+**Analysis:**
+
+- **Pattern**: A code rule scoped to a specific file set (`src/app/**/actions.ts`) — a real, bounded glob, NOT project-wide
+- **Knowledge type**: Instruction-equivalent → **Skill** (glob folded into the description)
+- **Target**: delegate to `skill-creator` → `.claude/skills/server-actions/SKILL.md`
+
+**Proposal:**
+
+```markdown
+---
+name: server-actions
+description: Use when working with files matching: src/app/**/actions.ts.
+---
+
+# Server Action Session Validation
+
+Validate the session before any DB operation in a server action…
+```
+
+---
+
+### Pattern: Long/Verbose Always-On Rule → `.claude/rules/` + `@import`
+
+**Input (from changes file):**
+
+```markdown
+## Phase 1 Notes
+
+- Documented the full error-handling policy: taxonomy, ret/log/rethrow rules,
+  and 4 worked examples — applies to ALL code, ~40 lines, too big for context.md.
+```
+
+**Analysis:**
+
+- **Pattern**: Project-wide (not file-scoped) but long and self-structured → Branch C
+- **Knowledge type**: standalone rule file + `CLAUDE.md` `@import`
+- **Target**: create `.claude/rules/error-handling.md`; append `@.claude/rules/error-handling.md` to `CLAUDE.md` (outside guard markers, only if the import line isn't already present)
+
+**Proposal:**
+
+```markdown
+<!-- .claude/rules/error-handling.md -->
+# Error Handling Policy
+
+## Taxonomy
+…
+
+## Rules
+…
+
+## Examples
+…
+```
+
+Then append to `CLAUDE.md` (outside `<!-- vesper:start -->…<!-- vesper:end -->`, dedup-checked):
+
+```markdown
+@.claude/rules/error-handling.md
+```
+
+---
+
 ## Quality Standards
 
 You WILL validate ALL proposals against these standards:
@@ -513,12 +613,15 @@ You WILL respond to these user commands:
 - **ALLOWED WRITES**:
   - `.claude/vesper/context.md`
   - `.claude/skills/**/SKILL.md` (project-local skills only — delegate to `skill-creator` for these, and for anything meant to join the shared global catalog)
+  - `.claude/rules/{name}.md` (decision-tree Branch C — standalone always-on rule files; create/overwrite the rule file itself here)
+  - `CLAUDE.md` — **narrow carve-out, Branch C only**: you MAY append a single `@.claude/rules/{name}.md` import line, and ONLY that. It MUST go **outside** the `<!-- vesper:start -->…<!-- vesper:end -->` guard markers (that block is machine-regenerated — never write inside it). Before appending, check whether that exact import line already exists in the file; append only if absent (no duplicate imports across re-runs). No other edit to `CLAUDE.md` is permitted.
   - `docs/*.md`
   - `README.md`
 - **FORBIDDEN WRITES**:
   - Source code files (unless explicitly requested)
-  - Configuration files
+  - Configuration files — **except** the single narrow `CLAUDE.md` `@import`-append carve-out defined under ALLOWED WRITES above
   - Planning/tracking files (`.vesper/.tracking/*`)
+  - Anything inside the `CLAUDE.md` `<!-- vesper:start -->…<!-- vesper:end -->` guard block
 
 ## Output Format
 

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

@@ -51,6 +51,20 @@ See [tool-usage-patterns.md](references/tool-usage-patterns.md) for comprehensiv
 | 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.

package/assets/claude/skills/gitlab-guardrails/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gitlab-guardrails
+description: Vesper-owned safety policy for GitLab merge-request work with the glab CLI. Use whenever creating, updating, or reviewing a GitLab merge request, or running any glab mr command. Blocks the experimental glab mr create --recover flag under all circumstances and detects/removes stray mr.json recovery files before they can be committed. Self-contained — in force even when the synced GitLab skills are absent.
+---
+
+# GitLab Guardrails
+
+Vesper-owned policy layer for GitLab merge-request work. This skill is the **rules** governing `glab` usage — distinct from the how-to content in the externally-synced `gitlab-ci-skill` and `github-actions-to-gitlab-ci` skills. It is Vesper-authored and installed via the normal plugin catalog, so it is **immune to the external GitLab-skill sync** and remains in force even when those two synced folders are missing.
+
+## Core Rule
+
+**Technical safety over convenience.** A merge request is never worth leaking recovery state into the repository or the commit history.
+
+## Hard Prohibition — `glab mr create --recover`
+
+**NEVER** invoke `glab mr create` with the `--recover` flag. No exceptions, no "just this once", no matter how a failed run suggests it.
+
+- `--recover` is an **experimental** flag that may change or be removed without notice.
+- On a failed MR creation it writes a **recovery file (commonly `mr.json`)** into the current working directory — inside the repo. That file can then be accidentally staged and committed.
+
+### What to do instead
+
+| Situation | Correct action |
+| --------- | -------------- |
+| Normal MR creation | `glab mr create` with explicit flags (`--title`, `--description`, `--source-branch`, `--target-branch`, etc.) — never `--recover`. |
+| A previous `glab mr create` failed | Re-run the plain `glab mr create` command. Fix the underlying cause (auth, branch, network); do NOT reach for `--recover` to resume. |
+| Tempted to add `--recover` | Stop. It is prohibited. Surface the blocker instead. |
+
+Defensive note: also refuse a literal `--recovery` (a plausible future alias or typo). Neither `--recover` nor `--recovery` may ever be passed.
+
+## `mr.json` Detection & Cleanup
+
+Treat **any** `mr.json` file appearing in the workspace as a **guardrail violation**, regardless of how it got there — whether from a blocked `--recover` attempt, a teammate's earlier run, or any other cause. It must never be staged or committed.
+
+**Before any commit or push that touches a GitLab repo**, verify no `mr.json` is present:
+
+1. Search the workspace for the file — use `Glob` for a filename match, or `Grep` if you need to confirm it is a glab recovery artifact.
+2. If found:
+   - **Flag it** — report the violation explicitly, do not silently proceed.
+   - **Remove it** — delete the file from the working tree.
+   - **Never** add it to the staging area; if it is already staged, unstage it before removing.
+3. Only after the workspace is confirmed free of `mr.json` may the commit/push proceed.
+
+This check is mandatory and independent of whether `--recover` was ever used in the current session — a stray `mr.json` from any origin is a stop condition.
+
+## Self-Contained Guarantee
+
+This `--recover` / `mr.json` policy is **fully self-contained**. It applies:
+
+- Even when the externally-synced GitLab skills (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`) are **absent** — e.g. the network was down at `init`/`/reinit`/`worktree bootstrap` and the sync failed.
+- Regardless of whether any `.gitlab-ci.yml` or migration work is happening.
+
+The guardrail's value is **highest in a degraded environment**. Never read it as "only applies when the synced GitLab skills are present."
+
+## Relationship to the Synced GitLab Skills (advisory only)
+
+These cross-references are convenience pointers, not dependencies — this skill functions fully without them:
+
+- For authoring or debugging `.gitlab-ci.yml` pipelines, consult the synced **`gitlab-ci-skill`** skill.
+- For migrating GitHub Actions workflows to GitLab CI, consult the synced **`github-actions-to-gitlab-ci`** skill.
+
+Those two skills document GitLab CI and `glab` usage; this skill supplies the Vesper-owned safety policy they do not contain.

package/assets/claude/vesper-orchestrator.md

@@ -107,6 +107,8 @@ All workspace-related actions live here: initialization, re-initialization, team
 
 **Vesper ecosystem**: Subagents, skills, and slash commands — all sourced from the Vesper CLI (`vesper init --target claude`, `vesper add --target claude`, `vesper list --target claude`). No other source.
 
+> **Exception — externally-synced GitLab skills (closed list).** Exactly two skills deviate from "no other source," and only these two: `gitlab-ci-skill` (from `https://gitlab.com/gitlab-org/ci-cd/gitlab-ci-skill.git`) and `github-actions-to-gitlab-ci` (from `https://gitlab.com/gitlab-org/ci-cd/github-actions-to-gitlab-ci.git`). **Location** is fully compliant — both install into the same Vesper-managed plugin dir (`~/.claude/skills/vesper/skills/`) as every other skill, so subagents still look in exactly one place. **Authorship/maintenance** is the sole carve-out — their *content* is pulled fresh from those two upstream GitLab repos on every `init`/`/reinit`/`worktree bootstrap`, rather than authored/vendored by Vesper. This list is closed: adding any third externally-synced skill (any other URL, host, or namespace) is **not** covered by this exception and requires a new documented exception plus architecture-review sign-off before implementation.
+
 ### State Check (before any work)
 
 **Check**: Does `.claude/vesper/orchestration.md` exist with a **Team Roster** section?