@hivehub/rulebook 2.0.0 → 3.0.0

package/templates/skills/modules/vectorizer/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "Vectorizer"
+description: "Use MCP Vectorizer as primary data source for project information instead of file reading."
+version: "1.0.0"
+category: "modules"
+author: "Rulebook"
+tags: ["modules", "mcp"]
+dependencies: []
+conflicts: []
+---
+<!-- VECTORIZER:START -->
+# Vectorizer Instructions
+
+**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
+
+## Core Functions
+
+### Search
+```
+mcp_vectorizer_search - Multiple strategies:
+  - intelligent: AI-powered with query expansion
+  - semantic: Advanced with reranking  
+  - contextual: Context-aware with filtering
+  - multi_collection: Cross-project search
+  - batch: Parallel queries
+  - by_file_type: Filter by extension (.rs, .ts, .py)
+```
+
+### File Operations
+```
+get_content - Retrieve file without disk I/O
+list_files - List indexed files with metadata
+get_summary - File summaries (extractive/structural)
+get_chunks - Progressive reading of large files
+get_outline - Project structure overview
+get_related - Find semantically related files
+```
+
+### Discovery
+```
+full_pipeline - Complete discovery with scoring
+broad_discovery - Multi-query with deduplication
+semantic_focus - Deep semantic search
+expand_queries - Generate query variations
+```
+
+## When to Use
+
+| Task | Tool |
+|------|------|
+| Explore unfamiliar code | intelligent search |
+| Read file | get_content |
+| Understand structure | get_outline |
+| Find related files | get_related |
+| Read large file | get_chunks |
+| Complex question | full_pipeline |
+
+## Best Practices
+
+✅ **DO:**
+- Start with intelligent search for exploration
+- Use file_operations to avoid disk I/O
+- Batch queries for related items
+- Set similarity thresholds (0.6-0.8)
+- Use specific collections when known
+
+❌ **DON'T:**
+- Read files from disk when available in vectorizer
+- Use sequential searches (batch instead)
+- Skip similarity thresholds
+- Search entire codebase when collection is known
+
+<!-- VECTORIZER:END -->

