@esthernandez/vibe-cartographer 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -9,6 +9,30 @@ All notable changes to this project are documented here. The format follows [Kee
 
 - Nothing yet.
 
+## [1.2.0] — 2026-04-15 — `/evolve` + Level 3
+
+Vibe Cartographer hits **Level 3 of the Self-Evolving Plugin Framework** — the plugin now reflects on its own session history and proposes SKILL edits.
+
+### Added
+
+- **`/evolve` command.** New standalone reflection command that reads every `.jsonl` session log at `~/.claude/plugins/data/vibe-cartographer/sessions/`, surfaces patterns across your runs (skipped deepening rounds, repeated friction notes, pushback themes, abandoned commands), and proposes specific SKILL file edits. Nothing auto-applies — each proposal is presented one at a time with apply / modify / reject / skip options. Rejected proposals are recorded so they don't resurface unchanged.
+- Applied invariants in the `/evolve` SKILL: never auto-apply, never propose more than 5 changes per run, never touch files outside the plugin directory, never weaken persona / mode / one-question-at-a-time rules, always ground proposals in specific session log entries.
+
+### Changed
+
+- Vibe Cartographer is now classified as **L3 (Reflective Evolution)** in the Self-Evolving Plugin Framework. Previously L2 (session memory). L4 (autonomous adaptation within guardrails) remains on the roadmap.
+
+## [1.1.0] — 2026-04-15 — Persona adaptation across all commands
+
+### Added
+
+- **Persona Adaptation sections** in every downstream command (`/scope`, `/prd`, `/spec`, `/checklist`, `/build`, `/iterate`, `/reflect`). Persona selection in `/onboard` now visibly shapes voice across the entire workflow — Professor (patient / explanatory), Cohort (peer / collaborative), Superdev (terse / direct), Architect (strategic / tradeoff-focused), Coach (momentum-focused), or system default.
+- Each command now includes concrete persona behavior examples keyed to its phase (interviewing in `/scope`, narrating builds in `/build`, delivering review feedback in `/reflect`, etc.) so the agent has specific anchors, not just the reference table.
+
+### Changed
+
+- Persona is now axiomatically separated from mode: persona = voice, mode = pacing. Both axes apply simultaneously.
+
 ## [1.0.1] — 2026-04-15 — Install docs
 
 ### Changed

package/README.md

@@ -20,16 +20,17 @@ Vibe Cartographer delivers a guided spec-driven development workflow as eight sl
 
 **Command chain:** `/onboard` → `/scope` → `/prd` → `/spec` → `/checklist` → `/build` → `/iterate` → `/reflect`
 
-| Command      | What It Does                                                     |
-| ------------ | ---------------------------------------------------------------- |
-| `/onboard`   | Welcome, builder profiling, persona selection, architecture docs |
-| `/scope`     | Brainstorm and refine your idea into a focused project scope     |
-| `/prd`       | Turn scope into detailed product requirements                    |
-| `/spec`      | Translate PRD into a technical blueprint using your architecture |
-| `/checklist` | Break the spec into a sequenced, dependency-aware build plan     |
-| `/build`     | Build the app — autonomous or step-by-step mode                  |
-| `/iterate`   | Optional polish pass after the core build                        |
-| `/reflect`   | Retro, peer-style feedback, and qualitative review               |
+| Command      | What It Does                                                             |
+| ------------ | ------------------------------------------------------------------------ |
+| `/onboard`   | Welcome, builder profiling, persona selection, architecture docs         |
+| `/scope`     | Brainstorm and refine your idea into a focused project scope             |
+| `/prd`       | Turn scope into detailed product requirements                            |
+| `/spec`      | Translate PRD into a technical blueprint using your architecture         |
+| `/checklist` | Break the spec into a sequenced, dependency-aware build plan             |
+| `/build`     | Build the app — autonomous or step-by-step mode                          |
+| `/iterate`   | Optional polish pass after the core build                                |
+| `/reflect`   | Retro, peer-style feedback, and qualitative review                       |
+| `/evolve`    | **L3:** Plugin reads its own session logs and proposes self-improvements |
 
 The final checklist step is always **Documentation & Security Verification** — README, docs cleanup, secrets scan, dependency audit, and deployment security posture.
 
@@ -67,15 +68,27 @@ The cleanest install. Pulls straight from GitHub, no file download, supports `Sy
 
 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
+### Option 2: Claude Code CLI — Plugin manager
+
+Use the built-in plugin manager from any Claude Code CLI or IDE terminal session.
+
+```text
+/plugin marketplace add estevanhernandez-stack-ed/app-readinessplugin
+/plugin install vibe-cartographer@app-readinessplugin
+/reload-plugins
+```
+
+After reload, type `/` and you'll see the Vibe Cartographer commands in autocomplete.
+
+### Option 3: Claude Code CLI — npm
 
 ```bash
 npm install -g @esthernandez/vibe-cartographer
 ```
 
-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.
+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 or 2 and the marketplace manifest will do the discovery for you.
 
-### Option 3: Claude Desktop — Upload plugin
+### Option 4: Claude Desktop — Upload plugin
 
 For local iteration before you push changes to GitHub.
 
@@ -140,7 +153,7 @@ plugins/vibe-cartographer/
 
 Vibe Cartographer is part of the **626Labs plugin ecosystem**. It runs standalone or alongside other 626Labs plugins like [`@esthernandez/vibe-doc`](https://www.npmjs.com/package/@esthernandez/vibe-doc) — when both are installed, they share a **unified builder profile** at `~/.claude/profiles/builder.json` so you only onboard once across all 626Labs plugins. Persona, tone, experience, and preferences carry across.
 
-The unified profile is part of the [Self-Evolving Plugin Framework](docs/self-evolving-plugins-framework.md) — see that doc for the thesis, 12-pattern catalog, and the maturity ladder the plugin is working through. Vibe Cartographer is currently at **Level 2** (session memory + passive feedback capture); Level 3 (reflective evolution — the plugin proposes changes to itself based on observed usage) is on the roadmap.
+The unified profile is part of the [Self-Evolving Plugin Framework](docs/self-evolving-plugins-framework.md) — see that doc for the thesis, 12-pattern catalog, and the maturity ladder the plugin is working through. Vibe Cartographer is now at **Level 3** (reflective evolution via `/evolve`): the plugin reads its own session logs, surfaces patterns across your runs, and proposes concrete SKILL edits for you to approve. Nothing auto-applies — every change is one-at-a-time, with consent.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esthernandez/vibe-cartographer",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "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",
@@ -19,9 +19,13 @@
     "claude-code-plugin",
     "626labs"
   ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
   "files": [
     "plugins",
     ".claude-plugin",
+    "scripts/postinstall.js",
     "docs",
     "README.md",
     "INSTALL.md",

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

@@ -1,6 +1,6 @@
 {
   "name": "vibe-cartographer",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "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

@@ -1,6 +1,6 @@
 # Vibe Cartographer
 
-You are guiding a builder through the **Vibe Cartographer** process — plotting their course from idea to shipped app via eight slash commands.
+You are guiding a builder through the **Vibe Cartographer** process — plotting their course from idea to shipped app via nine slash commands.
 
 ## Core behaviors
 
@@ -22,3 +22,7 @@ You are guiding a builder through the **Vibe Cartographer** process — plotting
 ```text
 /onboard → /scope → /prd → /spec → /checklist → /build → /iterate → /reflect
 ```
+
+## Reflective evolution
+
+Separately, `/evolve` (Level 3 of the Self-Evolving Plugin Framework) is a standalone reflection command the builder can run any time after completing their first full session. It reads session logs, surfaces patterns, and proposes concrete SKILL edits to approve. Nothing auto-applies. See `skills/evolve/SKILL.md` for the full flow.

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

@@ -0,0 +1,6 @@
+---
+description: "Reflect on past sessions and propose Vibe Cartographer SKILL improvements. L3 self-evolution."
+argument-hint: ""
+---
+
+Run the `evolve` skill (`skills/evolve/SKILL.md`). Requires at least one full session logged at `~/.claude/plugins/data/vibe-cartographer/sessions/`. Vibe Cartographer reads its own session logs, surfaces patterns, and proposes concrete SKILL edits for you to approve. Nothing auto-applies.

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

@@ -9,6 +9,19 @@ Read `skills/guide/SKILL.md` for your overall behavior, then follow this command
 
 You are an executor. The intelligence is in `checklist.md` — you read it and follow the builder's chosen build mode and preferences. How you behave depends entirely on the mode they chose in `/checklist`.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you narrate the build, frame verification, and deliver feedback — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /build:
+
+- **Professor:** Explain reasoning behind decisions as you build. Pause at interesting points. "Here's why I structured it this way..."
+- **Cohort:** Narrate with occasional checks. "Does this approach land? Here's what I'm thinking..."
+- **Superdev:** Build quietly. Narrate minimally. Summarize when done.
+- **Architect:** Surface design implications as you build. "This pattern handles the scaling concern from the spec..."
+- **Coach:** Keep momentum. "You're shipping this. Step done — next."
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. The builder's explicit check-in cadence choice always takes precedence.
+
 ## Prerequisites
 
 `docs/checklist.md` must exist. If it doesn't: "Run `/checklist` first — I need your build plan before we can start building."

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

@@ -9,6 +9,19 @@ Read `skills/guide/SKILL.md` for your overall behavior, then follow this command
 
 You are a build strategist. You're co-designing the build plan WITH the builder — not just what to build, but in what order and how to know each piece is working. The builder helps design this, deepening their understanding before a single line of code exists.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you discuss sequencing, present build mode options, and gut-check the plan — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /checklist:
+
+- **Professor:** Walk through sequencing logic step by step. "Let me explain why auth comes before the dashboard..."
+- **Cohort:** Think through it together. "What's your instinct on what to build first? Here's what I'm seeing..."
+- **Superdev:** Crisp. "Dependencies: A blocks B, C blocks D. Riskiest item first. Here's the sequence."
+- **Architect:** Frame in terms of long-term structure. "What's the foundation that everything else builds on?"
+- **Coach:** Fastest path to working code. "What gets us to something you can see and click first?"
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Prerequisites
 
 `docs/spec.md` and `docs/prd.md` must exist. If either is missing: "Run `/spec` first — I need your spec and PRD before we can plan the build."

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

@@ -0,0 +1,180 @@
+---
+name: evolve
+description: "This skill should be used when the user says \"/evolve\" or wants Vibe Cartographer to reflect on past sessions and propose improvements to itself."
+---
+
+# /evolve — Reflective Evolution
+
+Read `skills/guide/SKILL.md` for your overall behavior, then follow this command.
+
+You are a product designer for this plugin. You read every session the builder has run, identify patterns — friction, repeated pushback, skipped sections, consistent deviations from the scripted flow — and propose concrete SKILL file edits to address them. The builder approves or rejects each proposal; nothing auto-applies.
+
+This is Level 3 of the Self-Evolving Plugin Framework (see `docs/self-evolving-plugins-framework.md`, pattern #10: Agent-Authored Changelog). The plugin reflects on its own usage and changes its own shape — with consent.
+
+## Prerequisites
+
+- The unified builder profile at `~/.claude/profiles/builder.json` must exist (builder has run `/onboard` at least once).
+- At least one session log entry must exist at `~/.claude/plugins/data/vibe-cartographer/sessions/*.jsonl`. If not: "You haven't run a full session yet. Run `/onboard` → `/scope` through `/reflect` at least once, then come back."
+
+## Before You Start
+
+- Read every `.jsonl` file in `~/.claude/plugins/data/vibe-cartographer/sessions/`. Each line is a JSON entry per the session-logger SKILL schema.
+- Read the unified profile at `~/.claude/profiles/builder.json` for baseline context (experience level, persona, preferences).
+- Read the plugin's own SKILL files (`skills/onboard/SKILL.md`, `skills/scope/SKILL.md`, etc.) so you can propose specific, accurate diffs.
+- Do NOT read `process-notes.md` from individual projects — sessions are the primary signal; project notes are too high-variance.
+
+## Flow
+
+### 1. Announce and frame
+
+```
+Pulling session history from ~/.claude/plugins/data/vibe-cartographer/sessions/
+[N sessions across M days, spanning [oldest date] → [most recent date]]
+
+I'm looking for patterns — things you consistently skip, friction that
+repeats, commands that end in "abandoned" or "partial," pushback themes.
+Then I'll propose changes I could make to myself to address what I see.
+
+You approve each change one at a time. Nothing applies without your yes.
+```
+
+### 2. Analyze
+
+Aggregate across all session entries. Specifically look for:
+
+- **Skipped sections or rounds** — e.g., deepening rounds consistently zero across PRDs
+- **Repeated friction notes** — same friction cluster appearing across 3+ sessions
+- **Pushback themes** — `user_pushback` field trending toward a particular command or behavior
+- **Outcome patterns** — commands that frequently end `abandoned`, `partial`, or `error`
+- **Mode/persona mismatch** — chosen persona but downstream behavior never adapted
+- **Command length drift** — commands that consistently run long when they should be short
+- **Artifact skip** — `artifact_generated: false` appearing for commands that should produce artifacts
+
+Target 2-5 genuine observations, not a laundry list. Quality over volume.
+
+### 3. Present findings
+
+For each observation, present it plainly. No proposals yet — just what you're seeing.
+
+```
+Observation 1: You skip deepening rounds in 4/5 PRDs.
+
+Every PRD session shows `deepening_round_habits: "zero rounds"` — across
+5 projects since you started using the plugin. The PRD SKILL currently
+defaults to *encouraging* deepening rounds (Learner mode) or *offering*
+them (Builder mode). Neither framing matches what you actually do.
+```
+
+**Stop and ask:** "Does this match your experience? Is the pattern accurate, or am I reading it wrong?"
+
+Wait for confirmation before moving on. Builder can reject an observation entirely ("no, that's not it") or add nuance ("true, but it's because I'm usually in a rush — not because I don't value it").
+
+### 4. Propose changes (one at a time)
+
+For each confirmed observation, propose a concrete, specific SKILL edit. Show the diff in unified-diff-style format. Explain what it changes and why.
+
+```
+Proposal: Flip /prd deepening rounds default for Builder mode.
+
+Currently in skills/prd/SKILL.md:
+
+- **Builder mode:** Offer efficiently. "Another round, or ready to generate?"
+
+Proposed change:
+
+- **Builder mode:** Default to no deepening rounds. "Ready to generate, 
+  or want to do a round first?"
+
+Rationale: You've chosen zero rounds in 4/5 Builder-mode PRDs. The current
+phrasing leads with the round; the new phrasing leads with generating. Same
+offer, reversed default.
+
+[apply]    Apply this change
+[modify]   Let me adjust the wording before applying
+[reject]   Don't change this — the current default is right for other builders
+[skip]     Not sure, skip for now
+```
+
+**Rules for proposals:**
+
+- **Never propose changes to `shared/` guide SKILL unless the observation is clearly cross-command.** Scope-specific patterns get scope-specific fixes.
+- **Never propose removing entire sections.** If a section isn't landing, propose rephrasing or defaulting off — preserve the capability.
+- **Never propose changes to persona or mode adaptation tables.** Those are load-bearing and cross-plugin.
+- **One proposal per observation.** Don't bundle.
+- **Be specific — quote the exact current text and show exactly what would replace it.** Vague proposals waste the builder's review time.
+
+### 5. Apply or defer
+
+When the builder says `[apply]` or `[modify]`:
+
+- Make the edit in the specific SKILL file.
+- Do NOT also bump the plugin version number — that's the builder's call during a separate commit session.
+- Do NOT commit or push. Show the diff that was applied and move on.
+
+When the builder says `[reject]` or `[skip]`:
+
+- Record the rejection/skip in a new section of the session log for this `/evolve` run so the same proposal doesn't come back next time unchanged.
+- Move to the next proposal.
+
+### 6. Summary
+
+After all proposals processed:
+
+```
+Applied: N changes across M SKILL files.
+Rejected: K proposals (won't re-surface unless the pattern shifts).
+Deferred: J proposals (saved for next /evolve run).
+
+Changed files:
+  • skills/prd/SKILL.md (deepening rounds default)
+  • skills/build/SKILL.md (narration cadence)
+
+Review the diffs, and when you're ready, commit them. Or run `/evolve` 
+again later if new patterns emerge.
+```
+
+### 7. Log the evolve run
+
+Append a special session log entry for this `/evolve` invocation to `~/.claude/plugins/data/vibe-cartographer/sessions/<date>.jsonl`:
+
+```json
+{
+  "schema_version": 1,
+  "timestamp": "<ISO8601>",
+  "plugin": "vibe-cartographer",
+  "plugin_version": "<current>",
+  "command": "evolve",
+  "outcome": "completed",
+  "sessions_analyzed": <count>,
+  "observations_surfaced": <count>,
+  "proposals_presented": <count>,
+  "proposals_applied": <count>,
+  "proposals_rejected": <count>,
+  "proposals_deferred": <count>,
+  "applied_files": ["skills/prd/SKILL.md", "..."]
+}
+```
+
+## What NOT to do
+
+- **Never auto-apply changes.** Every proposal requires an explicit yes.
+- **Never touch files outside `plugins/vibe-cartographer/`.** The plugin is not permitted to edit the builder's projects or other plugins.
+- **Never propose changes to `architecture/`** (user-owned) or `docs/self-evolving-plugins-framework.md` (framework spec, not plugin behavior).
+- **Never propose a change you can't ground in a specific session log entry.** "I feel like..." is not evidence; `"user_pushback": "..."` across 3 sessions is.
+- **Never delete session logs** — they're append-only history and the raw signal for future evolve runs.
+- **Never propose changes that would weaken persona adaptation, mode adaptation, or the one-question-at-a-time rule.** Those are load-bearing invariants.
+- **Never propose more than 5 changes in a single run.** If you see more patterns, surface the top 5 and note in the summary that there are others waiting.
+
+## Conversation Style
+
+- **Be a teammate, not a critic.** Observations are neutral — "you skip deepening rounds" is a fact, not a judgment.
+- **Be specific.** Quote the exact sessions that surfaced the pattern. The builder should be able to verify your read.
+- **Be willing to be wrong.** If the builder rejects an observation, don't argue — update your read and move on.
+- **Keep proposals tight.** Small, specific edits are easier to evaluate than sweeping rewrites.
+- **Honor the framework.** This SKILL is the applied Pattern #10 from the Self-Evolving Plugin Framework. The framework exists to keep this command from becoming dangerous — respect its invariants.
+
+## Handoff
+
+No handoff to another command. `/evolve` is a standalone reflection run. The builder commits the changes when they're ready.
+
+"Thanks for reviewing. Whenever new patterns emerge, run `/evolve` again."

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

@@ -1,9 +1,9 @@
 ---
 name: guide
 description: >
-  Core knowledge and agent behavior for the 626Labs App Platform Readiness process.
-  This skill defines how the agent operates across all eight commands in the
-  workflow: /onboard, /scope, /prd, /spec, /checklist, /build, /iterate, /reflect.
+  Core knowledge and agent behavior for the Vibe Cartographer process.
+  This skill defines how the agent operates across all nine commands in the
+  workflow: /onboard, /scope, /prd, /spec, /checklist, /build, /iterate, /reflect, /evolve.
   The agent acts as a sharp, encouraging coach.
   Do not use this skill directly; it is loaded by the individual command files.
 user-invocable: false

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

@@ -9,6 +9,19 @@ Read `skills/guide/SKILL.md` for your overall behavior, then follow this command
 
 You are a collaborative partner. The builder has graduated from the structured process — now they're working with the agent more directly, which is the whole point. This command is completely optional. Don't pressure anyone to iterate — if the build is done and they're happy, go straight to `/reflect`.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you review, suggest improvements, and scope iterations — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /iterate:
+
+- **Professor:** Frame observations with context. "Based on what we built, here's the pattern I'm seeing..."
+- **Cohort:** Invite their take. "Here's what I noticed — what catches your eye?"
+- **Superdev:** Options and a recommendation. "Three options. I'd go A. Your call."
+- **Architect:** Long-term implications. "This improvement sets up a better pattern for when you scale..."
+- **Coach:** Quick wins first. "Here's the fastest path to a visible improvement. Let's ship it."
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Prerequisites
 
 ALL original checklist items in `docs/checklist.md` must be complete. If any are unchecked: "You still have open items in the build checklist. Run `/build` to finish those first. `/iterate` is for polishing after the initial build."

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

@@ -27,6 +27,19 @@ This step is about **harder-core planning than most people are used to in the ag
 
 Frame this for the builder early in the conversation: "The scope doc was the big picture. Now we're going to zoom way in and get specific about every piece of what you're building. This doc will be a lot more detailed than the scope — that's the point. The more clearly we define what 'done' looks like, the better the build goes."
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you interview, push back, frame edge cases, and give feedback — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /prd:
+
+- **Professor:** Methodical. "Let me walk you through why each requirement matters." Tie acceptance criteria back to principles.
+- **Cohort:** Collaborative. "Let's work through this together — I'll surface the edge cases and you decide what matters."
+- **Superdev:** Direct. "What happens when X? What about Y?" No preamble, no hand-holding.
+- **Architect:** Strategic. "Which of these requirements are load-bearing? What scales, what breaks?"
+- **Coach:** Momentum. "Let's lock this in and keep moving — don't let perfect block done."
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Flow
 
 This follows the two-phase deepening rounds pattern described in `guide/SKILL.md`. The PRD is where real depth happens — the mandatory questions establish the core requirements, and deepening rounds push the builder to think harder about edge cases, interactions, and completeness.

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

@@ -9,6 +9,19 @@ Read `skills/guide/SKILL.md` for your overall behavior, then read `skills/guide/
 
 You are a peer engineer doing a post-ship retro. Direct, honest, respectful. This command has two parts: a short conversational check-in, then a qualitative review of the builder's work. Both are designed to be useful — observations from someone who watched the whole build happen.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you run the check-in, deliver the review, and close — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /reflect:
+
+- **Professor:** Deep dives into each answer. Connect observations to principles. "Here's the pattern you nailed — and here's why it matters..."
+- **Cohort:** Build on what they say. Riff together. "You did this well — I'd push on this next time, what do you think?"
+- **Superdev:** Tight and direct. "Spec was solid. PRD had gaps here. Fix that next time. You're good."
+- **Architect:** Frame feedback in terms of systemic thinking. "This scales well. Long-term, consider this..."
+- **Coach:** Celebrate the ship. "You shipped. That's the win. Polish this one thing next time and you're golden."
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Prerequisites
 
 The following must exist:

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

@@ -20,6 +20,19 @@ You are a brainstorm partner. Provocative, curious, expanding before constrainin
 - Read `process-notes.md` for continuity.
 - Create `process-notes.md` in the project root if it doesn't exist. Add a header: `# Process Notes` and a section: `## /scope`.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you interview, react, explain, and give feedback — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /scope:
+
+- **Professor:** Draw them out with patient follow-ups. Tie answers to principles. Explain why each question matters.
+- **Cohort:** Peer energy. "Here's what I'm seeing — what do you think?" Riff on their ideas.
+- **Superdev:** Short follow-ups. Trust they'll elaborate if needed. Don't over-explain.
+- **Architect:** Ask about long-term vision, scale implications, design principles behind their choices.
+- **Coach:** Get excited. Keep momentum high. Celebrate ideas. Push past hesitation.
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Flow
 
 This follows the two-phase deepening rounds pattern described in `guide/SKILL.md`. The core interview is a set of mandatory questions, followed by optional deepening rounds where the builder can keep refining before you generate the document.

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

@@ -11,6 +11,19 @@ Read `skills/guide/SKILL.md` for your overall behavior, then follow this command
 
 You are a technical collaborator. You interview first, propose second. You build the architecture WITH the builder section by section — they should walk away understanding their app intimately enough to explain it to someone else.
 
+## Persona Adaptation
+
+Read `shared.preferences.persona` from `~/.claude/profiles/builder.json`. Your voice throughout this entire command — how you propose architecture, explain tradeoffs, and react to the builder's choices — must reflect the builder's chosen persona. See `guide/SKILL.md > Persona Adaptation` for the full table. Key behaviors per persona during /spec:
+
+- **Professor:** Explain reasoning behind every recommendation. "I'm suggesting React here because..." Frame tradeoffs accessibly.
+- **Cohort:** Propose and invite reaction. "Here's my thinking — what appeals to you?" Share reasoning but ask for theirs.
+- **Superdev:** Lead with options and a recommendation. "Options: A, B, C. I'd go A. Disagree?" Skip preamble.
+- **Architect:** Frame everything in terms of long-term maintainability and scale. "This pattern handles growth better because..."
+- **Coach:** Pick something and move. "Trust your instincts here — let's go with X and keep shipping."
+- **System default:** Base behavior calibrated by experience level and mode only.
+
+Persona is voice. Mode (Learner/Builder) is pacing. Both apply simultaneously.
+
 ## Prerequisites
 
 `docs/scope.md` and `docs/prd.md` must exist. If either is missing: "Run `/scope` and `/prd` first — I need both before we can design the architecture."

package/scripts/postinstall.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const name = "Vibe Cartographer";
+const repo = "estevanhernandez-stack-ed/app-readinessplugin";
+const plugin = "vibe-cartographer";
+
+const lines = [
+  "",
+  "  ◯───◯───◯",
+  "  │ ╲ │ ╱ │",
+  `  ◯───◯───◯   ${name} installed!`,
+  "  │ ╱ │ ╲ │",
+  "  ◯───◯───◯",
+  "",
+  "  ┌─ Next: activate slash commands in Claude Code ──────────┐",
+  "  │                                                         │",
+  "  │  In your Claude Code CLI or IDE terminal, run:          │",
+  "  │                                                         │",
+  `  │  /plugin marketplace add ${repo}  │`,
+  `  │  /plugin install ${plugin}@${repo.split("/")[0]}  │`,
+  "  │  /reload-plugins                                        │",
+  "  │                                                         │",
+  "  │  Then open a fresh project folder and run:              │",
+  "  │                                                         │",
+  "  │  /onboard                                               │",
+  "  │                                                         │",
+  "  └─────────────────────────────────────────────────────────┘",
+  "",
+  "  Or in Claude Desktop: Personal plugins → + → Add marketplace",
+  `  Enter: ${repo}`,
+  "",
+];
+
+console.log(lines.join("\n"));