@boshu2/vibe-check 1.7.0 → 1.8.1

package/docs/FEATURES.md

@@ -0,0 +1,340 @@
+# vibe-check: Feature Guide
+
+**Measure AI-assisted development sessions**
+
+---
+
+## What is Vibe-Coding?
+
+Vibe-coding is a methodology for AI-assisted software development that emphasizes:
+
+1. **Conscious calibration** - Knowing when to trust AI output and when to verify
+2. **Metric-driven feedback** - Measuring patterns, not productivity
+3. **Self-awareness** - Recognizing spirals before they consume hours
+4. **Progressive mastery** - Building trust through demonstrated accuracy
+
+The core insight: **AI assistance varies in reliability by task type.** Formatting code? Nearly 100% trustworthy. Designing authentication architecture? Maybe 20%. Vibe-coding gives you a framework to calibrate your verification effort appropriately.
+
+---
+
+## The Five Core Metrics
+
+| Metric | Question | Elite | Needs Work |
+|--------|----------|-------|------------|
+| **Trust Pass Rate** | What % of commits don't need immediate fixes? | >95% | <80% |
+| **Rework Ratio** | What % of commits are fixes vs. new work? | <30% | >50% |
+| **Debug Spiral Count** | How many fix-chain spirals detected? | 0 | 3+ |
+| **Debug Spiral Duration** | How long stuck in fix loops? | <15min | >45min |
+| **Flow Efficiency** | What % of time is productive building? | >90% | <70% |
+
+These metrics are **semantic-free** - they measure git patterns, not code content. This prevents gaming and ensures honest signal.
+
+---
+
+## Vibe Levels
+
+Before starting work, classify the task:
+
+| Level | Name | Trust AI | Verification | Example Tasks |
+|-------|------|----------|--------------|---------------|
+| **5** | Full Automation | 95% | Final only | Formatting, linting, boilerplate |
+| **4** | High Trust | 80% | Spot check | CRUD, simple features |
+| **3** | Balanced | 60% | Key outputs | Standard features, tests |
+| **2** | Careful | 40% | Every change | API integrations, complex logic |
+| **1** | Skeptical | 20% | Every line | Architecture, security, auth |
+| **0** | Manual | 0% | N/A | Novel research, exploration |
+
+**The insight:** Declaring a level upfront forces conscious calibration. After the session, compare actual metrics to expected - this builds intuition over time.
+
+---
+
+## vibe-check: The Tool
+
+`vibe-check` is a CLI tool that analyzes git history and provides immediate feedback on your coding patterns.
+
+### Installation
+
+```bash
+npm install -g @boshu2/vibe-check
+```
+
+Or run directly:
+
+```bash
+npx @boshu2/vibe-check
+```
+
+### Core Commands
+
+```bash
+# Basic analysis
+vibe-check --since "1 week ago"
+
+# Real-time monitoring
+vibe-check watch
+
+# Your profile (gamification)
+vibe-check profile
+
+# Start a tracked session
+vibe-check start --level 3
+```
+
+---
+
+## Feature Overview (v1.7.0)
+
+### 1. Metrics Engine
+
+The core analysis engine examines git history to compute:
+
+- **Trust Pass Rate**: Commits without immediate fix follow-ups
+- **Rework Ratio**: Proportion of fix/revert commits
+- **Debug Spirals**: Consecutive fix commits on same component
+- **VibeScore**: Weighted composite (0-100%)
+
+Output example:
+```
+VIBE-CHECK Nov 21 - Nov 28
+
+  Rating: ELITE
+  Trust: 94% ELITE
+  Rework: 18% ELITE
+  Spirals: 1 detected (12 min)
+
+  VibeScore: 87%
+```
+
+### 2. Watch Mode
+
+Real-time spiral detection while you work:
+
+```bash
+vibe-check watch
+```
+
+Monitors commits and alerts when patterns indicate a spiral forming:
+
+```
+  09:15 fix(auth) handle token refresh
+  09:18 fix(auth) add retry logic
+  09:22 fix(auth) increase timeout
+
+  SPIRAL DETECTED
+      Component: auth
+      Fixes: 3 commits, 7 min
+```
+
+### 3. Session Integration
+
+Track sessions with baseline comparison:
+
+```bash
+vibe-check session start --level 3   # Start session
+vibe-check session status            # Check active session
+vibe-check session end --format json # End and get metrics
+```
+
+Output includes failure pattern detection for AgentOps integration.
+
+---
+
+## Gamification System
+
+vibe-check includes a complete gamification layer to make improvement engaging:
+
+### XP & Levels
+
+```
+Level 1: Novice       (0-100 XP)      🌱
+Level 2: Apprentice   (100-300 XP)    🌿
+Level 3: Practitioner (300-600 XP)    🌳
+Level 4: Expert       (600-1000 XP)   🌲
+Level 5: Master       (1000-2000 XP)  🎋
+Level 6: Grandmaster  (2000-5000 XP)  🏔️
+```
+
+**Prestige tiers** (beyond Grandmaster):
+- Archmage (5000+ XP) 🔮
+- Sage (10000+ XP) 📿
+- Zenmester (20000+ XP) ☯️
+- Transcendent (40000+ XP) 🌟
+- Legendary (80000+ XP) 💫
+
+### Streaks
+
+Daily check-ins build streaks with visual progression:
+
+```
+🔥 5-day streak (1-5 days)
+🌟🌟 12-day streak (6-14 days)
+👑👑👑 18-day streak 🏆 (15+ days, Personal Best!)
+```
+
+Streak freezes protect against occasional missed days.
+
+### Achievements (19 total)
+
+Categories:
+- **Consistency**: First Blood, Week Warrior, Streak Master
+- **Quality**: Elite Vibes, Trust Builder, Zen Master
+- **Volume**: Centurion, Marathon Coder
+- **Improvement**: Comeback Kid, On Fire
+- **Special**: Night Owl, Early Bird, Weekend Warrior
+
+---
+
+## Integration Points
+
+### Git Hook
+
+Automatic vibe-check on every push:
+
+```bash
+vibe-check init-hook           # Install hook
+vibe-check init-hook --block-low  # Block LOW pushes
+```
+
+### GitHub Action
+
+Automated PR feedback:
+
+```yaml
+name: Vibe Check
+on: [pull_request]
+
+jobs:
+  vibe-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: boshu2/vibe-check@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### JSON Output
+
+Machine-readable for dashboards/CI:
+
+```bash
+vibe-check --format json --output vibe-results.json
+```
+
+---
+
+## The Workflow
+
+### Daily Practice
+
+```
+Morning:
+1. vibe-check profile         # Check streak, challenges
+2. Plan tasks, estimate levels
+
+During work:
+3. vibe-check watch           # Real-time monitoring
+4. Notice spiral alerts, intervene early
+
+End of session:
+5. vibe-check --since "today" # Review session
+6. XP/achievements auto-update
+```
+
+### Session Workflow (Optional)
+
+For explicit tracking:
+
+```bash
+# Before: declare expectation
+vibe-check start --level 3
+
+# ... work ...
+
+# After: compare reality
+vibe-check --since "1 hour ago"
+```
+
+The tool will show whether your level classification was accurate.
+
+---
+
+## Philosophy
+
+### What vibe-check IS
+
+- A self-reflection tool
+- A pattern detector
+- A gamified improvement system
+- A calibration feedback loop
+
+### What vibe-check IS NOT
+
+- A productivity metric
+- A performance review tool
+- A surveillance system
+- A judgment of AI effectiveness
+
+**Use it for yourself, not for measuring others.**
+
+---
+
+## The Science
+
+vibe-check uses **semantic-free signals** - patterns in git history that indicate workflow health without reading code content. This approach:
+
+1. **Can't be gamed** - You can't fake commit timestamps
+2. **Respects privacy** - Never reads actual code
+3. **Is universal** - Works for any language/framework
+4. **Provides honest signal** - Measures behavior, not intention
+
+The VibeScore combines metrics using validated weights derived from empirical analysis of productive vs. struggling sessions.
+
+---
+
+## Future Roadmap
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| CLI Core | ✅ Complete | Metrics, scoring, analysis |
+| Gamification | ✅ Complete | XP, streaks, achievements |
+| Watch Mode | ✅ Complete | Real-time spiral detection |
+| GitHub Action | ✅ Complete | Automated PR feedback |
+| Session Integration | ✅ Complete | AgentOps integration |
+| Visual Dashboard | ✅ Complete | HTML dashboard with charts |
+| VS Code Extension | 🔮 Planned | Status bar, live alerts |
+
+---
+
+## Getting Started
+
+```bash
+# Install
+npm install -g @boshu2/vibe-check
+
+# Run your first check
+vibe-check --since "1 week ago"
+
+# See your profile
+vibe-check profile
+
+# Start watching
+vibe-check watch
+```
+
+---
+
+## Resources
+
+- **npm**: [@boshu2/vibe-check](https://www.npmjs.com/package/@boshu2/vibe-check)
+- **GitHub**: [boshu2/vibe-check](https://github.com/boshu2/vibe-check)
+- **Issues**: [Report bugs or request features](https://github.com/boshu2/vibe-check/issues)
+
+---
+
+*"The goal isn't perfect metrics. It's conscious awareness of your patterns."*
+
+**Version:** 1.7.0
+**Last Updated:** 2025-12-02

package/docs/GAMIFICATION.md

@@ -1,12 +1,12 @@
 # vibe-check Gamification System
 
-**Deep dive into XP, levels, achievements, challenges, and more**
+**XP, levels, streaks, and achievements for self-improvement**
 
 ---
 
 ## Overview
 
-vibe-check includes a complete gamification layer to make self-improvement engaging. This isn't productivity surveillance—it's a personal game you play with yourself.
+vibe-check includes a gamification layer to make self-improvement engaging. This isn't productivity surveillance—it's a personal game you play with yourself.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -14,8 +14,8 @@ vibe-check includes a complete gamification layer to make self-improvement engag
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
-│  │    XP    │  │  Streaks │  │ Achieve- │  │Challenge │   │
-│  │ & Levels │  │          │  │  ments   │  │    s     │   │
+│  │    XP    │  │  Streaks │  │ Achieve- │  │  Weekly  │   │
+│  │ & Levels │  │          │  │  ments   │  │  Stats   │   │
 │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
 │       │             │             │             │          │
 │       └─────────────┴──────┬──────┴─────────────┘          │
@@ -23,12 +23,7 @@ vibe-check includes a complete gamification layer to make self-improvement engag
 │                     ┌──────┴──────┐                        │
 │                     │   Profile   │                        │
 │                     │   Storage   │                        │
-│                     └──────┬──────┘                        │
-│                            │                               │
-│  ┌──────────┐  ┌──────────┴──────────┐  ┌──────────┐     │
-│  │ Leader-  │  │     Hall of Fame    │  │  Badges  │     │
-│  │  boards  │  │                     │  │          │     │
-│  └──────────┘  └─────────────────────┘  └──────────┘     │
+│                     └─────────────┘                        │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -50,7 +45,6 @@ vibe-check includes a complete gamification layer to make self-improvement engag
 | No spirals | +15 | Bonus for 0 spirals |
 | Perfect trust | +20 | 100% trust pass rate |
 | Achievement unlock | +25-100 | Varies by achievement |
-| Challenge complete | +30-150 | Based on difficulty |
 
 ### XP Calculation Example
 
@@ -96,13 +90,13 @@ if (previousSession.periodFrom === currentPeriodFrom &&
 
 After reaching Grandmaster, prestige tiers unlock:
 
-| Tier | Name | XP Range | Icon | Time Estimate |
-|------|------|----------|------|---------------|
-| 1 | Archmage | 5000-9999 | 🔮 | ~3 months |
-| 2 | Sage | 10000-19999 | 📿 | ~6 months |
-| 3 | Zenmester | 20000-39999 | ☯️ | ~1 year |
-| 4 | Transcendent | 40000-79999 | 🌟 | ~2 years |
-| 5 | Legendary | 80000+ | 💫 | Long-term mastery |
+| Tier | Name | XP Range | Icon |
+|------|------|----------|------|
+| 1 | Archmage | 5000-9999 | 🔮 |
+| 2 | Sage | 10000-19999 | 📿 |
+| 3 | Zenmester | 20000-39999 | ☯️ |
+| 4 | Transcendent | 40000-79999 | 🌟 |
+| 5 | Legendary | 80000+ | 💫 |
 
 ### Level Display
 
@@ -215,131 +209,6 @@ Recent:
 
 ---
 
-## Weekly Challenges
-
-### How Challenges Work
-
-- **Generated weekly**: Based on your weak metrics
-- **3 challenges per week**: 1 targeted + 2 random
-- **Progress tracked**: Updates after each session
-- **XP rewards**: 30-150 XP per challenge
-
-### Challenge Types
-
-| Type | Name | Description | Targets |
-|------|------|-------------|---------|
-| `TRUST_STREAK` | Trust Gauntlet | Get 90%+ trust N times | 3, 5, 7 |
-| `ZERO_SPIRALS` | Zen Mode | N sessions with 0 spirals | 3, 5, 7 |
-| `ELITE_COUNT` | Elite Streak | Get N ELITE ratings | 2, 4, 6 |
-| `COMMIT_VOLUME` | Commit Champion | Analyze N+ commits | 50, 100, 200 |
-| `STREAK_EXTEND` | Streak Builder | Extend streak by N days | 3, 5, 7 |
-
-### Challenge Display
-
-```
-WEEKLY CHALLENGES
-
-🎯 Trust Gauntlet:  ████████░░  4/5 (+100 XP)
-🧘 Zen Mode:        ██████████  ✓ COMPLETE
-🔥 Streak Builder:  ██░░░░░░░░  1/5 (+40 XP)
-```
-
-### Challenge Selection Algorithm
-
-1. Analyze recent session metrics
-2. Identify weak areas (low trust? many spirals?)
-3. Generate 1 challenge targeting weakness (medium difficulty)
-4. Generate 2 random challenges (easy difficulty)
-
----
-
-## Leaderboards
-
-### Personal Leaderboards
-
-Track your high scores across all repos:
-
-```
-🏆 All-Time Top Scores
-
-🥇 96% ELITE  my-project (Nov 15)
-🥈 94% ELITE  vibe-check (Nov 28)
-🥉 91% ELITE  other-repo (Nov 20)
-4. 89% HIGH   work-app (Nov 18)
-5. 87% HIGH   side-project (Nov 10)
-```
-
-### Per-Repo Leaderboards
-
-```
-📊 Top Scores - vibe-check
-
-🥇 94% ELITE  Nov 28
-🥈 91% ELITE  Nov 27
-🥉 88% HIGH   Nov 26
-```
-
-### Data Stored
-
-```typescript
-interface LeaderboardEntry {
-  date: string;
-  repoPath: string;
-  repoName: string;
-  vibeScore: number;
-  overall: string;
-  commits: number;
-  xpEarned: number;
-}
-```
-
----
-
-## Hall of Fame
-
-Personal bests and records:
-
-```
-🏛️  HALL OF FAME
-
-🏆 Best Score: 96% (Nov 15)
-   my-project - ELITE rating
-
-🔥 Longest Streak: 15 days
-   Consecutive daily check-ins
-
-⚡ Best Week: 847 XP
-   Week of Nov 11
-
-📊 Most Commits: 127 (Nov 10)
-   big-refactor - single session
-```
-
----
-
-## Rank Badges
-
-Tier badges based on cumulative progress:
-
-| Badge | Icon | Requirement |
-|-------|------|-------------|
-| Bronze | 🥉 | 10+ sessions |
-| Silver | 🥈 | 50+ sessions |
-| Gold | 🥇 | 100+ sessions |
-| Platinum | 💎 | 14+ day streak |
-| Diamond | 🔷 | 5000+ XP |
-
-### Badge Display
-
-```
-Current: 💎 Platinum Tier
-
-Next: 🔷 Diamond (need 5000 XP, have 3200)
-Progress: ████████████░░░░  64%
-```
-
----
-
 ## Weekly Stats
 
 ### Sparklines
@@ -352,7 +221,6 @@ Visual trend of your scores this week:
    Avg Score: 87% ↑
    Sessions: 5
    XP Earned: 320
-   ELITE: 3 | Spirals: 2
 
    Trend: ▂▄▃▆▅██
 ```
