@hivehub/rulebook 1.2.0

package/templates/modules/SERENA.md

@@ -0,0 +1,337 @@
+<!-- SERENA:START -->
+# Serena MCP Instructions
+
+**CRITICAL**: Use MCP Serena for AI-powered development assistance, code analysis, and intelligent automation.
+
+## Core Operations
+
+### Code Analysis
+```typescript
+// Analyze code quality
+serena.analyze({
+  file: 'src/auth/login.ts',
+  checks: ['security', 'performance', 'best-practices']
+})
+
+// Get refactoring suggestions
+serena.suggest({
+  file: 'src/legacy-code.js',
+  type: 'refactor',
+  target: 'modern'
+})
+
+// Detect code smells
+serena.detectSmells({
+  directory: 'src/',
+  severity: 'high'
+})
+```
+
+### Code Generation
+```typescript
+// Generate tests
+serena.generateTests({
+  sourceFile: 'src/utils/validator.ts',
+  framework: 'vitest',
+  coverage: 'comprehensive'
+})
+
+// Generate documentation
+serena.generateDocs({
+  files: ['src/**/*.ts'],
+  format: 'markdown',
+  includeExamples: true
+})
+
+// Generate types
+serena.generateTypes({
+  from: 'api-schema.json',
+  to: 'src/types/api.ts',
+  style: 'strict'
+})
+```
+
+### Intelligent Refactoring
+```typescript
+// Extract function
+serena.refactor({
+  action: 'extract-function',
+  file: 'src/complex-logic.ts',
+  selection: { start: 45, end: 78 },
+  newFunctionName: 'processUserData'
+})
+
+// Rename symbol
+serena.refactor({
+  action: 'rename',
+  symbol: 'oldFunctionName',
+  newName: 'newFunctionName',
+  scope: 'project'
+})
+
+// Convert to async
+serena.refactor({
+  action: 'convert-to-async',
+  file: 'src/sync-operations.ts'
+})
+```
+
+### Code Review
+```typescript
+// Get code review
+serena.review({
+  files: ['src/new-feature/**/*.ts'],
+  focus: ['security', 'performance', 'maintainability'],
+  severity: 'warning-and-above'
+})
+
+// Check best practices
+serena.checkBestPractices({
+  language: 'typescript',
+  framework: 'react',
+  files: 'src/components/**/*.tsx'
+})
+```
+
+## Common Patterns
+
+### Pre-Commit Analysis
+```typescript
+// Analyze changed files before commit
+const changedFiles = execSync('git diff --cached --name-only').toString().split('\n')
+
+for (const file of changedFiles) {
+  const analysis = await serena.analyze({
+    file,
+    checks: ['security', 'performance', 'best-practices']
+  })
+  
+  if (analysis.issues.filter(i => i.severity === 'high').length > 0) {
+    console.error(`❌ High severity issues found in ${file}`)
+    process.exit(1)
+  }
+}
+```
+
+### Test Generation Workflow
+```typescript
+// Generate tests for new features
+const newFiles = findFilesWithoutTests('src/features/new-feature')
+
+for (const file of newFiles) {
+  const tests = await serena.generateTests({
+    sourceFile: file,
+    framework: 'vitest',
+    coverage: 'comprehensive'
+  })
+  
+  const testFile = file.replace('.ts', '.test.ts')
+  fs.writeFileSync(testFile, tests.code)
+  
+  console.log(`✅ Generated tests for ${file}`)
+}
+```
+
+### Code Quality Dashboard
+```typescript
+// Generate project health report
+const files = glob.sync('src/**/*.ts')
+
+const report = {
+  totalFiles: files.length,
+  issues: [],
+  codeSmells: [],
+  coverage: 0
+}
+
+for (const file of files) {
+  const analysis = await serena.analyze({ file })
+  report.issues.push(...analysis.issues)
+  
+  const smells = await serena.detectSmells({ file })
+  report.codeSmells.push(...smells)
+}
+
+// Post to dashboard
+await grafana.dashboards.updateDashboard({
+  panels: [
+    { title: 'Code Quality', value: calculateQualityScore(report) },
+    { title: 'Issues', value: report.issues.length },
+    { title: 'Code Smells', value: report.codeSmells.length }
+  ]
+})
+```
+
+### Automated Refactoring Pipeline
+```typescript
+// Identify and fix code smells automatically
+const smells = await serena.detectSmells({
+  directory: 'src/',
+  severity: 'medium-and-above'
+})
+
+for (const smell of smells) {
+  if (smell.autoFixable) {
+    const result = await serena.refactor({
+      action: smell.suggestedAction,
+      file: smell.file,
+      selection: smell.location
+    })
+    
+    if (result.success) {
+      console.log(`✅ Fixed: ${smell.description}`)
+    }
+  }
+}
+```
+
+### Documentation Sync
+```typescript
+// Keep documentation in sync with code
+const apiFiles = glob.sync('src/api/**/*.ts')
+
+for (const file of apiFiles) {
+  const docs = await serena.generateDocs({
+    files: [file],
+    format: 'markdown',
+    includeExamples: true
+  })
+  
+  const docFile = `docs/api/${path.basename(file, '.ts')}.md`
+  fs.writeFileSync(docFile, docs)
+}
+
+// Update CHANGELOG with AI summary
+const changes = execSync('git log --oneline --since="1 week ago"').toString()
+const summary = await serena.summarize({
+  text: changes,
+  format: 'changelog',
+  categorize: true
+})
+
+updateChangelog(summary)
+```
+
+### Intelligent Code Migration
+```typescript
+// Migrate from old to new API
+await serena.migrate({
+  from: 'old-api-v1',
+  to: 'new-api-v2',
+  files: 'src/**/*.ts',
+  strategy: 'safe',  // safe, aggressive, manual
+  createBackup: true
+})
+
+// Update imports
+await serena.refactor({
+  action: 'update-imports',
+  from: '@old-package',
+  to: '@new-package',
+  scope: 'project'
+})
+```
+
+## Best Practices
+
+✅ **DO:**
+- Run analysis before commits
+- Generate tests for new code
+- Use AI suggestions as starting point
+- Review generated code before accepting
+- Keep AI-generated docs in sync
+- Use for repetitive refactoring tasks
+- Leverage for code review automation
+
+❌ **DON'T:**
+- Blindly accept all suggestions
+- Skip manual code review
+- Use for critical security decisions
+- Ignore high-severity issues
+- Over-rely on automation
+- Skip testing generated code
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "serena": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-serena"],
+      "env": {
+        "SERENA_API_KEY": "your-api-key",
+        "SERENA_MODEL": "gpt-4",
+        "SERENA_TEMPERATURE": "0.2"
+      }
+    }
+  }
+}
+```
+
+**Configuration Options:**
+- `SERENA_MODEL`: AI model to use (gpt-4, claude-3, etc.)
+- `SERENA_TEMPERATURE`: Creativity level (0.0-1.0, lower = more deterministic)
+- `SERENA_MAX_TOKENS`: Maximum response length
+- `SERENA_TIMEOUT`: Request timeout in seconds
+
+## Integration with AGENT_AUTOMATION
+
+Enhance automation workflow with AI assistance:
+
+```typescript
+// Step 1: AI-powered code review before quality checks
+const review = await serena.review({
+  files: changedFiles,
+  focus: ['security', 'performance']
+})
+
+if (review.criticalIssues.length > 0) {
+  console.error('Critical issues found. Fix before proceeding.')
+  process.exit(1)
+}
+
+// Step 2: Generate missing tests
+const filesWithoutTests = findFilesWithoutTests()
+for (const file of filesWithoutTests) {
+  await serena.generateTests({ sourceFile: file })
+}
+
+// Step 3: Normal AGENT_AUTOMATION workflow
+// (lint, test, coverage, etc.)
+
+// Step 4: AI-powered commit message
+const commitMessage = await serena.generateCommitMessage({
+  diff: execSync('git diff --cached').toString(),
+  style: 'conventional'
+})
+
+git commit -m "${commitMessage}"
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/serena-review.yml
+name: AI Code Review
+
+on: [pull_request]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: AI Code Review
+        run: |
+          npx serena review \
+            --files="$(git diff --name-only origin/main)" \
+            --severity=warning \
+            --format=github-comment
+        env:
+          SERENA_API_KEY: ${{ secrets.SERENA_API_KEY }}
+```
+
+<!-- SERENA:END -->
+

package/templates/modules/SUPABASE.md

@@ -0,0 +1,223 @@
+<!-- SUPABASE:START -->
+# Supabase MCP Instructions
+
+**CRITICAL**: Use MCP Supabase for database operations, authentication, and storage.
+
+## Core Features
+
+### Database Operations
+```typescript
+// Query data
+supabase.from('users').select('*')
+supabase.from('users').select('id, name, email')
+
+// Insert
+supabase.from('users').insert({ name: 'John', email: 'john@example.com' })
+
+// Update
+supabase.from('users').update({ name: 'Jane' }).eq('id', 1)
+
+// Delete
+supabase.from('users').delete().eq('id', 1)
+
+// Filters
+supabase.from('users').select('*').eq('status', 'active')
+supabase.from('users').select('*').gt('age', 18)
+supabase.from('users').select('*').like('name', '%John%')
+```
+
+### Authentication
+```typescript
+// Sign up
+supabase.auth.signUp({ email, password })
+
+// Sign in
+supabase.auth.signInWithPassword({ email, password })
+
+// Sign out
+supabase.auth.signOut()
+
+// Get session
+supabase.auth.getSession()
+
+// Get user
+supabase.auth.getUser()
+```
+
+### Storage
+```typescript
+// Upload file
+supabase.storage.from('avatars').upload('path/file.jpg', file)
+
+// Download file
+supabase.storage.from('avatars').download('path/file.jpg')
+
+// List files
+supabase.storage.from('avatars').list('folder')
+
+// Delete file
+supabase.storage.from('avatars').remove(['path/file.jpg'])
+
+// Get public URL
+supabase.storage.from('avatars').getPublicUrl('path/file.jpg')
+```
+
+### Real-time Subscriptions
+```typescript
+// Subscribe to changes
+supabase
+  .channel('room1')
+  .on('postgres_changes', { 
+    event: '*', 
+    schema: 'public', 
+    table: 'users' 
+  }, (payload) => {
+    console.log('Change received!', payload)
+  })
+  .subscribe()
+```
+
+## Common Patterns
+
+### CRUD Operations
+```typescript
+// Create
+const { data, error } = await supabase
+  .from('tasks')
+  .insert({ title: 'New Task', completed: false })
+  .select()
+
+// Read
+const { data, error } = await supabase
+  .from('tasks')
+  .select('*')
+  .eq('completed', false)
+
+// Update
+const { data, error } = await supabase
+  .from('tasks')
+  .update({ completed: true })
+  .eq('id', taskId)
+
+// Delete
+const { data, error } = await supabase
+  .from('tasks')
+  .delete()
+  .eq('id', taskId)
+```
+
+### Authentication Flow
+```typescript
+// 1. Sign up user
+const { data: signUpData, error: signUpError } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password'
+})
+
+// 2. Sign in
+const { data: signInData, error: signInError } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password'
+})
+
+// 3. Check session
+const { data: { session } } = await supabase.auth.getSession()
+
+// 4. Sign out
+await supabase.auth.signOut()
+```
+
+### File Upload with Validation
+```typescript
+// 1. Validate file
+if (file.size > 5 * 1024 * 1024) {
+  throw new Error('File too large (max 5MB)')
+}
+
+// 2. Upload
+const { data, error } = await supabase.storage
+  .from('uploads')
+  .upload(`${userId}/${file.name}`, file, {
+    cacheControl: '3600',
+    upsert: false
+  })
+
+// 3. Get public URL
+if (!error) {
+  const { data: { publicUrl } } = supabase.storage
+    .from('uploads')
+    .getPublicUrl(`${userId}/${file.name}`)
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use Row Level Security (RLS) policies
+- Handle errors properly (`if (error) throw error`)
+- Use `.select()` after insert/update to get returned data
+- Use prepared statements (automatic with Supabase)
+- Enable real-time only when needed
+- Use storage buckets with proper permissions
+
+❌ **DON'T:**
+- Expose service role key in client code
+- Skip RLS policies (always enable)
+- Ignore error responses
+- Store sensitive data without encryption
+- Use anon key for admin operations
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-supabase"],
+      "env": {
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_ANON_KEY": "your-anon-key",
+        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
+      }
+    }
+  }
+}
+```
+
+**Security:**
+- Use `SUPABASE_ANON_KEY` for client-side operations
+- Use `SUPABASE_SERVICE_ROLE_KEY` only server-side
+- Never commit keys to version control
+- Enable RLS on all tables
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test database for development
+const supabase = createClient(
+  process.env.SUPABASE_TEST_URL,
+  process.env.SUPABASE_TEST_KEY
+)
+
+// Clean up after tests
+afterEach(async () => {
+  await supabase.from('test_table').delete().neq('id', 0)
+})
+```
+
+### Migrations
+```bash
+# Create migration
+supabase migration new add_users_table
+
+# Apply migrations
+supabase db push
+
+# Reset database
+supabase db reset
+```
+
+<!-- SUPABASE:END -->
+

