@boshu2/vibe-check 1.6.2 → 1.8.0

package/CLAUDE.md

@@ -72,7 +72,37 @@ Most users have `^` (caret) in their package.json, meaning they'll auto-update t
 
 ## Development Workflow
 
-### Running Locally
+### Makefile Commands
+
+All commands are available via `make`. Run `make help` for full list.
+
+```bash
+# Build & Run
+make build            # Compile TypeScript
+make dev              # Run with ts-node
+make test             # Run all tests
+make test-coverage    # Tests with coverage
+
+# Vibe-Check
+make dashboard        # Open visual dashboard
+make analyze          # Analyze last week
+make profile          # Show XP, streaks, achievements
+make watch            # Real-time spiral detection
+
+# Session Integration
+make session-start    # Start session (prompts for level)
+make session-end      # End session and get metrics
+make session-status   # Show active session info
+
+# Publishing
+make publish          # Build, test, publish to npm
+make version-patch    # Bump patch version
+make version-minor    # Bump minor version
+```
+
+See [Makefile](./Makefile) for all available targets.
+
+### Running Locally (npm)
 
 ```bash
 npm run dev           # Run with ts-node
@@ -110,8 +140,17 @@ src/
 ├── commands/
 │   ├── index.ts        # Command exports
 │   ├── analyze.ts      # Main analyze command
-│   ├── level.ts        # Level recommendation command
+│   ├── session.ts      # Session start/end/status + coaching
+│   ├── dashboard.ts    # Visual dashboard command
+│   ├── watch.ts        # Real-time monitoring + coaching
+│   ├── insights.ts     # Spiral patterns + recommendations
+│   ├── timeline.ts     # Session history
 │   └── profile.ts      # Profile/stats command
+├── storage/
+│   ├── spiral-history.ts  # Spiral history NDJSON log
+│   ├── atomic.ts          # Atomic file operations
+│   ├── commit-log.ts      # Commit log storage
+│   └── timeline-store.ts  # Timeline cache
 ├── metrics/
 │   ├── index.ts        # Orchestrates all metrics
 │   ├── velocity.ts     # Iteration velocity
@@ -129,7 +168,10 @@ src/
 │   ├── xp.ts           # XP calculation and levels
 │   ├── streaks.ts      # Daily/weekly streak tracking
 │   ├── achievements.ts # Achievement definitions and checks
+│   ├── stats.ts        # Weekly statistics
 │   └── profile.ts      # Profile persistence (.vibe-check/)
+├── sessions/
+│   └── index.ts        # Session tracking and baseline comparison
 ├── calibration/
 │   ├── index.ts        # Calibration orchestration
 │   ├── ece.ts          # Expected calibration error
@@ -152,9 +194,14 @@ dashboard/              # Static HTML dashboard
 ├── app.js              # Dashboard JavaScript
 └── styles.css          # Dashboard styles
 
-.vibe-check/            # Local profile data (per-repo)
+~/.vibe-check/          # Global profile data (in home dir)
 ├── profile.json        # XP, streaks, achievements
+├── spiral-history.ndjson  # Spiral log for coaching
 └── calibration.json    # Calibration samples
+
+.vibe-check/            # Local data (per-repo)
+├── active-session.json # Active session state
+└── timeline.json       # Timeline cache
 ```
 
 ## Commands