@@ -367,129 +235,26 @@ Visual trend of your scores this week:
 
 ---
 
-## Pattern Memory
-
-Tracks YOUR spiral triggers over time:
-
-```
-YOUR SPIRAL TRIGGERS
-
-  Pattern      Times   Avg Duration
-  SECRETS_AUTH   5     18 min
-  VOLUME_CONFIG  3     12 min
-  API_MISMATCH   2     25 min
-
-Your kryptonite: OAuth/token issues
-Consider: Tracer tests for auth flows
-```
-
----
-
-## Intervention Tracking
-
-Records what breaks YOUR spirals:
-
-```
-WHAT WORKS FOR YOU
-
-  Intervention   Times   Success Rate
-  Take a break     4     75%
-  Write test       3     100%
-  Read docs        2     50%
-  Ask for help     1     100%
-
-Recommendation: Write a test first!
-```
-
-### Intervention Types
-
-| Type | Description |
-|------|-------------|
-| `TRACER_TEST` | Wrote a test to validate |
-| `BREAK` | Took a break |
-| `DOCS` | Consulted documentation |
-| `REFACTOR` | Changed approach |
-| `HELP` | Asked for help |
-| `ROLLBACK` | Reverted to known state |
-| `OTHER` | Custom intervention |
-
----
-
-## Share Feature
-
-### Shareable Text
-
-```bash
-vibe-check profile --share
-```
-
-Output:
-```
-🎮 bodefuller's Vibe-Check Profile
-
-Level 5 Master (Archmage I) 💎 Platinum
-1,250 Total XP
-
-🔥 12-day streak (Best: 15)
-📊 45 sessions | Avg: 87% | Best: 96%
-🏆 12 achievements unlocked
-
-Track your coding vibes: npx @boshu2/vibe-check
-```
-
-### Shareable JSON
-
-```bash
-vibe-check profile --share-json
-```
-
-Machine-readable profile for integrations.
-
----
-
-## Near-Miss Psychology
-
-Motivational messages when you're close to achievements:
-
-```
-🎯 SO CLOSE!
-
-Just 1-2 metrics away from ELITE overall!
-88% vibe score - just 2% from the Ninety Club!
-```
-
-Triggers when:
-- HIGH rating with 3+ ELITE metrics
-- Score 85-89% (close to 90)
-- Trust 90-99% (close to 100)
-- 1 spiral (close to Zen Master)
-
----
-
 ## Profile Storage
 
 ### Location
 
 ```
 ~/.vibe-check/
-├── profile.json       # Main profile
-└── leaderboards.json  # High scores
+└── profile.json       # Main profile
 ```
 
 ### Profile Schema
 
 ```typescript
 interface UserProfile {
-  version: string;           // "1.5.0"
+  version: string;
   createdAt: string;
   updatedAt: string;
   streak: StreakState;
   xp: XPState;
   achievements: Achievement[];
   sessions: SessionRecord[];
-  patternMemory?: PatternMemory;
-  interventionMemory?: InterventionMemory;
-  challenges?: Challenge[];
   preferences: {
     weeklyGoal: number;
     showNotifications: boolean;
@@ -517,22 +282,10 @@ vibe-check profile
 # View specific sections
 vibe-check profile --achievements
 vibe-check profile --stats
-vibe-check profile --challenges
-vibe-check profile --leaderboard
-vibe-check profile --hall-of-fame
 vibe-check profile --weekly
-vibe-check profile --patterns
-vibe-check profile --interventions
-
-# Share
-vibe-check profile --share
-vibe-check profile --share-json
-
-# Record intervention
-vibe-check intervene TRACER_TEST
-vibe-check intervene BREAK
-vibe-check intervene --list
-vibe-check intervene --stats
+
+# JSON output
+vibe-check profile --json
 ```
 
 ---
@@ -560,5 +313,5 @@ Make you WANT to improve your vibe score—not because someone's watching, but b
 
 ---
 
-**Version:** 1.5.0
-**Last Updated:** 2025-11-29
+**Version:** 1.7.0
+**Last Updated:** 2025-12-02