package/templates/modules/SYNAP.md

@@ -0,0 +1,69 @@
+<!-- SYNAP:START -->
+# Synap Instructions
+
+**CRITICAL**: Use MCP Synap for persistent task and data storage across context windows.
+
+## Core Features
+
+### Key-Value Store
+```
+synap_kv_set(key, value, ttl?)   # Store with optional TTL
+synap_kv_get(key)                 # Retrieve  
+synap_kv_delete(key)              # Remove
+synap_kv_scan(prefix)             # List by prefix
+```
+
+### Queue & Pub/Sub
+```
+synap_queue_publish(queue, message, priority)  # Add to queue
+synap_queue_consume(queue)                     # Process from queue
+synap_pubsub_publish(topic, message)           # Broadcast
+synap_stream_publish(room, event)              # Stream events
+```
+
+## Common Patterns
+
+### Task Tracking
+```
+Pattern: "task:<feature>:<subtask-id>"
+
+synap_kv_set("task:auth:login", JSON.stringify({
+  status: "in_progress",
+  tests: ["test_login_success"],
+  coverage: 95.2
+}))
+```
+
+### Session State
+```
+Pattern: "session:<id>:<data-type>"
+
+synap_kv_set("session:abc:current-file", "/src/auth.ts")
+synap_kv_set("session:abc:todo-list", JSON.stringify([...]))
+```
+
+### Test Results
+```
+Pattern: "test:<suite>:<timestamp>"
+
+synap_kv_set("test:integration:latest", JSON.stringify({
+  passed: 42,
+  failed: 0,
+  coverage: 96.5
+}), 86400) // TTL: 24 hours
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use TTL for temporary data
+- Use prefixes for organization
+- Store session state before context switch
+- Clean up old data regularly
+
+❌ **DON'T:**
+- Store large binary data
+- Use random keys (use structured prefixes)
+- Skip TTL for temporary data
+
+<!-- SYNAP:END -->

package/templates/modules/VECTORIZER.md

@@ -0,0 +1,63 @@
+<!-- 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 -->