bluera-knowledge 0.31.0 → 0.32.0

package/commands/index.md

@@ -0,0 +1,48 @@
+---
+description: Re-index a knowledge store
+argument-hint: "[store-name-or-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Re-index Knowledge Store
+
+Re-index a knowledge store: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the store name or ID from $ARGUMENTS (required)
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:index":
+   - args.store: The store name or ID from $ARGUMENTS
+
+3. Display results showing job ID for background indexing:
+
+```
+✓ Indexing store: react...
+🔄 Indexing started in background
+   Job ID: job_def456ghi789
+
+Check status with: /bluera-knowledge:check-status job_def456ghi789
+Or view all jobs: /bluera-knowledge:check-status
+```
+
+## When to Re-index
+
+Re-index a store when:
+- The source repository has been updated (for repo stores)
+- Files have been added or modified (for file stores)
+- You want to refresh embeddings with an updated model
+- Search results seem out of date
+
+## Error Handling
+
+If indexing fails:
+
+```
+✗ Failed to index store: [error message]
+
+Common issues:
+- Store name or ID not found - use /bluera-knowledge:stores to list available stores
+- Source directory no longer exists (for file stores)
+- Network issues pulling latest changes (for repo stores)
+```

package/commands/remove-store.md

@@ -0,0 +1,52 @@
+---
+description: Delete a knowledge store and all associated data
+argument-hint: "[store-name-or-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Remove Knowledge Store
+
+Delete a knowledge store and all associated data: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the store name or ID from $ARGUMENTS (required)
+   - If no store provided, show error and suggest using /bluera-knowledge:stores to list available stores
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:delete":
+   - args.store: The store name or ID from $ARGUMENTS
+
+3. Display deletion result:
+
+```
+Store "react" deleted successfully.
+
+Removed:
+- Store registry entry
+- LanceDB search index
+- Cloned repository files (for repo stores)
+```
+
+## What Gets Deleted
+
+When you remove a store:
+- **Registry entry** - Store is removed from the list
+- **Search index** - LanceDB vector embeddings are dropped
+- **Cloned files** - For repo stores created from URLs, the cloned repository is deleted
+
+## Warning
+
+This action is **permanent**. The store and all indexed data will be deleted.
+To re-create, you'll need to add and re-index the source again.
+
+## Error Handling
+
+If store not found:
+
+```
+Store not found: nonexistent-store
+
+Available stores:
+- Use /bluera-knowledge:stores to list all stores
+- Check spelling of store name or ID
+```

package/commands/search.md

@@ -0,0 +1,80 @@
+---
+description: Search indexed library sources
+argument-hint: "[query] [--stores names] [--limit N] [--mode vector|fts|hybrid] [--detail minimal|contextual|full] [--threshold 0-1] [--min-relevance 0-1]"
+allowed-tools: ["mcp__bluera-knowledge__search"]
+---
+
+# Search Knowledge Stores
+
+Search indexed library sources for: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the query from $ARGUMENTS:
+   - Extract the search query (required)
+   - Extract --stores parameter (optional, comma-separated store names)
+   - Extract --limit parameter (optional, default 10)
+   - Extract --mode parameter (optional: vector, fts, hybrid; default hybrid)
+   - Extract --detail parameter (optional: minimal, contextual, full; default minimal)
+   - Extract --threshold parameter (optional, 0-1 range for normalized score filtering)
+   - Extract --min-relevance parameter (optional, 0-1 range for raw cosine similarity filtering)
+
+2. Call mcp__bluera-knowledge__search with:
+   - query: The search query string
+   - stores: Array of store names (if --stores specified)
+   - limit: Number of results (if --limit specified, default 10)
+   - mode: Search mode (if --mode specified, default "hybrid")
+   - detail: Detail level (if --detail specified, default "minimal")
+   - threshold: Minimum normalized score (if --threshold specified)
+   - minRelevance: Minimum raw cosine similarity (if --min-relevance specified)
+   - intent: "find-implementation"
+
+3. Format and display results with rich context:
+
+   ```
+   ## Search Results: "query" (hybrid search)
+
+   **1. [Score: 0.95] [Vector+FTS]**
+   Store: claude-code
+   File: 📄 path/to/file.ts
+   Purpose: → Purpose description here
+   Top Terms: 🔑 (in this chunk): concept1, concept2, concept3
+   Imports: 📦 (in this chunk): package1, package2
+
+   **2. [Score: 0.87] [Vector]**
+   Store: another-store
+   File: 📄 path/to/file.js
+   Purpose: → Another purpose here
+   Top Terms: 🔑 (in this chunk): other-concept
+
+   ---
+   **Found 10 results in 45ms**
+
+   💡 **Next Steps:**
+   - Read file: `Read /path/to/file.ts`
+   - Get full code: `mcp__bluera-knowledge__get_full_context("result-id")`
+   - Refine search: Use keywords above
+   ```
+
+   **Formatting rules:**
+   - Header: `## Search Results: "query" (mode search)` - Extract mode from response (vector/fts/hybrid)
+   - Each result on its own block with blank line between
+   - Result header: `**N. [Score: X.XX]**`
+   - Store: `Store: storeName`
+   - File: `File: 📄 filename` (from summary.location, strip repoRoot prefix)
+   - Purpose: `Purpose: → purpose text` (from summary.purpose)
+   - Footer: `**Found {{totalResults}} results in {{timeMs}}ms**` with separator line above
+
+4. For the footer next steps, include:
+   - First result's ID in the get_full_context example
+   - First result's actual file path in the Read example
+   - Use the actual keywords from top results
+
+5. If no results:
+   ```
+   No results found for "query"
+
+   Try:
+   - Broadening your search terms
+   - Checking indexed stores: /bluera-knowledge:stores
+   ```

