ruvnet-kb-first 5.0.0

package/install/install-global.sh

@@ -0,0 +1,257 @@
+#!/bin/bash
+# RuvNet KB-First Global Installer
+# Version 5.0.0 | Updated 2026-01-02
+#
+# Installs KB-First skill, command, hooks, and auto-detection globally to ~/.claude/
+
+set -e
+
+echo "╔═══════════════════════════════════════════════════════════════╗"
+echo "║         RuvNet KB-First Application Builder v5.0.0           ║"
+echo "║              Global Installation Script                       ║"
+echo "╚═══════════════════════════════════════════════════════════════╝"
+echo ""
+
+# Determine script location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Target directories
+CLAUDE_DIR="$HOME/.claude"
+SKILLS_DIR="$CLAUDE_DIR/skills"
+COMMANDS_DIR="$CLAUDE_DIR/commands"
+HOOKS_DIR="$CLAUDE_DIR/hooks"
+
+# Create directories if needed
+echo "Creating directories..."
+mkdir -p "$SKILLS_DIR"
+mkdir -p "$COMMANDS_DIR"
+mkdir -p "$HOOKS_DIR"
+
+# Install skill
+echo "Installing KB-First skill..."
+cp "$SCRIPT_DIR/kb-first-skill.md" "$SKILLS_DIR/kb-first.md"
+echo "  ✅ Installed to $SKILLS_DIR/kb-first.md"
+
+# Install command
+echo "Installing /kb-first command..."
+cp "$SCRIPT_DIR/kb-first-command.md" "$COMMANDS_DIR/kb-first.md"
+echo "  ✅ Installed to $COMMANDS_DIR/kb-first.md"
+
+# Install hook scripts
+echo "Installing hook scripts..."
+
+if [ -f "$REPO_DIR/phases/01.5-hooks-setup.md" ]; then
+  # Extract hook scripts from phase documentation
+  # For now, create minimal working hooks
+
+  cat > "$HOOKS_DIR/pre_tool_use.py" << 'HOOK_EOF'
+#!/usr/bin/env python3
+"""RuVector PreToolUse Hook - KB-First Enforcement"""
+import json
+import sys
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_name = input_data.get('tool_name', '')
+        tool_input = input_data.get('tool_input', {})
+
+        if tool_name not in ('Edit', 'Write', 'MultiEdit'):
+            print(json.dumps({"decision": "continue"}))
+            return
+
+        file_path = tool_input.get('file_path', '')
+        if '/domain/' in file_path or '/src/' in file_path:
+            print(json.dumps({
+                "decision": "continue",
+                "message": "📚 KB-First: Remember to query KB for domain values"
+            }))
+        else:
+            print(json.dumps({"decision": "continue"}))
+    except:
+        print(json.dumps({"decision": "continue"}))
+
+if __name__ == '__main__':
+    main()
+HOOK_EOF
+
+  cat > "$HOOKS_DIR/post_tool_use.py" << 'HOOK_EOF'
+#!/usr/bin/env python3
+"""RuVector PostToolUse Hook - Outcome Recording"""
+import json
+import sys
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        # Record outcome for SONA learning (stub)
+    except:
+        pass
+    print(json.dumps({"decision": "continue"}))
+
+if __name__ == '__main__':
+    main()
+HOOK_EOF
+
+  cat > "$HOOKS_DIR/session_end.py" << 'HOOK_EOF'
+#!/usr/bin/env python3
+"""RuVector SessionEnd Hook - Pattern Persistence"""
+import json
+import sys
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        # Persist patterns (stub)
+    except:
+        pass
+    print(json.dumps({"decision": "continue"}))
+
+if __name__ == '__main__':
+    main()
+HOOK_EOF
+
+  chmod +x "$HOOKS_DIR"/*.py
+  echo "  ✅ Installed hook scripts to $HOOKS_DIR/"
+fi
+
+# Update settings.json to register hooks
+echo "Configuring hooks in settings.json..."
+
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+
+if [ -f "$SETTINGS_FILE" ]; then
+  # Backup existing
+  cp "$SETTINGS_FILE" "$SETTINGS_FILE.bak"
+
+  # Check if hooks already configured
+  if grep -q '"hooks"' "$SETTINGS_FILE"; then
+    echo "  ⚠️  Hooks already configured in settings.json"
+    echo "  ℹ️  Review $SETTINGS_FILE to ensure KB-First hooks are active"
+  else
+    # Add hooks to existing settings
+    python3 << PYTHON_EOF
+import json
+
+with open('$SETTINGS_FILE', 'r') as f:
+    settings = json.load(f)
+
+settings['hooks'] = {
+    "PreToolUse": [{
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/pre_tool_use.py"}]
+    }],
+    "PostToolUse": [{
+        "matcher": "*",
+        "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/post_tool_use.py"}]
+    }],
+    "SessionEnd": [{
+        "matcher": "*",
+        "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/session_end.py"}]
+    }]
+}
+
+with open('$SETTINGS_FILE', 'w') as f:
+    json.dump(settings, f, indent=2)
+PYTHON_EOF
+    echo "  ✅ Hooks configured in settings.json"
+  fi
+else
+  # Create new settings file
+  cat > "$SETTINGS_FILE" << SETTINGS_EOF
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write|MultiEdit",
+      "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/pre_tool_use.py"}]
+    }],
+    "PostToolUse": [{
+      "matcher": "*",
+      "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/post_tool_use.py"}]
+    }],
+    "SessionEnd": [{
+      "matcher": "*",
+      "hooks": [{"type": "command", "command": "python3 $HOOKS_DIR/session_end.py"}]
+    }]
+  }
+}
+SETTINGS_EOF
+  echo "  ✅ Created settings.json with hooks"
+fi
+
+# Verify installation
+echo ""
+echo "Verifying installation..."
+echo ""
+
+PASS=0
+FAIL=0
+
+if [ -f "$SKILLS_DIR/kb-first.md" ]; then
+  echo "  ✅ Skill installed"
+  PASS=$((PASS + 1))
+else
+  echo "  ❌ Skill not found"
+  FAIL=$((FAIL + 1))
+fi
+
+if [ -f "$COMMANDS_DIR/kb-first.md" ]; then
+  echo "  ✅ Command installed"
+  PASS=$((PASS + 1))
+else
+  echo "  ❌ Command not found"
+  FAIL=$((FAIL + 1))
+fi
+
+if [ -f "$HOOKS_DIR/pre_tool_use.py" ] && [ -x "$HOOKS_DIR/pre_tool_use.py" ]; then
+  echo "  ✅ Hooks installed and executable"
+  PASS=$((PASS + 1))
+else
+  echo "  ❌ Hooks not installed or not executable"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q '"hooks"' "$SETTINGS_FILE" 2>/dev/null; then
+  echo "  ✅ Hooks configured in settings.json"
+  PASS=$((PASS + 1))
+else
+  echo "  ❌ Hooks not configured"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+
+# Install auto-detection hook
+echo "Installing auto-detection hook..."
+if [ -f "$SCRIPT_DIR/kb-first-autodetect.sh" ]; then
+  cp "$SCRIPT_DIR/kb-first-autodetect.sh" "$HOOKS_DIR/kb-first-autodetect.sh"
+  chmod +x "$HOOKS_DIR/kb-first-autodetect.sh"
+  echo "  ✅ Auto-detection hook installed"
+  PASS=$((PASS + 1))
+else
+  echo "  ⚠️  Auto-detection hook not found in install directory"
+fi
+
+if [ $FAIL -eq 0 ]; then
+  echo "✅ Installation complete! ($PASS checks passed)"
+  echo ""
+  echo "Usage:"
+  echo "  /kb-first              # Start interactive builder"
+  echo "  kb-first init          # Initialize in current project"
+  echo "  kb-first score         # Score existing KB and app"
+  echo "  kb-first verify        # Run verification checks"
+  echo "  kb-first status        # Show project status"
+  echo ""
+  echo "NPM Package:"
+  echo "  npx ruvnet-kb-first init"
+  echo "  npx ruvnet-kb-first score --detailed"
+  echo ""
+  echo "Full documentation: $SKILLS_DIR/kb-first.md"
+else
+  echo "⚠️  Installation completed with warnings ($PASS passed, $FAIL failed)"
+  echo "Review the output above for details."
+fi
+
+exit 0

package/install/kb-first-autodetect.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# KB-First Auto-Detection Hook
+#
+# This hook runs on session start to detect if the current project
+# should be using KB-First methodology.
+#
+# Install to: ~/.claude/hooks/kb-first-autodetect.sh
+# Add to settings.json:
+#   "hooks": {
+#     "SessionStart": ["~/.claude/hooks/kb-first-autodetect.sh"]
+#   }
+#
+# Version: 5.0.0
+# Created: 2026-01-02
+
+set -e
+
+# Check if we're in a git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  exit 0
+fi
+
+PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+KB_FIRST_CONFIG="$PROJECT_DIR/.ruvector/config.json"
+
+# ============================================
+# Check 1: Already a KB-First Project
+# ============================================
+if [ -f "$KB_FIRST_CONFIG" ]; then
+  # Project is already KB-First enabled
+  echo "📚 KB-First project detected"
+
+  # Read current phase
+  CURRENT_PHASE=$(cat "$KB_FIRST_CONFIG" | python3 -c "import sys,json; print(json.load(sys.stdin).get('phases',{}).get('current',0))" 2>/dev/null || echo "0")
+
+  echo "   Phase: $CURRENT_PHASE"
+  echo "   Run: kb-first status"
+  exit 0
+fi
+
+# ============================================
+# Check 2: Detect KB-First Indicators
+# ============================================
+KB_SCORE=0
+KB_INDICATORS=""
+
+# Check for knowledge-intensive directories
+if [ -d "$PROJECT_DIR/docs" ] && [ "$(find "$PROJECT_DIR/docs" -name "*.md" 2>/dev/null | wc -l)" -gt 5 ]; then
+  KB_SCORE=$((KB_SCORE + 20))
+  KB_INDICATORS="$KB_INDICATORS\n  • Extensive documentation"
+fi
+
+# Check for domain-specific content
+if grep -rq "knowledge\|domain\|expertise\|specification" "$PROJECT_DIR/README.md" 2>/dev/null; then
+  KB_SCORE=$((KB_SCORE + 15))
+  KB_INDICATORS="$KB_INDICATORS\n  • Domain-specific content in README"
+fi
+
+# Check for existing schema/database references
+if find "$PROJECT_DIR" -name "*.sql" -o -name "*schema*" -o -name "*migration*" 2>/dev/null | head -1 | grep -q .; then
+  KB_SCORE=$((KB_SCORE + 15))
+  KB_INDICATORS="$KB_INDICATORS\n  • Database/schema files present"
+fi
+
+# Check for API/specification files
+if find "$PROJECT_DIR" -name "openapi*" -o -name "swagger*" -o -name "*.graphql" 2>/dev/null | head -1 | grep -q .; then
+  KB_SCORE=$((KB_SCORE + 15))
+  KB_INDICATORS="$KB_INDICATORS\n  • API specification files"
+fi
+
+# Check for vector/embedding references
+if grep -rq "vector\|embedding\|similarity\|semantic" "$PROJECT_DIR" --include="*.json" --include="*.yaml" --include="*.yml" 2>/dev/null; then
+  KB_SCORE=$((KB_SCORE + 20))
+  KB_INDICATORS="$KB_INDICATORS\n  • Vector/embedding references"
+fi
+
+# Check for ruvector dependency
+if grep -q "ruvector\|pgvector\|qdrant\|pinecone" "$PROJECT_DIR/package.json" 2>/dev/null; then
+  KB_SCORE=$((KB_SCORE + 20))
+  KB_INDICATORS="$KB_INDICATORS\n  • Vector database dependency"
+fi
+
+# Check for existing KB-related files
+if find "$PROJECT_DIR" -name "*knowledge*" -o -name "*kb*" 2>/dev/null | head -1 | grep -q .; then
+  KB_SCORE=$((KB_SCORE + 15))
+  KB_INDICATORS="$KB_INDICATORS\n  • KB-related file names"
+fi
+
+# ============================================
+# Output Recommendation
+# ============================================
+if [ $KB_SCORE -ge 50 ]; then
+  echo "🔍 KB-First Recommended (Score: $KB_SCORE/100)"
+  echo ""
+  echo "This project shows indicators of knowledge-intensive work:"
+  echo -e "$KB_INDICATORS"
+  echo ""
+  echo "Initialize KB-First with:"
+  echo "  npx ruvnet-kb-first init"
+  echo ""
+  echo "Or skip this check:"
+  echo "  touch $PROJECT_DIR/.ruvector/.skip-detection"
+elif [ $KB_SCORE -ge 25 ]; then
+  echo "💡 KB-First might be beneficial (Score: $KB_SCORE/100)"
+  echo "   Run: npx ruvnet-kb-first init --help"
+fi
+
+exit 0

package/install/kb-first-command.md

@@ -0,0 +1,80 @@
+Updated: 2026-01-01 23:55:00 EST | Version 4.2.0
+Created: 2026-01-01 23:55:00 EST
+
+# /kb-first
+
+Build or transform applications using KB-First architecture.
+
+## Usage
+
+```
+/kb-first              # Start interactive KB-First builder
+/kb-first init         # Initialize KB-First in current project
+/kb-first score        # Score existing KB and app compliance
+/kb-first plan         # Generate transformation plan
+/kb-first transform    # Execute KB-First transformation
+/kb-first verify       # Run all Phase 8 verification checks
+/kb-first hooks        # Configure Claude Code hooks
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| (none) | Start interactive builder, detect greenfield/brownfield |
+| `init` | Initialize KB-First structure in current project |
+| `score` | Score existing KB quality and app compliance |
+| `plan` | Generate transformation plan without executing |
+| `transform` | Execute full KB-First transformation |
+| `verify` | Run all 8 verification scripts |
+| `hooks` | Install and configure RuVector hooks |
+
+## Examples
+
+### Build a New Application
+```
+/kb-first
+
+# Then provide your intentions:
+> I want to build a retirement planning advisor that helps users optimize
+> their Social Security claiming strategy and tax-efficient withdrawals.
+```
+
+### Transform Existing Application
+```
+/kb-first score
+# Shows: KB Quality: 45/100, App Compliance: 30/100
+
+/kb-first plan
+# Shows: 15 files need modification, 8 new files needed
+
+/kb-first transform
+# Executes the 10-phase build process
+```
+
+### Quick Verification
+```
+/kb-first verify
+# Runs: 8.1-8.8 verification scripts
+# Returns: PASS/FAIL for each check
+```
+
+---
+
+## What This Command Does
+
+1. **Detects** application type (greenfield vs brownfield)
+2. **Scores** existing KB and app compliance (brownfield only)
+3. **Confirms** transformation scope with user
+4. **Identifies** which intelligence pattern fits
+5. **Executes** the 10-phase build process with HARD quality gates
+6. **Enforces** KB-First rules throughout development
+7. **Verifies** all 8 verification sub-phases pass
+8. **Reports** delta (before/after scores)
+
+---
+
+## Skill Reference
+
+This command invokes the KB-First Application Builder skill.
+Full documentation: `~/.claude/skills/kb-first.md`

package/install/kb-first-skill.md

@@ -0,0 +1,262 @@
+Updated: 2026-01-01 23:55:00 EST | Version 4.2.0
+Created: 2026-01-01 23:55:00 EST
+
+# KB-First Application Builder
+
+Build applications where curated expert knowledge drives intelligent decision-making through GNN reasoning, attention routing, and SONA learning.
+
+---
+
+## Triggers
+
+Use this skill when:
+- "Build [description] with KB-First" (greenfield)
+- "Apply KB-First to my existing app" (brownfield)
+- "Score my existing KB"
+- "What's my app compliance score?"
+- "/kb-first" (invoke skill directly)
+
+---
+
+## The 10-Phase Build Process
+
+| Phase | Name | Sub-Phases | Gate Type |
+|-------|------|------------|-----------|
+| 0 | Assessment | 6 | User Confirmation |
+| 1 | Storage | 6 | Script Check |
+| 1.5 | Hooks Setup | 4 | Hook Verify |
+| 2 | KB Creation | 8 | Score ≥98 |
+| 3 | Persistence | - | SQL Check |
+| 4 | Visualization | - | Manual/Playwright |
+| 5 | Integration | - | Compile Check |
+| 6 | Scaffold | - | File Check |
+| 7 | Build | 7 | Script Check |
+| 8 | Verification | 8 | All Must Pass |
+
+---
+
+## Critical Rules (NEVER VIOLATE)
+
+```
+RULE 1: No hardcoded domain logic
+        ❌ const rate = 0.04;
+        ✅ const rate = await kb.search("withdrawal rate");
+
+RULE 2: Every domain function queries KB
+        Every file in src/domain/ imports from ../kb
+
+RULE 3: All responses include kbSources
+        Traceability is mandatory
+
+RULE 4: Startup verification required
+        App exits if KB unavailable
+
+RULE 5: No fallback logic
+        ❌ rules = kb.get() || DEFAULT_RULES
+        ✅ rules = kb.get(); if (!rules) throw Error("KB missing");
+```
+
+---
+
+## Quick Start
+
+### Greenfield (New Project)
+
+```bash
+# 1. Clone the KB-First builder
+git clone https://github.com/ruvnet/kb-first-builder.git my-app
+cd my-app
+
+# 2. Create your intentions
+cat > PROJECT_INTENTIONS.md << 'EOF'
+# Project Intentions
+
+## What I Want to Build
+[Describe your application]
+
+## Users
+[Who will use this]
+
+## Core Features
+- Feature 1
+- Feature 2
+
+## Domain
+[The knowledge domain]
+EOF
+
+# 3. Run the builder
+/kb-first
+```
+
+### Brownfield (Existing Project)
+
+```bash
+# 1. Initialize KB-First in your project
+npx kb-first-builder init
+
+# 2. Score your current state
+/kb-first score
+
+# 3. See the transformation plan
+/kb-first plan
+
+# 4. Execute
+/kb-first transform
+```
+
+---
+
+## Phase 0: Assessment
+
+For brownfield applications, Claude MUST score before any changes:
+
+### KB Quality Score (0-100)
+```
+Expert Coverage (0-40):
+  - 100+ experts cited = 40 points
+  - 50-99 experts = 30 points
+  - 20-49 experts = 20 points
+  - <20 experts = 10 points
+
+Depth Score (0-30):
+  - Recursive depth ≥5 = 30 points
+  - Depth 3-4 = 20 points
+  - Depth 1-2 = 10 points
+
+Completeness (0-30):
+  - All nodes have content = 30 points
+  - >90% = 20 points
+  - <90% = 10 points
+```
+
+### App Compliance Score (0-100)
+```
+KB Imports (0-25):
+  - All domain files import kb = 25 points
+
+Source Returns (0-25):
+  - All responses include kbSources = 25 points
+
+No Hardcode (0-20):
+  - No hardcoded values in domain = 20 points
+
+Startup Verify (0-15):
+  - Entry point verifies KB = 15 points
+
+No Fallbacks (0-15):
+  - No || DEFAULT patterns = 15 points
+```
+
+---
+
+## Phase 1.5: Hooks Setup
+
+**Without hooks, KB-First is an honor system.**
+
+```bash
+# Install and configure hooks
+npx @ruvector/cli hooks init
+npx @ruvector/cli hooks install
+
+# Pre-train ReasoningBank
+npx @ruvector/cli reasoningbank seed --kb-first
+
+# Verify
+./scripts/1.5-hooks-verify.sh
+```
+
+Hooks enforce:
+- PreToolUse: Check KB before any Write/Edit
+- PostToolUse: Record outcomes, trigger SONA learning
+- SessionEnd: Persist patterns
+
+---
+
+## Scoring Formula
+
+### KB Quality Score
+
+| Component | Points | Criteria |
+|-----------|--------|----------|
+| Expert Coverage | 0-40 | Number of cited experts |
+| Depth | 0-30 | Recursive depth of KB tree |
+| Completeness | 0-30 | Nodes with actual content |
+| Attribution | +5 | All nodes have source_expert |
+| Confidence | +5 | All nodes have confidence score |
+
+**Target: ≥98/100**
+
+### App Compliance Score
+
+| Component | Points | Criteria |
+|-----------|--------|----------|
+| KB Imports | 0-25 | All domain files import kb |
+| Source Returns | 0-25 | All responses have kbSources |
+| No Hardcode | 0-20 | No magic numbers in domain |
+| Startup Verify | 0-15 | KB check in entry point |
+| No Fallbacks | 0-15 | No `|| DEFAULT` patterns |
+
+**Target: 100/100**
+
+---
+
+## Intelligence Patterns
+
+### Pattern Selection
+
+```
+Q1: Does changing one variable affect many others?
+    YES → Decision Web (GNN-first)
+
+Q2: Do you need to route queries to different expert domains?
+    YES → Combinatorial Routing (Attention-first)
+
+Q3: Is "what worked for similar cases" the core value?
+    YES → Scenario Learning (SONA-first)
+
+Q4: Is this a continuous monitoring/optimization loop?
+    YES → Continuous Optimization (Attention + SONA)
+
+Otherwise → Standard KB-First (Vector Search primary)
+```
+
+### Technology Matrix
+
+| Pattern | GNN | Attention | SONA | Vector |
+|---------|-----|-----------|------|--------|
+| Decision Web | PRIMARY | Compare | Learn | Foundation |
+| Combinatorial Routing | Networks | PRIMARY | Patterns | Foundation |
+| Scenario Learning | Dynamics | Parameters | PRIMARY | Foundation |
+| Continuous Optimization | Structure | PRIMARY | PRIMARY | Foundation |
+
+---
+
+## Verification Checks (Phase 8)
+
+| Check | Script | Purpose |
+|-------|--------|---------|
+| 8.1 | code-scan.sh | No hardcoded values |
+| 8.2 | import-check.sh | KB imports required |
+| 8.3 | source-returns.sh | kbSources in returns |
+| 8.4 | startup-verify.sh | KB connection at startup |
+| 8.5 | fallback-check.sh | No fallback patterns |
+| 8.6 | attribution.sh | Expert attribution |
+| 8.7 | confidence.sh | Confidence scores |
+| 8.8 | gap-logging.sh | Gap detection |
+
+All 8 checks must PASS for completion.
+
+---
+
+## Full Documentation
+
+For complete documentation, see the KB-First Builder repository:
+- Phases: `./phases/`
+- Scripts: `./scripts/`
+- Templates: `./templates/`
+- References: `./references/`
+
+---
+
+*KB-First v4.2.0 — Intelligence-First Architecture*