@hivehub/rulebook 5.8.2 → 6.0.0

package/templates/modules/FIGMA.md

@@ -1,267 +0,0 @@
-<!-- FIGMA:START -->
-# Figma MCP Instructions
-
-**CRITICAL**: Use MCP Figma for design system integration, asset export, and design-to-code workflows.
-
-## Core Operations
-
-### File Operations
-```typescript
-// Get file
-figma.getFile({ file_key: 'file-key' })
-
-// Get file nodes
-figma.getFileNodes({
-  file_key: 'file-key',
-  ids: ['node-id-1', 'node-id-2']
-})
-
-// Get file versions
-figma.getFileVersions({ file_key: 'file-key' })
-```
-
-### Image Export
-```typescript
-// Export images
-figma.getImage({
-  file_key: 'file-key',
-  ids: 'node-id',
-  format: 'png',  // png, jpg, svg, pdf
-  scale: 2  // @2x resolution
-})
-
-// Export multiple
-figma.getImage({
-  file_key: 'file-key',
-  ids: 'node-1,node-2,node-3',
-  format: 'svg',
-  svg_outline_text: true
-})
-```
-
-### Components
-```typescript
-// Get components
-figma.getFileComponents({ file_key: 'file-key' })
-
-// Get component sets
-figma.getFileComponentSets({ file_key: 'file-key' })
-
-// Get team components
-figma.getTeamComponents({ team_id: 'team-id' })
-```
-
-### Styles
-```typescript
-// Get file styles
-figma.getFileStyles({ file_key: 'file-key' })
-
-// Get team styles
-figma.getTeamStyles({ team_id: 'team-id' })
-```
-
-### Comments
-```typescript
-// Get comments
-figma.getComments({ file_key: 'file-key' })
-
-// Post comment
-figma.postComment({
-  file_key: 'file-key',
-  message: 'Approved for development',
-  comment_id: 'parent-comment-id'  // For replies
-})
-```
-
-## Common Patterns
-
-### Design Token Export
-```typescript
-// Export design tokens from Figma styles
-const { data: { styles } } = await figma.getFileStyles({ file_key: fileKey })
-
-const tokens = {
-  colors: {},
-  typography: {},
-  spacing: {}
-}
-
-for (const style of Object.values(styles)) {
-  if (style.style_type === 'FILL') {
-    tokens.colors[style.name] = extractColor(style)
-  } else if (style.style_type === 'TEXT') {
-    tokens.typography[style.name] = extractTextStyle(style)
-  }
-}
-
-// Write to tokens.json
-fs.writeFileSync('tokens.json', JSON.stringify(tokens, null, 2))
-```
-
-### Component Sync
-```typescript
-// Sync Figma components to code
-const { data: components } = await figma.getFileComponents({ file_key: fileKey })
-
-for (const component of Object.values(components)) {
-  // Export component as SVG
-  const { data: images } = await figma.getImage({
-    file_key: fileKey,
-    ids: component.node_id,
-    format: 'svg'
-  })
-  
-  // Save to assets folder
-  const svg = await fetch(images[component.node_id]).then(r => r.text())
-  fs.writeFileSync(`assets/icons/${component.name}.svg`, svg)
-}
-```
-
-### Screenshot Generation
-```typescript
-// Generate screenshots for documentation
-const screens = ['home-screen', 'login-screen', 'dashboard']
-
-for (const screenId of screens) {
-  const { data: images } = await figma.getImage({
-    file_key: fileKey,
-    ids: screenId,
-    format: 'png',
-    scale: 2
-  })
-  
-  const imageUrl = images[screenId]
-  const response = await fetch(imageUrl)
-  const buffer = await response.buffer()
-  
-  fs.writeFileSync(`docs/screenshots/${screenId}.png`, buffer)
-}
-```
-
-### Design Review Automation
-```typescript
-// Check for new comments
-const { data: comments } = await figma.getComments({ file_key: fileKey })
-
-const unresolved = comments.filter(c => !c.resolved_at)
-
-if (unresolved.length > 0) {
-  console.log(`${unresolved.length} unresolved design comments`)
-  
-  // Create Jira issues for unresolved comments
-  for (const comment of unresolved) {
-    await jira.issues.createIssue({
-      fields: {
-        project: { key: 'DESIGN' },
-        summary: `Design feedback: ${comment.message.substring(0, 50)}`,
-        description: comment.message,
-        issuetype: { name: 'Task' }
-      }
-    })
-  }
-}
-```
-
-### Design System Documentation
-```typescript
-// Generate component documentation
-const { data: components } = await figma.getFileComponents({ file_key: fileKey })
-
-let markdown = '# Design System Components\n\n'
-
-for (const [id, component] of Object.entries(components)) {
-  // Export thumbnail
-  const { data: images } = await figma.getImage({
-    file_key: fileKey,
-    ids: id,
-    format: 'png',
-    scale: 1
-  })
-  
-  markdown += `## ${component.name}\n\n`
-  markdown += `![${component.name}](${images[id]})\n\n`
-  markdown += `**Description:** ${component.description || 'No description'}\n\n`
-}
-
-fs.writeFileSync('docs/design-system.md', markdown)
-```
-
-## Best Practices
-
-✅ **DO:**
-- Cache file data to reduce API calls
-- Use version history for tracking changes
-- Export assets at appropriate resolutions
-- Document component usage
-- Use meaningful component names
-- Keep design tokens in sync
-- Handle rate limits (requests/minute)
-
-❌ **DON'T:**
-- Export entire files repeatedly
-- Ignore version control
-- Hardcode file keys
-- Skip error handling
-- Export at wrong resolutions
-- Commit API tokens
-
-## Configuration
-
-```json
-{
-  "mcpServers": {
-    "figma": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-figma"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "your-personal-access-token"
-      }
-    }
-  }
-}
-```
-
-**Setup:**
-1. Generate personal access token: Account Settings → Personal Access Tokens
-2. Grant appropriate scopes (file content, comments)
-3. Store token securely
-
-## Integration Patterns
-
-### CI/CD Asset Pipeline
-```bash
-# Export icons on every design update
-figma-export --file-key=$FIGMA_FILE --format=svg --output=src/assets/icons
-
-# Optimize SVGs
-svgo --folder src/assets/icons
-
-# Commit if changes detected
-git diff --quiet src/assets/icons || git commit -m "chore: Update design assets"
-```
-
-### Design-to-Code Workflow
-```typescript
-// 1. Detect design changes
-const currentVersion = await figma.getFile({ file_key: fileKey })
-const lastVersion = loadLastProcessedVersion()
-
-if (currentVersion.version !== lastVersion) {
-  // 2. Export updated components
-  await exportComponents(fileKey)
-  
-  // 3. Generate code
-  await generateComponentCode()
-  
-  // 4. Run tests
-  await runVisualRegressionTests()
-  
-  // 5. Create PR if tests pass
-  if (testsPass) {
-    await createPullRequest('Update components from Figma')
-  }
-}
-```
-
-<!-- FIGMA:END -->
-

package/templates/modules/GRAFANA.md

@@ -1,328 +0,0 @@
-<!-- GRAFANA:START -->
-# Grafana MCP Instructions
-
-**CRITICAL**: Use MCP Grafana for metrics visualization, alerting, and observability dashboards.
-
-## Core Operations
-
-### Dashboard Management
-```typescript
-// Get dashboard
-grafana.dashboards.getDashboardByUid({ uid: 'dashboard-uid' })
-
-// Create dashboard
-grafana.dashboards.postDashboard({
-  dashboard: {
-    title: 'Application Metrics',
-    tags: ['production', 'api'],
-    timezone: 'browser',
-    panels: [
-      {
-        title: 'Request Rate',
-        type: 'graph',
-        targets: [{ expr: 'rate(http_requests_total[5m])' }]
-      }
-    ]
-  },
-  overwrite: false
-})
-
-// Update dashboard
-grafana.dashboards.postDashboard({
-  dashboard: modifiedDashboard,
-  overwrite: true
-})
-
-// Delete dashboard
-grafana.dashboards.deleteDashboardByUid({ uid: 'dashboard-uid' })
-```
-
-### Data Sources
-```typescript
-// Get data sources
-grafana.datasources.getDataSources()
-
-// Add data source
-grafana.datasources.addDataSource({
-  name: 'Prometheus',
-  type: 'prometheus',
-  url: 'http://prometheus:9090',
-  access: 'proxy',
-  isDefault: true
-})
-
-// Query data source
-grafana.datasources.queryDataSource({
-  datasourceId: 1,
-  from: Date.now() - 3600000,  // 1 hour ago
-  to: Date.now(),
-  queries: [
-    { expr: 'up', refId: 'A' }
-  ]
-})
-```
-
-### Alerts
-```typescript
-// Get alerts
-grafana.alerting.getAlerts({ state: 'alerting' })
-
-// Create alert rule
-grafana.alerting.postAlertRule({
-  title: 'High Error Rate',
-  condition: 'A',
-  data: [
-    {
-      refId: 'A',
-      queryType: '',
-      relativeTimeRange: { from: 600, to: 0 },
-      datasourceUid: 'prometheus-uid',
-      model: {
-        expr: 'rate(http_errors_total[5m]) > 0.05'
-      }
-    }
-  ],
-  noDataState: 'NoData',
-  execErrState: 'Alerting',
-  for: '5m',
-  annotations: {
-    description: 'Error rate exceeded 5%'
-  },
-  labels: { severity: 'high' }
-})
-
-// Pause alert
-grafana.alerting.pauseAlertRule({ uid: 'alert-uid', paused: true })
-```
-
-### Annotations
-```typescript
-// Create annotation
-grafana.annotations.postAnnotation({
-  dashboardUid: 'dashboard-uid',
-  time: Date.now(),
-  timeEnd: Date.now(),
-  tags: ['deployment'],
-  text: 'Deployed version 1.2.0'
-})
-
-// Get annotations
-grafana.annotations.getAnnotations({
-  from: Date.now() - 86400000,  // Last 24h
-  to: Date.now(),
-  tags: ['deployment']
-})
-```
-
-### Organizations & Users
-```typescript
-// Get organization
-grafana.orgs.getOrgByName({ orgName: 'Main Org' })
-
-// Add user
-grafana.users.createUser({
-  email: 'user@example.com',
-  login: 'username',
-  password: 'secure-password',
-  name: 'User Name'
-})
-
-// Update user permissions
-grafana.org.updateOrgUser({
-  userId: 123,
-  role: 'Editor'  // Viewer, Editor, Admin
-})
-```
-
-## Common Patterns
-
-### Deployment Tracking
-```typescript
-// Mark deployment on dashboard
-await grafana.annotations.postAnnotation({
-  time: Date.now(),
-  tags: ['deployment', 'production'],
-  text: `Deployed ${process.env.GIT_SHA}`,
-  dashboardUid: 'main-dashboard'
-})
-
-// Create snapshot after deployment
-const snapshot = await grafana.snapshots.createDashboardSnapshot({
-  dashboard: dashboard,
-  name: `Production Metrics - ${new Date().toISOString()}`,
-  expires: 86400  // 24 hours
-})
-```
-
-### Automated Dashboard Creation
-```typescript
-// Create dashboard for new service
-async function createServiceDashboard(serviceName) {
-  const dashboard = {
-    title: `${serviceName} Metrics`,
-    tags: ['microservices', serviceName],
-    panels: [
-      {
-        title: 'Request Rate',
-        type: 'graph',
-        targets: [{
-          expr: `rate(http_requests_total{service="${serviceName}"}[5m])`
-        }]
-      },
-      {
-        title: 'Error Rate',
-        type: 'graph',
-        targets: [{
-          expr: `rate(http_errors_total{service="${serviceName}"}[5m])`
-        }]
-      },
-      {
-        title: 'Response Time (p95)',
-        type: 'graph',
-        targets: [{
-          expr: `histogram_quantile(0.95, rate(http_duration_seconds_bucket{service="${serviceName}"}[5m]))`
-        }]
-      }
-    ]
-  }
-  
-  return await grafana.dashboards.postDashboard({
-    dashboard,
-    overwrite: false
-  })
-}
-```
-
-### Alert Management
-```typescript
-// Check for firing alerts
-const alerts = await grafana.alerting.getAlerts({ state: 'alerting' })
-
-if (alerts.length > 0) {
-  console.log(`${alerts.length} alerts firing:`)
-  
-  for (const alert of alerts) {
-    console.log(`- ${alert.labels.alertname}: ${alert.annotations.description}`)
-    
-    // Create incident ticket
-    await jira.issues.createIssue({
-      fields: {
-        project: { key: 'OPS' },
-        summary: `Alert: ${alert.labels.alertname}`,
-        description: alert.annotations.description,
-        issuetype: { name: 'Incident' },
-        priority: { name: alert.labels.severity === 'critical' ? 'Highest' : 'High' }
-      }
-    })
-  }
-}
-```
-
-### Metrics Reporting
-```typescript
-// Generate daily metrics report
-async function generateDailyReport() {
-  const datasourceId = 1  // Prometheus
-  const from = Date.now() - 86400000  // 24h ago
-  const to = Date.now()
-  
-  // Query metrics
-  const requestRate = await grafana.datasources.queryDataSource({
-    datasourceId,
-    from,
-    to,
-    queries: [{ expr: 'sum(rate(http_requests_total[24h]))', refId: 'A' }]
-  })
-  
-  const errorRate = await grafana.datasources.queryDataSource({
-    datasourceId,
-    from,
-    to,
-    queries: [{ expr: 'sum(rate(http_errors_total[24h]))', refId: 'A' }]
-  })
-  
-  // Create report
-  const report = {
-    date: new Date().toISOString(),
-    totalRequests: requestRate.results.A.frames[0].data.values[1][0],
-    totalErrors: errorRate.results.A.frames[0].data.values[1][0],
-    errorPercentage: (totalErrors / totalRequests * 100).toFixed(2)
-  }
-  
-  // Post to Confluence/Notion
-  await notion.pages.create({
-    parent: { database_id: reportsDbId },
-    properties: {
-      'Title': { title: [{ text: { content: `Daily Metrics - ${report.date}` } }] },
-      'Requests': { number: report.totalRequests },
-      'Errors': { number: report.totalErrors },
-      'Error Rate': { number: parseFloat(report.errorPercentage) }
-    }
-  })
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use dashboard folders for organization
-- Tag dashboards appropriately
-- Set up proper alert thresholds
-- Use variables for flexibility
-- Create snapshots before changes
-- Document dashboard purpose
-- Use templating for multi-instance dashboards
-
-❌ **DON'T:**
-- Create duplicate dashboards
-- Set alerts without testing
-- Ignore alert fatigue
-- Hardcode dashboard IDs
-- Skip dashboard backups
-- Over-complicate queries
-
-## Configuration
-
-```json
-{
-  "mcpServers": {
-    "grafana": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-grafana"],
-      "env": {
-        "GRAFANA_URL": "http://grafana:3000",
-        "GRAFANA_API_KEY": "your-api-key",
-        "GRAFANA_ORG_ID": "1"
-      }
-    }
-  }
-}
-```
-
-**Setup:**
-1. Create API key: Configuration → API Keys → Add API key
-2. Grant appropriate permissions (Admin for management, Viewer for read-only)
-3. Store securely
-
-## Integration with CI/CD
-
-```typescript
-// Add deployment annotation on successful deploy
-if (deploymentSuccess) {
-  await grafana.annotations.postAnnotation({
-    time: Date.now(),
-    tags: ['deployment', process.env.ENVIRONMENT],
-    text: `Deployed ${process.env.GIT_SHA} to ${process.env.ENVIRONMENT}`,
-    dashboardUid: process.env.GRAFANA_DASHBOARD_UID
-  })
-}
-
-// Check alerts before deployment
-const alerts = await grafana.alerting.getAlerts({ state: 'alerting' })
-if (alerts.length > 0) {
-  console.warn('⚠️  Active alerts detected. Deployment may be risky.')
-}
-```
-
-<!-- GRAFANA:END -->
-

package/templates/modules/MEMORY.md

@@ -1,126 +0,0 @@
-<!-- MEMORY:START -->
-## Persistent Memory System
-
-The rulebook memory system provides persistent context across AI sessions using hybrid search (BM25 keyword + HNSW vector) with zero native dependencies.
-
-### 3-Layer Search Pattern (Token-Efficient)
-
-**Layer 1 — Compact Search**: Get brief results to scan relevance.
-```
-rulebook_memory_search({ query: "authentication bug", mode: "hybrid", limit: 10 })
-→ Returns: { id, title, type, score, matchType, createdAt } per result (~50 tokens each)
-```
-
-**Layer 2 — Timeline**: Get chronological context around a memory.
-```
-rulebook_memory_timeline({ memoryId: "abc-123", window: 5 })
-→ Returns: 5 memories before + anchor + 5 memories after (~200 tokens each)
-```
-
-**Layer 3 — Full Details**: Get complete content only for selected memories.
-```
-rulebook_memory_get({ ids: ["abc-123", "def-456"] })
-→ Returns: Full memory objects with content (~500-1000 tokens each)
-```
-
-### Memory Structure
-
-Each memory contains:
-- **id**: Unique identifier
-- **type**: Memory type (see below)
-- **title**: Short title (80 chars)
-- **summary**: Rich contextual summary with key concepts, decisions, patterns, gotchas (auto-extracted)
-- **content**: Full content
-- **tags**: Searchable tags for categorization
-- **createdAt/updatedAt/accessedAt**: Timestamps for LRU tracking
-
-### Memory Types
-
-- **bugfix**: Bug fixes, error resolutions — save root cause and solution
-- **feature**: New features, additions — save design approach and patterns
-- **refactor**: Code restructuring — save architectural reasoning
-- **decision**: Architectural decisions (protected from eviction) — save why this choice
-- **discovery**: Insights and learnings — save patterns and gotchas
-- **change**: Updates and modifications — save impact and reasoning
-- **observation**: General observations — save insights worth preserving
-
-### What to Capture in Summaries
-
-Effective summaries include:
-1. **Problem/Context**: What was being solved
-2. **Approach**: How it was solved
-3. **Key Decision**: Why this approach
-4. **Pattern**: Reusable solution discovered
-5. **Gotcha**: Edge case or limitation found
-6. **Result**: Outcome or impact
-
-**Example Summary**:
-```
-"Implemented OAuth token refresh with 30-min expiry. Decision: Used interceptor middleware for transparent refresh (avoids scattered retry logic). Gotcha: Tokens expire silently - must check response headers before retrying. Pattern: Double-request pattern for simultaneous requests during refresh."
-```
-
-### CLI Commands
-
-```bash
-# Search with hybrid BM25+Vector
-rulebook memory search "authentication bug"     # Returns top results with summaries
-rulebook memory search "oauth" --mode bm25      # BM25 keyword-only search
-rulebook memory search "token" --mode vector    # Vector semantic search
-rulebook memory search "api" --type feature     # Filter by memory type
-
-# Save memories (summary auto-extracted from content)
-rulebook memory save "Fixed OAuth token refresh..." --type feature --title "OAuth Implementation"
-rulebook memory save "Decided to use sql.js for zero-dependency..." --type decision --title "DB Choice" --tags architecture,database
-
-# Timeline and details
-rulebook memory timeline --memoryId abc-123     # See 5 before/after
-rulebook memory get abc-123 def-456             # Full details for specific memories
-
-# Management
-rulebook memory list --limit 10                  # Recent memories
-rulebook memory stats                            # Database statistics & health
-rulebook memory cleanup --force                  # Force cache eviction
-rulebook memory export --format json             # Export all memories
-```
-
-### Best Practices for Rich Memories
-
-1. **Save immediately after learning**: Capture insights while fresh
-2. **Use memory types correctly**: Features vs decisions vs discoveries
-3. **Include context in content**: Don't just save code, save reasoning
-4. **Add relevant tags**: Enable discovery for related work
-5. **Reference past memories**: Include memory IDs when related
-
-**Workflow**:
-```bash
-# Before implementing: search for similar work
-rulebook memory search "your feature" --mode hybrid
-
-# During implementation: save discoveries
-rulebook memory save "Pattern discovered: use X instead of Y because Z" --type discovery --title "Pattern Name"
-
-# After implementation: save complete solution
-rulebook memory save "Full implementation details, gotchas, test cases..." --type feature --title "Feature Name" --tags relevant,tags
-
-# Next session: reference past work
-rulebook memory search "feature name" --type feature
-# → Displays summaries automatically, can drill down to full details
-```
-
-### Configuration (.rulebook)
-
-```json
-{
-  "memory": {
-    "enabled": true,
-    "dbPath": ".rulebook-memory/memory.db",
-    "maxSizeBytes": 524288000,
-    "vectorDimensions": 256
-  }
-}
-```
-
-### Privacy
-
-Content between `<private>` and `</private>` tags is automatically stripped before storage.
-<!-- MEMORY:END -->