@boshu2/vibe-check 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +87 -63
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.0.2] - 2025-11-28
9
+
10
+ ### Changed
11
+ - Complete README rewrite with problem-first structure
12
+ - Added "The Problem" and "The Insight" sections
13
+ - Added practical "When to Run" guidance
14
+ - Added prevention tips for debug spiral patterns
15
+
8
16
  ## [1.0.1] - 2025-11-28
9
17
 
10
18
  ### Added
package/README.md CHANGED
@@ -1,10 +1,54 @@
1
1
  # vibe-check
2
2
 
3
- Measure vibe coding effectiveness with git commit analysis.
3
+ **Stop guessing if AI coding is working. Start measuring.**
4
4
 
5
- ## What is Vibe Coding?
5
+ ## The Problem
6
6
 
7
- Vibe coding is AI-assisted development where you collaborate with an AI coding assistant. This tool measures how effectively that collaboration is working by analyzing your git commit patterns.
7
+ You're using AI to write code, but how do you know if it's actually helping?
8
+
9
+ Are you shipping features faster, or just generating more commits? Building new features, or debugging AI mistakes? Moving forward, or stuck in fix-fix-fix loops?
10
+
11
+ Without data, you're guessing.
12
+
13
+ ## The Insight
14
+
15
+ vibe-check analyzes your git history and tells you:
16
+
17
+ | What You'll Learn | Why It Matters |
18
+ |-------------------|----------------|
19
+ | **Trust Pass Rate** | Are you accepting AI code that works, or code that breaks immediately? |
20
+ | **Debug Spirals** | Are you stuck in fix loops on the same component? |
21
+ | **Rework Ratio** | What percentage of your work is building vs. cleaning up? |
22
+ | **Pattern Detection** | What types of problems keep recurring? (auth, config, APIs...) |
23
+
24
+ ## Quick Demo
25
+
26
+ ```bash
27
+ $ npx @boshu2/vibe-check --since "1 week ago"
28
+
29
+ ================================================================
30
+ VIBE-CHECK RESULTS
31
+ ================================================================
32
+ Period: Nov 21 - Nov 28, 2025 (12.5h active)
33
+ Commits: 47 total (28 feat, 15 fix, 4 docs)
34
+
35
+ METRIC VALUE RATING
36
+ --------------------------------------------------
37
+ Iteration Velocity 4.2/hr HIGH
38
+ Rework Ratio 35% MEDIUM
39
+ Trust Pass Rate 92% HIGH
40
+ Debug Spiral Duration 18min HIGH
41
+ Flow Efficiency 85% HIGH
42
+
43
+ DEBUG SPIRALS (2 detected):
44
+ - auth: 4 commits, 25m (SECRETS_AUTH)
45
+ - api: 3 commits, 12m (API_MISMATCH)
46
+
47
+ OVERALL: HIGH
48
+ ================================================================
49
+ ```
50
+
51
+ **What this tells you:** You're productive (4.2 commits/hour, 92% trust pass rate), but 35% of your work is fixing things—room to improve. OAuth caused a 25-minute spiral. Next time: validate auth flows with a tracer test before full implementation.
8
52
 
9
53
  ## Installation
10
54
 
@@ -12,7 +56,7 @@ Vibe coding is AI-assisted development where you collaborate with an AI coding a
12
56
  npm install -g @boshu2/vibe-check
13
57
  ```
14
58
 
15
- Or run directly with npx:
59
+ Or run directly:
16
60
 
17
61
  ```bash
18
62
  npx @boshu2/vibe-check
@@ -21,87 +65,66 @@ npx @boshu2/vibe-check
21
65
  ## Usage
22
66
 
23
67
  ```bash
24
- # Analyze current repository
68
+ # Analyze current repository (all history)
25
69
  vibe-check
26
70
 
27
- # Analyze last week
71
+ # Analyze specific time period
28
72
  vibe-check --since "1 week ago"
73
+ vibe-check --since "2025-11-01"
29
74
 
30
- # JSON output for CI/automation
31
- vibe-check --format json
75
+ # Different output formats
76
+ vibe-check --format json # For CI/automation
77
+ vibe-check --format markdown # For reports
32
78
 
33
- # Markdown report
34
- vibe-check --format markdown
35
-
36
- # Analyze specific repo
79
+ # Analyze a different repo
37
80
  vibe-check --repo /path/to/repo
38
81
  ```
39
82
 
40
- ## The 5 Core Metrics (FAAFO)
41
-
42
- | Metric | What It Measures | Target |
43
- |--------|------------------|--------|
44
- | **Iteration Velocity** | Commits per hour | >5/hr = Elite |
45
- | **Rework Ratio** | % commits that are fixes | <30% = Elite |
46
- | **Trust Pass Rate** | % commits that stick (no immediate fix) | >95% = Elite |
47
- | **Debug Spiral Duration** | Time spent in fix chains | <15m = Elite |
48
- | **Flow Efficiency** | % time in productive work vs debugging | >90% = Elite |
83
+ ## The 5 Metrics
49
84
 
