bluera-knowledge 0.31.0 → 0.33.0

package/skills/search-optimization/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: search-optimization
+description: Optimize BK search with intent, detail level, and store filtering
+---
+
+# Optimizing Bluera Knowledge Search
+
+Master the `search()` MCP tool parameters to get better results with less context usage.
+
+## Understanding Search Parameters
+
+```typescript
+search(
+  query: string,                    // Your search query
+  intent?: SearchIntent,            // What you're looking for
+  detail?: 'minimal' | 'contextual' | 'full',  // How much context to return
+  limit?: number,                   // Max results (default: 10)
+  stores?: string[]                 // Which stores to search
+)
+```
+
+## Search Intent: Choosing the Right Type
+
+The `intent` parameter helps the search engine rank results appropriately for your query type.
+
+### Intent Decision Tree
+
+**Looking for implementation details? Use `find-implementation`**
+- "How does X work internally?"
+- "Show me the implementation of Y"
+- "What's inside the Z class/function?"
+
+```
+search("Vue computed properties implementation", intent='find-implementation')
+→ Prioritizes: actual class/function implementations
+→ Ranks higher: ComputedRefImpl class, createComputed() function
+→ Ranks lower: tests, documentation, examples
+```
+
+**Looking for usage patterns? Use `find-pattern`**
+- "How to use X?"
+- "Examples of Y pattern"
+- "Common ways to implement Z"
+
+```
+search("React hooks patterns", intent='find-pattern')
+→ Prioritizes: example code, usage patterns, HOCs
+→ Ranks higher: common patterns like useEffect cleanup
+→ Ranks lower: internal implementation details
+```
+
+**Looking for references? Use `find-usage`**
+- "Where is X used?"
+- "Find all calls to Y"
+- "What depends on Z?"
+
+```
+search("useCallback usage", intent='find-usage')
+→ Prioritizes: call sites, import statements
+→ Ranks higher: files importing and using useCallback
+→ Ranks lower: useCallback's own implementation
+```
+
+**Looking for definitions/APIs? Use `find-definition`**
+- "What is the API for X?"
+- "Show me the type definition of Y"
+- "What are the parameters for Z?"
+
+```
+search("FastAPI route decorator", intent='find-definition')
+→ Prioritizes: function signatures, type definitions
+→ Ranks higher: @app.get() decorator definition
+→ Ranks lower: examples using the decorator
+```
+
+**Looking for documentation? Use `find-documentation`**
+- "What does the doc say about X?"
+- "Explain Y from the documentation"
+- "API reference for Z"
+
+```
+search("Pydantic validators documentation", intent='find-documentation')
+→ Prioritizes: README, docstrings, comments
+→ Ranks higher: markdown docs, inline documentation
+→ Ranks lower: implementation code
+```
+
+### Default (No Intent)
+
+If unsure, omit `intent` - the search engine will use hybrid ranking:
+
+```
+search("authentication middleware")
+→ Returns mixed: implementations, patterns, usage, docs
+→ Balanced ranking across all categories
+```
+
+## Detail Level: Progressive Context Strategy
+
+The `detail` parameter controls how much code context is returned **per result**.
+
+### Detail Levels Explained
+
+| Level | What You Get | Tokens/Result | Use When |
+|-------|--------------|---------------|----------|
+| `minimal` | Summary, file path, relevance | ~100 | Browsing many results |
+| `contextual` | + imports, types, signatures | ~300 | Need interface context |
+| `full` | + complete code, all context | ~800 | Deep dive on specific file |
+
+### Progressive Detail Strategy (Recommended)
+
+**Step 1: Start Minimal**
+```
+search(query, detail='minimal', limit=20)
+→ Get 20 summaries (~2k tokens total)
+→ Scan quickly for relevance
+→ Identify top 3-5 candidates
+```
+
+**Step 2: Evaluate Scores**
+```
+Review relevance scores:
+- 0.9-1.0: Excellent match (almost certainly relevant)
+- 0.7-0.9: Strong match (very likely relevant)
+- 0.5-0.7: Moderate match (possibly relevant)
+- < 0.5: Weak match (probably not relevant)
+```
+
+**Step 3: Selective Deep Dive**
+```
+For top results (score > 0.7):
+  get_full_context(result_ids)
+  → Fetch complete code only for relevant items
+
+For moderate results (score 0.5-0.7):
+  search(refined_query, detail='contextual')
+  → Try different query with more context
+```
+
+## Result Limiting
+
+The `limit` parameter caps the number of results returned.
+
+### Choosing the Right Limit
+
+| Limit | Mode | Use When |
+|-------|------|----------|
+| 20-50 | Discovery | Exploring, not sure what exists |
+| 10-20 | Standard | Specific question, multiple files |
+| 3-5 | Targeted | Know exactly what you need |
+
+**Tip**: Large limits work best with `detail='minimal'` to control tokens.
+
+## Store Filtering
+
+The `stores` parameter restricts search to specific knowledge stores.
+
+### When to Filter Stores
+
+**✅ Filter when:** You know the library, comparing specific libs, want focused results
+
+**❌ Don't filter when:** Discovering where code lives, want cross-library perspective
+
+```
+# Check available stores first
+list_stores()
+
+# Then filter
+search(query, stores=['fastapi', 'express'])
+```
+
+## Quick Reference
+
+### High-Efficiency Defaults
+```
+search(query, detail='minimal', limit=20)
+→ Good for most discovery tasks
+→ Review, then selectively fetch full context
+```
+
+### High-Precision Defaults
+```
+search(query, intent='find-implementation', detail='full', limit=5, stores=['known-lib'])
+→ When you know exactly what you're looking for
+→ Fastest path to deep answer
+```
+
+### Balanced Defaults
+```
+search(query, detail='contextual', limit=10)
+→ Good middle ground
+→ See interfaces without full implementation
+```
+
+## Deep Dive
+
+For advanced strategies and token optimization examples:
+- @references/strategies.md - Combined optimization strategies with token counts
+- @references/mistakes.md - Common mistakes to avoid

