@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/claude/skills/vesper-orchestration/references/implement-pipeline.md

@@ -0,0 +1,337 @@
+# Implementation Pipeline (Steps 4-11)
+
+Detailed orchestration for the Implementation purpose pipeline Steps 4-11. Which of these steps run
+is decided by the **scope tier** the orchestrator chose — the tier table in the playbook (section
+*2. Implementation* → *Scope tiers*) is the single definition; this file describes the steps and
+never restates the tiers.
+
+**Step mapping** (pipeline step → action → tiers that run it):
+
+| Step | Action                          | Tiers                                              |
+| :--- | :------------------------------ | :------------------------------------------------- |
+| 4    | Validate Planning Files         | L                                                  |
+| 5    | Execute Implementation          | S, M, L                                            |
+| 6    | Code Review + Fix Loop          | M (`code-reviewer`), L (+ `principal-software-engineer`) |
+| 7    | Gate (`vespercli gate`)         | S, M, L — the orchestrator's own CLI call          |
+| 8    | Unit Testing                    | L                                                  |
+| 9    | Documentation Wrap-Up           | M, L — only when the public surface changed        |
+| 10   | Feature Wrap                    | L; M only on `New pattern learned: yes`            |
+| 11   | Update Task Board + Move Story  | M, L when the task came from a story               |
+
+Steps 1-3 (Research, Plan, Architect Validation) are covered by `research-plan-pipeline.md`.
+Step 12 (Log completion) is the orchestrator's own CLI call — `vespercli log completed --pipeline
+implementation --slug [slug] --status DONE --author "<you>"` — mirroring the `vespercli log started …`
+it ran beside the tier's first step. The CLI is the run ledger's writer of record; logging is never
+delegated. Step 12 runs only after `GATE PASS` (or a gate exit `2`, reported to the user once).
+
+**S tier**: no planning files exist. The orchestrator delegates Step 5 with the playbook's S
+prompt (the user's request is the spec), runs Step 7 itself, then Step 12. Steps 4, 6, 8-11 do not
+run — no LLM review, no docs, no retrospective.
+
+## Prerequisites
+
+- ✅ Tier decided (S / M / L) and its step budget written into the orchestrator's todo list
+- ✅ M/L: Research & Plan phase complete (plan, details, prompts exist)
+- Developer resolved from the Team Roster
+
+## Orchestration Steps
+
+### STEP 4: Validate Planning Files (L only — BLOCKING)
+
+Search for the required files from the Plan phase:
+
+- [ ] `.vesper/.tracking/prompts/implement-*.prompt.md`
+- [ ] `.vesper/.tracking/plans/YYYYMMDD-*-plan.md`
+- [ ] `.vesper/.tracking/details/YYYYMMDD-*-details.md`
+- [ ] `.vesper/.tracking/research/YYYYMMDD-*-research.md`
+
+**Ledger context**: `vespercli log tail --slug [slug]` — the `note`/`returned` rows from the
+planning phase say how far it got; the plan file holds the decisions. Memory holds domain
+knowledge (`search_nodes("<task domain>")`), never pipeline state.
+
+**IF ANY FILE MISSING:**
+
+- STOP and report: "Planning incomplete. Cannot proceed. Missing: [list]"
+- Suggest: "Run Research & Plan phase first"
+- DO NOT PROCEED
+
+**M tier**: the Planner produced the same files, but the orchestrator does not run this check —
+it delegates Step 5 with the plan and prompt paths directly.
+
+### STEP 5: Execute Implementation (⚡ PARALLEL BY TRACK on L)
+
+The plan may contain multiple independent implementation tracks (e.g., backend API + frontend UI +
+database migration). Each track has its own prompt file. (An M plan has one track by definition —
+one surface.)
+
+1. List all prompt files: `.vesper/.tracking/prompts/implement-*.prompt.md`
+2. For EACH prompt file, resolve the matching Developer from the Team Roster (the prompt specifies
+   the surface/stack — match to the best agent)
+3. Delegate ALL independent tracks in parallel — one subagent per track, one `Agent` call each,
+   issued in the same message
+4. Each developer tracks changes in their own file:
+   `.vesper/.tracking/changes/YYYYMMDD-[slug]-[track]-changes.md`
+
+Delegate to each Developer:
+
+```
+"Execute implementation using the prepared prompt.
+
+Nesting depth: 1
+Tier: [M|L]
+Implementation Prompt: .vesper/.tracking/prompts/implement-[slug]-[track].prompt.md
+
+The prompt contains:
+- References to plan, details, and research files
+- Step-by-step instructions for this track
+- Success criteria
+
+Memory: search_nodes('<task domain>') for relevant learnings before starting (the plan/details files carry the task context).
+
+Follow the implementation prompt exactly. Stay inside the plan's file list — the gate checks plan
+conformance on L and fails on an unplanned file.
+Track changes in: .vesper/.tracking/changes/YYYYMMDD-[slug]-[track]-changes.md
+Before returning, run `vespercli gate` yourself and fix whatever it reports.
+
+Apply your assigned skills: [from the roster's Assigned Skills column, plus task-implementation]"
+```
+
+**Single track**: If only one prompt file exists, this is a standard single-developer delegation.
+
+**WAIT** for ALL tracks to complete before proceeding to review.
+
+If any track returns `NEED_HELP` or `BLOCKED` → handle that track without blocking other running tracks.
+A `NEED_HELP` that says the scope is bigger than the tier (more files, another surface, a design
+decision) is a **tier raise**: the orchestrator restarts at the higher tier's first step with the
+higher tier's budget. A tier is raised, never lowered.
+
+**Gate re-entry**: when Step 7 returns `GATE FAIL: <reasons>`, the orchestrator re-enters this
+step with the same Developer and the headline as the **only** context:
+
+```
+"gate failed: <reasons>.
+
+Nesting depth: 1
+Run `vespercli gate` yourself to see the details, fix them, re-run it until it passes, then return.
+Track changes in: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md"
+```
+
+The orchestrator never reads the gate's check output, logs or code — the Developer does.
+
+### STEP 6: Code Review (M: one reviewer; L: ⚡ both in parallel)
+
+After implementation, call the tier's reviewer(s):
+
+**Every tier that reviews (M and L) — delegate to `vesper:code-reviewer`:**
+
+```
+"Review changes for [task].
+
+Nesting depth: 1
+Tier: [M|L]
+Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.md
+
+Focus: Code quality, standards compliance, maintainability, test coverage.
+Approve or request specific changes.
+End with your pipeline trailer — `Public surface changed: yes|no` and `New pattern learned: yes|no`
+directly above the Status line; they decide whether the docs and feature-wrap steps run."
+```
+
+**L only — additionally delegate to `vesper:principal-software-engineer`, in the same message:**
+
+```
+"Review changes for [task].
+
+Nesting depth: 1
+Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.md
+
+Focus: Architecture alignment, security, performance, scalability, design patterns.
+Approve or request specific changes."
+```
+
+Consolidate the feedback (on L, from both reviewers).
+
+**IF any reviewer has feedback:**
+
+1. Delegate to the Developer to fix all issues
+2. Re-review with the same reviewer(s) (parallel on L)
+3. Repeat until every reviewer approves. **3** consecutive failed loops → the orchestrator stops and
+   asks the user (continue / change approach / stop); **10** is the hard cap after which unresolved
+   issues go to `.vesper/.tracking/issues/` and the pipeline continues — both rules live in the
+   playbook's *Escalation and budgets*.
+
+The orchestrator keeps the reviewer's two trailer answers for Steps 9 and 10 — it reads them from
+the trailer, never from the review body.
+
+### STEP 7: Gate — `vespercli gate` (orchestrator's own CLI call, every tier)
+
+Not a delegation. After the review fix loop has ended (M/L) or straight after Step 5 (S), the
+orchestrator runs:
+
+- **L**: `vespercli gate --plan .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.md` (plan conformance on)
+- **S, M**: `vespercli gate`
+
+and reads exactly two things — the exit code and the headline (the last line):
+
+| Exit | Headline               | Orchestrator action                                                                                          |
+| :--- | :--------------------- | :----------------------------------------------------------------------------------------------------------- |
+| `0`  | `GATE PASS`            | Continue. Required before Steps 9, 10 and 12                                                                 |
+| `1`  | `GATE FAIL: <reasons>` | Re-enter STEP 5 with the gate re-entry prompt above (headline only), then STEP 6 if code changed, then re-run the gate. One **gate loop** per re-entry — same 3 / 10 escalation as the review loop |
+| `2`  | none                   | No `.vesper/gates.json` (or unreadable). Tell the user once — `vespercli init` seeds it — and continue without the gate. Never block |
+
+After a re-entry that passes: `vespercli log note --pipeline implementation --slug [slug] --step 7
+--note "GATE PASS after <n> loops"` — the resumption point.
+
+### STEP 8: Unit Testing (L only)
+
+Delegate to the **Tester from roster** → fallback Developer:
+
+```
+"Write unit tests for implemented code.
+
+Nesting depth: 1
+Scope: Unit tests ONLY (integration/E2E tests are handled in the Testing purpose)
+
+Requirements:
+- Cover all acceptance criteria from the plan
+- Include edge cases identified in research
+- Test individual functions/components in isolation
+
+Track in: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md"
+```
+
+**WAIT** for unit tests to pass. If tests fail and require code changes, loop with the Developer
+until green (subject to the global loop limit in the orchestrator playbook). M has no unit-test
+step of its own — the gate already runs the project's test command.
+
+### STEP 9: Documentation Wrap-Up (conditional — public surface changed)
+
+Runs only when the plan or a reviewer's trailer says `Public surface changed: yes` (a CLI flag or
+command, an exported API, a config-file format, user-facing text). Otherwise mark the todo
+"Docs: skipped — no public-surface change" and move on; skipping is correct, not a shortcut.
+
+Delegate to `vesper:se-technical-writer`:
+
+```
+"Update documentation for completed implementation.
+
+Nesting depth: 1
+
+Review:
+- Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
+
+Public surface that changed: [from the plan / the reviewer's trailer]
+Update: README, API docs, inline comments as needed.
+Capture learnings for future reference."
+```
+
+### STEP 10: Feature Wrap (L always; M only on `New pattern learned: yes`)
+
+Never on S. On M, run it only when the reviewer's trailer said `New pattern learned: yes`;
+otherwise mark the todo "Feature wrap: skipped — no new pattern".
+
+**Delegate to `vesper:feature-wrap-document`:**
+
+```
+"Analyze completed implementation for knowledge capture.
+
+Nesting depth: 1
+Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+
+Identify:
+- Patterns worth documenting
+- Rule/instruction updates needed
+- Skill opportunities
+- Newly discovered best practices, pitfalls, or workspace-specific insights
+
+Memory: Use the MCP memory server's tools to create learning, workspace_pattern, and agent_insight entities.
+Apply your assigned skill mcp-memory for entity schema and hygiene rules.
+Append the one-line decision to .claude/vesper/context/recent-decisions.md (ring buffer, N=10).
+
+Present numbered proposals. Vesper will approve."
+```
+
+**Orchestrator approval:**
+
+- Review the agent's proposals
+- Approve ONLY what is truly reusable and necessary
+- Skip one-off solutions or obvious patterns
+- Criteria: "Would this help future tasks significantly?"
+
+The memory capture in this step is the whole of the post-implementation knowledge update — there is
+no separate follow-up memory pass.
+
+### STEP 11: Update Task Board & Move Story
+
+**When the task came from a story** (regardless of Task Management): move the story file from
+`inprogress/` to `inreview/` with `vespercli story move [slug] inreview`. Skip when there is no story.
+
+**Additionally, if Task Management is configured AND a task reference exists**:
+
+Delegate to the Task Agent (from the Team Roster):
+
+```
+"Update task [task-id] status to IN REVIEW.
+Add comment: Implementation complete. Changes tracked in .vesper/.tracking/changes/"
+```
+
+**WAIT** for confirmation before proceeding to Step 12 (Log completion).
+
+## Output
+
+- Code changes implemented
+- `.vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md` (complete log)
+- `GATE PASS` (or exit `2`, reported once)
+- L: unit tests written and passing
+- Documentation updated when the public surface changed
+- Story file moved to `inreview/` (when the task came from a story)
+- Task status: IN REVIEW (if Task Management is configured)
+
+## Next
+
+→ After Step 12 (Log completion) of an **L** pipeline, **E2E/integration testing** auto-triggers via
+the Testing purpose (Mode A: Post-Implementation). After S or M it runs only when the user asks.
+See `qa-e2e-pipeline.md`.
+
+---
+
+## Bug Fix Review Focus (when Purpose = bug fix)
+
+When delegating to reviewers in STEP 6 for a bug fix, add to the delegate prompt:
+
+```
+"Additional review focus for bug fix:
+- Fix addresses root cause (not just symptoms)
+- Regression test covers the exact scenario
+- No unintended side effects introduced
+- Is the fix minimal and scoped correctly?"
+```
+
+Bug fixes often reveal patterns worth documenting — a reviewer that finds one says
+`New pattern learned: yes`, which is what makes STEP 10 run on an M-tier fix; ensure Feature Wrap
+then captures root cause categories, testing gaps, or common pitfalls.
+
+---
+
+## Skill Creation (when task = skill creation)
+
+When the task is creating a skill, STEP 5 delegates to `vesper:skill-creator` instead of the
+Developer from the roster:
+
+```
+"Create skill for [topic/technology].
+
+Nesting depth: 1
+Research: .vesper/.tracking/research/YYYYMMDD-skill-research.md
+Plan: .vesper/.tracking/plans/YYYYMMDD-skill-plan.md
+
+Apply your assigned skills: skill-creator, mcp-builder, docs-seeker"
+```
+
+If the Knowledge Codifier returns `Status: NEED_HELP` asking about workspace patterns:
+
+1. Delegate to `vesper:workspace-learner` to answer the specific question (do NOT re-scan the codebase)
+2. Return the answer to `vesper:skill-creator` in a follow-up call

package/assets/claude/skills/vesper-orchestration/references/multi-task-dispatch.md

@@ -0,0 +1,13 @@
+<!-- markdownlint-disable-file -->
+# Multi-Task Dispatch (⚡ Parallel Pipelines)
+
+On-demand detail for the playbook's "Multi-Task Dispatch" pointer (`### 2. Implementation`). The two rules that must hold are restated in the playbook; the phases and the todo structure live here.
+
+Several tasks at once (a backlog batch, a list from the user, PM-queued stories): decide a **tier per task** first. Each task then runs its own tier's steps as an independent pipeline keyed by `[slug]` — `YYYYMMDD-[slug]-research.md`, …; every delegation prompt carries `"Task slug: [slug]"` and `"Tier: [S|M|L]"`.
+
+- **Phase 1 — Research & Plan (M and L tasks only; per-task waterfall, parallel across tasks)**: one Researcher `Agent` call per M/L task in parallel; each Planner call as its research completes; on L each Architect validation as its plan completes, then the planning-file check. S tasks have no Phase 1 and go straight to Phase 3.
+- **Phase 2 — Cross-task dependency check (only when ≥ 2 tasks are M or L)**: after all M/L plans are approved, delegate every plan path to `se-system-architecture-reviewer` for overlapping files/modules, conflicting changes and execution order; it returns the groups safe to implement in parallel and those that must be sequential. With at most one M/L task there is nothing to cross-check — skip Phase 2. Two S tasks that name the same file run one after the other (a file-name match is routing, not analysis).
+- **Phase 3 — Implementation (dependency-aware)**: no conflicts → each task's remaining steps (5 onward) in parallel, every task with its own gate, budget and bookkeeping; conflicts → conflicting tasks sequential, the rest parallel.
+
+**Todo list structure**: one top-level todo per task carrying its tier, the tier's steps beneath — `[Task A · L] Research`, `[Task B · M] Plan`, `[Task C · S] Implement`, … **Single task**: skip this section — the tier table applies.
+

package/assets/claude/skills/vesper-orchestration/references/qa-e2e-pipeline.md

@@ -0,0 +1,160 @@
+# QA / E2E Testing Pipeline
+
+Detailed orchestration steps for the Testing purpose.
+
+## Mode A: Post-Implementation (auto-triggered after an **L-tier** Implementation pipeline completes — Step 12)
+
+Uses existing materials from the completed Implementation pipeline — no research or planning needed.
+Mode A auto-triggers **only after an L pipeline** (playbook tier table). After an S or M pipeline
+it runs only when the user asks for E2E/integration tests on that change — then it uses the same
+steps below, with the `changes/` file as its input (an S change has no `details/` file).
+
+### Prerequisites
+
+- ✅ Implementation complete
+- ✅ Changes file exists: `.vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md`
+- ✅ Details file exists: `.vesper/.tracking/details/YYYYMMDD-[slug]-details.md`
+
+### STEP 1: Run E2E/Integration Tests
+
+Delegate to the **Tester from roster**:
+
+```
+"Execute E2E and integration tests for [task/feature].
+
+Nesting depth: 1
+
+Scope:
+- Integration tests for API changes
+- E2E tests for user flows
+- Cross-browser testing (if applicable)
+
+Reference:
+- Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
+
+Report results and any failures."
+```
+
+### STEP 2: Log Issues (if tests fail)
+
+**IF tests fail:**
+
+Delegate to the Tester:
+
+```
+"Log test failures to the issues file.
+
+Nesting depth: 1
+Create/update: .vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md
+
+For each failure include:
+- Test name and file
+- Expected vs actual behavior
+- Steps to reproduce
+- Error logs/screenshots
+- Severity (critical/high/medium/low)
+
+Format as actionable bug reports."
+```
+
+### STEP 3: Fix Issues
+
+**IF issues logged:**
+
+Delegate to the **Developer from roster**:
+
+```
+"Fix issues identified in QA testing.
+
+Nesting depth: 1
+Issues: .vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md
+
+For each issue:
+- Implement fix
+- Add/update a unit test to cover the case
+- Update the changes file
+
+Track in: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md"
+```
+
+### STEP 4: Re-run Tests
+
+After fixes are applied:
+
+1. Return to STEP 1
+2. Repeat until all tests pass (subject to the global loop limit in the orchestrator playbook)
+
+### STEP 5: Review Test Quality
+
+Delegate to `vesper:code-reviewer`:
+
+```
+"Review test quality for [task].
+
+Nesting depth: 1
+Test files: [paths from the Tester's output]
+Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
+
+Check: coverage, edge cases, maintainability, no flaky tests."
+```
+
+### STEP 6: Update Status (when all tests pass)
+
+Delegate to the **Task Agent** (from the Team Roster, if Task Management is configured):
+
+```
+"Update task [task-id] status to DONE.
+Add comment: QA complete. All E2E/integration tests passing."
+```
+
+---
+
+## Mode B: Standalone (user explicitly requests tests)
+
+Full pipeline — same rigor as Implementation.
+
+### Steps
+
+| Step | Action                                                      | Agent                                                                |
+| :--- | :---------------------------------------------------------- | :-------------------------------------------------------------------- |
+| 1    | Research (understand system, existing tests, coverage gaps) | Researcher/Analyzer from roster → fallback `vesper:task-researcher`   |
+| 2    | Plan (test strategy, cases, scope)                          | Planner from roster → fallback `vesper:code-planner`                  |
+| 3    | Write + run tests                                           | Tester from roster                                                    |
+| 4    | Fix failures (if any)                                       | Developer from roster                                                 |
+| 5    | Re-run tests                                                | Tester from roster                                                    |
+| 6    | Review test quality                                         | `vesper:code-reviewer`                                                |
+| 7    | Feature wrap                                                | `vesper:feature-wrap-document`                                        |
+| 8    | Log completion                                              | Vesper — `vespercli log completed --pipeline testing --slug [slug] --status DONE` |
+
+**Loop**: Steps 3-5 repeat until tests pass (subject to the global loop limit in the orchestrator
+playbook). Issues are logged in `issues/`.
+
+---
+
+## Output
+
+- E2E/Integration tests passing
+- `.vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md` (resolved issues log)
+- Additional unit tests for edge cases found
+- Task status: DONE
+
+## Issue File Format
+
+```markdown
+# QA Issues: [Task Name]
+
+## Issue 1: [Test Name]
+
+- **Severity**: critical/high/medium/low
+- **Test File**: path/to/test.spec.ts
+- **Expected**: What should happen
+- **Actual**: What actually happened
+- **Steps to Reproduce**:
+  1. Step 1
+  2. Step 2
+- **Error Log**: [stack trace or error message]
+- **Status**: OPEN / FIXED / VERIFIED
+
+## Issue 2: ...
+```

package/assets/claude/skills/vesper-orchestration/references/reinit-pipeline.md

@@ -0,0 +1,98 @@
+# Re-initialization Pipeline
+
+Triggered when the user explicitly asks to re-initialize (e.g. "re-vesperize", "re-initialize",
+"refresh workspace setup"), or runs `/reinit`.
+
+The committed `/reinit` maintenance skill is the **user-facing entry point** and states the intent;
+this reference carries the **step detail** for actually running it.
+
+## Prerequisites
+
+- ✅ `.claude/rules/vesper-orchestration.md` with a Team Roster already exists
+- This is NOT a first-time setup — this is a refresh of an existing workspace
+
+## Orchestration Steps
+
+| Step | Action                                                                                                                                                                          | Agent                                |
+| :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------- |
+| 1    | Force a full re-scan of the codebase. Do NOT skip with "already current" — treat as fresh analysis. Compare with the existing whitepaper and produce a diff summary of what changed. | `vesper:workspace-learner`           |
+| 2    | Review Team Roster changes: validate that the agent composition still fits the project's current needs. Approve or recommend additions/removals.                                 | `vesper:se-system-architecture-reviewer` |
+| 3    | Present the diff summary + roster recommendations to the user for confirmation.                                                                                                 | Vesper (via `AskUserQuestion`)       |
+| 4    | Apply confirmed changes to `.claude/rules/vesper-context.md` and `.claude/rules/vesper-orchestration.md`.                                                                        | `vesper:workspace-learner`           |
+| 5    | Scoped memory update (see Memory Protocol below).                                                                                                                               | `vesper:feature-wrap-document`       |
+| 6    | Run `vespercli log note --pipeline workspace --note "Workspace re-initialized" --author "<you>"`                                                                              | Vesper (bookkeeping CLI)             |
+
+### Step 1 — Force Re-scan
+
+Delegate to `vesper:workspace-learner`:
+
+```
+"Force a full workspace re-scan. This is a RE-INITIALIZATION — do NOT skip with 'already current'.
+Treat this as a fresh analysis. Compare results with the existing .claude/rules/vesper-context.md.
+Produce a diff summary: what changed, what's new, what was removed.
+Save the updated whitepaper and return the diff summary in your response.
+
+Nesting depth: 1
+
+If root CLAUDE.md exists during your conventions scan, skip its guarded
+<!-- vesper:start -->...<!-- vesper:end --> import block — it's machine-generated, not a project convention."
+```
+
+### Step 2 — Architect Roster Review
+
+Delegate to `vesper:se-system-architecture-reviewer` with the current Team Roster included in the prompt:
+
+```
+"Review the current Team Roster against the updated project whitepaper.
+
+Nesting depth: 1
+
+Current Team Roster:
+[Vesper: paste the Team Roster table from .claude/rules/vesper-orchestration.md here]
+
+Evaluate:
+- Are all current agents still needed?
+- Are there gaps — new capabilities needed that no current agent covers?
+- Should any agents be added or removed based on how the project has evolved?
+
+Provide specific recommendations: keep / add / remove for each agent role."
+```
+
+### Step 3 — User Confirmation
+
+Use `AskUserQuestion` with these options, and allow free-form input:
+
+- **"Apply all changes"** — accept both the workspace learning and the roster updates
+- **"Apply workspace learning only"** — keep the current Team Roster unchanged
+- **"Cancel"** — abort re-initialization, keep everything as-is
+
+### Step 4 — Apply Changes
+
+Based on the user's choice:
+
+- **"Apply all changes"** → Delegate to `vesper:workspace-learner` to apply whitepaper + roster changes
+- **"Apply workspace learning only"** → Delegate to `vesper:workspace-learner` to apply the whitepaper only, skip roster changes
+- **"Cancel"** → Stop. Log `"Re-initialization cancelled by user"` and return
+
+### Step 5 — Memory Update
+
+Delegate to `vesper:feature-wrap-document`, instructing it to apply its assigned `mcp-memory` skill.
+
+That skill defines the entity schema, the per-agent memory protocols, and the hygiene rules for the
+MCP memory knowledge graph.
+
+This applies to:
+
+- **Initial creation** (Auto-Setup Step 2 in the orchestrator playbook)
+- **Re-initialization** (Step 5 above)
+
+---
+
+## Memory Content Rules
+
+Constraints for what goes into the memory graph (applies to both initial setup and re-initialization):
+
+- Memory captures workspace-specific patterns and learnings
+- Do NOT duplicate information already in `.claude/rules/vesper-context.md`
+- Focus on: discovered patterns, pitfalls, and workspace-specific conventions
+- Keep entries concise and actionable