package/commands/search.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Search command that uses Python formatter for deterministic table output
+
+set -euo pipefail
+
+# Parse arguments
+QUERY=""
+STORES=""
+LIMIT=10
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --stores)
+      STORES="$2"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    *)
+      # Everything else is the query
+      if [ -z "$QUERY" ]; then
+        QUERY="$1"
+      else
+        QUERY="$QUERY $1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# Remove quotes from query if present
+QUERY=$(echo "$QUERY" | sed 's/^["'\'']*//;s/["'\'']*$//')
+
+if [ -z "$QUERY" ]; then
+  echo "Error: No search query provided"
+  exit 1
+fi
+
+# Build MCP tool call JSON
+TOOL_INPUT=$(cat <<EOF
+{
+  "query": "$QUERY",
+  "limit": $LIMIT,
+  "detail": "contextual",
+  "intent": "find-implementation"
+}
+EOF
+)
+
+# Call MCP tool (this would need to be done via Claude)
+# For now, output instructions for Claude
+cat <<EOF
+Please call mcp__bluera-knowledge__search with these parameters and pipe the results through the formatter:
+
+Query: $QUERY
+Limit: $LIMIT
+Detail: contextual
+Intent: find-implementation
+
+Then execute: echo '<results_json>' | ${CLAUDE_PLUGIN_ROOT}/hooks/format-search-results.py
+EOF

package/commands/skill-activation.md