package/templates/skills/services/azure-blob/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: "Azure Blob Storage"
+description: "Use Azure Blob Storage for object storage, file uploads, static assets, and backup storage in Azure cloud."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "storage"]
+dependencies: []
+conflicts: []
+---
+<!-- AZURE_BLOB:START -->
+# Azure Blob Storage Instructions
+
+**CRITICAL**: Use Azure Blob Storage for object storage, file uploads, static assets, and backup storage in Azure cloud.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @azure/storage-blob
+import { BlobServiceClient, StorageSharedKeyCredential } from '@azure/storage-blob'
+
+const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME || ''
+const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY || ''
+
+const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey)
+const blobServiceClient = new BlobServiceClient(
+  `https://${accountName}.blob.core.windows.net`,
+  sharedKeyCredential
+)
+
+const containerClient = blobServiceClient.getContainerClient(
+  process.env.AZURE_CONTAINER_NAME || 'mycontainer'
+)
+```
+
+### Basic Operations
+```typescript
+// Create container
+await containerClient.createIfNotExists({
+  access: 'blob', // 'blob', 'container', or 'private'
+})
+
+// Upload blob
+const blockBlobClient = containerClient.getBlockBlobClient('path/to/file.jpg')
+await blockBlobClient.upload(fileBuffer, fileBuffer.length, {
+  blobHTTPHeaders: {
+    blobContentType: 'image/jpeg',
+  },
+  metadata: {
+    userId: '123',
+    originalName: 'photo.jpg',
+  },
+})
+
+// Download blob
+const downloadResponse = await blockBlobClient.download()
+const fileContent = await streamToBuffer(downloadResponse.readableStreamBody)
+
+// Delete blob
+await blockBlobClient.delete()
+
+// List blobs
+for await (const blob of containerClient.listBlobsFlat()) {
+  console.log(blob.name, blob.properties.contentLength)
+}
+```
+
+### Advanced Features
+```typescript
+// Generate SAS URL
+import { generateBlobSASQueryParameters, BlobSASPermissions, StorageSharedKeyCredential } from '@azure/storage-blob'
+
+const sasToken = generateBlobSASQueryParameters(
+  {
+    containerName: 'mycontainer',
+    blobName: 'path/to/file.jpg',
+    permissions: BlobSASPermissions.parse('r'), // read
+    startsOn: new Date(),
+    expiresOn: new Date(new Date().valueOf() + 3600 * 1000), // 1 hour
+  },
+  sharedKeyCredential
+).toString()
+
+const sasUrl = `https://${accountName}.blob.core.windows.net/mycontainer/path/to/file.jpg?${sasToken}`
+
+// Copy blob
+const sourceBlobClient = containerClient.getBlockBlobClient('source/file.jpg')
+const destBlobClient = containerClient.getBlockBlobClient('dest/file.jpg')
+await destBlobClient.beginCopyFromURL(sourceBlobClient.url)
+
+// Set blob metadata
+await blockBlobClient.setMetadata({
+  category: 'profile',
+  uploadedBy: 'user-123',
+})
+
+// Get blob properties
+const properties = await blockBlobClient.getProperties()
+console.log(properties.contentType, properties.contentLength, properties.metadata)
+```
+
+## Common Patterns
+
+### File Upload Handler
+```typescript
+async function uploadFile(file: Buffer, filename: string, userId: string) {
+  const blobName = `users/${userId}/${Date.now()}-${filename}`
+  const blobClient = containerClient.getBlockBlobClient(blobName)
+  
+  await blobClient.upload(file, file.length, {
+    blobHTTPHeaders: {
+      blobContentType: getContentType(filename),
+    },
+    metadata: {
+      userId,
+      originalName: filename,
+      uploadedAt: new Date().toISOString(),
+    },
+  })
+  
+  return {
+    blobName,
+    url: blobClient.url,
+  }
+}
+```
+
+### Temporary Access URL
+```typescript
+async function generateTemporaryUrl(blobName: string, expiresInMinutes: number = 60) {
+  const blobClient = containerClient.getBlockBlobClient(blobName)
+  const sasToken = generateBlobSASQueryParameters(
+    {
+      containerName: containerClient.containerName,
+      blobName,
+      permissions: BlobSASPermissions.parse('r'),
+      expiresOn: new Date(Date.now() + expiresInMinutes * 60 * 1000),
+    },
+    sharedKeyCredential
+  ).toString()
+  
+  return `${blobClient.url}?${sasToken}`
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use appropriate access tiers (Hot, Cool, Archive)
+- Set blob metadata for organization
+- Use SAS tokens for temporary access
+- Implement proper error handling
+- Use appropriate content types
+- Enable soft delete for important data
+- Monitor storage usage and costs
+- Use lifecycle management policies
+- Implement retry logic
+- Use connection strings or managed identity
+
+❌ **DON'T:**
+- Store sensitive data without encryption
+- Use public access unnecessarily
+- Hardcode credentials
+- Ignore error handling
+- Skip content-type validation
+- Ignore lifecycle policies
+- Skip access logging
+- Use default access levels
+- Ignore cost optimization
+- Store large files without chunking
+
+## Configuration
+
+### Environment Variables
+```bash
+AZURE_STORAGE_ACCOUNT_NAME=myaccount
+AZURE_STORAGE_ACCOUNT_KEY=your-account-key
+AZURE_CONTAINER_NAME=mycontainer
+AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+```
+
+### Managed Identity (Recommended)
+```typescript
+import { DefaultAzureCredential } from '@azure/identity'
+
+const blobServiceClient = new BlobServiceClient(
+  `https://${accountName}.blob.core.windows.net`,
+  new DefaultAzureCredential()
+)
+```
+
+<!-- AZURE_BLOB:END -->
+

package/templates/skills/services/cassandra/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: "Cassandra"
+description: "Use Cassandra for distributed NoSQL database with high availability, linear scalability, and eventual consistency."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "database"]
+dependencies: []
+conflicts: []
+---
+<!-- CASSANDRA:START -->
+# Apache Cassandra Database Instructions
+
+**CRITICAL**: Use Cassandra for distributed NoSQL database with high availability, linear scalability, and eventual consistency.
+
+## Core Features
+
+### Connection
+```typescript
+// Using cassandra-driver
+import { Client } from 'cassandra-driver'
+
+const client = new Client({
+  contactPoints: (process.env.CASSANDRA_HOSTS || 'localhost').split(','),
+  localDataCenter: process.env.CASSANDRA_DATACENTER || 'datacenter1',
+  keyspace: process.env.CASSANDRA_KEYSPACE || 'myapp',
+  credentials: {
+    username: process.env.CASSANDRA_USER || 'cassandra',
+    password: process.env.CASSANDRA_PASSWORD || 'cassandra',
+  },
+  queryOptions: {
+    consistency: 1, // ONE, QUORUM, ALL
+    prepare: true,
+  },
+})
+```
+
+### Basic Operations
+```typescript
+// Create keyspace
+await client.execute(`
+  CREATE KEYSPACE IF NOT EXISTS myapp
+  WITH REPLICATION = {
+    'class': 'SimpleStrategy',
+    'replication_factor': 1
+  }
+`)
+
+// Use keyspace
+await client.execute('USE myapp')
+
+// Create table
+await client.execute(`
+  CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY,
+    email TEXT,
+    name TEXT,
+    created_at TIMESTAMP
+  )
+`)
+
+// Create index
+await client.execute('CREATE INDEX IF NOT EXISTS ON users (email)')
+
+// Insert
+await client.execute(
+  'INSERT INTO users (id, email, name, created_at) VALUES (?, ?, ?, ?)',
+  [cassandra.types.Uuid.random(), 'john@example.com', 'John Doe', new Date()],
+  { prepare: true }
+)
+
+// Select
+const result = await client.execute(
+  'SELECT * FROM users WHERE id = ?',
+  [userId],
+  { prepare: true }
+)
+const user = result.first()
+
+// Update
+await client.execute(
+  'UPDATE users SET name = ? WHERE id = ?',
+  ['Jane Doe', userId],
+  { prepare: true }
+)
+
+// Delete
+await client.execute(
+  'DELETE FROM users WHERE id = ?',
+  [userId],
+  { prepare: true }
+)
+```
+
+### Advanced Features
+```typescript
+// Batch operations
+const queries = [
+  {
+    query: 'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+    params: [id1, 'user1@example.com', 'User 1'],
+  },
+  {
+    query: 'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+    params: [id2, 'user2@example.com', 'User 2'],
+  },
+]
+
+await client.batch(queries, { prepare: true })
+
+// Collections
+await client.execute(`
+  CREATE TABLE IF NOT EXISTS products (
+    id UUID PRIMARY KEY,
+    name TEXT,
+    tags SET<TEXT>,
+    metadata MAP<TEXT, TEXT>
+  )
+`)
+
+await client.execute(
+  'UPDATE products SET tags = tags + ? WHERE id = ?',
+  [['electronics', 'gadgets'], productId],
+  { prepare: true }
+)
+
+// Time-to-Live (TTL)
+await client.execute(
+  'INSERT INTO sessions (id, data) VALUES (?, ?) USING TTL 3600',
+  [sessionId, sessionData],
+  { prepare: true }
+)
+```
+
+## Common Patterns
+
+### Data Modeling
+```typescript
+// Design tables for query patterns
+// Query: Get users by email
+await client.execute(`
+  CREATE TABLE users_by_email (
+    email TEXT PRIMARY KEY,
+    id UUID,
+    name TEXT,
+    created_at TIMESTAMP
+  )
+`)
+
+// Query: Get posts by user and date
+await client.execute(`
+  CREATE TABLE posts_by_user (
+    user_id UUID,
+    created_at TIMESTAMP,
+    post_id UUID,
+    title TEXT,
+    content TEXT,
+    PRIMARY KEY (user_id, created_at, post_id)
+  ) WITH CLUSTERING ORDER BY (created_at DESC)
+`)
+```
+
+### Consistency Levels
+```typescript
+// Read with QUORUM consistency
+const result = await client.execute(
+  'SELECT * FROM users WHERE id = ?',
+  [userId],
+  {
+    consistency: 2, // QUORUM
+    prepare: true,
+  }
+)
+
+// Write with ALL consistency (strongest)
+await client.execute(
+  'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+  [id, email, name],
+  {
+    consistency: 3, // ALL
+    prepare: true,
+  }
+)
+```
+
+## Best Practices
+
+✅ **DO:**
+- Design tables for query patterns (denormalize)
+- Use appropriate partition keys
+- Use clustering keys for sorting
+- Create secondary indexes sparingly
+- Use prepared statements
+- Set appropriate consistency levels
+- Use TTL for time-based data
+- Monitor cluster health
+- Use batch operations carefully
+- Implement retry logic
+
+❌ **DON'T:**
+- Use secondary indexes on high-cardinality columns
+- Create too many secondary indexes
+- Use ALL consistency for all operations
+- Store large values (> 1MB)
+- Skip error handling
+- Ignore cluster topology
+- Hardcode contact points
+- Use SELECT * in production
+- Ignore data modeling best practices
+- Skip monitoring
+
+## Configuration
+
+### Environment Variables
+```bash
+CASSANDRA_HOSTS=localhost
+CASSANDRA_HOSTS=node1:9042,node2:9042,node3:9042
+CASSANDRA_DATACENTER=datacenter1
+CASSANDRA_KEYSPACE=myapp
+CASSANDRA_USER=cassandra
+CASSANDRA_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  cassandra:
+    image: cassandra:4
+    ports:
+      - "9042:9042"
+    environment:
+      CASSANDRA_CLUSTER_NAME: my-cluster
+      CASSANDRA_DC: datacenter1
+      CASSANDRA_RACK: rack1
+      CASSANDRA_ENDPOINT_SNITCH: GossipingPropertyFileSnitch
+    volumes:
+      - cassandra_data:/var/lib/cassandra
+    healthcheck:
+      test: ["CMD-SHELL", "nodetool status | grep -E '^UN' || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+volumes:
+  cassandra_data:
+```
+
+<!-- CASSANDRA:END -->
+