ruvnet-kb-first 6.2.0 → 6.4.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.
Files changed (10) hide show
  1. package/README.md +318 -533
  2. package/SKILL.md +139 -6
  3. package/bin/kb-first.js +9 -6
  4. package/package.json +5 -5
  5. package/scripts/kb-ingest-template.js +548 -0
  6. package/scripts/kb-optimize.sql +250 -0
  7. package/scripts/kb-quality-audit.js +956 -0
  8. package/src/commands/dashboard.js +359 -0
  9. package/src/commands/init.js +138 -9
  10. package/src/commands/status.js +59 -5
package/README.md CHANGED
@@ -1,655 +1,408 @@
1
- Updated: 2026-01-02 10:20:00 EST | Version 6.0.0
1
+ Updated: 2026-01-02 11:15:00 EST | Version 6.3.0
2
2
  Created: 2026-01-01 15:28:53 EST
3
3
 
4
- # RuvNet KB-First Application Builder v6.0
4
+ # RuvNet-KB-First Application Builder v6.3.0
5
5
 
6
- ## Score-Driven Architecture: Measurement IS Enforcement
6
+ ## Build Intelligent Applications on Expert Knowledge
7
7
 
8
8
  [![npm version](https://img.shields.io/npm/v/ruvnet-kb-first.svg)](https://www.npmjs.com/package/ruvnet-kb-first)
9
9
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
10
 
11
11
  <p align="center">
12
- <img src="assets/kb-first-architecture.svg" alt="KB-First Architecture" width="800">
12
+ <img src="assets/kb-first-architecture.svg" alt="RuvNet-KB-First Architecture" width="800">
13
13
  </p>
14
14
 
15
15
  <details>
16
- <summary>📄 Text Version (for AI/accessibility)</summary>
16
+ <summary>Text Version (for AI/accessibility)</summary>
17
17
 
18
18
  ```
19
- ┌─────────────────────────────────────────────────────────────────────────────────┐
20
- │ KB-FIRST INTELLIGENCE ARCHITECTURE │
21
- ├─────────────────────────────────────────────────────────────────────────────────┤
22
- │ │
23
- │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
24
- │ │ GNN │ │ ATTENTION │ │ SONA │ │
25
- │ │ Graph Neural Nets │ │ 39 Mechanisms │ │ Self-Optimizing │ │
26
- │ ├─────────────────────┤ ├─────────────────────┤ ├─────────────────────┤ │
27
- │ │ • Decision cascades │ │ • MoE expert routing│ │ • Pattern memory │ │
28
- │ │ • Relationship │ │ • Cross-attention │ │ • Outcome learning │ │
29
- │ │ modeling │ │ compare │ │ • Anti-forgetting │ │
30
- │ │ • "What if" │ │ • Flash for speed │ │ (EWC++) │ │
31
- │ │ simulation │ │ │ │ │ │
32
- │ └──────────┬──────────┘ └──────────┬──────────┘ └──────────┬──────────┘ │
33
- │ │ Decision Web │ Routing │ Learning │
34
- │ └────────────────────────┼────────────────────────┘ │
35
- │ ▼ │
36
- │ ┌─────────────────────────────────┐ │
37
- │ │ VECTOR SEARCH │ │
38
- │ │ Foundation Layer │ │
39
- │ ├─────────────────────────────────┤ │
40
- │ │ PostgreSQL + ruvector/pgvector │ │
41
- │ │ Semantic retrieval • Hybrid │ │
42
- │ └─────────────────┬───────────────┘ │
43
- │ ▼ │
44
- │ ┌─────────────────────────────────┐ │
45
- │ │ KNOWLEDGE BASE │ │
46
- │ ├─────────────────────────────────┤ │
47
- │ │ Expert-attributed content │ │
48
- │ │ Confidence scores • Gap detect │ │
49
- │ └─────────────────────────────────┘ │
50
- │ │
51
- └─────────────────────────────────────────────────────────────────────────────────┘
19
+ RUVNET-KB-FIRST ARCHITECTURE
20
+
21
+ ┌─────────────────────────────────────────────────────────────────────┐
22
+ │ │
23
+ │ User runs: npx ruvnet-kb-first │
24
+ │ │ │
25
+ │ ▼ │
26
+ │ ┌─────────────────────┐ │
27
+ │ │ KB Discovery │ │
28
+ │ │ Layer │ │
29
+ │ └──────────┬──────────┘ │
30
+ │ ┌───────────────┼───────────────┐ │
31
+ │ ▼ ▼ ▼ │
32
+ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
33
+ │ │ TIER 1 │ │ TIER 2 │ │ TIER 3 │ │
34
+ │ │ Full KB │ │ Starter │ │ None │ │
35
+ │ │ 230K+ │ │ 500 ent │ │ Struct │ │
36
+ │ └───────────┘ └───────────┘ └───────────┘ │
37
+ │ │
38
+ │ Fallback: Tier 1 → Tier 2 → Tier 3 (graceful degradation) │
39
+ │ │
40
+ └─────────────────────────────────────────────────────────────────────┘
52
41
  ```
53
42
 
54
43
  </details>
55
44
 
56
- **KB-First** is a methodology and skill for building applications where **curated expert knowledge drives intelligent decision-making**. Every response is grounded in verified sources. Every decision can be traced. Every gap is detected and logged.
57
-
58
- This is **not just RAG** (Retrieval-Augmented Generation). RAG retrieves context to supplement responses. KB-First applications treat the knowledge base as the **authoritative source** — if it's not in the KB, the system says so.
45
+ **RuvNet-KB-First** is a methodology for building applications where **curated expert knowledge drives intelligent decision-making**. Every response is grounded in verified sources. Every decision can be traced. Every gap is detected and logged.
59
46
 
60
47
  ---
61
48
 
62
- ## 🚀 Quick Start (v6.0 - Score-Driven)
63
-
64
- ### MCP Server (Recommended)
65
-
66
- Add to your Claude Code `settings.json`:
67
-
68
- ```json
69
- {
70
- "mcpServers": {
71
- "ruvnet-kb-first": {
72
- "command": "npx",
73
- "args": ["ruvnet-kb-first", "mcp"]
74
- }
75
- }
76
- }
77
- ```
49
+ ## Quick Start
78
50
 
79
- Then use the 4 MCP tools:
51
+ ### One Command
80
52
 
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
53
+ ```bash
54
+ # Run dashboard (shows status, scores, recommendations)
55
+ npx ruvnet-kb-first
87
56
  ```
88
57
 
89
- ### NPX (CLI Wrapper)
58
+ ### First Time Setup
90
59
 
91
60
  ```bash
92
- # Start MCP server
93
- npx ruvnet-kb-first mcp
61
+ # Initialize with your knowledge base
62
+ npx ruvnet-kb-first init --kb ask_ruvnet
94
63
 
95
- # Legacy CLI commands still work
96
- npx ruvnet-kb-first score
97
- npx ruvnet-kb-first status
98
- ```
99
-
100
- ### The Score-Driven Workflow
101
-
102
- ```
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
- └──────────────────────────────────────────────────────────────┘
64
+ # Or run interactive setup
65
+ npx ruvnet-kb-first init
111
66
  ```
112
67
 
113
- **Key Rule:** Negative delta BLOCKS progress. No shortcuts.
114
-
115
- ### Legacy Options
68
+ ### Then Ask Claude
116
69
 
117
- ```json
118
- {
119
- "mcpServers": {
120
- "ruvnet-kb-first": {
121
- "command": "npx",
122
- "args": ["ruvnet-kb-first", "mcp"]
123
- }
124
- }
125
- }
126
- ```
70
+ > "Review this app using RuvNet-KB-First and recommend improvements"
127
71
 
128
72
  ---
129
73
 
130
- ## 📦 CLI Commands
74
+ ## Three-Tier Knowledge Base System
131
75
 
132
- | Command | Description |
133
- |---------|-------------|
134
- | `ruvnet-kb-first init` | Initialize KB-First structure in project |
135
- | `ruvnet-kb-first status` | Show project status and phase progress |
136
- | `ruvnet-kb-first score` | Calculate compliance score (0-100) |
137
- | `ruvnet-kb-first verify` | Run verification checks |
138
- | `ruvnet-kb-first phase <n>` | Run or view specific phase (0-11) |
139
- | `ruvnet-kb-first hooks` | Manage KB-First enforcement hooks |
140
-
141
- ---
142
-
143
- ## 🎯 What This Solves
144
-
145
- | Problem | KB-First Solution |
146
- |---------|-------------------|
147
- | AI hallucinations | Every response cites KB sources or acknowledges gaps |
148
- | Untraceable advice | Every answer includes expert attribution |
149
- | Generic responses | Domain-specific knowledge from top experts |
150
- | Static systems | SONA learning improves with usage |
151
- | Simple search | GNN models decision cascades, Attention routes to experts |
152
-
153
- ---
154
-
155
- ## 🧠 The Intelligence Stack
156
-
157
- KB-First leverages the full **RuVector** stack for intelligent applications:
76
+ RuvNet-KB-First uses a tiered approach to ensure it works for everyone:
158
77
 
159
78
  <p align="center">
160
- <img src="assets/intelligence-stack.svg" alt="The Intelligence Stack" width="800">
79
+ <img src="assets/kb-discovery-flow.svg" alt="KB Discovery Flow" width="800">
161
80
  </p>
162
81
 
163
82
  <details>
164
- <summary>📄 Text Version (for AI/accessibility)</summary>
83
+ <summary>Text Version (for AI/accessibility)</summary>
165
84
 
166
85
  ```
167
86
  ┌─────────────────────────────────────────────────────────────────────────────┐
168
- │ THE INTELLIGENCE STACK │
87
+ │ KB DISCOVERY FLOW │
169
88
  ├─────────────────────────────────────────────────────────────────────────────┤
170
- │ │
171
- │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
172
- │ │ GNN │ │ ATTENTION │ │ SONA │ │
173
- │ │ (Reasoning) │ │ (Routing) │ │ (Learning) │ │
174
- │ │ │ │ │ │ │ │
175
- │ │ Sees how things │ │ Knows which │ │ Remembers what │ │
176
- │ │ connect and │ │ expert/approach │ │ worked and │ │
177
- │ │ cascade │ │ fits this query │ │ patterns that │ │
178
- │ │ │ │ │ │ succeed │ │
179
- │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
180
- │ │ │ │ │
181
- │ └────────────────────┼────────────────────┘ │
182
- │ │ │
183
- │ ┌───────────▼───────────┐ │
184
- │ │ VECTOR SEARCH │ │
185
- │ │ (Foundation) │ │
186
- │ │ │ │
187
- │ │ Semantic retrieval │ │
188
- │ │ from knowledge base │ │
189
- │ └───────────────────────┘ │
190
- │ │
89
+ │ │
90
+ │ START: npx ruvnet-kb-first │
91
+ │ │ │
92
+ │ ▼ │
93
+ │ ┌─────────────────────────────────────────────────────────────────┐ │
94
+ │ │ Check: Is ruvector-postgres running on port 5435? │ │
95
+ │ └─────────────────────────────────────────────────────────────────┘ │
96
+ │ │ │
97
+ │ ├─── YES ──► TIER 1: Full KB (230K+ entries) │
98
+ │ │ • All features enabled │
99
+ │ │ • Semantic search, citations, gap detection │
100
+ │ │ • Score: KB Health + Application Scores │
101
+ │ │ │
102
+ │ └─── NO ───► Check: Does bundled starter KB exist? │
103
+ │ │ │
104
+ │ ├─── YES ──► TIER 2: Starter KB (500 entries) │
105
+ │ │ • Core patterns included │
106
+ │ │ • Limited but functional │
107
+ │ │ │
108
+ │ └─── NO ───► TIER 3: Structural Only │
109
+ │ • Directory/file scoring only │
110
+ │ • Offers setup options: │
111
+ │ [1] Set up full KB (Docker) │
112
+ │ [2] Download starter KB │
113
+ │ [3] Continue in limited mode │
114
+ │ │
191
115
  └─────────────────────────────────────────────────────────────────────────────┘
192
116
  ```
193
117
 
194
118
  </details>
195
119
 
196
- ### When to Use Each Technology
120
+ ### Tier Comparison
197
121
 
198
- | Technology | Primary Use | Example Application |
199
- |------------|-------------|---------------------|
200
- | **GNN** | Decisions affect other decisions | Retirement planning, medical diagnosis |
201
- | **Attention (MoE)** | Route queries to expert domains | Travel optimizer, customer support |
202
- | **SONA** | Learn from outcomes | Business simulator, strategy advisor |
203
- | **Vector Search** | Find relevant content | All applications (foundation) |
122
+ | Tier | Requirements | Entries | Features |
123
+ |------|--------------|---------|----------|
124
+ | **Full** | Docker + ruvector-postgres | 230K+ | All features: semantic search, citations, gap detection |
125
+ | **Starter** | None (bundled SQLite) | 500 | Core patterns, basic semantic search |
126
+ | **Structural** | None | 0 | Directory scoring, phase tracking, hooks only |
204
127
 
205
128
  ---
206
129
 
207
- ## 🏗️ The 12-Phase Build Process
208
-
209
- KB-First applications are built through a rigorous 12-phase process with **57 sub-phases** and **hard gates**:
210
-
211
- <p align="center">
212
- <img src="https://raw.githubusercontent.com/stuinfla/Ruvnet-KB-App_Creator/main/assets/build-process.svg?v=2" alt="The 8-Phase Build Process" width="800">
213
- </p>
130
+ ## What You See
214
131
 
215
- <details>
216
- <summary>📄 Text Version (for AI/accessibility)</summary>
132
+ When you run `npx ruvnet-kb-first`:
217
133
 
218
134
  ```
219
- ┌─────────────────────────────────────────────────────────────────────────────┐
220
- │ THE 8-PHASE BUILD PROCESS │
221
- ├─────────────────────────────────────────────────────────────────────────────┤
222
- │ │
223
- │ Phase 1 Phase 2 Phase 3 Phase 4 │
224
- │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
225
- │ │STORAGE│ ────► │ KB │ ────► │PERSIST│ ────► │ VIZ │ │
226
- │ │ SETUP │ │ BUILD │ │ │ │ │ │
227
- │ └───────┘ └───┬───┘ └───────┘ └───┬───┘ │
228
- │ │ │ │
229
- │ │ Sub-phases: │ │
230
- │ │ ├─ 2.1 Domain Scoping │ │
231
- │ │ ├─ 2.2 Perspective Expansion │ │
232
- │ │ ├─ 2.3 Expert Discovery │ │
233
- │ │ ├─ 2.4 Completeness Audit │ │
234
- │ │ ├─ 2.5 Gap Filling │ │
235
- │ │ ├─ 2.6 Structure (≤9 nodes) │ │
236
- │ │ ├─ 2.7 Recursive Depth │ │
237
- │ │ └─ 2.8 Quality Loop (≥98) └──────────┐ │
238
- │ │ │ │
239
- │ │ ▼ │
240
- │ Phase 8 Phase 7 Phase 6 Phase 5 │
241
- │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
242
- │ │VERIFY │ ◄──── │ BUILD │ ◄──── │SCAFF- │ ◄──── │ SDK │ │
243
- │ │ │ │ (ENF) │ │ OLD │ │ LAYER │ │
244
- │ └───────┘ └───┬───┘ └───────┘ └───────┘ │
245
- │ │ │
246
- │ └─► ENFORCEMENT RULES: │
247
- │ • NO SHORTCUTS │
248
- │ • NO HARDCODED VALUES │
249
- │ • ALL SOURCES TRACED │
250
- │ │
251
- └─────────────────────────────────────────────────────────────────────────────┘
135
+ ╔════════════════════════════════════════════════════════════════════════╗
136
+ ║ RuvNet-KB-First Dashboard ║
137
+ ║ Build intelligent applications on expert knowledge ║
138
+ ╚════════════════════════════════════════════════════════════════════════╝
139
+
140
+ KNOWLEDGE BASE
141
+ ────────────────────────────────────────────────────────────────────
142
+ ● Status: CONNECTED
143
+ Schema: ask_ruvnet
144
+ Entries: 230,721
145
+ Host: localhost:5435
146
+
147
+ KB Health Score: █████████████████░░░ 85/100
148
+
149
+ APPLICATION SCORES
150
+ ────────────────────────────────────────────────────────────────────
151
+ KB Coverage ████████████████████ 100/100 No code yet
152
+ Phase Progress ░░░░░░░░░░░░░░░░░░░░ 0/100 0/12 complete
153
+ Hooks ████████████████████ 100/100 All installed
154
+ KB Gaps ████████████████████ 100/100 No gaps
155
+ Documentation ░░░░░░░░░░░░░░░░░░░░ 0/100 Incomplete
156
+ Security ████████████████░░░░ 80/100 Issues found
157
+
158
+ ────────────────────────────────────────────────────────────────────
159
+ OVERALL SCORE █████████████░░░░░░░ 63/100 C
160
+
161
+ RECOMMENDATIONS
162
+ ────────────────────────────────────────────────────────────────────
163
+ → Complete build phases: ruvnet-kb-first phase 0
164
+ → Add documentation: README.md, docs/api.md, docs/architecture.md
165
+ → Fix security issues: ruvnet-kb-first verify --phase=9
166
+
167
+ COMMANDS
168
+ ────────────────────────────────────────────────────────────────────
169
+ ruvnet-kb-first score --detailed Full score breakdown
170
+ ruvnet-kb-first status --detailed Detailed project status
171
+ ruvnet-kb-first verify Run verification checks
172
+ ruvnet-kb-first phase <n> Execute build phase
173
+
174
+ Ask Claude: "Review this app using RuvNet-KB-First and recommend improvements"
252
175
  ```
253
176
 
254
- </details>
255
-
256
- ### Phase Summary
257
-
258
- | Phase | Name | Sub-Phases | Purpose | Quality Gate |
259
- |-------|------|------------|---------|--------------|
260
- | 0 | Assessment | 6 | Score existing KB/app (brownfield) | ⛔ User types "PROCEED" |
261
- | 1 | Storage Setup | 6 | Start PostgreSQL + ruvector | Connection verified |
262
- | 1.5 | Hooks Setup | 4 | RuVector hooks for KB enforcement | Hook verify passes |
263
- | 2 | KB Creation | 8 | Build world-class knowledge base | Score ≥98/100 |
264
- | 3 | Persistence | - | Store with embeddings | Semantic search works |
265
- | 4 | Visualization | - | Interactive 3D tree | Navigation works |
266
- | 5 | Integration Layer | - | TypeScript SDK | All functions compile |
267
- | 6 | Scaffold | - | Project structure | KB enforcement in place |
268
- | 7 | Build | 7 | Implement with KB enforcement | No hardcoded values |
269
- | 8 | Verification | 8 | Final check | All 8 checks pass |
270
- | 9 | Security | 6 | Security audit & hardening | 0 critical/high issues |
271
- | 10 | Documentation | 6 | Complete docs & versioning | All docs complete |
272
- | 11 | Deployment | 6 | Production with public access | Go-live verified |
273
-
274
- **Total: 12 phases, 57 sub-phases, hard gates at every boundary.**
275
-
276
177
  ---
277
178
 
278
- ## 🎭 Four Intelligence Patterns
279
-
280
- Every KB-First application fits one of four patterns. The pattern determines your primary technology:
281
-
282
- ### Pattern 1: Decision Web (GNN-First)
283
- **Use when:** Changing one variable affects many others
284
-
285
- *Examples: Retirement planning, medical treatment, portfolio construction*
179
+ ## Distribution Model
286
180
 
287
181
  <p align="center">
288
- <img src="assets/decision-web-gnn.svg" alt="GNN Decision Web Pattern" width="800">
182
+ <img src="assets/distribution-model.svg" alt="Distribution Model" width="800">
289
183
  </p>
290
184
 
291
185
  <details>
292
- <summary>📄 Text Version (for AI/accessibility)</summary>
186
+ <summary>Text Version (for AI/accessibility)</summary>
293
187
 
294
188
  ```
295
189
  ┌─────────────────────────────────────────────────────────────────────────────┐
296
- │ USER QUERY: "What if I take Social Security at 70?" │
190
+ │ DISTRIBUTION MODEL │
297
191
  ├─────────────────────────────────────────────────────────────────────────────┤
298
- │ │ │
299
- │ ▼ │
300
- │ ┌───────────────────────────────────────────────────────────────────────┐ │
301
- │ │ GNN DECISION GRAPH │ │
302
- │ │ │ │
303
- │ │ ┌───────────┐ │ │
304
- │ │ │ SS Age │ │ │
305
- │ │ │ (70) │ │ │
306
- │ │ └─────┬─────┘ │ │
307
- │ │ affects │ affects │ │
308
- │ │ ┌───────────────┴───────────────┐ │ │
309
- │ │ ▼ ▼ │ │
310
- │ │ ┌─────────────┐ ┌─────────────────┐ │ │
311
- │ │ │ Tax Bracket │ │ Roth Conversion │ │ │
312
- │ │ └──────┬──────┘ │ Space │ │ │
313
- │ │ │ affects └────────┬────────┘ │ │
314
- │ │ └──────────┐ affects │ │ │
315
- │ │ ▼ ◄─────────────────┘ │ │
316
- │ │ ┌──────────────┐ │ │
317
- │ │ │ Medicare │ │ │
318
- │ │ │ Premium │ │ │
319
- │ │ └──────────────┘ │ │
320
- │ └───────────────────────────────────────────────────────────────────────┘ │
321
- │ │ │
322
- │ ▼ │
323
- │ OUTPUT: Cascade effects, similar patterns, scenario comparison │
192
+ │ │
193
+ │ CANONICAL USAGE (Always Latest): │
194
+ │ ───────────────────────────────── │
195
+ │ │
196
+ │ npx ruvnet-kb-first@latest │
197
+ │ │
198
+ │ WHY: │
199
+ │ • npx caches locally but checks for updates │
200
+ │ • @latest ensures you always get current version │
201
+ │ • No global install = no stale versions │
202
+ │ • Works identically on all machines │
203
+ │ │
204
+ │ ───────────────────────────────────────────────────────────────────────── │
205
+ │ │
206
+ │ MCP CONFIG (Auto-Updating): │
207
+ │ ─────────────────────────── │
208
+ │ │
209
+ │ { │
210
+ │ "mcpServers": { │
211
+ │ "ruvnet-kb-first": { │
212
+ │ "command": "npx", │
213
+ │ "args": ["ruvnet-kb-first@latest", "mcp"] │
214
+ │ } │
215
+ │ } │
216
+ │ } │
217
+ │ │
218
+ │ ───────────────────────────────────────────────────────────────────────── │
219
+ │ │
220
+ │ AVOID (Causes Version Sprawl): │
221
+ │ ───────────────────────────── │
222
+ │ │
223
+ │ ✗ npm install -g ruvnet-kb-first (hard to update) │
224
+ │ ✗ Version pinning in MCP config (prevents updates) │
225
+ │ │
324
226
  └─────────────────────────────────────────────────────────────────────────────┘
325
227
  ```
326
228
 
327
229
  </details>
328
230
 
329
- ### Pattern 2: Combinatorial Routing (Attention-First)
330
- **Use when:** Queries need to go to different expert domains
231
+ ### Why npx?
331
232
 
332
- *Examples: Travel optimizer, customer support, resource allocation*
233
+ | Approach | Problem |
234
+ |----------|---------|
235
+ | `npm install -g` | Creates stale versions across machines |
236
+ | `npx ruvnet-kb-first` | Always checks for latest, caches locally |
333
237
 
334
- <p align="center">
335
- <img src="https://raw.githubusercontent.com/stuinfla/Ruvnet-KB-App_Creator/main/assets/combinatorial-routing.svg?v=2" alt="MoE Expert Routing Pattern" width="800">
336
- </p>
238
+ ---
337
239
 
338
- <details>
339
- <summary>📄 Text Version (for AI/accessibility)</summary>
240
+ ## CLI Commands
340
241
 
341
- ```
342
- ┌─────────────────────────────────────────────────────────────────────────────┐
343
- │ USER QUERY: "Find me cheap business class to Tokyo using points" │
344
- ├─────────────────────────────────────────────────────────────────────────────┤
345
- │ │ │
346
- │ ▼ │
347
- │ ┌───────────────────────────────────────────────────────────────────────┐ │
348
- │ │ MoE EXPERT ROUTING │ │
349
- │ │ │ │
350
- │ │ Query ─────┬─────────────────┬─────────────────┐ │ │
351
- │ │ │ │ │ │ │
352
- │ │ ▼ ▼ ▼ │ │
353
- │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
354
- │ │ │ Award Travel │ │ Cash Fares │ │ Positioning │ │ │
355
- │ │ │ Expert │ │ Expert │ │ Expert │ │ │
356
- │ │ │ │ │ │ │ │ │ │
357
- │ │ │ Score: 0.85 │ │ Score: 0.45 │ │ Score: 0.72 │ │ │
358
- │ │ │ ████████████░░ │ │ ████████░░░░░░ │ │ ███████████░░░ │ │ │
359
- │ │ │ [SELECTED] │ │ [SKIP] │ │ [SELECTED] │ │ │
360
- │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
361
- │ │ │ │
362
- │ │ Route to: Award Travel + Positioning │ │
363
- │ └───────────────────────────────────────────────────────────────────────┘ │
364
- │ │ │
365
- │ ▼ │
366
- │ OUTPUT: Multi-expert synthesis, optimal combinations │
367
- └─────────────────────────────────────────────────────────────────────────────┘
368
- ```
242
+ | Command | Description |
243
+ |---------|-------------|
244
+ | `ruvnet-kb-first` | Show dashboard (status, scores, recommendations) |
245
+ | `ruvnet-kb-first init` | Initialize RuvNet-KB-First in project |
246
+ | `ruvnet-kb-first init --kb <schema>` | Initialize with existing KB |
247
+ | `ruvnet-kb-first status` | Show project status and phase progress |
248
+ | `ruvnet-kb-first score` | Calculate compliance score (0-100) |
249
+ | `ruvnet-kb-first score --detailed` | Show detailed score breakdown |
250
+ | `ruvnet-kb-first verify` | Run verification checks |
251
+ | `ruvnet-kb-first phase <n>` | Run or view specific phase (0-11) |
252
+ | `ruvnet-kb-first hooks` | Manage KB-First enforcement hooks |
369
253
 
370
- </details>
254
+ ---
371
255
 
372
- ### Pattern 3: Scenario Learning (SONA-First)
373
- **Use when:** "What worked for people like me?" is the core value
256
+ ## MCP Server Integration
374
257
 
375
- *Examples: Business simulator, strategy advisor, personalized coaching*
258
+ Add to your Claude Code `settings.json`:
376
259
 
377
- <p align="center">
378
- <img src="assets/scenario-learning-sona.svg" alt="SONA Pattern Recall" width="800">
379
- </p>
260
+ ```json
261
+ {
262
+ "mcpServers": {
263
+ "ruvnet-kb-first": {
264
+ "command": "npx",
265
+ "args": ["ruvnet-kb-first@latest", "mcp"]
266
+ }
267
+ }
268
+ }
269
+ ```
380
270
 
381
- <details>
382
- <summary>📄 Text Version (for AI/accessibility)</summary>
271
+ ### MCP Tools
272
+
273
+ | Tool | Description |
274
+ |------|-------------|
275
+ | `kb_first_assess` | Establish baseline score (always first) |
276
+ | `kb_first_phase` | Get phase guidance with baseline reminder |
277
+ | `kb_first_delta` | Compare scores - blocks if regression |
278
+ | `kb_first_gate` | Pass quality gate, proceed to next phase |
279
+
280
+ ---
281
+
282
+ ## The Score-Driven Workflow
383
283
 
384
284
  ```
385
- ┌─────────────────────────────────────────────────────────────────────────────┐
386
- │ USER QUERY: "What pricing strategy should I use for my SaaS?" │
387
- ├─────────────────────────────────────────────────────────────────────────────┤
388
- │ │ │
389
- │ ▼ │
390
- │ ┌───────────────────────────────────────────────────────────────────────┐ │
391
- │ │ SONA PATTERN RECALL │ │
392
- │ │ │ │
393
- │ │ ┌─────────────────┐ ┌─────────────────┐ │ │
394
- │ │ │ Your Profile │ │ Similar │ │ │
395
- │ │ │ │ ──────► │ Businesses │ │ │
396
- │ │ │ • B2B SaaS │ pattern │ │ │ │
397
- │ │ │ • Seed stage │ match │ 847 matches │ │ │
398
- │ │ │ • $50K MRR │ │ 94% confidence │ │ │
399
- │ │ └─────────────────┘ └────────┬────────┘ │ │
400
- │ │ │ │ │
401
- │ │ ▼ │ │
402
- │ │ ┌───────────────────────────────────────────────────────────────┐ │ │
403
- │ │ │ "Companies like yours that used freemium saw 23% better │ │ │
404
- │ │ │ conversion than those starting with paid-only models..." │ │ │
405
- │ │ │ │ │ │
406
- │ │ │ Source: 312 similar outcomes analyzed │ │ │
407
- │ │ └───────────────────────────────────────────────────────────────┘ │ │
408
- │ └───────────────────────────────────────────────────────────────────────┘ │
409
- │ │ │
410
- │ ▼ │
411
- │ OUTPUT: Learned patterns, outcome data, confidence score │
412
- └─────────────────────────────────────────────────────────────────────────────┘
285
+ ┌──────────────────────────────────────────────────────────────┐
286
+ │ 1. kb_first_assess → Baseline: 47/100 (Grade: D) │
287
+ │ 2. kb_first_phase → Phase 3: KB Population tasks │
288
+ │ 3. [Do the work] → Add content, generate embeddings │
289
+ │ 4. kb_first_delta → Current: 62/100, Delta: +15 ✓ PASS │
290
+ │ 5. kb_first_gate → Gate passed, proceed to Phase 4 │
291
+ │ 6. REPEAT → New baseline: 62/100 │
292
+ └──────────────────────────────────────────────────────────────┘
413
293
  ```
414
294
 
415
- </details>
295
+ **Key Rule:** Negative delta BLOCKS progress. No shortcuts.
416
296
 
417
- ### Pattern 4: Continuous Optimization (Attention + SONA Loop)
418
- **Use when:** You need ongoing monitoring and adaptation
297
+ ---
298
+
299
+ ## The 12-Phase Build Process
419
300
 
420
- *Examples: SEO optimizer, trading system, adaptive marketing*
301
+ KB-First applications are built through a rigorous 12-phase process:
421
302
 
422
303
  <p align="center">
423
- <img src="assets/continuous-optimization.svg" alt="Continuous Optimization Loop" width="800">
304
+ <img src="assets/build-process.svg" alt="The 12-Phase Build Process" width="800">
424
305
  </p>
425
306
 
426
307
  <details>
427
- <summary>📄 Text Version (for AI/accessibility)</summary>
308
+ <summary>Text Version (for AI/accessibility)</summary>
428
309
 
429
310
  ```
430
311
  ┌─────────────────────────────────────────────────────────────────────────────┐
431
- │ CONTINUOUS OPTIMIZATION LOOP │
432
- │ (Weekly Cycle) │
312
+ │ THE 12-PHASE BUILD PROCESS │
433
313
  ├─────────────────────────────────────────────────────────────────────────────┤
434
314
  │ │
435
- │ ┌─────────────────┐ │
436
- │ │ Flash Attention │ │
437
- │ ┌────────►│ │────────┐ │
438
- │ │ │ Scan content & │ │ │
439
- │ │ │ competitors │ │ │
440
- │ │ └─────────────────┘ │ │
441
- │ │ ▼ │
442
- │ ┌─────────────────┐ ┌─────────────────┐ │
443
- │ │ SONA Learning │ │ Cross Attention │ │
444
- │ │ │ │ │ │
445
- │ │ Remember what │ │ Identify gaps │ │
446
- │ │ worked │ │ │ │
447
- │ └─────────────────┘ └─────────────────┘ │
448
- │ ▲ │ │
449
- │ │ ▼ │
450
- │ │ ┌─────────────────┐ │ │
451
- │ │ │ Track Results │ │ │
452
- │ └─────────│ │◄───────┘ │
453
- │ │ Measure impact │ │
454
- │ └────────┬────────┘ │
455
- │ │ │
456
- │ ▼ │
457
- │ ┌─────────────────┐ │
458
- │ │ Deploy Changes │ │
459
- │ │ │ │
460
- │ │ Push updates │ │
461
- │ └─────────────────┘ │
315
+ │ Phase 0 Phase 1 Phase 1.5 Phase 2 │
316
+ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
317
+ │ │ASSESS │ ────► │STORAGE│ ────► │ HOOKS │ ────► │ KB │ │
318
+ │ │ │ │ SETUP │ │ SETUP │ │ BUILD │ │
319
+ │ └───────┘ └───────┘ └───────┘ └───────┘ │
320
+ │ │
321
+ │ Phase 3 Phase 4 Phase 5 Phase 6 │
322
+ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
323
+ │ │PERSIST│ ────► │ VIZ │ ────► │ SDK │ ────► │SCAFF- │ │
324
+ │ │ │ │ │ │ LAYER │ │ OLD │ │
325
+ │ └───────┘ └───────┘ └───────┘ └───────┘ │
326
+ │ │
327
+ │ Phase 7 Phase 8 Phase 9 Phase 10 │
328
+ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
329
+ │ │ BUILD │ ────► │VERIFY │ ────► │SECURITY│ ───► │ DOCS │ │
330
+ │ │ (ENF) │ │ │ │ │ │ │ │
331
+ │ └───────┘ └───────┘ └───────┘ └───────┘ │
332
+ │ │
333
+ │ Phase 11 │
334
+ │ ┌───────┐ │
335
+ │ │DEPLOY │ │
336
+ │ │ │ │
337
+ │ └───────┘ │
338
+ │ │
339
+ │ ENFORCEMENT: NO SHORTCUTS • NO HARDCODED VALUES • ALL SOURCES TRACED │
462
340
  │ │
463
- │ Each iteration improves: KB quality, content coverage, search rankings │
464
341
  └─────────────────────────────────────────────────────────────────────────────┘
465
342
  ```
466
343
 
467
344
  </details>
468
345
 
469
- ---
470
-
471
- ## 🚀 Quick Start
472
-
473
- ### Prerequisites
474
- - Docker
475
- - Node.js 18+
476
- - Python 3 (for hooks)
477
- - Claude Code
478
-
479
- ### Option 1: Global Installation (Recommended)
480
-
481
- Install KB-First as a skill available in ALL your projects:
482
-
483
- ```bash
484
- # Clone the repository
485
- git clone https://github.com/stuinfla/Ruvnet-KB-App_Creator.git
486
- cd Ruvnet-KB-App_Creator
487
-
488
- # Install globally
489
- ./install/install-global.sh
490
- ```
346
+ ### Phase Summary
491
347
 
492
- This installs:
493
- - `/kb-first` command in Claude Code
494
- - Hook scripts for automatic KB enforcement
495
- - Skill documentation in `~/.claude/skills/`
348
+ | Phase | Name | Purpose | Quality Gate |
349
+ |-------|------|---------|--------------|
350
+ | 0 | Assessment | Score existing KB/app | User types "PROCEED" |
351
+ | 1 | Storage Setup | Start PostgreSQL + ruvector | Connection verified |
352
+ | 1.5 | Hooks Setup | RuVector hooks for KB enforcement | Hook verify passes |
353
+ | 2 | KB Creation | Build world-class knowledge base | Score ≥98/100 |
354
+ | 3 | Persistence | Store with embeddings | Semantic search works |
355
+ | 4 | Visualization | Interactive 3D tree | Navigation works |
356
+ | 5 | Integration Layer | TypeScript SDK | All functions compile |
357
+ | 6 | Scaffold | Project structure | KB enforcement in place |
358
+ | 7 | Build | Implement with KB enforcement | No hardcoded values |
359
+ | 8 | Verification | Final check | All 8 checks pass |
360
+ | 9 | Security | Security audit & hardening | 0 critical/high issues |
361
+ | 10 | Documentation | Complete docs & versioning | All docs complete |
362
+ | 11 | Deployment | Production with public access | Go-live verified |
496
363
 
497
- Then in any project, just type:
498
- ```
499
- /kb-first
500
- ```
364
+ ---
501
365
 
502
- ### Option 2: Project-Level Installation
366
+ ## User Scenarios
503
367
 
504
- Initialize KB-First in a specific project:
368
+ ### Scenario A: Power User (Full KB)
505
369
 
506
370
  ```bash
507
- # In your project directory
508
- curl -sSL https://raw.githubusercontent.com/stuinfla/Ruvnet-KB-App_Creator/main/install/init-project.sh | bash
509
- ```
371
+ $ npx ruvnet-kb-first
510
372
 
511
- Or manually:
512
- ```bash
513
- git clone https://github.com/stuinfla/Ruvnet-KB-App_Creator.git
514
- ./Ruvnet-KB-App_Creator/install/init-project.sh
373
+ KB: ask_ruvnet (230,721 entries) on localhost:5435
374
+ Tier: FULL
375
+ All features enabled.
515
376
  ```
516
377
 
517
- ### Option 3: Manual Setup
378
+ ### Scenario B: New User (No Docker)
518
379
 
519
380
  ```bash
520
- # Clone the repository
521
- git clone https://github.com/stuinfla/Ruvnet-KB-App_Creator.git
522
- cd Ruvnet-KB-App_Creator
523
-
524
- # Start the database
525
- docker run -d --name kb-postgres \
526
- -e POSTGRES_PASSWORD=secret \
527
- -p 5432:5432 \
528
- ruvnet/ruvector-postgres:latest
381
+ $ npx ruvnet-kb-first
529
382
 
530
- # Set environment
531
- export DATABASE_URL="postgres://postgres:secret@localhost:5432/postgres"
383
+ No Knowledge Base detected.
532
384
 
533
- # Initialize schema
534
- psql $DATABASE_URL -f templates/schema.sql
385
+ Options:
386
+ [1] Set up full KB (Docker) - recommended
387
+ [2] Download starter KB - quick start
388
+ [3] Continue in structural-only mode
535
389
 
536
- # Install hooks (Phase 1.5)
537
- npx @ruvector/cli hooks init
538
- npx @ruvector/cli hooks install
390
+ Select [1/2/3]:
539
391
  ```
540
392
 
541
- ### Usage
393
+ ### Scenario C: CI/CD Pipeline
542
394
 
543
- ```bash
544
- /kb-first # Start interactive builder
545
- /kb-first init # Initialize in current project
546
- /kb-first score # Score existing KB and app
547
- /kb-first verify # Run verification checks
548
- /kb-first hooks # Configure hooks
395
+ ```yaml
396
+ # GitHub Actions - structural-only mode
397
+ - name: KB-First Verification
398
+ run: npx ruvnet-kb-first verify --structural-only
549
399
  ```
550
400
 
551
401
  ---
552
402
 
553
- ## 📁 Repository Structure
403
+ ## The Five Enforcement Rules
554
404
 
555
- ```
556
- kb-first-v43/
557
- ├── README.md # This file
558
- ├── SKILL.md # Main skill documentation (v4.3)
559
- ├── .github/
560
- │ └── workflows/
561
- │ └── kb-first-ci.yml # CI/CD quality gates
562
- ├── install/ # Installation scripts
563
- │ ├── install-global.sh # Global skill installation
564
- │ ├── init-project.sh # Project-level initialization
565
- │ ├── kb-first-skill.md # Skill file for ~/.claude/skills/
566
- │ └── kb-first-command.md # Command file for ~/.claude/commands/
567
- ├── phases/ # Phase-by-phase instructions
568
- │ ├── 00-assessment.md # Greenfield + Brownfield assessment
569
- │ ├── 01-storage.md # PostgreSQL + ruvector setup
570
- │ ├── 01.5-hooks-setup.md # RuVector hooks configuration
571
- │ ├── 02-kb-creation.md
572
- │ ├── 03-persistence.md
573
- │ ├── 04-visualization.md
574
- │ ├── 05-integration.md
575
- │ ├── 06-scaffold.md
576
- │ ├── 07-build.md
577
- │ ├── 08-verification.md # 8 numbered sub-phases (8.1-8.8)
578
- │ ├── 09-security.md # Security audit & hardening
579
- │ ├── 10-documentation.md # Docs & versioning
580
- │ ├── 11-deployment.md # Production deployment
581
- │ └── testing.md # Comprehensive testing strategy
582
- ├── patterns/ # Intelligence pattern guides
583
- │ ├── decision-web.md # GNN-first pattern
584
- │ ├── combinatorial-routing.md # Attention-first pattern
585
- │ ├── scenario-learning.md # SONA-first pattern
586
- │ └── continuous-optimization.md
587
- ├── templates/ # Code templates
588
- │ ├── intentions.md # Greenfield project intentions
589
- │ ├── schema.sql # PostgreSQL schema
590
- │ ├── kb-client.ts # TypeScript KB client
591
- │ ├── gnn-engine.ts # GNN implementation
592
- │ ├── attention-router.ts # Attention routing
593
- │ ├── sona-config.ts # SONA configuration
594
- │ ├── code-analysis.ts # Code analysis engine
595
- │ └── federated-kb-learner.ts # Federated KB learning
596
- ├── prompts/ # AI prompts for KB creation
597
- │ ├── expert-discovery.md
598
- │ ├── completeness-audit.md
599
- │ └── quality-critique.md
600
- ├── scripts/ # Verification scripts
601
- │ ├── 1.5-hooks-verify.sh # Hook verification suite
602
- │ ├── 8.1-code-scan.sh # No hardcoded values
603
- │ ├── 8.2-import-check.sh # KB imports required
604
- │ ├── 8.3-source-returns.sh # kbSources in returns
605
- │ ├── 8.4-startup-verify.sh # KB connection at startup
606
- │ ├── 8.5-fallback-check.sh # No fallback patterns
607
- │ ├── 8.6-attribution.sh # Expert attribution
608
- │ ├── 8.7-confidence.sh # Confidence scores
609
- │ ├── 8.8-gap-logging.sh # Gap detection
610
- │ ├── 9-security-audit.sh # Security verification suite
611
- │ ├── init-project.sh # Project initialization
612
- │ └── verify-enforcement.sh # Full enforcement check
613
- ├── references/ # Technical references
614
- │ ├── ruvector-functions.md
615
- │ ├── attention-mechanisms.md
616
- │ ├── sona-config.md
617
- │ ├── hooks-integration.md
618
- │ ├── hard-gates.md # Gate enforcement rules
619
- │ ├── swarm-config.md # Parallel execution config
620
- │ ├── error-recovery.md # Rollback procedures
621
- │ └── troubleshooting.md # Quick diagnosis guide
622
- ├── examples/ # Working examples
623
- │ ├── retirement-advisor/
624
- │ ├── travel-optimizer/
625
- │ ├── business-simulator/
626
- │ └── seo-engine/
627
- └── assets/ # Images and diagrams
628
- ├── kb-first-architecture.svg
629
- ├── intelligence-stack.svg
630
- ├── build-process.svg
631
- ├── decision-web-gnn.svg
632
- ├── combinatorial-routing.svg
633
- ├── scenario-learning-sona.svg
634
- └── continuous-optimization.svg
635
- ```
636
-
637
- ---
638
-
639
- ## 📖 Documentation
640
-
641
- | Document | Purpose |
642
- |----------|---------|
643
- | [SKILL.md](SKILL.md) | Complete skill documentation for Claude |
644
- | [phases/](phases/) | Detailed phase-by-phase instructions |
645
- | [patterns/](patterns/) | Intelligence pattern implementation guides |
646
- | [references/](references/) | Technical API and function references |
647
-
648
- ---
649
-
650
- ## 🔧 The Five Enforcement Rules
651
-
652
- Every KB-First application follows these rules:
405
+ Every RuvNet-KB-First application follows these rules:
653
406
 
654
407
  ### Rule 1: KB-First Mandate
655
408
  > Every response must cite KB sources or explicitly acknowledge a gap.
@@ -668,22 +421,54 @@ Every KB-First application follows these rules:
668
421
 
669
422
  ---
670
423
 
671
- ## 🤝 Contributing
424
+ ## Environment Variables
672
425
 
673
- Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) first.
426
+ Configure KB connection via environment:
427
+
428
+ | Variable | Default | Description |
429
+ |----------|---------|-------------|
430
+ | `KB_HOST` | `localhost` | Database host |
431
+ | `KB_PORT` | `5435` | Database port |
432
+ | `KB_PASSWORD` | `guruKB2025` | Database password |
433
+ | `KB_MODE` | `auto` | Force mode: `full`, `starter`, `structural` |
674
434
 
675
435
  ---
676
436
 
677
- ## 📄 License
437
+ ## Repository Structure
678
438
 
679
- MIT License - see [LICENSE](LICENSE) for details.
439
+ ```
440
+ ruvnet-kb-first/
441
+ ├── bin/
442
+ │ └── kb-first.js # CLI entry point
443
+ ├── src/
444
+ │ ├── commands/
445
+ │ │ ├── dashboard.js # Default dashboard view
446
+ │ │ ├── init.js # Project initialization
447
+ │ │ ├── status.js # Status display
448
+ │ │ ├── score.js # Scoring engine
449
+ │ │ ├── verify.js # Verification checks
450
+ │ │ ├── phase.js # Phase execution
451
+ │ │ └── hooks.js # Hook management
452
+ │ ├── kb-discovery.js # Three-tier KB detection
453
+ │ └── mcp-server.js # MCP server for Claude
454
+ ├── phases/ # Phase-by-phase instructions
455
+ ├── templates/ # Code templates
456
+ ├── scripts/ # Verification scripts
457
+ ├── install/ # Installation helpers
458
+ └── assets/ # SVG diagrams
459
+ ```
460
+
461
+ ---
462
+
463
+ ## Contributing
464
+
465
+ Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) first.
680
466
 
681
467
  ---
682
468
 
683
- ## 🙏 Acknowledgments
469
+ ## License
684
470
 
685
- - [RuVector](https://github.com/ruvnet/ruvector) - The intelligence stack
686
- - [Anthropic](https://www.anthropic.com) - Claude AI
471
+ MIT License - see [LICENSE](LICENSE) for details.
687
472
 
688
473
  ---
689
474