@@ -180,6 +227,33 @@ vibe-check level               # Get level recommendation
 vibe-check level --calibrate 3 # Record calibration sample
 ```
 
+### Session Commands (AgentOps Integration)
+```bash
+vibe-check session start --level 3   # Start session, capture baseline
+vibe-check session status            # Show active session
+vibe-check session end --format json # End session, get metrics + coaching
+```
+
+Output includes failure pattern detection and personalized coaching:
+```json
+{
+  "metrics": { "trust_pass_rate": 92, "rework_ratio": 11, ... },
+  "retro": {
+    "failure_patterns_hit": [],
+    "failure_patterns_avoided": ["Debug Spiral", "Context Amnesia"]
+  }
+}
+```
+
+### Insights Command (Coaching)
+```bash
+vibe-check insights              # Your spiral patterns + what works
+vibe-check insights --days 90    # Longer history
+vibe-check insights --format json  # Export for analysis
+```
+
+Shows your spiral history, patterns by frequency, what resolutions worked, and personalized recommendations.
+
 ## The 5 Metrics
 
 | Metric | Measures | Threshold |
@@ -200,3 +274,5 @@ A "debug spiral" is detected when 3+ consecutive fix commits target the same com
 - `SSL_TLS` - Certificate problems
 - `IMAGE_REGISTRY` - Container pull issues
 - `GITOPS_DRIFT` - Sync/reconciliation issues
+
+**Coaching Integration:** Spirals are automatically recorded to `~/.vibe-check/spiral-history.ndjson`. Watch mode and session end show personalized advice based on what's worked before for you.

package/Makefile

@@ -0,0 +1,160 @@
+# vibe-check Makefile
+# All npm commands and development shortcuts
+
+.PHONY: help build dev start test test-coverage lint clean install publish dashboard watch profile analyze session-start session-end
+
+# Default target
+help:
+	@echo "vibe-check Development Commands"
+	@echo "================================"
+	@echo ""
+	@echo "Build & Run:"
+	@echo "  make build          - Compile TypeScript to dist/"
+	@echo "  make dev            - Run with ts-node (no compile)"
+	@echo "  make start          - Run compiled version"
+	@echo "  make clean          - Remove dist/ directory"
+	@echo ""
+	@echo "Testing:"
+	@echo "  make test           - Run all tests"
+	@echo "  make test-coverage  - Run tests with coverage report"
+	@echo "  make test-watch     - Run tests in watch mode"
+	@echo ""
+	@echo "Publishing:"
+	@echo "  make install        - Install dependencies"
+	@echo "  make publish        - Build, test, and publish to npm"
+	@echo "  make version-patch  - Bump patch version (1.0.x)"
+	@echo "  make version-minor  - Bump minor version (1.x.0)"
+	@echo "  make version-major  - Bump major version (x.0.0)"
+	@echo ""
+	@echo "Vibe-Check Commands:"
+	@echo "  make dashboard      - Open visual dashboard"
+	@echo "  make watch          - Real-time spiral detection"
+	@echo "  make profile        - Show XP, streaks, achievements"
+	@echo "  make analyze        - Analyze last week"
+	@echo "  make analyze-today  - Analyze today only"
+	@echo "  make timeline       - Show coding timeline"
+	@echo ""
+	@echo "Session Commands:"
+	@echo "  make session-start  - Start session (prompts for level)"
+	@echo "  make session-end    - End session and get metrics"
+	@echo "  make session-status - Show active session info"
+	@echo ""
+
+# ============================================
+# Build & Run
+# ============================================
+
+build:
+	npm run build
+
+dev:
+	npm run dev
+
+start:
+	npm run start
+
+clean:
+	rm -rf dist/
+
+# ============================================
+# Testing
+# ============================================
+
+test:
+	npm test
+
+test-coverage:
+	npm run test:coverage
+
+test-watch:
+	npx vitest watch
+
+# ============================================
+# Publishing
+# ============================================
+
+install:
+	npm install
+
+publish: build test
+	npm publish --access=public
+
+version-patch:
+	npm version patch
+
+version-minor:
+	npm version minor
+
+version-major:
+	npm version major
+
+# ============================================
+# Vibe-Check Commands
+# ============================================
+
+dashboard:
+	node dist/cli.js dashboard
+
+watch:
+	node dist/cli.js watch
+
+profile:
+	node dist/cli.js profile
+
+analyze:
+	node dist/cli.js --since "1 week ago" --score
+
+analyze-today:
+	node dist/cli.js --since "today" --score
+
+analyze-json:
+	node dist/cli.js --since "1 week ago" --score --format json
+
+timeline:
+	node dist/cli.js timeline --since "1 week ago"
+
+timeline-expand:
+	node dist/cli.js timeline --since "1 week ago" --expand
+
+# ============================================
+# Session Commands
+# ============================================
+
+session-start:
+	@read -p "Vibe Level (0-5): " level; \
+	node dist/cli.js session start --level $$level
+
+session-start-json:
+	@read -p "Vibe Level (0-5): " level; \
+	node dist/cli.js session start --level $$level --format json
+
+session-end:
+	node dist/cli.js session end
+
+session-end-json:
+	node dist/cli.js session end --format json
+
+session-status:
+	node dist/cli.js session status
+
+# ============================================
+# Shortcuts
+# ============================================
+
+# Quick check (alias for analyze)
+check: analyze
+
+# Full analysis with all features
+full:
+	node dist/cli.js --since "1 week ago" --score --verbose
+
+# Export dashboard data without opening browser
+export-dashboard:
+	node dist/cli.js dashboard --no-open
+
+# Cache management
+cache-stats:
+	node dist/cli.js cache --stats
+
+cache-clear:
+	node dist/cli.js cache --clear

package/README.md

@@ -1,232 +1,215 @@
-# vibe-check
+<p align="center">
+  <img src="https://raw.githubusercontent.com/boshu2/vibe-check/main/assets/logo.svg" alt="vibe-check" width="400">
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@boshu2/vibe-check.svg)](https://www.npmjs.com/package/@boshu2/vibe-check)
-[![CI](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml/badge.svg)](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <strong>Catch the debug spiral before it catches you.</strong>
+</p>
 
-![Vibe-Check Dashboard](docs/images/dashboard.png)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@boshu2/vibe-check"><img src="https://img.shields.io/npm/v/@boshu2/vibe-check.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@boshu2/vibe-check"><img src="https://img.shields.io/npm/dm/@boshu2/vibe-check.svg?style=flat-square" alt="downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="license"></a>
+</p>
 
-**Git-powered metrics for AI-assisted coding.** Catch debug spirals before they catch you.
+<p align="center">
+  Git-powered metrics for AI-assisted development.<br>
+  Detects the failure patterns from <a href="https://itrevolution.com/product/vibe-coding-book/"><em>Vibe Coding</em></a> (Gene Kim & Steve Yegge, 2025).
+</p>
+
+---
 
 ```bash
