ruvnet-kb-first 5.0.0 → 6.0.0
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.
- package/README.md +41 -23
- package/SKILL.md +153 -75
- package/package.json +1 -1
- package/src/mcp-server.js +592 -258
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
Updated: 2026-01-02
|
|
1
|
+
Updated: 2026-01-02 10:20:00 EST | Version 6.0.0
|
|
2
2
|
Created: 2026-01-01 15:28:53 EST
|
|
3
3
|
|
|
4
|
-
# RuvNet KB-First Application Builder
|
|
4
|
+
# RuvNet KB-First Application Builder v6.0
|
|
5
5
|
|
|
6
|
-
##
|
|
6
|
+
## Score-Driven Architecture: Measurement IS Enforcement
|
|
7
7
|
|
|
8
8
|
[](https://www.npmjs.com/package/ruvnet-kb-first)
|
|
9
9
|
[](https://opensource.org/licenses/MIT)
|
|
@@ -59,42 +59,60 @@ This is **not just RAG** (Retrieval-Augmented Generation). RAG retrieves context
|
|
|
59
59
|
|
|
60
60
|
---
|
|
61
61
|
|
|
62
|
-
## 🚀 Quick Start
|
|
62
|
+
## 🚀 Quick Start (v6.0 - Score-Driven)
|
|
63
63
|
|
|
64
|
-
###
|
|
64
|
+
### MCP Server (Recommended)
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
# Initialize KB-First in any project
|
|
68
|
-
npx ruvnet-kb-first init
|
|
66
|
+
Add to your Claude Code `settings.json`:
|
|
69
67
|
|
|
70
|
-
|
|
71
|
-
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"mcpServers": {
|
|
71
|
+
"ruvnet-kb-first": {
|
|
72
|
+
"command": "npx",
|
|
73
|
+
"args": ["ruvnet-kb-first", "mcp"]
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Then use the 4 MCP tools:
|
|
72
80
|
|
|
73
|
-
|
|
74
|
-
|
|
81
|
+
```
|
|
82
|
+
kb_first_assess # ALWAYS FIRST - establish baseline score
|
|
83
|
+
kb_first_phase 0 # Get phase guidance (shows baseline reminder)
|
|
84
|
+
# ... do the work ...
|
|
85
|
+
kb_first_delta # Compare scores - BLOCKS if regression
|
|
86
|
+
kb_first_gate 0 # Pass gate, proceed to next phase
|
|
75
87
|
```
|
|
76
88
|
|
|
77
|
-
###
|
|
89
|
+
### NPX (CLI Wrapper)
|
|
78
90
|
|
|
79
91
|
```bash
|
|
80
|
-
|
|
92
|
+
# Start MCP server
|
|
93
|
+
npx ruvnet-kb-first mcp
|
|
81
94
|
|
|
82
|
-
|
|
83
|
-
ruvnet-kb-first
|
|
84
|
-
ruvnet-kb-first
|
|
95
|
+
# Legacy CLI commands still work
|
|
96
|
+
npx ruvnet-kb-first score
|
|
97
|
+
npx ruvnet-kb-first status
|
|
85
98
|
```
|
|
86
99
|
|
|
87
|
-
###
|
|
100
|
+
### The Score-Driven Workflow
|
|
88
101
|
|
|
89
102
|
```
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
103
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
104
|
+
│ 1. kb_first_assess → Baseline: 47/100 (Grade: D) │
|
|
105
|
+
│ 2. kb_first_phase → Phase 3: KB Population tasks │
|
|
106
|
+
│ 3. [Do the work] → Add content, generate embeddings │
|
|
107
|
+
│ 4. kb_first_delta → Current: 62/100, Delta: +15 ✓ PASS │
|
|
108
|
+
│ 5. kb_first_gate → Gate passed, proceed to Phase 4 │
|
|
109
|
+
│ 6. REPEAT → New baseline: 62/100 │
|
|
110
|
+
└──────────────────────────────────────────────────────────────┘
|
|
93
111
|
```
|
|
94
112
|
|
|
95
|
-
|
|
113
|
+
**Key Rule:** Negative delta BLOCKS progress. No shortcuts.
|
|
96
114
|
|
|
97
|
-
|
|
115
|
+
### Legacy Options
|
|
98
116
|
|
|
99
117
|
```json
|
|
100
118
|
{
|
package/SKILL.md
CHANGED
|
@@ -1,42 +1,48 @@
|
|
|
1
|
-
Updated: 2026-01-02
|
|
1
|
+
Updated: 2026-01-02 10:15:00 EST | Version 6.0.0
|
|
2
2
|
Created: 2026-01-01 15:00:00 EST
|
|
3
3
|
|
|
4
|
-
# RuvNet KB-First Application Builder
|
|
4
|
+
# RuvNet KB-First Application Builder v6.0
|
|
5
5
|
|
|
6
|
-
##
|
|
6
|
+
## Score-Driven Architecture: Scoring IS Enforcement
|
|
7
7
|
|
|
8
|
-
**Version:**
|
|
8
|
+
**Version:** 6.0.0
|
|
9
9
|
**NPM Package:** `ruvnet-kb-first`
|
|
10
|
-
**
|
|
10
|
+
**Philosophy:** Every operation requires baseline scoring. Every change shows delta. Negative delta BLOCKS progress. No shortcuts.
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
## What's New in
|
|
14
|
+
## What's New in v6.0 - BREAKING CHANGES
|
|
15
15
|
|
|
16
16
|
| Feature | Description |
|
|
17
17
|
|---------|-------------|
|
|
18
|
-
| **
|
|
19
|
-
| **
|
|
20
|
-
| **
|
|
21
|
-
| **
|
|
22
|
-
| **
|
|
23
|
-
| **
|
|
18
|
+
| **Score-Driven Architecture** | Scoring is THE enforcement mechanism, not just a metric |
|
|
19
|
+
| **4 MCP Tools** | Simplified from 7 CLI commands to 4 focused MCP tools |
|
|
20
|
+
| **Delta Enforcement** | Every phase requires before/after comparison |
|
|
21
|
+
| **Hard Gate Blocking** | Negative score delta BLOCKS progress - no bypass |
|
|
22
|
+
| **Baseline Requirement** | Cannot start work without establishing baseline |
|
|
23
|
+
| **Automatic Refresh** | Baseline resets after each gate passage |
|
|
24
24
|
|
|
25
|
-
###
|
|
25
|
+
### The 4 MCP Tools
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
27
|
+
| Tool | Purpose | When to Use |
|
|
28
|
+
|------|---------|-------------|
|
|
29
|
+
| `kb_first_assess` | Calculate baseline scores | **FIRST** - before any work |
|
|
30
|
+
| `kb_first_phase` | Get phase guidance with baseline | After assess, shows tasks |
|
|
31
|
+
| `kb_first_delta` | Compare current vs baseline | After work, shows improvement |
|
|
32
|
+
| `kb_first_gate` | Hard gate - blocks on regression | When ready to proceed |
|
|
30
33
|
|
|
31
|
-
|
|
32
|
-
npm install -g ruvnet-kb-first
|
|
33
|
-
kb-first init
|
|
34
|
+
### The Score-Driven Workflow
|
|
34
35
|
|
|
35
|
-
|
|
36
|
-
/
|
|
36
|
+
```
|
|
37
|
+
1. kb_first_assess → Establishes baseline (saves to .ruvector/baseline.json)
|
|
38
|
+
2. kb_first_phase → Get phase tasks, see baseline reminder
|
|
39
|
+
3. [Do the work]
|
|
40
|
+
4. kb_first_delta → Compare scores, PASS if delta ≥ 0, FAIL if < 0
|
|
41
|
+
5. kb_first_gate → Verify gate, proceed OR blocked
|
|
42
|
+
6. REPEAT from step 1 for next phase
|
|
37
43
|
```
|
|
38
44
|
|
|
39
|
-
### MCP
|
|
45
|
+
### Quick Start (MCP Only)
|
|
40
46
|
|
|
41
47
|
Add to your Claude Code settings:
|
|
42
48
|
|
|
@@ -51,71 +57,143 @@ Add to your Claude Code settings:
|
|
|
51
57
|
}
|
|
52
58
|
```
|
|
53
59
|
|
|
60
|
+
Then use the tools:
|
|
61
|
+
```
|
|
62
|
+
kb_first_assess # Start here - get your baseline
|
|
63
|
+
kb_first_phase 0 # Get Phase 0 (Assessment) guidance
|
|
64
|
+
# ... do the work ...
|
|
65
|
+
kb_first_delta # Check your improvement
|
|
66
|
+
kb_first_gate 0 # Pass gate, move to Phase 1
|
|
67
|
+
```
|
|
68
|
+
|
|
54
69
|
---
|
|
55
70
|
|
|
56
|
-
##
|
|
71
|
+
## Scoring Formula (100 Points Total)
|
|
72
|
+
|
|
73
|
+
### KB Score (40 points)
|
|
74
|
+
| Component | Points | Measurement |
|
|
75
|
+
|-----------|--------|-------------|
|
|
76
|
+
| Entries | 10 | KB has content (2 pts per 5 entries) |
|
|
77
|
+
| Coverage | 10 | Domain docs exist (2 pts per doc) |
|
|
78
|
+
| Embeddings | 10 | Vectors generated |
|
|
79
|
+
| Freshness | 10 | Updated within 24h=10, 7d=7, 30d=4 |
|
|
80
|
+
|
|
81
|
+
### App Score (40 points)
|
|
82
|
+
| Component | Points | Measurement |
|
|
83
|
+
|-----------|--------|-------------|
|
|
84
|
+
| KB Citations | 15 | Code files cite KB sources |
|
|
85
|
+
| Gap Resolution | 10 | 10 - (unresolved gaps) |
|
|
86
|
+
| Test Coverage | 10 | Tests exist and pass |
|
|
87
|
+
| Security | 5 | .gitignore excludes .env |
|
|
88
|
+
|
|
89
|
+
### Process Score (20 points)
|
|
90
|
+
| Component | Points | Measurement |
|
|
91
|
+
|-----------|--------|-------------|
|
|
92
|
+
| Phase Completion | 10 | % of phases completed |
|
|
93
|
+
| Gates Passed | 5 | % of gates verified |
|
|
94
|
+
| Documentation | 5 | README, API docs, architecture |
|
|
57
95
|
|
|
58
|
-
|
|
59
|
-
|---------|-------------|
|
|
60
|
-
| **Phase 9: Security Audit** | OWASP Top 10, SQL injection, secrets scanning |
|
|
61
|
-
| **Phase 10: Documentation** | Complete docs, API specs, versioning |
|
|
62
|
-
| **Phase 11: Deployment** | Production deployment with public access |
|
|
63
|
-
| **Security Scripts** | Automated security verification (9-security-audit.sh) |
|
|
64
|
-
| **Go-Live Checklist** | Pre-launch and post-launch verification |
|
|
96
|
+
---
|
|
65
97
|
|
|
66
|
-
##
|
|
98
|
+
## How It Works
|
|
67
99
|
|
|
68
|
-
|
|
69
|
-
|---------|-------------|
|
|
70
|
-
| **Phase 1.5: Hooks Setup** | Automatic KB enforcement via RuVector hooks |
|
|
71
|
-
| **Hook Pre-training** | ReasoningBank seeded with KB-First patterns |
|
|
72
|
-
| **Hook Verification** | Comprehensive verification script (1.5-hooks-verify.sh) |
|
|
73
|
-
| **Global Skill Install** | Install to ~/.claude/skills/ for all repos |
|
|
74
|
-
| **Init Script** | One-command project initialization |
|
|
100
|
+
### 1. `kb_first_assess` - Establish Baseline
|
|
75
101
|
|
|
76
|
-
|
|
102
|
+
**ALWAYS RUN FIRST.** Returns:
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"action": "BASELINE_ESTABLISHED",
|
|
106
|
+
"total": 47,
|
|
107
|
+
"grade": "D",
|
|
108
|
+
"summary": { "kb": "12/40", "app": "25/40", "process": "10/20" },
|
|
109
|
+
"breakdown": { ... component details ... }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
77
112
|
|
|
78
|
-
|
|
79
|
-
|---------|-------------|
|
|
80
|
-
| **Greenfield Support** | Full workflow for new projects via PROJECT_INTENTIONS.md |
|
|
81
|
-
| **Interactive Discovery** | Structured questions when no intentions file exists |
|
|
82
|
-
| **IS/SHOULD/COULD Analysis** | Present vision to user before execution |
|
|
83
|
-
| **User Feedback Loop** | Mandatory feedback before proceeding |
|
|
84
|
-
| **CI/CD Pipeline** | GitHub Actions workflow for quality gates |
|
|
85
|
-
| **Verification Scripts** | 8 executable scripts (8.1-8.8) for Phase 8 |
|
|
113
|
+
### 2. `kb_first_phase` - Get Phase Guidance
|
|
86
114
|
|
|
87
|
-
|
|
115
|
+
**Shows phase tasks and reminds you of baseline:**
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"phase": 3,
|
|
119
|
+
"name": "KB Population",
|
|
120
|
+
"baseline": { "score": 47, "grade": "D" },
|
|
121
|
+
"tasks": ["Collect domain content", "Generate embeddings", ...],
|
|
122
|
+
"reminder": "⚠️ Run kb_first_delta when complete"
|
|
123
|
+
}
|
|
124
|
+
```
|
|
88
125
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
126
|
+
### 3. `kb_first_delta` - Measure Improvement
|
|
127
|
+
|
|
128
|
+
**THE ENFORCEMENT MECHANISM:**
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"verdict": "PASS",
|
|
132
|
+
"canProceed": true,
|
|
133
|
+
"baseline": { "score": 47 },
|
|
134
|
+
"current": { "score": 62 },
|
|
135
|
+
"delta": { "total": "+15", "kb": "+10", "app": "+3", "process": "+2" }
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Or if regression:
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"verdict": "FAIL",
|
|
143
|
+
"canProceed": false,
|
|
144
|
+
"delta": { "total": "-3" },
|
|
145
|
+
"blockReason": "Score dropped by 3 points. You CANNOT proceed until score improves."
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### 4. `kb_first_gate` - Pass or Block
|
|
150
|
+
|
|
151
|
+
**Hard gate that enforces progress:**
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"canProceed": true,
|
|
155
|
+
"gateStatus": "PASSED",
|
|
156
|
+
"scoreImprovement": "+15",
|
|
157
|
+
"nextPhase": 4,
|
|
158
|
+
"nextPhaseName": "Scoring & Gaps"
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Or if blocked:
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"canProceed": false,
|
|
166
|
+
"blockReason": "GATE_BLOCKED: Score regression detected (-3 points)."
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Why Score-Driven?
|
|
173
|
+
|
|
174
|
+
> "When you just stare at something, you take shortcuts."
|
|
175
|
+
|
|
176
|
+
The previous version (v5.0) had 7 CLI commands, a skill file, a command file, and an MCP server. **Too much complexity, not enough rigor.**
|
|
177
|
+
|
|
178
|
+
v6.0 simplifies to:
|
|
179
|
+
- **One interface:** MCP server with 4 tools
|
|
180
|
+
- **One enforcement mechanism:** Scoring with delta comparison
|
|
181
|
+
- **One rule:** No negative deltas allowed
|
|
182
|
+
|
|
183
|
+
This prevents:
|
|
184
|
+
- Skipping phases
|
|
185
|
+
- Claiming "good enough" without measurement
|
|
186
|
+
- Forgetting to verify improvements
|
|
187
|
+
- Proceeding with regressions
|
|
97
188
|
|
|
98
189
|
---
|
|
99
190
|
|
|
100
|
-
##
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
3. **Confirm** transformation scope with user (brownfield only)
|
|
107
|
-
4. **Identify** which intelligence pattern fits
|
|
108
|
-
5. **Execute** the 9-phase build process with HARD quality gates
|
|
109
|
-
6. **Enforce** KB-First rules throughout development
|
|
110
|
-
7. **Verify** all 8 verification sub-phases pass
|
|
111
|
-
8. **Report** delta (before/after scores)
|
|
112
|
-
|
|
113
|
-
**Trigger phrases:**
|
|
114
|
-
- "Build [description] with KB-First" (greenfield)
|
|
115
|
-
- "Apply KB-First to my existing app" (brownfield)
|
|
116
|
-
- "Score my existing KB"
|
|
117
|
-
- "What's my app compliance score?"
|
|
118
|
-
- "/kb-first" (invoke skill directly)
|
|
191
|
+
## Trigger Phrases
|
|
192
|
+
|
|
193
|
+
- "Score my project" → `kb_first_assess`
|
|
194
|
+
- "What phase am I on?" → `kb_first_phase`
|
|
195
|
+
- "Did I improve?" → `kb_first_delta`
|
|
196
|
+
- "Can I proceed?" → `kb_first_gate`
|
|
119
197
|
|
|
120
198
|
---
|
|
121
199
|
|