package/skills/search-optimization/references/mistakes.md

@@ -0,0 +1,21 @@
+# Common Mistakes to Avoid
+
+1. **Using detail='full' with limit=50**
+   - Result: ~40k tokens consumed
+   - Fix: Start with detail='minimal', escalate selectively
+
+2. **Not using intent parameter**
+   - Result: Mixed ranking, less relevant results
+   - Fix: Choose intent based on query type
+
+3. **Over-filtering stores too early**
+   - Result: Miss better answers in other libraries
+   - Fix: Search broadly first, then narrow
+
+4. **Setting limit too low (1-2)**
+   - Result: Miss relevant alternatives
+   - Fix: Use limit=5 minimum, more for discovery
+
+5. **Not checking relevance scores**
+   - Result: Waste time on low-relevance results
+   - Fix: Filter by score > 0.7 before deep dive

package/skills/search-optimization/references/strategies.md

@@ -0,0 +1,80 @@
+# Combined Optimization Strategies
+
+### Strategy 1: Efficient Discovery
+```
+Goal: Find something across many files, minimize tokens
+
+1. search(query, detail='minimal', limit=30)
+   → Browse summaries (~3k tokens)
+
+2. Filter top 5 by score (>0.7)
+
+3. get_full_context(top_5_ids)
+   → Deep dive selectively (~4k tokens)
+
+Total: ~7k tokens (vs ~24k with detail='full' upfront)
+Savings: ~70% token reduction
+```
+
+### Strategy 2: Precise Targeting
+```
+Goal: Get exactly what you need, fast
+
+1. Identify store: list_stores()
+
+2. search(precise_query,
+         intent='find-implementation',
+         detail='full',
+         limit=3,
+         stores=['target-store'])
+   → Exact match with full code
+
+Total: ~2.5k tokens
+Result: Fastest path to answer
+```
+
+### Strategy 3: Comparative Analysis
+```
+Goal: Compare implementations across libraries
+
+1. search(query,
+         intent='find-implementation',
+         detail='minimal',
+         limit=20,
+         stores=['lib1', 'lib2', 'lib3'])
+   → Get summaries from multiple libraries
+
+2. Review distribution:
+   - lib1: 8 results
+   - lib2: 7 results
+   - lib3: 5 results
+
+3. get_full_context(top_2_from_each_lib)
+   → Compare implementations
+
+Total: ~5k tokens
+Result: Balanced cross-library comparison
+```
+
+---
+
+# Token Usage Examples
+
+Real token counts for different strategies:
+
+```
+# Inefficient approach
+search("auth middleware", detail='full', limit=30)
+→ 30 results × 800 tokens = 24,000 tokens
+→ Most results not even relevant!
+
+# Optimized approach
+search("auth middleware", detail='minimal', limit=30)
+→ 30 results × 100 tokens = 3,000 tokens
+→ Identify top 3 (score > 0.8)
+
+get_full_context([id1, id2, id3])
+→ 3 results × 800 tokens = 2,400 tokens
+
+Total: 5,400 tokens (78% reduction!)
+```

package/skills/skill-activation/SKILL.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/skills/statusline/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: statusline
+description: Install or update the bluera-knowledge statusline module
+allowed-tools: [Read, Edit, Write, Bash]
+---
+
+Install the bluera-knowledge statusline module into the user's Claude Code statusline.
+
+## Steps
+
+1. Locate the plugin root by finding `scripts/statusline-module.sh` relative to this command file
+2. Read `scripts/statusline-module.sh` from the plugin directory to get the latest module content
+3. Read `~/.claude/statusline.sh` (or `$CLAUDE_CONFIG_DIR/statusline.sh`)
+4. If the file doesn't exist, tell the user to first set up a statusline with `/bluera-base:claude-code-statusline`
+5. Look for existing boundary comments `# --- bluera-knowledge ---` / `# --- end bluera-knowledge ---`
+6. If found: replace everything between the boundary comments (exclusive) with the module content (the function and call site from `statusline-module.sh`, excluding the shebang and header comments)
+7. If not found: insert the full boundary-commented section before the final output `printf` statements, and ensure `$BK_STATUS` is referenced in the `PLUGIN_SEG` variable
+8. Ensure the call site passes `"$PROJECT_DIR"` to `get_bk_status`
+9. Show the user the updated section and confirm success