-npx @boshu2/vibe-check --since "2 hours ago"
+npx @boshu2/vibe-check
 ```
 
-```
-╭──────────────────────────────────────────────────────────────╮
-│  VIBE-CHECK                                    Nov 30, 2025  │
-├──────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Rating: ELITE ✨                                            │
-│                                                              │
-│  Trust Pass Rate   ████████████████████  95%  ELITE          │
-│  Rework Ratio      ████░░░░░░░░░░░░░░░░  18%  ELITE          │
-│  Debug Spirals     None detected              ELITE          │
-│                                                              │
-│  You're in the zone. Ship it.                                │
-│                                                              │
-╰──────────────────────────────────────────────────────────────╯
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/boshu2/vibe-check/main/assets/demo.gif" alt="vibe-check demo" width="600">
+</p>
 
 ---
 
-## Dashboard
+## The Problem
 
-```bash
-vibe-check dashboard
-```
+> "AI can destroy months of work in minutes." — Gene Kim & Steve Yegge
 
-Opens the dashboard above in your browser. Features:
-- 📊 Score trend charts with 7/30/90 day views
-- 🎯 AI-generated insights about your coding patterns
-- 🏆 Achievement tracking (19 achievements, 2 hidden)
-- 📈 Session history and ratings distribution
-- 🌙 GitHub dark theme
+AI-assisted coding creates a new failure mode: **the debug spiral**.
 
----
+You ask AI for a fix. It breaks something else. You ask for another fix. It breaks more. Three commits later, you've lost 30 minutes and made negative progress.
 
-## Install
+**vibe-check detects these spirals by analyzing your git history.**
 
-```bash
-npm install -g @boshu2/vibe-check
-```
+---
 
 ## Quick Start
 
 ```bash
 # Analyze recent work
-vibe-check --since "1 week ago"
+npx @boshu2/vibe-check --since "1 week ago"
 
 # Real-time spiral detection
-vibe-check watch
+npx @boshu2/vibe-check watch
 
 # Visual dashboard
-vibe-check dashboard
-
-# View your profile & achievements
-vibe-check profile
+npx @boshu2/vibe-check dashboard
 ```
 
 ---
 
-## Watch Mode
+## What It Measures
 
-Catch spirals **as they happen**, not after:
+| Metric | Question | Target |
+|--------|----------|--------|
+| **Trust Pass Rate** | Does the code stick? | >95% |
+| **Rework Ratio** | Building or debugging? | <30% |
+| **Debug Spirals** | Are you stuck? | 0 active |
 
