@esthernandez/vibe-cartographer 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -9,6 +9,17 @@ All notable changes to this project are documented here. The format follows [Kee
 
 - Nothing yet.
 
+## [1.0.1] — 2026-04-15 — Install docs
+
+### Changed
+
+- **README and INSTALL rewritten** to document all three Claude Desktop install paths: **Add marketplace** (recommended — pulls from GitHub via `.claude-plugin/marketplace.json`), **npm install -g** (for Claude Code CLI / VS Code / JetBrains), and **Upload plugin** (for local iteration via `python scripts/build-plugin.py`).
+- Added a **"Which option should I use?"** decision table mapping situation → recommended install path.
+- Added a reproducible `scripts/build-plugin.py` build script that produces a `.plugin` bundle in `bundles/` for the upload-plugin path. Excludes `dist/`, `node_modules/`, `src/`, and other runtime/build artifacts per Cowork's plugin spec.
+- GitHub releases now ship a pre-built `.plugin` file as a release asset for one-click downloads.
+
+No behavior changes — this release exists so the npm-published README on `npmjs.com/package/@esthernandez/vibe-cartographer` reflects the marketplace install path.
+
 ## [1.0.0] — 2026-04-15 — Rebrand to Vibe Cartographer
 
 The plugin formerly known as `@esthernandez/app-project-readiness` is now **Vibe Cartographer**. Same 8-command spec-driven workflow, same personas, same session memory — new name that actually says what the plugin does: *plot your course from idea to shipped app*.

package/INSTALL.md

@@ -8,42 +8,69 @@
 
 ## Install paths
 
-You only need one of these. Pick whichever matches how you're already running Claude Code.
+Pick whichever matches how you're running Claude Code. All three lead to the same plugin working.
 
-### Option 1: npm (recommended)
+### Option 1: Claude Desktop — Add marketplace (recommended)
+
+The cleanest path. Pulls from GitHub directly, supports `Sync` to update, no file downloads.
+
+1. Open Claude Desktop → **Personal plugins** panel (left sidebar)
+2. Click the **+** button → **Add marketplace**
+3. Enter: `estevanhernandez-stack-ed/vibe-cartographer`
+4. Click **Sync**
+
+Claude Desktop reads `.claude-plugin/marketplace.json` at the repo root, discovers the `vibe-cartographer` plugin inside `./plugins/vibe-cartographer`, and registers its slash commands. Updates propagate by clicking **Sync** again on the marketplace entry.
+
+### Option 2: Claude Code CLI — npm
+
+For users running Claude Code in a terminal, VS Code, or JetBrains.
 
 ```bash
 npm install -g @esthernandez/vibe-cartographer
 ```
 
-This drops the plugin files on your disk at your npm global root — typically `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/` on macOS/Linux or `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\` on Windows. You then need to tell Claude Code about them — see [Connecting to Claude Code](#connecting-to-claude-code) below.
+This drops the plugin files at:
 
-### Option 2: Claude Desktop — Personal plugin
+- **macOS/Linux:** `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/`
+- **Windows:** `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\plugins\vibe-cartographer\`
 
-If you're on the Claude Desktop app and don't want an npm install:
+If your Claude Code CLI has a `plugin add <path>` command, point it at that path. Otherwise, use Option 1 (Add marketplace) — it works for CLI clients too because Claude Code reads marketplace entries from the global plugin config.
 
-1. Open **Personal plugins** in Claude Desktop (the panel in the left sidebar).
-2. Click the **+** button → **Create plugin**.
-3. Point it at a local clone of this repo (see Option 3 for the clone step).
-4. The plugin's slash commands become available immediately — no restart required.
+### Option 3: Claude Desktop — Upload plugin (for local iteration)
 
-### Option 3: Clone and reference locally
+For testing changes locally before pushing them to GitHub.
 
-```bash
-git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer ~/vibe-cartographer
-```
+1. Clone the repo:
+
+   ```bash
+   git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer
+   cd vibe-cartographer
+   ```
+
+2. Build a `.plugin` bundle:
+
+   ```bash
+   python scripts/build-plugin.py
+   ```
+
+   This writes `bundles/vibe-cartographer-<version>.plugin` — a zip archive Cowork accepts directly. The script excludes `dist/`, `node_modules/`, `src/`, and other runtime/build artifacts per Cowork's plugin spec.
+
+3. In Claude Desktop → **Personal plugins** → **+** → **Upload plugin**, pick the `.plugin` file.
 
-Then point Claude Code at `~/vibe-cartographer/plugins/vibe-cartographer/` as the plugin root. This is the same as Option 2 minus the Claude Desktop UI step — useful if you're on the Claude Code CLI directly.
+You can also download a pre-built `.plugin` file from the [GitHub releases page](https://github.com/estevanhernandez-stack-ed/vibe-cartographer/releases) — each tagged release ships a ready-to-upload asset.
 
-## Connecting to Claude Code
+## Which option should I use?
 
-After installing, Claude Code needs to know where the plugin lives. The exact steps depend on your client:
+| Situation                                            | Option                                                                            |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------- |
+| I use Claude Desktop and want the simplest install   | **Option 1** (Add marketplace)                                                    |
+| I use Claude Code CLI / VS Code / JetBrains          | **Option 2** (npm) — then use Option 1 in Claude Desktop if you also use it there |
+| I'm developing or testing plugin changes locally     | **Option 3** (Upload plugin)                                                      |
+| I want to install without an internet connection     | **Option 3** — download the `.plugin` from releases ahead of time                 |
 
-- **Claude Desktop** — use the **Personal plugins** panel (**+** button → **Create plugin** → point at the folder). Same flow for Option 1 (point at the npm install path) and Option 3 (point at your local clone).
-- **Claude Code CLI** — if your version has a plugin-add command, point it at the install path. Otherwise clone the repo and rely on Claude Code's plugin discovery for folders in its known marketplace list.
-- **VS Code / JetBrains** — Claude Code in your IDE reads from the same global plugin config as Claude Desktop. Install via Option 2 on Claude Desktop first and the IDE will pick it up on next launch.
+## Verifying the install
 
-**Pointing at the right folder matters.** The plugin root is the folder that contains `.claude-plugin/plugin.json` — in this repo that's `plugins/vibe-cartographer/`, not the repo root. Pointing at the repo root will not work.
+**The plugin root is the folder that contains `.claude-plugin/plugin.json`.** In this repo that's `plugins/vibe-cartographer/`, not the repo root. Most install paths handle this automatically (marketplace manifest tells Claude Desktop where to look), but if you're troubleshooting, that's the folder to point at.
 
 ## Verification
 

package/README.md

@@ -54,40 +54,50 @@ See [`plugins/vibe-cartographer/architecture/`](plugins/vibe-cartographer/archit
 
 ## Install
 
-Requires [Claude Code](https://claude.ai/code) or Claude Desktop with plugin support.
+Requires [Claude Code](https://claude.ai/code) CLI or Claude Desktop with plugin support. Pick whichever path matches how you're running Claude Code — all three lead to the same plugin working inside a fresh project folder.
 
-### Option 1: npm (recommended)
+### Option 1: Claude Desktop — Add marketplace (recommended)
+
+The cleanest install. Pulls straight from GitHub, no file download, supports `Sync` to update.
+
+1. Open Claude Desktop → **Personal plugins** panel
+2. Click the **+** button → **Add marketplace**
+3. Enter: `estevanhernandez-stack-ed/vibe-cartographer`
+4. Click **Sync**
+
+Claude Desktop reads `.claude-plugin/marketplace.json` at the repo root, loads the `vibe-cartographer` plugin from inside `./plugins/vibe-cartographer`, and the slash commands (`/onboard`, `/scope`, `/prd`, etc.) become available.
+
+### Option 2: Claude Code CLI — npm
 
 ```bash
 npm install -g @esthernandez/vibe-cartographer
 ```
 
-Then in Claude Code / Claude Desktop, point your personal plugins at the installed path:
+The package ships the plugin files at `<npm-global>/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/`. If your Claude Code CLI has a plugin-add command, point it at that path; otherwise use Option 1 (Add marketplace) and the marketplace manifest will do the discovery for you.
 
-- macOS/Linux: `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer`
-- Windows: `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\plugins\vibe-cartographer`
+### Option 3: Claude Desktop — Upload plugin
 
-### Option 2: Claude Desktop personal plugin
+For local iteration before you push changes to GitHub.
 
-1. Open Claude Desktop's **Personal plugins** panel.
-2. Click **+ Create a plugin**.
-3. Point it to the `plugins/vibe-cartographer` folder from this repo (cloned or downloaded).
-4. The slash commands (`/onboard`, `/scope`, `/prd`, etc.) become available.
+1. Clone the repo: `git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer`
+2. Build a `.plugin` bundle:
 
-### Option 3: Clone and reference locally
+   ```bash
+   python scripts/build-plugin.py
+   ```
 
-```bash
-git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer ~/vibe-cartographer
-```
+   This writes `bundles/vibe-cartographer-<version>.plugin` — a zip archive Cowork accepts directly.
+3. In Claude Desktop → **Personal plugins** → **+** → **Upload plugin**, pick the `.plugin` file.
 
-Then point your Claude Code / Claude Desktop at `~/vibe-cartographer/plugins/vibe-cartographer`.
+Also available as a one-click download from the [GitHub releases page](https://github.com/estevanhernandez-stack-ed/vibe-cartographer/releases) — each release ships a pre-built `.plugin` file as a release asset.
 
 ### Migrating from `@esthernandez/app-project-readiness`
 
-Vibe Cartographer is the rename of what was previously `@esthernandez/app-project-readiness` (v0.5.0 and earlier). The migration is automatic:
+Vibe Cartographer is the rename of what was previously `@esthernandez/app-project-readiness` (v0.5.0 and earlier). Migration is automatic on first `/onboard` run:
 
-- Your unified builder profile at `~/.claude/profiles/builder.json` gets its `plugins.app-project-readiness` block copied to `plugins.vibe-cartographer` on first v1.0.0+ run.
-- The old `@esthernandez/app-project-readiness` npm package is deprecated. Run `npm install -g @esthernandez/vibe-cartographer` and uninstall the old one when you're ready.
+- Your unified builder profile at `~/.claude/profiles/builder.json` gets its `plugins.app-project-readiness` block copied to `plugins.vibe-cartographer` (old key preserved for one release as a safety net).
+- Deep-legacy markdown profiles at `~/.claude/plugins/data/app-project-readiness/user-profile.md` also migrate.
+- The old `@esthernandez/app-project-readiness` npm package is deprecated with a pointer. Run `npm install -g @esthernandez/vibe-cartographer` and uninstall the old one when you're ready.
 - Legacy session logs at `~/.claude/plugins/data/app-project-readiness/sessions/` are left in place — append-only history isn't touched.
 
 ### Start the workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esthernandez/vibe-cartographer",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vibe Cartographer — plot your course from idea to shipped app. Spec-driven development workflow as a Claude Code plugin, delivered as eight slash commands (onboard, scope, prd, spec, checklist, build, iterate, reflect).",
   "author": "626Labs LLC",
   "license": "MIT",

package/plugins/vibe-cartographer/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-cartographer",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vibe Cartographer — plot your course from idea to shipped app. Spec-driven development delivered as eight slash commands: onboard, scope, prd, spec, checklist, build, iterate, reflect.",
   "author": {"name": "626Labs LLC"}
 }

package/plugins/vibe-cartographer/CLAUDE.md

@@ -9,7 +9,7 @@ You are guiding a builder through the **Vibe Cartographer** process — plotting
 - Guard rails: every command checks prerequisite artifacts. If missing, name the command to run and stop.
 - Tone: encouraging but sharp, brisk pace, concise feedback (2-4 sentences max for embedded feedback).
 - Embedded feedback uses ✓/△ format. Tight.
-- Handoff: end of each command, tell the builder to run `/clear` and then run the next command.
+- Handoff: end of each command, tell the builder to move to the next command. Phrasing is client-aware — CLI users get "run `/clear`, then run `/next`"; Cowork (Claude Desktop) users get "when you're ready, run `/next`" because Cowork has no `/clear` command and manages context automatically. When unsure, default to the Cowork form. See the guide SKILL's Handoff section for the full rule.
 - Active engagement: the builder should actively shape every decision. Log passivity vs activity in process-notes. This is evaluated.
 - Interaction rules: one question at a time. Free-form only for all interview/planning questions. The one exception: comprehension checks during /build use AskUserQuestion (multiple choice).
 - Architecture docs: during `/onboard`, the builder points to architecture docs (in the `architecture/` folder or elsewhere). These guide all technical decisions in `/spec`, `/checklist`, and `/build`.

package/plugins/vibe-cartographer/commands/build.md

@@ -0,0 +1,8 @@
+---
+description: "Step 6 of 8 · Build the app — autonomous or step-by-step mode. Reads checklist.md + all prior artifacts, writes source code."
+argument-hint: "(no arguments)"
+---
+
+Use the **build** skill to actually ship the project. Walks the checklist item by item, either autonomously (the agent executes each step and reports) or step-by-step (the agent pauses for your input between items). Respects your mode preference (Learner vs Builder) and persona voice from the unified profile.
+
+**Prerequisites:** `/checklist` must have run first (`docs/checklist.md` must exist).

package/plugins/vibe-cartographer/commands/checklist.md

@@ -0,0 +1,8 @@
+---
+description: "Step 5 of 8 · Break the spec into a sequenced, dependency-aware build plan. Reads spec.md, writes checklist.md."
+argument-hint: "(no arguments)"
+---
+
+Use the **checklist** skill to turn the technical spec into an ordered build plan — each item with its dependencies, acceptance criteria, and rough effort. The final item is always **Documentation & Security Verification** (README, docs cleanup, secrets scan, dependency audit, deployment security).
+
+**Prerequisites:** `/spec` must have run first (`docs/spec.md` must exist).

package/plugins/vibe-cartographer/commands/iterate.md

@@ -0,0 +1,8 @@
+---
+description: "Step 7 of 8 · Optional polish pass after the core build. Identifies rough edges, iterates on UX, tightens the ship."
+argument-hint: "(optional focus area, e.g. 'performance' or 'ux')"
+---
+
+Use the **iterate** skill for a polish pass after the core build is done. Optional — skip it if you're already shipping. Useful for hackathons in the last hour before submission: the agent looks at what you built, suggests the highest-leverage improvements given remaining time, and helps you implement them.
+
+**Prerequisites:** `/build` must have produced working code.

package/plugins/vibe-cartographer/commands/onboard.md

@@ -0,0 +1,14 @@
+---
+description: "Step 1 of 8 · Welcome, builder profile, persona selection, architecture docs. Start here for any new Vibe Cartographer run."
+argument-hint: "(no arguments)"
+---
+
+Use the **onboard** skill to start the Vibe Cartographer workflow. Welcomes the builder, checks the unified profile at `~/.claude/profiles/builder.json`, runs the 11-step interview (skipped if builder is returning), picks a persona and mode, captures project goals and architecture docs, and writes `docs/builder-profile.md`.
+
+This is the entry point for the entire 8-command chain:
+
+```text
+/onboard → /scope → /prd → /spec → /checklist → /build → /iterate → /reflect
+```
+
+Run in a **fresh, empty folder** for your project. All artifacts go in `docs/`.

package/plugins/vibe-cartographer/commands/prd.md

@@ -0,0 +1,8 @@
+---
+description: "Step 3 of 8 · Turn scope into detailed product requirements with testable acceptance criteria. Reads scope.md, writes prd.md."
+argument-hint: "(no arguments)"
+---
+
+Use the **prd** skill to expand the scope doc into a real Product Requirements Document: user stories, acceptance criteria, edge cases, prioritization (must-have vs later). Supports optional deepening rounds for richer requirements — accept them if the project is complex.
+
+**Prerequisites:** `/scope` must have run first (`docs/scope.md` must exist).

package/plugins/vibe-cartographer/commands/reflect.md

@@ -0,0 +1,10 @@
+---
+description: "Step 8 of 8 · Retro and peer-style review. Writes reflection.md and updates the unified profile with what you learned."
+argument-hint: "(no arguments)"
+---
+
+Use the **reflect** skill to close out the project with a peer-style retro (not a classroom quiz). Two parts: a conversational check-in about the process, then a qualitative review of all the artifacts you produced. Output is `docs/reflection.md` — a shareable document that captures what landed, what to tighten next time, and how you worked.
+
+Also updates `~/.claude/profiles/builder.json` with project completion data and any new observations about your working style.
+
+**Prerequisites:** At least `/onboard` must have run. Ideally the full chain up through `/build`.

package/plugins/vibe-cartographer/commands/scope.md

@@ -0,0 +1,8 @@
+---
+description: "Step 2 of 8 · Brainstorm and refine your idea into a focused project scope. Reads builder-profile.md, writes scope.md."
+argument-hint: "(no arguments)"
+---
+
+Use the **scope** skill to turn a vague idea into a buildable project scope. The agent interviews you through the idea, user, problem, constraints, and explicit cuts. Output is `docs/scope.md` — the input to every downstream command.
+
+**Prerequisites:** `/onboard` must have run first (`docs/builder-profile.md` must exist).

package/plugins/vibe-cartographer/commands/spec.md

@@ -0,0 +1,8 @@
+---
+description: "Step 4 of 8 · Translate PRD into a technical blueprint using your architecture. Reads prd.md + architecture docs, writes spec.md."
+argument-hint: "(no arguments)"
+---
+
+Use the **spec** skill to turn the PRD into a technical specification: stack choices, file structure, data flow, external dependencies, submission approach. Guided by the architecture docs you pointed at during `/onboard` (or the plugin's `architecture/default-patterns.md` fallback).
+
+**Prerequisites:** `/prd` must have run first (`docs/prd.md` must exist).

package/plugins/vibe-cartographer/skills/build/SKILL.md

@@ -96,9 +96,9 @@ If comprehension checks are off, skip this step.
 
 #### 6. Hand Off
 
-"Step N is done. Run `/clear`, then run `/build` again for the next item."
+"Step N is done. Run `/build` again for the next item." *(CLI / IDE users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
-If the next item is the documentation & security verification step, mention it: "Next up is the final step — writing your README, cleaning up docs, and running a security review of the codebase. Run `/clear`, then run `/build` when you're ready."
+If the next item is the documentation & security verification step, mention it: "Next up is the final step — writing your README, cleaning up docs, and running a security review of the codebase. Run `/build` when you're ready." *(CLI / IDE users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ---
 
@@ -179,7 +179,7 @@ Provide 2-4 sentences using checkmark/triangle markers. Evaluate:
 
 ### Handoff
 
-"Want to polish or add features? Run `/iterate`. When you're ready to wrap up, run `/clear`, then run `/reflect`."
+"Want to polish or add features? Run `/iterate`. When you're ready to wrap up, run `/reflect`." *(CLI / IDE users: prefix the `/reflect` handoff with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ### Process Notes (autonomous mode summary)
 
@@ -193,6 +193,6 @@ If this was an autonomous build, append a `## /build` section to `process-notes.
 
 Everything from the guide SKILL.md interaction rules applies here, plus:
 
-- **In step-by-step mode:** Be brief. This is a building session, not a planning session. Keep narration proportional to the check-in cadence they chose. The checklist is your script — don't improvise new items, reorder things, or skip steps (unless something breaks and you need to adapt). One item per session. Always tell the builder to run `/clear` before the next item.
+- **In step-by-step mode:** Be brief. This is a building session, not a planning session. Keep narration proportional to the check-in cadence they chose. The checklist is your script — don't improvise new items, reorder things, or skip steps (unless something breaks and you need to adapt). One item per session. Follow the client-aware handoff rule from the guide SKILL — CLI / IDE users get prompted to run `/clear` between items; Cowork users are told to just run `/build` again when ready.
 - **In autonomous mode:** Be efficient. The builder is watching you work, not co-building. At checkpoints, be concise — tell them what to look for and wait. Between checkpoints, just build.
 - **In both modes:** Verification (when opted in) is how the builder stays connected to the project. Don't skip it even if you're confident. And if something breaks, stop and talk — don't try to be a hero.

package/plugins/vibe-cartographer/skills/checklist/SKILL.md

@@ -193,8 +193,8 @@ Provide 2-4 sentences using ✓/△ markers. Evaluate:
 
 ### Handoff
 
-- **If autonomous mode:** "Run `/clear`, then run `/build` when you're ready. I'll work through the whole checklist and pause at checkpoints for you to verify."
-- **If step-by-step mode:** "Run `/clear`, then run `/build` when you're ready — you'll run it once per checklist item. Run `/clear` between each item so the agent gets a fresh context. Each run picks up the next unchecked step."
+- **If autonomous mode:** "Run `/build` when you're ready. I'll work through the whole checklist and pause at checkpoints for you to verify." *(CLI / IDE users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
+- **If step-by-step mode:** "Run `/build` when you're ready — you'll run it once per checklist item. Each run picks up the next unchecked step." *(CLI / IDE users: run `/clear` between each item to fight context rot. Cowork users don't need to — context is managed automatically.)*
 
 ### Process Notes
 

package/plugins/vibe-cartographer/skills/guide/SKILL.md

@@ -49,7 +49,16 @@ This is a gut check, not a report card. Keep it tight. This feedback pattern is
 
 ## Handoff
 
-At the end of each command, after embedded feedback and process notes, tell the builder to run `/clear`, then run the next command. Keep it brief — no teaching moment, just the transition.
+At the end of each command, after embedded feedback and process notes, tell the builder to move to the next command. Keep the handoff brief — no teaching moment, just the transition.
+
+**The handoff phrasing is client-aware:**
+
+- **Claude Code CLI / VS Code / JetBrains terminal:** "Run `/clear`, then run `/scope`" — `/clear` wipes the conversation between commands to fight context rot. The builder should run it between every command in these environments.
+- **Claude Desktop (Cowork):** "When you're ready, run `/scope`" — Cowork does not have a `/clear` command and the conversation persists through the session. Do NOT prompt the builder to run `/clear` in Cowork — it will confuse them or error out. Cowork manages its own context window automatically.
+
+**How to detect the client:** Check your operating environment at the start of every command. If the environment identifies you as running in Claude Code CLI / IDE / VS Code / JetBrains / a terminal-style coding agent, use the CLI form. If it identifies you as running in Claude Desktop / Cowork / the Claude chat app, use the Cowork form. When unsure, **default to the Cowork form** — it's safe in both environments (CLI users can always run `/clear` manually if they want).
+
+**Rule of thumb for individual command SKILLs:** the handoff line in each SKILL file defaults to the Cowork form ("run `/X` when you're ready") because it works everywhere. Claude Code CLI users who want to fight context rot can still run `/clear` manually between commands — the onboard SKILL's step 2 teaches them the pattern, but only conditionally.
 
 ## Session Logging
 
@@ -158,7 +167,7 @@ Each command produces artifacts that downstream commands consume. The chain is l
 
 **`/build` behavior depends on the build mode chosen in `/checklist`:**
 
-- **Step-by-step mode:** `/build` runs once per checklist item, in a fresh chat session each time. The builder runs `/clear` between items to fight context rot. Each invocation picks up the next unchecked item. Verification and comprehension checks are optional per the builder's preference. Process notes are logged per item.
+- **Step-by-step mode:** `/build` runs once per checklist item. In CLI / IDE environments, the builder runs `/clear` between items to fight context rot. In Cowork, context is managed automatically and no manual reset is needed — the builder just runs `/build` again for the next item. Each invocation picks up the next unchecked item. Verification and comprehension checks are optional per the builder's preference. Process notes are logged per item.
 - **Autonomous mode:** `/build` runs once and works through the entire checklist. The agent acts as an orchestrator, dispatching each item to a subagent via the `Agent` tool. If the builder opted into verification, the agent pauses at checkpoints every 3-4 items for the builder to review. No per-item process notes — just a summary at the end.
 - **In both modes**, the checklist is a living document. If something breaks, the agent stops, proposes reverting to the last clean state, and works with the builder to revise the checklist before resuming. Plans adapt when they meet reality.
 - **No mode switching mid-build.** The choice made in `/checklist` is locked in.

package/plugins/vibe-cartographer/skills/iterate/SKILL.md

@@ -69,7 +69,7 @@ Append these to `docs/checklist.md` under an `## Iteration N` header (where N in
 
 ### 5. Hand Off to /build
 
-"Your iteration items are added to the checklist. Run `/clear`, then run `/build` to start working through them."
+"Your iteration items are added to the checklist. Run `/build` to start working through them." *(CLI / IDE users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 The builder runs /build exactly as before — same mode, same verification preferences, same comprehension checks (if opted in). The iteration items just happen to be at the bottom of checklist.md under a new section header.
 
@@ -94,4 +94,4 @@ Everything from the guide SKILL.md interaction rules applies here, plus:
 - **This should feel lighter than the structured commands.** The builder has earned autonomy. Be a collaborator, not a guide.
 - **The review pass is quick.** 2-3 observations, not a full audit. Don't make the builder feel like they're back in planning mode.
 - **Respect their time.** If they're short on time, don't propose a 5-item checklist. Scale to the time available.
-- **Keep handoff brief.** Just tell them to run `/clear`, then `/build`.
+- **Keep handoff brief.** Follow the guide SKILL's client-aware handoff — CLI / IDE users get "Run `/clear`, then run `/build`"; Cowork users get "Run `/build` when you're ready".

package/plugins/vibe-cartographer/skills/onboard/SKILL.md

@@ -13,6 +13,34 @@ You are a warm, energetic host kicking off the build process. This is the very f
 
 None. This is the entry point for the entire process.
 
+## Version Check (soft, non-blocking)
+
+Before displaying the welcome banner, do a quick background version check against the npm registry. If a newer version of Vibe Cartographer is available, mention it once at the top of the welcome — don't nag, don't block, don't print anything if the check fails.
+
+**Run this bash command** (ignore any errors — this is best-effort, offline/network issues must NOT block /onboard):
+
+```bash
+INSTALLED=$(cat ~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/.claude-plugin/plugin.json 2>/dev/null \
+  || find "$APPDATA/npm/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/.claude-plugin/plugin.json" 2>/dev/null \
+  | head -1 | xargs cat 2>/dev/null \
+  | python -c "import sys, json; print(json.load(sys.stdin).get('version', 'unknown'))" 2>/dev/null) && \
+LATEST=$(curl -sf --max-time 5 https://registry.npmjs.org/@esthernandez/vibe-cartographer/latest \
+  | python -c "import sys, json; print(json.load(sys.stdin).get('version', 'unknown'))" 2>/dev/null) && \
+if [ -n "$INSTALLED" ] && [ -n "$LATEST" ] && [ "$INSTALLED" != "$LATEST" ] && [ "$LATEST" != "unknown" ]; then
+  echo "📦 Vibe Cartographer $LATEST is available (you're on $INSTALLED)."
+  echo "   Upgrade: npm install -g @esthernandez/vibe-cartographer@latest"
+fi
+```
+
+**Rules:**
+- Run this ONCE at the very start of /onboard, before any other output
+- If the command fails, errors, times out, or returns nothing — silently continue with the rest of /onboard
+- Never print anything if installed version equals latest version
+- Never print anything if the check couldn't determine a version
+- The user should never see "version check failed" — only the positive notification or silence
+
+This is a nice-to-have, not load-bearing. If it's too noisy or breaks in practice, it can be removed without affecting any other plugin behavior.
+
 ## Before You Start
 
 - **Check the working directory.** The builder should be running their coding agent in an empty folder they've set aside specifically for their project. Check the current directory — if it has existing files (beyond dotfiles like `.git`, `.claude`, etc.), pause and ask: "It looks like this folder already has files in it. This process works best in a fresh, empty folder you've designated for your project. Want to create a new folder and move there, or are you good to continue here?" If it's empty (or they confirm), proceed.
@@ -42,8 +70,8 @@ The file at `~/.claude/profiles/builder.json` has this shape:
   "schema_version": 1,
   "last_updated": "2026-04-15",
   "shared": {
-    "name": "Estevan",
-    "identity": "Builder and outsider. 626 exchange, Fort Worth roots. Runs 626Labs.",
+    "name": "Alex",
+    "identity": "Full-stack builder. Mix of client work and side projects. Ships fast.",
     "technical_experience": {
       "level": "experienced",
       "languages": ["TypeScript", "Python", "Go"],
@@ -128,7 +156,11 @@ Then name the full command chain: `/onboard` (that's now) → `/scope` → `/prd
 
 Mention that the documents they create through this process are a real part of their project — they're not throwaway scaffolding. And remind them that these techniques work everywhere, even outside this plugin.
 
-**Introduce `/clear` and context rot.** Tell them: "Remember context rot from the video? AI performance gets worse as conversations get longer. That's why after each command, I'll ask you to run `/clear` — it wipes the conversation and gives the AI a fresh start. Don't worry about losing anything — all the important stuff lives in the docs we write together. The AI reads those fresh each time. So the flow is: finish a command, run `/clear`, then run the next command."
+**Introduce context management.** Context management works differently depending on where the builder is running Claude. Check the environment you're running in and say the right thing:
+
+- **If in Claude Code CLI / VS Code / JetBrains:** "Remember context rot? AI performance gets worse as conversations get longer. That's why after each command, I'll ask you to run `/clear` — it wipes the conversation and gives the AI a fresh start. Don't worry about losing anything — all the important stuff lives in the docs we write together. The AI reads those fresh each time. So the flow is: finish a command, run `/clear`, then run the next command."
+- **If in Claude Desktop / Cowork:** "Context management works a bit differently here than in the terminal — Cowork handles it automatically as the conversation grows. You don't need to manually reset between commands. After each command, just run the next one when you're ready. All the important context lives in the docs we write together, which the AI reads fresh each time."
+- **If unsure which environment:** Default to the Cowork version. It's safe in both contexts.
 
 ### 3. Get to Know the Builder
 
@@ -306,7 +338,7 @@ If they shared something particularly interesting or specific, acknowledge it: "
 
 ### Handoff
 
-"Great — I've got everything I need. Run `/clear`, then run `/scope` — that's where we'll find your idea."
+"Great — I've got everything I need. Run `/scope` when you're ready — that's where we'll find your idea." *(If the builder is in Claude Code CLI / VS Code / JetBrains, prefix the handoff with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ### Process Notes
 

package/plugins/vibe-cartographer/skills/prd/SKILL.md

@@ -89,7 +89,7 @@ Provide 2-4 sentences using ✓/△ markers. Evaluate:
 - Whether ambiguities were genuinely surfaced and resolved
 ### Handoff
 
-"Run `/clear`, then run `/spec` when you're ready."
+"Run `/spec` when you're ready." *(Claude Code CLI / VS Code / JetBrains users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ### Process Notes
 

package/plugins/vibe-cartographer/skills/scope/SKILL.md

@@ -100,7 +100,7 @@ Provide 2-4 sentences using ✓/△ markers. Evaluate:
 
 ### Handoff
 
-"Run `/clear`, then run `/prd` when you're ready."
+"Run `/prd` when you're ready." *(Claude Code CLI / VS Code / JetBrains users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ### Process Notes
 

package/plugins/vibe-cartographer/skills/spec/SKILL.md

@@ -105,7 +105,7 @@ Provide 2-4 sentences using ✓/△ markers. Evaluate:
 
 ### Handoff
 
-"That spec is the heart of spec-driven development — everything from here flows from it. Run `/clear`, then run `/checklist` when you're ready."
+"That spec is the heart of spec-driven development — everything from here flows from it. Run `/checklist` when you're ready." *(Claude Code CLI / VS Code / JetBrains users: prefix with "Run `/clear`, then " per the guide SKILL's Handoff section.)*
 
 ### Process Notes