50
- ## Output Ratings
85
+ | Metric | What It Measures | Elite | Good | Needs Work |
86
+ |--------|------------------|-------|------|------------|
87
+ | **Iteration Velocity** | Commits per hour | >5/hr | 3-5/hr | <3/hr |
88
+ | **Rework Ratio** | % of commits that are fixes | <30% | 30-50% | >50% |
89
+ | **Trust Pass Rate** | % of commits without immediate fix | >95% | 80-95% | <80% |
90
+ | **Debug Spiral Duration** | Avg time stuck in fix chains | <15m | 15-30m | >30m |
91
+ | **Flow Efficiency** | % time building vs debugging | >90% | 75-90% | <75% |
51
92
 
52
- | Rating | Meaning |
53
- |--------|---------|
54
- | **ELITE** | Vibe coding working excellently |
55
- | **HIGH** | Good effectiveness, minor improvements possible |
56
- | **MEDIUM** | Room for improvement |
57
- | **LOW** | Process issues, reassess approach |
93
+ ### What the ratings mean
58
94
 
59
- ## Example Output
60
-
61
- ```
62
- ╔════════════════════════════════════════════════════════════╗
63
- ║ VIBE CHECK RESULTS ║
64
- ╠════════════════════════════════════════════════════════════╣
65
- ║ Period: Nov 21 - Nov 28, 2025 ║
66
- ║ Commits Analyzed: 47 ║
67
- ╠════════════════════════════════════════════════════════════╣
68
- ║ ║
69
- ║ Iteration Velocity ████████████░░░░ 4.2/hr HIGH ║
70
- ║ Rework Ratio ██████░░░░░░░░░░ 35% MEDIUM ║
71
- ║ Trust Pass Rate ████████████████ 92% HIGH ║
72
- ║ Debug Spiral Duration ██████████████░░ 18min HIGH ║
73
- ║ Flow Efficiency ██████████████░░ 85% HIGH ║
74
- ║ ║
75
- ╠════════════════════════════════════════════════════════════╣
76
- ║ Overall Rating: HIGH ║
77
- ╚════════════════════════════════════════════════════════════╝
78
- ```
95
+ - **ELITE**: Your AI collaboration is working excellently
96
+ - **HIGH**: Good effectiveness, minor improvements possible
97
+ - **MEDIUM**: Room for improvement—check which metrics are lagging
98
+ - **LOW**: Process issues—you're debugging more than building
79
99
 
80
100
  ## Debug Spiral Detection
81
101
 
82
- When the tool detects fix chains (multiple fix commits in a row), it identifies:
83
- - Which component had issues
84
- - Pattern category (e.g., `API_MISMATCH`, `SSL_TLS`, `VOLUME_CONFIG`)
85
- - Duration of the spiral
86
- - Suggested tracer test to prevent recurrence
102
+ When vibe-check detects 3+ consecutive fix commits on the same component, it flags a "debug spiral" and categorizes the pattern:
87
103
 
88
- ## Integration with Claude Code
104
+ | Pattern | What It Means | Prevention |
105
+ |---------|---------------|------------|
106
+ | `SECRETS_AUTH` | Auth/OAuth/credentials issues | Validate auth flow before implementation |
107
+ | `API_MISMATCH` | API version or schema problems | Check API docs, deploy minimal test first |
108
+ | `VOLUME_CONFIG` | Mount/path/permission issues | Test volume config in isolation |
109
+ | `SSL_TLS` | Certificate/HTTPS problems | Verify certs before deploying |
110
+ | `IMAGE_REGISTRY` | Container pull/tag issues | Test image pull separately |
89
111
 
90
- This tool is designed to work with the RPI (Research-Plan-Implement) workflow:
112
+ ## When to Run
91
113
 
92
- 1. **Before implementation**: Run `vibe-check` to establish baseline
93
- 2. **After implementation**: Run `vibe-check --since "<start-time>"` to measure session
94
- 3. **Weekly review**: Run `vibe-check --since "1 week ago" --format markdown`
114
+ - **Before starting work**: Establish your baseline
115
+ - **After a session**: Measure what just happened
116
+ - **Weekly**: Track trends over time
117
+ - **After frustrating sessions**: Identify what went wrong
95
118
 
96
- ## Options
119
+ ## CLI Options
97
120
 
98
121
  ```
99
122
  -V, --version Output version number
100
- --since <date> Start date for analysis (e.g., "1 week ago", "2025-11-01")
101
- --until <date> End date for analysis (default: now)
102
- -f, --format <type> Output format: terminal, json, markdown (default: terminal)
123
+ --since <date> Start date (e.g., "1 week ago", "2025-11-01")
124
+ --until <date> End date (default: now)
125
+ -f, --format <type> Output: terminal, json, markdown
103
126
  -r, --repo <path> Repository path (default: current directory)
104
- -v, --verbose Show verbose output
127
+ -v, --verbose Show detailed output
105
128
  -h, --help Display help
106
129
  ```
107
130
 
@@ -109,6 +132,7 @@ This tool is designed to work with the RPI (Research-Plan-Implement) workflow:
109
132
 
110
133
  - Node.js >= 18.0.0
111
134
  - Git repository with commit history
135
+ - Conventional commits recommended (but not required)
112
136
 
113
137
  ## License
114
138
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@boshu2/vibe-check",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Measure vibe coding effectiveness with git commit analysis",
5
5
  "main": "dist/cli.js",
6
6
  "bin": {