-```bash
-vibe-check watch
-```
+### Detection Patterns
+
+| Pattern | Severity | What It Means |
+|---------|----------|---------------|
+| **Tests Passing Lie** | HIGH | AI claims tests pass, but they don't |
+| **Instruction Drift** | MEDIUM | AI gradually moves off-target |
+| **Debug Loop Spiral** | HIGH | 3+ fix commits on same component |
+| **Context Amnesia** | MEDIUM | Repeated fixes, forgotten solutions |
+
+---
+
+## Watch Mode
+
+Catches spirals **as they form** with personalized coaching:
 
 ```
 VIBE-CHECK WATCH MODE
-Monitoring: ~/projects/my-app
-────────────────────────────────────────────────────────
+────────────────────────────────────────────────
 
   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 over 7 minutes                   │
-  │                                                    │
-  │  💡 Consider:                                      │
-  │     • Step back and write a test                   │
-  │     • Check the docs or ask for help               │
-  │     • Take a 5-minute break                        │
-  └────────────────────────────────────────────────────┘
-
-────────────────────────────────────────────────────────
+  ⚠️  SPIRAL FORMING
+      auth component, 3 fixes, 7 min
+
+      Your history: 4 auth spirals, avg 18 min
+      What worked: wrote a test (3x), took a break (1x)
+
+      → Write a test before your next fix attempt.
+
+────────────────────────────────────────────────
 ```
 
----
+Watch mode learns from your history and suggests what's worked before.
 
-## Gamification
+---
 
-Level up your coding with XP, streaks, and achievements:
+## Install
 
 ```bash
-vibe-check profile
+npm install -g @boshu2/vibe-check
 ```
 
-```
-╭─────────────────────────────────────────────────────╮
-│                                                     │
-│   🏔️  Level 6 Grandmaster                          │
-│   ████████████████░░░░░░░░  2140 / 5000 XP         │
-│                                                     │
-│   🔥  12 day streak (longest: 14)                   │
-│   🏆  8/19 achievements unlocked                    │
-│                                                     │
-│   Recent Unlocks:                                   │
-│   ✨ Elite Vibes    🧘 Zen Master    📊 Regular     │
-│                                                     │
-╰─────────────────────────────────────────────────────╯
-```
+Or use directly with `npx`:
 
-**19 achievements** including 2 hidden ones. Can you find them?
+```bash
+npx @boshu2/vibe-check --since "2 hours ago"
+```
 
 ---
 
-## The Metrics
+## Commands
 
-| Metric | What It Measures | 🟢 Elite | 🔴 Needs Work |
-|--------|------------------|----------|---------------|
-| **Trust Pass Rate** | % commits without immediate fix | >95% | <80% |
-| **Rework Ratio** | % commits that are fixes | <30% | >50% |
-| **Debug Spiral** | Stuck in fix loops? | 0 | 3+ |
+### Core Analysis
 
----
+```bash
+vibe-check                      # Analyze git history
+vibe-check watch                # Real-time spiral monitoring
+vibe-check dashboard            # Visual dashboard
+vibe-check timeline             # View coding journey
+vibe-check forensics            # Deep pattern analysis
+```
+
+### Sessions
 
-## Vibe Levels
+```bash
+vibe-check start --level 3      # Quick session start
+vibe-check session start        # Interactive session start
+vibe-check session end          # End with metrics
+vibe-check session status       # Check active session
+```
 
-Declare your trust level before starting work:
+### Profile & Insights
 
 ```bash
-vibe-check start --level 3
-# ... code ...
-vibe-check --since "1 hour ago"
+vibe-check profile              # XP and achievements
+vibe-check insights             # Your spiral patterns
 ```
 
-| Level | Name | Trust | Use For |
-|-------|------|-------|---------|
-| **5** | Full Auto | 95% | Formatting, linting |
-| **4** | High Trust | 80% | Boilerplate, CRUD |
-| **3** | Balanced | 60% | Features, tests |
-| **2** | Careful | 40% | Integrations, APIs |
-| **1** | Skeptical | 20% | Architecture, security |
-| **0** | Manual | 0% | Novel research |
+### Tools
+
+```bash
+vibe-check cache status         # Cache statistics
+vibe-check cache clear          # Clear cache
+vibe-check init-hook            # Install pre-push hook
+vibe-check pipeline             # Audit CI/CD safety
+```
 
 ---
 
