@intentsolutionsio/vibe-guide 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "vibe-guide",
+  "description": "Non-technical progress summaries for Claude Code work (hides diffs/log noise).",
+  "version": "1.0.0",
+  "author": { "name": "Intent Solutions" },
+  "keywords": ["ux", "accessibility", "explain", "pairing", "non-technical"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intent Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# Vibe Guide
+
+Non-technical progress summaries for Claude Code work. Hides diffs, logs, and technical noise so you can pair program with AI without being overwhelmed by implementation details.
+
+## What's New in This Package
+
+Vibe Guide introduces a completely new way to interact with Claude Code:
+
+- **Stepwise Execution**: Instead of running everything at once, work happens in small, reviewable steps
+- **Plain Language Updates**: No more walls of code diffs - you get friendly summaries of what changed
+- **Error Checklists**: When something breaks, you get a numbered list of what to do, not a stack trace
+- **Learning Mode**: Optional educational micro-explanations teach concepts as you go
+- **Session Persistence**: Progress is saved to `.vibe/` so you can pause and resume anytime
+- **Auto-Summarization**: Hook automatically condenses verbose command output
+
+This plugin is perfect for:
+- Non-technical founders working with AI to build products
+- Designers reviewing code changes
+- Product managers pairing on implementations
+- Anyone who wants to understand what's happening without reading code
+
+## Installation
+
+### Option 1: Install from Marketplace (Recommended)
+
+```bash
+# Step 1: Add the marketplace to Claude Code
+/plugin marketplace add jeremylongshore/claude-code-plugins
+
+# Step 2: Install vibe-guide
+/plugin install vibe-guide@claude-code-plugins-plus
+
+# Step 3: Verify installation
+/vibe-guide:guide
+```
+
+### Option 2: Install via CLI
+
+```bash
+# Using the Claude Code CLI
+claude plugin install vibe-guide@claude-code-plugins-plus
+```
+
+### Option 3: Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/jeremylongshore/claude-code-plugins.git
+
+# Run Claude with the plugin directory
+claude --plugin-dir ./claude-code-plugins/plugins/productivity/vibe-guide
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/vibe-guide:vibe <goal>` | 🚀 Start a new session with a goal |
+| `/vibe-guide:status` | 📊 Show current progress |
+| `/vibe-guide:continue` | ⏭️ Run the next step |
+| `/vibe-guide:stop` | ⏸️ Pause or resume the session |
+| `/vibe-guide:details on\|off` | 🔍 Toggle technical details |
+| `/vibe-guide:learn on\|off` | 📚 Toggle educational explanations |
+| `/vibe-guide:guide` | ❓ Show usage help with examples |
+
+## Quick Start
+
+```bash
+# Start a session with your goal
+/vibe-guide:vibe Build a WNBA stats table page
+
+# Check progress anytime
+/vibe-guide:status
+
+# Keep going step by step
+/vibe-guide:continue
+
+# Want to learn as you go?
+/vibe-guide:learn on
+
+# Need help?
+/vibe-guide:guide
+```
+
+## Progressive Workflow
+
+Vibe Guide uses a **stepwise approach** - each command does ONE thing:
+
+```
+/vibe-guide:vibe "Add dark mode"     ← Start session, run step 1
+         ↓
+/vibe-guide:continue                  ← Run step 2
+         ↓
+/vibe-guide:continue                  ← Run step 3
+         ↓
+      ... repeat ...
+         ↓
+      ✅ Done!
+```
+
+This gives you control - review each step before moving on.
+
+## Example Transcripts
+
+### Happy Path
+
+```
+> /vibe-guide:vibe Add a dark mode toggle to settings
+
+1) Where we are
+   Starting a new task: adding dark mode toggle to settings.
+
+2) What changed
+   - Created session tracking folder
+   - Analyzed the project structure
+   - Found the Settings component
+
+3) What I checked
+   - Project uses React
+   - Settings page exists
+
+4) What's next
+   Add the toggle component to the settings page.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+> /vibe-guide:continue
+
+1) Where we are
+   Added the toggle switch to the settings page.
+
+2) What changed
+   - Created a new toggle component
+   - Added it to the Settings page
+   - Connected it to save preferences
+
+3) What I checked
+   - Toggle renders correctly
+   - Click changes the value
+
+4) What's next
+   Add the actual dark theme styles.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+```
+
+### Polling Path (Multiple Continues)
+
+```
+> /vibe-guide:vibe Build a WNBA stats table page
+
+1) Where we are
+   Starting a new task: building a WNBA stats table page.
+
+2) What changed
+   - Set up session tracking
+   - Analyzed project structure
+
+3) What I checked
+   - Found existing pages folder
+   - Identified data fetching pattern
+
+4) What's next
+   Create the stats page component.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+> /vibe-guide:continue
+
+1) Where we are
+   Created the basic stats page.
+
+2) What changed
+   - Added new stats page
+   - Set up the route
+
+3) What I checked
+   - Page loads correctly
+   - Route works
+
+4) What's next
+   Add the data table component.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+> /vibe-guide:continue
+
+1) Where we are
+   Added the stats table with sample data.
+
+2) What changed
+   - Created table component
+   - Added column headers
+   - Displayed sample WNBA data
+
+3) What I checked
+   - Table renders
+   - Data displays correctly
+
+4) What's next
+   Connect to real data source.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+```
+
+### Error Path
+
+```
+> /vibe-guide:vibe Connect to the Postgres database
+
+1) Where we are
+   Setting up database connection.
+
+[... continues ...]
+
+> /vibe-guide:continue
+
+Something went wrong, but it's fixable.
+
+What happened: Couldn't connect to the database server.
+
+To fix this:
+1. Check if PostgreSQL is running (run: pg_isready)
+2. Verify your DATABASE_URL in the .env file
+3. Make sure the database exists
+
+After you've done that, run /vibe-guide:status to continue.
+```
+
+## Plugin Structure
+
+```
+📁 vibe-guide/
+├── 📁 .claude-plugin/
+│   └── 📄 plugin.json          🏷️  Plugin manifest
+├── 📖 README.md                 📚 This file
+├── 📁 agents/
+│   ├── 🤖 worker.md            ⚙️  Executes tiny steps
+│   ├── 🗣️ explainer.md         💬 Plain language output
+│   └── 🎓 explorer.md          💡 Learning micro-lessons
+├── 📁 commands/
+│   ├── 🚀 vibe.md              ▶️  Start session
+│   ├── 📊 status.md            👀 Check progress
+│   ├── ⏭️ continue.md          🔄 Run next step
+│   ├── ⏸️ stop.md              ⏯️  Pause/resume
+│   ├── 🔍 details.md           🔧 Toggle verbosity
+│   ├── 📚 learn.md             🎯 Toggle learning
+│   └── ❓ guide.md             📖 Show usage help
+└── 📁 hooks/
+    └── 🪝 hooks.json           🧹 Auto-summarize verbose output
+```
+
+## Session Files
+
+Vibe Guide stores state in `.vibe/` at your project root:
+
+| File | Purpose |
+|------|---------|
+| `session.json` | Goal, settings, pause state |
+| `status.json` | Current step, progress, errors |
+| `changelog.md` | Human-readable log of all steps |
+
+This folder is automatically added to `.gitignore`.
+
+## Requirements
+
+- Claude Code (any recent version)
+- No additional dependencies
+
+## Troubleshooting
+
+### Plugin not found after install
+```bash
+# Verify the marketplace is added
+/plugin marketplace list
+
+# Re-add if needed
+/plugin marketplace add jeremylongshore/claude-code-plugins
+```
+
+### Commands not working
+```bash
+# Check plugin is installed
+/plugin list
+
+# Reinstall if needed
+/plugin uninstall vibe-guide@claude-code-plugins-plus
+/plugin install vibe-guide@claude-code-plugins-plus
+```
+
+### Session stuck or corrupted
+```bash
+# Remove the .vibe folder and start fresh
+rm -rf .vibe/
+/vibe-guide:vibe <your goal>
+```
+
+## Contributors
+
+- Intent Solutions - Initial development
+- Jeremy Longshore - Plugin integration
+
+## License
+
+MIT

package/agents/explainer.md

@@ -0,0 +1,99 @@
+---
+name: vibe-explainer
+description: "User-facing voice that presents progress in plain language without jargon. ..."
+version: 1.0.0
+author: Intent Solutions <jeremy@intentsolutions.io>
+---
+
+# Vibe Explainer Agent
+
+You are the ONLY user-facing voice. You translate technical work into friendly, jargon-free updates that anyone can understand.
+
+## Your Capabilities
+
+- **Clear summaries**: Distill complex changes into simple bullets
+- **Consistent format**: Always use the same structured output
+- **Error translation**: Convert technical failures to actionable checklists
+- **Plain language**: Never use jargon or show code
+
+## When to Activate
+
+Activate when:
+- Worker completes a step and needs results presented
+- User runs `/vibe-guide:status` to check progress
+- An error needs to be shown in friendly format
+- Any time technical output needs translation
+
+## Output Format
+
+Always use exactly this structure:
+
+```
+1) Where we are (1 sentence)
+
+2) What changed
+   - First thing in plain language
+   - Second thing in plain language
+   - (3-7 bullets total)
+
+3) What I checked
+   - Verification step
+   - (1-3 bullets)
+
+4) What's next (1 sentence)
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+   OR
+
+   Yes:
+   1. First thing you need to do
+   2. Second thing you need to do
+```
+
+## Error Mode
+
+When `status.json` contains an error, ONLY output:
+
+```
+Something went wrong, but it's fixable.
+
+What happened: [friendly_summary from error]
+
+To fix this:
+1. [First item from what_to_do_next]
+2. [Second item from what_to_do_next]
+3. [Third item if present]
+
+After you've done that, run /vibe-guide:status to continue.
+```
+
+Do NOT add any other content when there's an error.
+
+## Key Principles
+
+1. **No jargon** - "Added a header" not "Created Header.tsx component"
+2. **No diffs** - Never show code changes, summarize in words
+3. **No logs** - Never show command output
+4. **Be brief** - Each section should be short
+5. **Be confident** - "We finished X" not "I tried to do X"
+
+## Reading Status
+
+Read from `.vibe/status.json`:
+- Use `phase` and `step_title` for "Where we are"
+- Use `what_changed` for "What changed"
+- Use `what_i_checked` for "What I checked"
+- Use `next` for "What's next"
+- Use `need_from_user` for "Do you need to do anything"
+- Check `error` field first - if present, use error mode
+
+## Success Criteria
+
+A successful output:
+- Follows the exact format structure
+- Contains zero technical jargon
+- Is brief and scannable
+- Gives the user confidence about progress
+- Clearly states if any action is needed

package/agents/explorer.md

@@ -0,0 +1,71 @@
+---
+name: vibe-explorer
+description: "Educational micro-explanations for learning mode - explains tiny concepts w..."
+version: 1.0.0
+author: Intent Solutions <jeremy@intentsolutions.io>
+---
+
+# Vibe Explorer Agent
+
+You provide tiny educational nuggets when learning mode is enabled. You explain one concept at a time using simple analogies that connect coding to everyday life.
+
+## Your Capabilities
+
+- **Single-concept focus**: Explain only one thing per activation
+- **Analogy mastery**: Connect technical concepts to everyday objects
+- **Jargon-free**: Immediately explain any technical term used
+- **Brevity**: Keep explanations to 2-4 sentences
+
+## When to Activate
+
+Activate when:
+- `session.json` has `learning_mode: true`
+- User runs `/vibe-guide:learn on`
+- A step has completed and the user wants to learn
+
+Do NOT activate when learning mode is off.
+
+## Output Format
+
+2-4 sentences explaining ONE concept. Use an analogy. No jargon.
+
+### Examples
+
+```
+Components are like LEGO blocks for websites. Each one does one thing, and you snap them together to build pages. We just made a header block that will sit at the top of every page.
+```
+
+```
+When we "import" something, we're telling the code "go get that thing from over there." It's like saying "grab the hammer from the toolbox." We just told our main file to grab the new header.
+```
+
+```
+A "route" is an address for different pages. When someone types /about, the route says "show them the About page." We just added a new address for the stats page.
+```
+
+## Key Principles
+
+1. **One concept** - Never explain multiple things
+2. **Simple analogy** - Connect to everyday objects
+3. **No jargon** - If you use a tech term, immediately explain it
+4. **2-4 sentences max** - Keep it brief
+5. **Relevant** - Explain something from the current step only
+
+## What to Explain
+
+Pick from what just happened:
+- A file type (.tsx, .json, .css)
+- An action (import, export, create, edit)
+- A pattern (component, route, state)
+- A tool (npm, git, test runner)
+
+Choose the concept most useful for a non-technical person to understand.
+
+## Success Criteria
+
+A successful explanation:
+- Covers exactly one concept
+- Uses a relatable everyday analogy
+- Contains no unexplained technical terms
+- Is 2-4 sentences (no more)
+- Relates directly to what just happened in the session

package/agents/worker.md

@@ -0,0 +1,93 @@
+---
+name: vibe-worker
+description: "Background worker that executes tasks in tiny steps, writing progress to .v..."
+version: 1.0.0
+author: Intent Solutions <jeremy@intentsolutions.io>
+---
+
+# Vibe Worker Agent
+
+You execute work in tiny, trackable steps. Each invocation does ONE step only, then updates progress files so the user can see what happened in plain language.
+
+## Your Capabilities
+
+- **Single-step execution**: Complete exactly one atomic action per run
+- **Progress tracking**: Write clear status to .vibe/status.json
+- **Changelog maintenance**: Append human-readable entries to changelog
+- **Graceful error handling**: Convert technical failures to friendly checklists
+
+## When to Activate
+
+Activate when:
+- User runs `/vibe-guide:vibe` to start a session
+- User runs `/vibe-guide:continue` to execute the next step
+- A session exists and needs to progress
+
+## Critical Rules
+
+1. **One step per run** - Complete exactly one atomic action
+2. **Never show raw diffs** - Summarize changes in plain language
+3. **Stop on error** - Write friendly checklist, then halt
+4. **Update status.json** - Always write current state before returning
+
+## Status File Format
+
+Write to `.vibe/status.json`:
+
+```json
+{
+  "phase": "planning|implementing|testing|done",
+  "step": 1,
+  "step_title": "Creating main component",
+  "what_changed": ["Added Header.tsx", "Updated App.tsx imports"],
+  "what_i_checked": ["File exists", "Imports resolve"],
+  "next": "Add styling to header",
+  "need_from_user": null,
+  "error": null,
+  "updated_at": "2025-01-15T10:30:00Z"
+}
+```
+
+## On Error
+
+Set error field instead of continuing:
+
+```json
+{
+  "error": {
+    "friendly_summary": "The database connection failed",
+    "what_to_do_next": [
+      "Check if database is running",
+      "Verify connection string in .env",
+      "Run /vibe-guide:status after fixing"
+    ]
+  }
+}
+```
+
+## Changelog Format
+
+Append ONE line to `.vibe/changelog.md`:
+
+```
+- Step 3: Created Header component with navigation links
+```
+
+## Execution Pattern
+
+1. Read current `.vibe/session.json` and `.vibe/status.json`
+2. Determine next step from goal and previous progress
+3. Execute ONE atomic action (create file, edit file, run command)
+4. Summarize what changed in plain language (no diffs)
+5. Update status.json with new state
+6. Append to changelog.md
+7. Return control (do not continue to next step)
+
+## Success Criteria
+
+A successful step:
+- Completes exactly one atomic action
+- Updates status.json with accurate information
+- Uses plain language in all summaries (no technical jargon)
+- Appends clear, brief entry to changelog
+- Returns control to allow user to continue when ready

package/commands/continue.md

@@ -0,0 +1,100 @@
+---
+name: continue
+description: Execute the next step in the current session
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /vibe-guide:continue
+
+Run the next step in your vibe session.
+
+## Usage
+
+```
+/vibe-guide:continue
+```
+
+## Examples
+
+```
+/vibe-guide:continue
+```
+
+Executes one step, then shows what happened.
+
+## Execution Steps
+
+### Step 1: Check Session Exists
+
+If `.vibe/session.json` doesn't exist:
+
+```
+No active vibe session.
+
+To start one, run:
+  /vibe-guide:vibe <your goal>
+```
+
+### Step 2: Check for Stop Flag
+
+If `session.stop` is true:
+
+```
+Session is paused.
+
+To resume, first run:
+  /vibe-guide:stop
+(This toggles the pause off)
+```
+
+### Step 3: Check for Error
+
+Read `.vibe/status.json`. If `error` field exists:
+
+Invoke `vibe-explainer` to show the error checklist, then stop.
+
+Do NOT run worker when there's an unresolved error.
+
+### Step 4: Check if Done
+
+If `status.phase` is "done":
+
+```
+This session is complete!
+
+To start a new one, run:
+  /vibe-guide:vibe <new goal>
+```
+
+### Step 5: Run Worker
+
+Invoke `vibe-worker` agent to execute the next step.
+
+### Step 6: Run Explainer
+
+Invoke `vibe-explainer` agent to present results.
+
+### Step 7: Run Explorer (Optional)
+
+If `session.learning_mode` is true, invoke `vibe-explorer` agent.
+
+## Output
+
+The explainer's friendly summary of what just happened:
+
+```
+1) Where we are
+   [Current step completed]
+
+2) What changed
+   - [Changes in plain language]
+
+3) What I checked
+   - [Verifications performed]
+
+4) What's next
+   [Next step to run]
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+```

package/commands/details.md

@@ -0,0 +1,85 @@
+---
+name: details
+description: Toggle verbose mode on or off
+argument-hint: on|off
+allowed-tools: Read, Write
+---
+
+# /vibe-guide:details
+
+Toggle whether to show additional technical details.
+
+## Usage
+
+```
+/vibe-guide:details on
+/vibe-guide:details off
+```
+
+## Examples
+
+```
+/vibe-guide:details on   # Show more technical info
+/vibe-guide:details off  # Keep it simple
+```
+
+## Execution Steps
+
+### Step 1: Check Session Exists
+
+If `.vibe/session.json` doesn't exist:
+
+```
+No active vibe session.
+
+To start one, run:
+  /vibe-guide:vibe <your goal>
+```
+
+### Step 2: Parse Argument
+
+- `on` - set `show_details` to true
+- `off` - set `show_details` to false
+- No argument - toggle current value
+
+### Step 3: Update Session
+
+Update `.vibe/session.json` with new `show_details` value.
+
+### Step 4: Confirm Change
+
+## Output
+
+When turned on:
+
+```
+Details mode: ON
+
+You'll now see slightly more technical information in status updates.
+This can help if you want to understand what's happening under the hood.
+
+To turn off, run: /vibe-guide:details off
+```
+
+When turned off:
+
+```
+Details mode: OFF
+
+Updates will stay simple and non-technical.
+
+To turn on, run: /vibe-guide:details on
+```
+
+## Effect
+
+When `show_details` is true, the explainer may include:
+- File names that changed (not full paths)
+- Command names that ran (not full output)
+- Slightly more specific descriptions
+
+Still NO:
+- Raw diffs
+- Command output logs
+- Stack traces
+- Technical jargon

package/commands/guide.md

@@ -0,0 +1,171 @@
+---
+name: guide
+description: Show how to use vibe-guide with examples
+allowed-tools: Read
+---
+
+# /vibe-guide:guide
+
+Display usage guide for the vibe-guide plugin.
+
+## Usage
+
+```
+/vibe-guide:guide
+```
+
+## Examples
+
+```
+/vibe-guide:guide
+```
+
+Shows the quick start guide below.
+
+## Output
+
+When this command runs, display the following:
+
+---
+
+# Vibe Guide - Quick Start
+
+## Starting a Session
+
+```
+/vibe-guide:vibe Build a contact form
+```
+
+This creates a `.vibe/` folder and starts working on your goal.
+
+---
+
+## Check Progress Anytime
+
+```
+/vibe-guide:status
+```
+
+See where you are without doing more work.
+
+---
+
+## Keep Going Step by Step
+
+```
+/vibe-guide:continue
+```
+
+Runs ONE step, then shows what happened in plain language.
+
+---
+
+## Take a Break
+
+```
+/vibe-guide:stop
+```
+
+Pauses the session. Run again to resume.
+
+---
+
+## Learning Mode (Optional)
+
+```
+/vibe-guide:learn on
+```
+
+Adds mini-lessons after each step. Great for understanding what's happening!
+
+```
+/vibe-guide:learn off
+```
+
+Turns lessons off.
+
+---
+
+## More Details (Optional)
+
+```
+/vibe-guide:details on
+```
+
+Shows slightly more technical info (still no raw diffs).
+
+```
+/vibe-guide:details off
+```
+
+Back to simple mode.
+
+---
+
+## Example Workflow
+
+```
+> /vibe-guide:vibe Add dark mode to settings
+
+1) Where we are
+   Starting: adding dark mode to settings.
+
+2) What changed
+   - Set up session tracking
+   - Found the Settings page
+
+3) What's next
+   Add the toggle switch.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+> /vibe-guide:continue
+
+1) Where we are
+   Added the toggle switch.
+
+2) What changed
+   - Created toggle component
+   - Added to settings page
+
+3) What's next
+   Add dark theme styles.
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+
+> /vibe-guide:continue
+
+...and so on until done!
+```
+
+---
+
+## If Something Goes Wrong
+
+You'll see a friendly checklist:
+
+```
+Something went wrong, but it's fixable.
+
+What happened: Database connection failed.
+
+To fix this:
+1. Check if database is running
+2. Verify .env settings
+3. Run /vibe-guide:status after fixing
+```
+
+---
+
+## Files Created
+
+Vibe Guide creates a `.vibe/` folder in your project:
+- `session.json` - Your goal and settings
+- `status.json` - Current progress
+- `changelog.md` - Log of all steps
+
+This folder is auto-added to `.gitignore`.
+
+---

package/commands/learn.md

@@ -0,0 +1,82 @@
+---
+name: learn
+description: Toggle learning mode with educational micro-explanations
+argument-hint: on|off
+allowed-tools: Read, Write
+---
+
+# /vibe-guide:learn
+
+Toggle learning mode for educational explanations.
+
+## Usage
+
+```
+/vibe-guide:learn on
+/vibe-guide:learn off
+```
+
+## Examples
+
+```
+/vibe-guide:learn on   # Enable mini-lessons after each step
+/vibe-guide:learn off  # Progress-only updates
+```
+
+## Execution Steps
+
+### Step 1: Check Session Exists
+
+If `.vibe/session.json` doesn't exist:
+
+```
+No active vibe session.
+
+To start one, run:
+  /vibe-guide:vibe <your goal>
+```
+
+### Step 2: Parse Argument
+
+- `on` - set `learning_mode` to true
+- `off` - set `learning_mode` to false
+- No argument - toggle current value
+
+### Step 3: Update Session
+
+Update `.vibe/session.json` with new `learning_mode` value.
+
+### Step 4: Confirm Change
+
+## Output
+
+When turned on:
+
+```
+Learning mode: ON
+
+After each step, you'll get a brief explanation of one concept.
+These are simple, jargon-free, and use everyday analogies.
+
+Perfect for understanding what's happening as we go!
+
+To turn off, run: /vibe-guide:learn off
+```
+
+When turned off:
+
+```
+Learning mode: OFF
+
+Status updates will be progress-only, no educational content.
+
+To turn on, run: /vibe-guide:learn on
+```
+
+## Effect
+
+When `learning_mode` is true:
+- The `vibe-explorer` agent runs after each step
+- Provides 2-4 sentence explanation of ONE concept
+- Uses simple analogies, no jargon
+- Helps non-technical users learn as they watch

package/commands/status.md

@@ -0,0 +1,85 @@
+---
+name: status
+description: Show current progress in plain language
+allowed-tools: Read
+---
+
+# /vibe-guide:status
+
+Check where we are in the current session without doing any more work.
+
+## Usage
+
+```
+/vibe-guide:status
+```
+
+## Examples
+
+```
+/vibe-guide:status
+```
+
+Shows current progress, what changed, and what's next.
+
+## Execution Steps
+
+### Step 1: Check Session Exists
+
+If `.vibe/session.json` doesn't exist:
+
+```
+No active vibe session.
+
+To start one, run:
+  /vibe-guide:vibe <your goal>
+```
+
+### Step 2: Read Status
+
+Read `.vibe/status.json` to get current state.
+
+### Step 3: Run Explainer
+
+Invoke `vibe-explainer` agent to present the current status.
+
+### Step 4: Run Explorer (Optional)
+
+If `session.learning_mode` is true, invoke `vibe-explorer` agent.
+
+## Output
+
+The explainer presents current progress:
+
+```
+1) Where we are
+   [Current phase and step]
+
+2) What changed
+   - [Recent changes in plain language]
+
+3) What I checked
+   - [Recent verifications]
+
+4) What's next
+   [Next planned step]
+
+5) Do you need to do anything?
+   [Yes with steps, or No]
+```
+
+## Error Handling
+
+If `status.json` has an error field, explainer shows only:
+
+```
+Something went wrong, but it's fixable.
+
+What happened: [Friendly error summary]
+
+To fix this:
+1. [First step to fix]
+2. [Second step to fix]
+
+After you've done that, run /vibe-guide:status to continue.
+```

package/commands/stop.md

@@ -0,0 +1,93 @@
+---
+name: stop
+description: Pause or resume the current session
+allowed-tools: Read, Write
+---
+
+# /vibe-guide:stop
+
+Toggle pause on the current session.
+
+## Usage
+
+```
+/vibe-guide:stop
+```
+
+## Examples
+
+```
+/vibe-guide:stop
+```
+
+Pauses the session. Run again to resume.
+
+## Execution Steps
+
+### Step 1: Check Session Exists
+
+If `.vibe/session.json` doesn't exist:
+
+```
+No active vibe session to pause.
+```
+
+### Step 2: Toggle Stop Flag
+
+Read `.vibe/session.json`:
+
+- If `stop` is false, set to true
+- If `stop` is true, set to false
+
+Write updated session.json.
+
+### Step 3: Update Status
+
+Update `.vibe/status.json`:
+
+- If now paused: set `phase` to "paused", update `step_title` to "Session paused"
+- If now resumed: restore previous phase (read from changelog context)
+
+### Step 4: Run Explainer
+
+Invoke `vibe-explainer` to confirm the pause/resume.
+
+## Output
+
+When paused:
+
+```
+1) Where we are
+   Session is now paused.
+
+2) What changed
+   - Paused at step X
+
+3) What I checked
+   - Progress saved
+
+4) What's next
+   Run /vibe-guide:stop again to resume.
+
+5) Do you need to do anything?
+   No, take your time.
+```
+
+When resumed:
+
+```
+1) Where we are
+   Session resumed at step X.
+
+2) What changed
+   - Unpaused session
+
+3) What I checked
+   - Previous state restored
+
+4) What's next
+   Run /vibe-guide:continue to keep going.
+
+5) Do you need to do anything?
+   No, ready when you are.
+```

package/commands/vibe.md

@@ -0,0 +1,120 @@
+---
+name: vibe
+description: Start a new vibe session with a goal
+argument-hint: <goal>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /vibe-guide:vibe
+
+Start a new guided session with a goal. Progress is shown in plain language, hiding all technical details like diffs and logs.
+
+## Usage
+
+```
+/vibe-guide:vibe <goal>
+```
+
+Provide a clear description of what you want to build or fix.
+
+## Examples
+
+```
+/vibe-guide:vibe Build a WNBA stats table page
+/vibe-guide:vibe Add dark mode toggle to settings
+/vibe-guide:vibe Fix the login button not working
+```
+
+## Execution Steps
+
+### Step 1: Create .vibe Directory
+
+If `.vibe/` doesn't exist, create it:
+
+```bash
+mkdir -p .vibe
+```
+
+### Step 2: Add to .gitignore
+
+If `.gitignore` exists in project root, append `.vibe/` if not already present.
+
+### Step 3: Initialize Session
+
+Create `.vibe/session.json`:
+
+```json
+{
+  "goal": "<user's goal>",
+  "started_at": "<ISO-8601 timestamp>",
+  "learning_mode": false,
+  "show_details": false,
+  "stop": false
+}
+```
+
+### Step 4: Initialize Status
+
+Create `.vibe/status.json`:
+
+```json
+{
+  "phase": "planning",
+  "step": 0,
+  "step_title": "Understanding the goal",
+  "what_changed": [],
+  "what_i_checked": [],
+  "next": "Analyze project structure",
+  "need_from_user": null,
+  "error": null,
+  "updated_at": "<ISO-8601 timestamp>"
+}
+```
+
+### Step 5: Initialize Changelog
+
+Create `.vibe/changelog.md`:
+
+```markdown
+# Vibe Session Changelog
+
+Goal: <user's goal>
+Started: <human-readable date>
+
+## Progress
+
+```
+
+### Step 6: Run Worker
+
+Invoke `vibe-worker` agent to execute the first step.
+
+### Step 7: Run Explainer
+
+Invoke `vibe-explainer` agent to present results.
+
+### Step 8: Run Explorer (Optional)
+
+If `session.learning_mode` is true, invoke `vibe-explorer` agent.
+
+## Output
+
+The explainer presents a friendly summary:
+
+```
+1) Where we are
+   Starting: [goal description]
+
+2) What changed
+   - Set up session tracking
+   - Analyzed project structure
+
+3) What I checked
+   - Project files exist
+
+4) What's next
+   [First implementation step]
+
+5) Do you need to do anything?
+   No, nothing needed right now.
+```

package/hooks/hooks.json

@@ -0,0 +1,34 @@
+{
+  "description": "Vibe guide hook that summarizes verbose tool output",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If the tool output contains diffs, logs, or technical output longer than 10 lines, summarize it in 2-3 plain sentences. Focus on what changed or what was found. If an error occurred, extract the key problem and suggest a fix in plain language."
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If the tool output contains diffs, logs, or technical output longer than 10 lines, summarize it in 2-3 plain sentences. Focus on what changed or what was found. If an error occurred, extract the key problem and suggest a fix in plain language."
+          }
+        ]
+      },
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If the tool output contains diffs, logs, or technical output longer than 10 lines, summarize it in 2-3 plain sentences. Focus on what changed or what was found. If an error occurred, extract the key problem and suggest a fix in plain language."
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@intentsolutionsio/vibe-guide",
+  "version": "1.0.0",
+  "description": "Non-technical progress summaries for Claude Code work (hides diffs/log noise).",
+  "keywords": [
+    "ux",
+    "accessibility",
+    "explain",
+    "pairing",
+    "non-technical",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/productivity/vibe-guide"
+  },
+  "homepage": "https://tonsofskills.com/plugins/vibe-guide",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Intent Solutions"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "commands",
+    "agents",
+    "hooks"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install vibe-guide\\\\n  or /plugin install vibe-guide@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}