@hivehub/rulebook 5.1.1 → 5.1.3

package/templates/rules/research-first.md

@@ -1,30 +1,30 @@
----
-name: research-first
-tier: 1
-description: "Always research before implementing — never guess"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Research Before Implementing
-
-NEVER guess at bug causes, API behavior, or algorithm correctness.
-
-## Required Process
-
-1. **State what you KNOW** (from logs, debug output, code reading)
-2. **State what you DON'T KNOW**
-3. **Research** the unknown (read source, check docs, use diagnostic tools)
-4. **Only then** implement the fix
-
-## Forbidden
-
-- Guessing at the cause of a bug
-- "Trying things" to see if they work
-- Hypothesizing without reading code
-- Assuming how an API works without checking docs
-- Iterating blindly — each attempt must be informed by new data
-
-**"I think this might be the problem" is NOT acceptable.**
-**"Source X does Y at file:line, we do Z, the difference causes W" IS acceptable.**
+---
+name: research-first
+tier: 1
+description: "Always research before implementing — never guess"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Research Before Implementing
+
+NEVER guess at bug causes, API behavior, or algorithm correctness.
+
+## Required Process
+
+1. **State what you KNOW** (from logs, debug output, code reading)
+2. **State what you DON'T KNOW**
+3. **Research** the unknown (read source, check docs, use diagnostic tools)
+4. **Only then** implement the fix
+
+## Forbidden
+
+- Guessing at the cause of a bug
+- "Trying things" to see if they work
+- Hypothesizing without reading code
+- Assuming how an API works without checking docs
+- Iterating blindly — each attempt must be informed by new data
+
+**"I think this might be the problem" is NOT acceptable.**
+**"Source X does Y at file:line, we do Z, the difference causes W" IS acceptable.**

package/templates/rules/sequential-editing.md

@@ -1,21 +1,21 @@
----
-name: sequential-editing
-tier: 1
-description: "Edit files one at a time, never batch-edit"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Sequential File Editing
-
-ALWAYS edit files one at a time: Read file1 → Edit file1 → Read file2 → Edit file2.
-
-NEVER batch-read multiple files then batch-edit them. By the time you edit file 3, context from file 1 may be stale.
-
-When a task touches 3+ files across subsystems:
-1. **STOP** — do not start implementing
-2. **Plan** the changes (list files, dependency order)
-3. **Decompose** into sub-tasks of 1-2 files each
-4. **Execute** sub-tasks in dependency order (upstream first)
-5. **Build/test** after each sub-task
+---
+name: sequential-editing
+tier: 1
+description: "Edit files one at a time, never batch-edit"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Sequential File Editing
+
+ALWAYS edit files one at a time: Read file1 → Edit file1 → Read file2 → Edit file2.
+
+NEVER batch-read multiple files then batch-edit them. By the time you edit file 3, context from file 1 may be stale.
+
+When a task touches 3+ files across subsystems:
+1. **STOP** — do not start implementing
+2. **Plan** the changes (list files, dependency order)
+3. **Decompose** into sub-tasks of 1-2 files each
+4. **Execute** sub-tasks in dependency order (upstream first)
+5. **Build/test** after each sub-task

package/templates/rules/session-workflow.md

@@ -1,24 +1,24 @@
----
-name: session-workflow
-tier: 2
-description: "Read PLANS.md at session start, save summary at session end"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Session Workflow — Preserve Context Across Sessions
-
-## At Session Start
-1. Read `.rulebook/PLANS.md` for current context and active task
-2. Search memory for relevant past work: `rulebook_memory_search` or `rulebook_session_start`
-3. Check `.rulebook/tasks/` for pending work
-
-## During Session
-- Update PLANS.md when making key decisions or discoveries
-- Save important context to memory as you go
-
-## At Session End
-1. Save session summary to PLANS.md: `rulebook_session_end`
-2. Summary should include: what was accomplished, key decisions, next steps
-3. Update tasks.md with completed items
+---
+name: session-workflow
+tier: 2
+description: "Read PLANS.md at session start, save summary at session end"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Session Workflow — Preserve Context Across Sessions
+
+## At Session Start
+1. Read `.rulebook/PLANS.md` for current context and active task
+2. Search memory for relevant past work: `rulebook_memory_search` or `rulebook_session_start`
+3. Check `.rulebook/tasks/` for pending work
+
+## During Session
+- Update PLANS.md when making key decisions or discoveries
+- Save important context to memory as you go
+
+## At Session End
+1. Save session summary to PLANS.md: `rulebook_session_end`
+2. Summary should include: what was accomplished, key decisions, next steps
+3. Update tasks.md with completed items

package/templates/rules/task-decomposition.md

@@ -1,32 +1,32 @@
----
-name: task-decomposition
-tier: 2
-description: "Decompose multi-file tasks into 1-2 file sub-tasks"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Task Decomposition
-
-When a task touches multiple subsystems, decompose into sub-tasks where each modifies **at most 1-2 files**.
-
-## Why
-
-AI agents lose accuracy when editing 3+ files in one pass. Context from earlier files gets compressed away.
-
-## Rules
-
-1. **Each sub-task modifies 1-2 files** — never more
-2. **Each sub-task is independently verifiable** — it compiles, it doesn't break existing behavior
-3. **Sub-tasks follow data flow order** — upstream first (component → buffer → renderer → shader)
-4. **Each sub-task has a clear "done when"** — not "implement X", but "field Y exists with default Z"
-5. **Build after each sub-task** — verify compilation before proceeding
-
-## When an Agent Receives a Multi-File Task
-
-1. **STOP** — do not start implementing
-2. **Create a change plan** listing all files and dependency order
-3. **Decompose** into sub-tasks following this rule
-4. **Report back** with the decomposition
-5. **Implement** one sub-task at a time
+---
+name: task-decomposition
+tier: 2
+description: "Decompose multi-file tasks into 1-2 file sub-tasks"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Task Decomposition
+
+When a task touches multiple subsystems, decompose into sub-tasks where each modifies **at most 1-2 files**.
+
+## Why
+
+AI agents lose accuracy when editing 3+ files in one pass. Context from earlier files gets compressed away.
+
+## Rules
+
+1. **Each sub-task modifies 1-2 files** — never more
+2. **Each sub-task is independently verifiable** — it compiles, it doesn't break existing behavior
+3. **Sub-tasks follow data flow order** — upstream first (component → buffer → renderer → shader)
+4. **Each sub-task has a clear "done when"** — not "implement X", but "field Y exists with default Z"
+5. **Build after each sub-task** — verify compilation before proceeding
+
+## When an Agent Receives a Multi-File Task
+
+1. **STOP** — do not start implementing
+2. **Create a change plan** listing all files and dependency order
+3. **Decompose** into sub-tasks following this rule
+4. **Report back** with the decomposition
+5. **Implement** one sub-task at a time

package/templates/services/AZURE_BLOB.md

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