-## Git Hook
+## Session Integration
 
-Auto-run before every push:
+Integrate with Claude Code or other AI dev tools:
 
 ```bash
-vibe-check init-hook           # Install hook
-vibe-check init-hook --block-low  # Block LOW pushes
-```
+# Start session
+vibe-check session start --level 3
 
----
+# End session - get JSON for logging
+vibe-check session end --format json
+```
 
-## GitHub Action
-
-```yaml
-name: Vibe Check
-on: [pull_request]
-
-jobs:
-  vibe:
-    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
+{
+  "metrics": { "trust_pass_rate": 92, "rework_ratio": 18 },
+  "retro": {
+    "failure_patterns_hit": [],
+    "failure_patterns_avoided": ["Debug Spiral", "Context Amnesia"]
+  }
+}
 ```
 
 ---
 
-## All Commands
+## The Ecosystem
 
-```
-vibe-check [options]           Analyze git history
-vibe-check watch               Real-time spiral detection
-vibe-check dashboard           Visual dashboard + insights
-vibe-check profile             XP, streaks, achievements
-vibe-check timeline            Coding journey visualization
-vibe-check start --level <n>   Declare vibe level (0-5)
-vibe-check intervene           Record spiral intervention
-vibe-check init-hook           Install git hook
-vibe-check cache               Manage local storage
-```
+vibe-check implements **Factor V (Measurement)** from [12-Factor AgentOps](https://github.com/boshu2/12-factor-agentops):
 
-**Options:**
-```
---since <date>       Start date ("1 week ago", "2024-01-01")
---until <date>       End date (default: now)
---score              Include VibeScore calculation
---simple             Compact output
---format <type>      terminal | json | markdown
---output <file>      Save JSON to file
---verbose            Detailed output
+```text
+BUILD              →     WORK          →     RUN
+12-Factor Agents        Vibe Coding         12-Factor AgentOps
+(HumanLayer)           (Gene & Steve)       (Operations)
+                                                  ↓
+                                             vibe-check
+                                            (Measurement)
 ```
 
+| Factor | What vibe-check Provides |
+|--------|-------------------------|
+| **IV: Validation Gates** | Pre-commit hooks, CI integration |
+| **V: Measurement** | Quantified feedback loop |
+| **VII: Smart Routing** | Spiral detection triggers intervention |
+| **XI: Fail-Safe Checks** | Pattern detection for all 12 failures |
+
 ---
 
 ## Philosophy
 
-**vibe-check is a mirror, not a judge.**
+vibe-check is a mirror, not a judge.
 
-Use it for self-reflection. Catch your own patterns. Improve your own flow.
+It answers one question: *are you building, or are you spiraling?*
 
-It's not a productivity metric. It's not for performance reviews. It's not measuring AI effectiveness.
+Use it for self-reflection. Catch your own patterns. Improve your own flow.
 
-It's just asking: *are you building, or are you spiraling?*
+It's not a productivity metric. It's not for performance reviews.
 
 ---
 
@@ -235,13 +218,16 @@ It's just asking: *are you building, or are you spiraling?*
 - Node.js >= 20.0.0
 - Git repository with commits
 
-## Docs
+---
+
+## Learn More
 
-- [Vibe-Coding Ecosystem](docs/VIBE-ECOSYSTEM.md) - Full methodology
-- [Architecture](docs/ARCHITECTURE.md) - Codebase structure
-- [Gamification](docs/GAMIFICATION.md) - XP & achievements deep dive
-- [Metrics Explained](docs/METRICS-EXPLAINED.md) - How it works
-- [Changelog](CHANGELOG.md) - Version history
+- [Vibe-Coding Ecosystem](docs/VIBE-ECOSYSTEM.md) — Full methodology, all features
+- [Vibe Coding Book](https://itrevolution.com/product/vibe-coding-book/) — Gene Kim & Steve Yegge (2025)
+- [12-Factor AgentOps](https://github.com/boshu2/12-factor-agentops) — Operational framework
+- [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) — Engineering patterns (HumanLayer)
+
+---
 
 ## License
 
@@ -250,5 +236,5 @@ MIT
 ---
 
 <p align="center">
-  <i>Built for developers who vibe with AI</i>
+  <em>Built for developers who work with AI.</em>
 </p>