@hivehub/rulebook 1.2.0

package/templates/modules/FIGMA.md

@@ -0,0 +1,267 @@
+<!-- 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/GITHUB_MCP.md

@@ -0,0 +1,64 @@
+<!-- GITHUB_MCP:START -->
+# GitHub MCP Server Integration
+
+**CRITICAL**: Monitor CI/CD workflows after every `git push` using GitHub MCP.
+
+## Workflow After Push
+
+```
+1. Push changes
+2. Wait 10 seconds  
+3. Check workflow status via GitHub MCP
+4. If workflows running → check again in next interaction
+5. If workflows failed → fetch logs, analyze, fix
+6. If workflows passed → confirm to user
+```
+
+## Error Recovery
+
+**When CI/CD fails:**
+
+```
+1. Fetch error information (workflow, job, step, logs)
+2. Analyze against AGENTS.md standards
+3. Propose fix
+4. Implement fix with full quality checks
+5. Commit and provide push command
+6. Monitor workflows again
+```
+
+## Best Practices
+
+✅ **DO:**
+- Always check workflows after push
+- Fetch complete error logs on failures
+- Fix issues before next feature
+- Verify fixes locally before re-pushing
+- Report status to user
+
+❌ **DON'T:**
+- Ignore workflow failures
+- Push again without fixing
+- Skip error analysis
+- Proceed if workflows failing
+- Create tags if CI/CD failed
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Token permissions:** Repository (read), Actions (read), Workflows (read/write)
+
+<!-- GITHUB_MCP:END -->

package/templates/modules/GRAFANA.md

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