@@ -0,0 +1,131 @@
+---
+description: Toggle skill auto-activation on/off or configure individual skills
+argument-hint: "[on|off|status|config]"
+allowed-tools: ["Read", "Write", "AskUserQuestion"]
+---
+
+# Skill Activation Configuration
+
+Manage the bluera-knowledge skill auto-activation system.
+
+## Configuration File
+
+Location: `.bluera/bluera-knowledge/skill-activation.json` (per-repo, in project root)
+
+Default configuration (created if missing):
+```json
+{
+  "enabled": true,
+  "threshold": 1,
+  "skills": {
+    "knowledge-search": true,
+    "when-to-query": true,
+    "search-optimization": true,
+    "advanced-workflows": true,
+    "store-lifecycle": true
+  }
+}
+```
+
+## Steps
+
+### 1. Parse Arguments
+
+Extract the subcommand from $ARGUMENTS:
+- Empty or "status": Show current status
+- "on": Enable skill activation
+- "off": Disable skill activation
+- "config": Interactive skill configuration
+
+### 2. Read Current Configuration
+
+Read `.bluera/bluera-knowledge/skill-activation.json`
+
+If the file doesn't exist, use the default configuration shown above.
+
+### 3. Execute Subcommand
+
+**For "status" or empty arguments:**
+
+Display the current configuration:
+
+```
+## Skill Activation Status
+
+**Status**: [Enabled/Disabled]
+**Threshold**: [threshold value]
+
+### Individual Skills
+| Skill | Status |
+|-------|--------|
+| knowledge-search | enabled/disabled |
+| when-to-query | enabled/disabled |
+| search-optimization | enabled/disabled |
+| advanced-workflows | enabled/disabled |
+| store-lifecycle | enabled/disabled |
+
+Use `/bluera-knowledge:skill-activation config` to toggle individual skills.
+```
+
+**For "on":**
+
+1. Read configuration (or use defaults)
+2. Set `enabled: true`
+3. Ensure directory exists: `.bluera/bluera-knowledge/`
+4. Write updated configuration
+5. Confirm: "Skill activation **enabled**. Skills will be suggested based on your prompts."
+
+**For "off":**
+
+1. Read configuration (or use defaults)
+2. Set `enabled: false`
+3. Write updated configuration
+4. Confirm: "Skill activation **disabled**. No skill suggestions will appear."
+
+**For "config":**
+
+1. Read current configuration
+2. Use AskUserQuestion to let user toggle skills:
+
+```json
+{
+  "questions": [{
+    "question": "Which skills should auto-activate when relevant patterns are detected?",
+    "header": "Skills",
+    "multiSelect": true,
+    "options": [
+      {
+        "label": "knowledge-search",
+        "description": "Suggests when to query BK for library questions"
+      },
+      {
+        "label": "when-to-query",
+        "description": "Guides BK vs Grep/Read decisions"
+      },
+      {
+        "label": "search-optimization",
+        "description": "Tips for optimizing search parameters"
+      },
+      {
+        "label": "advanced-workflows",
+        "description": "Multi-tool orchestration patterns"
+      },
+      {
+        "label": "store-lifecycle",
+        "description": "Managing knowledge stores"
+      }
+    ]
+  }]
+}
+```
+
+3. Update skills based on selection (selected = enabled, unselected = disabled)
+4. Write updated configuration
+5. Show updated status table
+
+## Notes
+
+- Configuration is per-repo (stored in project's `.bluera/bluera-knowledge/` directory)
+- The configuration directory is created automatically if it doesn't exist
+- Changes take effect immediately on the next prompt
+- When disabled globally, no skills are suggested regardless of individual settings

package/commands/stores.md

@@ -0,0 +1,54 @@
+---
+description: List all indexed library stores
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# List Knowledge Stores
+
+Show all configured knowledge stores in the project.
+
+## Steps
+
+1. Use the mcp__bluera-knowledge__execute tool with command "stores" to retrieve all stores
+
+2. Present results in a clean table format:
+
+```
+| Name | Type | ID | Source |
+|------|------|----|--------------------|
+| react | repo | a1b2c3d4 | https://github.com/facebook/react |
+| lodash | repo | e5f6g7h8 | https://github.com/lodash/lodash |
+| my-docs | file | i9j0k1l2 | ~/docs |
+
+**Total**: 3 stores
+```
+
+3. Format each row:
+   - **Name**: The store name
+   - **Type**: Store type (repo, file, or web)
+   - **ID**: First 8 characters of the store ID (no ellipsis)
+   - **Source**:
+     - For repo stores: The git URL
+     - For file stores: The local path (use ~ for home directory to keep it concise)
+     - For web stores: The base URL
+
+## If No Stores Found
+
+If no stores exist, show:
+
+```
+## No Knowledge Stores Found
+
+You haven't created any knowledge stores yet.
+
+To get started:
+- `/bluera-knowledge:add-repo <url> --name=<name>` - Clone and index a library repository
+- `/bluera-knowledge:add-folder <path> --name=<name>` - Index a local folder of documentation
+
+Example:
+```
+/bluera-knowledge:add-repo https://github.com/facebook/react --name=react
+```
+
+After creating stores, they will be searchable via the MCP search tool.
+```

package/commands/suggest.md

@@ -0,0 +1,118 @@
+---
+description: Suggest important dependencies to add to knowledge stores
+allowed-tools: ["Glob", "Read", "mcp__bluera-knowledge__execute", "WebSearch", "AskUserQuestion", "Skill"]
+---
+
+# Suggest Dependencies to Index
+
+Analyze project dependencies and suggest important libraries to add to knowledge stores.
+
+## Steps
+
+1. **Find dependency files** using Glob tool:
+   - `**/package.json` (JavaScript/TypeScript projects)
+   - `**/requirements.txt` (Python projects)
+   - `**/go.mod` (Go projects)
+   - `**/Cargo.toml` (Rust projects)
+
+2. **Read and parse dependencies**:
+   - Use Read tool to read each dependency file
+   - Extract package names and usage patterns
+   - For package.json: dependencies and devDependencies
+   - For requirements.txt: all packages
+   - For go.mod: require statements
+   - For Cargo.toml: dependencies section
+
+3. **Scan for import statements** using Glob + Read:
+   - Find all source files (*.js, *.ts, *.py, *.go, *.rs)
+   - Count imports/requires for each dependency
+   - Rank dependencies by frequency of use
+
+4. **Get existing stores** using mcp__bluera-knowledge__execute with command "stores":
+   - Filter out dependencies already in stores
+   - Focus on new suggestions
+
+5. **Find repository URLs** using WebSearch:
+   - For top 5 most-used dependencies
+   - Search for official GitHub/GitLab repositories
+   - Prefer official repos over forks
+
+6. **Present selectable list** using AskUserQuestion:
+
+First, show a summary of what was found:
+```
+## Dependency Analysis
+
+Scanned 342 source files and found 24 dependencies.
+Already indexed: typescript, express, jest
+```
+
+Then use AskUserQuestion with multiSelect to let the user choose which to add:
+
+```json
+{
+  "questions": [{
+    "question": "Which dependencies would you like to add to your knowledge stores?",
+    "header": "Add deps",
+    "multiSelect": true,
+    "options": [
+      {
+        "label": "react (Recommended)",
+        "description": "147 imports across 52 files - https://github.com/facebook/react"
+      },
+      {
+        "label": "lodash",
+        "description": "89 imports across 31 files - https://github.com/lodash/lodash"
+      },
+      {
+        "label": "axios",
+        "description": "45 imports across 18 files - https://github.com/axios/axios"
+      },
+      {
+        "label": "zod",
+        "description": "32 imports across 12 files - https://github.com/colinhacks/zod"
+      }
+    ]
+  }]
+}
+```
+
+**Note:** Maximum 4 options per question (AskUserQuestion limit). If more than 4 dependencies, show top 4 and mention others in summary.
+
+7. **Execute selected add-repo commands**:
+
+For each selected dependency, invoke the Skill tool:
+```
+Skill(skill="bluera-knowledge:add-repo", args="<repo-url> --name=<package-name>")
+```
+
+Example for react selection:
+```
+Skill(skill="bluera-knowledge:add-repo", args="https://github.com/facebook/react --name=react")
+```
+
+8. **Show completion summary**:
+```
+## Added to Knowledge Stores
+
+✓ react - https://github.com/facebook/react
+✓ lodash - https://github.com/lodash/lodash
+
+Indexing started. Check progress with /bluera-knowledge:check-status
+```
+
+## If No Dependencies Found
+
+```
+No external dependencies found in this project.
+
+Make sure you have a dependency manifest file:
+- package.json (JavaScript/TypeScript)
+- requirements.txt or pyproject.toml (Python)
+- go.mod (Go)
+- Cargo.toml (Rust)
+```
+
+## If User Selects "Other"
+
+If the user types a custom response instead of selecting options, try to parse package names from their input and search for the corresponding repositories.

package/commands/sync.md

@@ -0,0 +1,96 @@
+---
+description: Sync stores from definitions config (bootstrap on fresh clone)
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Sync Stores from Definitions
+
+Sync stores from the git-committable definitions config. This is useful when:
+- You've cloned a repo that has `.bluera/bluera-knowledge/stores.config.json`
+- You want to recreate all stores defined by the team
+- You want to check for orphan stores not in the config
+
+## Steps
+
+1. Use the mcp__bluera-knowledge__execute tool with command "stores:sync" to sync stores from definitions
+
+   Optional arguments:
+   - `dryRun: true` - Show what would happen without making changes
+   - `prune: true` - Remove stores not in definitions
+   - `reindex: true` - Re-index existing stores after sync
+
+2. Present results in a structured format:
+
+```
+## Sync Results
+
+**Created**: 3 stores
+- my-docs (file)
+- react-source (repo)
+- api-docs (web)
+
+**Skipped** (already exist): 2 stores
+- lodash
+- typescript-docs
+
+**Orphans** (not in definitions): 1 store
+- old-unused-store
+
+No errors occurred.
+```
+
+## Dry Run Mode
+
+When using dry run, show what WOULD happen:
+
+```
+## Sync Preview (Dry Run)
+
+**Would create**: 3 stores
+- my-docs (file)
+- react-source (repo)
+- api-docs (web)
+
+**Would skip** (already exist): 2 stores
+- lodash
+- typescript-docs
+
+**Orphans** (not in definitions): 1 store
+- old-unused-store
+
+To apply these changes, run without --dry-run
+```
+
+## If No Definitions Found
+
+If no store definitions config exists:
+
+```
+## No Store Definitions Found
+
+The config file `.bluera/bluera-knowledge/stores.config.json` doesn't exist yet.
+
+Store definitions are automatically created when you:
+- Add a repo: `/bluera-knowledge:add-repo <url>`
+- Add a folder: `/bluera-knowledge:add-folder <path>`
+- Crawl a website: `/bluera-knowledge:crawl <url>`
+
+The config file will be created automatically and can be committed to git for team sharing.
+```
+
+## Error Handling
+
+If some stores fail to sync, report them individually:
+
+```
+## Sync Results
+
+**Created**: 2 stores
+- my-docs
+- api-docs
+
+**Failed**: 1 store
+- react-source: Directory does not exist: /path/to/repo
+
+Continue to resolve the errors manually.
+```