@hivehub/rulebook 1.2.0

package/templates/modules/NOTION.md

@@ -0,0 +1,247 @@
+<!-- NOTION:START -->
+# Notion MCP Instructions
+
+**CRITICAL**: Use MCP Notion for documentation, task tracking, and knowledge management.
+
+## Core Operations
+
+### Database Queries
+```typescript
+// Query database
+notion.databases.query({
+  database_id: 'database-id',
+  filter: {
+    property: 'Status',
+    select: { equals: 'In Progress' }
+  },
+  sorts: [{ property: 'Created', direction: 'descending' }]
+})
+
+// Get database
+notion.databases.retrieve({ database_id: 'database-id' })
+```
+
+### Page Operations
+```typescript
+// Create page
+notion.pages.create({
+  parent: { database_id: 'database-id' },
+  properties: {
+    'Name': { title: [{ text: { content: 'New Task' } }] },
+    'Status': { select: { name: 'To Do' } },
+    'Priority': { select: { name: 'High' } }
+  }
+})
+
+// Update page
+notion.pages.update({
+  page_id: 'page-id',
+  properties: {
+    'Status': { select: { name: 'Done' } }
+  }
+})
+
+// Get page
+notion.pages.retrieve({ page_id: 'page-id' })
+```
+
+### Block Operations
+```typescript
+// Get blocks
+notion.blocks.children.list({ block_id: 'page-id' })
+
+// Append blocks
+notion.blocks.children.append({
+  block_id: 'page-id',
+  children: [
+    {
+      object: 'block',
+      type: 'heading_2',
+      heading_2: {
+        rich_text: [{ type: 'text', text: { content: 'Section Title' } }]
+      }
+    },
+    {
+      object: 'block',
+      type: 'paragraph',
+      paragraph: {
+        rich_text: [{ type: 'text', text: { content: 'Content here' } }]
+      }
+    }
+  ]
+})
+```
+
+### Search
+```typescript
+// Search all content
+notion.search({
+  query: 'search term',
+  filter: { property: 'object', value: 'page' },
+  sort: { direction: 'descending', timestamp: 'last_edited_time' }
+})
+```
+
+## Common Patterns
+
+### Task Management
+```typescript
+// Create task
+await notion.pages.create({
+  parent: { database_id: tasksDbId },
+  properties: {
+    'Task': { title: [{ text: { content: 'Implement feature X' } }] },
+    'Status': { select: { name: 'To Do' } },
+    'Assignee': { people: [{ id: userId }] },
+    'Due Date': { date: { start: '2024-12-31' } }
+  }
+})
+
+// Update task status
+await notion.pages.update({
+  page_id: taskId,
+  properties: {
+    'Status': { select: { name: 'In Progress' } },
+    'Started': { date: { start: new Date().toISOString() } }
+  }
+})
+
+// Complete task
+await notion.pages.update({
+  page_id: taskId,
+  properties: {
+    'Status': { select: { name: 'Done' } },
+    'Completed': { date: { start: new Date().toISOString() } }
+  }
+})
+```
+
+### Documentation Generation
+```typescript
+// Create documentation page
+const page = await notion.pages.create({
+  parent: { database_id: docsDbId },
+  properties: {
+    'Title': { title: [{ text: { content: 'API Documentation' } }] },
+    'Category': { select: { name: 'Technical' } }
+  }
+})
+
+// Add content blocks
+await notion.blocks.children.append({
+  block_id: page.id,
+  children: [
+    { type: 'heading_1', heading_1: { rich_text: [{ text: { content: 'API Reference' } }] } },
+    { type: 'paragraph', paragraph: { rich_text: [{ text: { content: 'Endpoints overview...' } }] } },
+    { type: 'code', code: { 
+      language: 'typescript',
+      rich_text: [{ text: { content: 'const api = new API()' } }]
+    }}
+  ]
+})
+```
+
+### Meeting Notes
+```typescript
+// Create meeting notes
+await notion.pages.create({
+  parent: { database_id: meetingsDbId },
+  properties: {
+    'Title': { title: [{ text: { content: 'Sprint Planning - Jan 2024' } }] },
+    'Date': { date: { start: '2024-01-15' } },
+    'Attendees': { people: attendeeIds }
+  }
+})
+
+// Add agenda and notes
+await notion.blocks.children.append({
+  block_id: pageId,
+  children: [
+    { type: 'heading_2', heading_2: { rich_text: [{ text: { content: 'Agenda' } }] } },
+    { type: 'bulleted_list_item', bulleted_list_item: { rich_text: [{ text: { content: 'Review last sprint' } }] } },
+    { type: 'bulleted_list_item', bulleted_list_item: { rich_text: [{ text: { content: 'Plan next sprint' } }] } },
+    { type: 'heading_2', heading_2: { rich_text: [{ text: { content: 'Action Items' } }] } }
+  ]
+})
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use databases for structured data
+- Cache database schemas
+- Batch operations when possible
+- Handle rate limits (3 requests/second)
+- Use rich text for formatting
+- Archive instead of delete
+
+❌ **DON'T:**
+- Make excessive API calls
+- Ignore rate limiting
+- Store large binary files
+- Skip error handling
+- Hardcode database IDs
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-notion"],
+      "env": {
+        "NOTION_API_KEY": "secret_xxx",
+        "NOTION_VERSION": "2022-06-28"
+      }
+    }
+  }
+}
+```
+
+**Setup:**
+1. Create integration at https://www.notion.so/my-integrations
+2. Copy internal integration token
+3. Share databases/pages with integration
+4. Use token as `NOTION_API_KEY`
+
+## Integration Patterns
+
+### Sync Tasks from Code
+```typescript
+// Sync OpenSpec tasks to Notion
+const tasks = parseOpenSpecTasks('openspec/changes/my-feature/tasks.md')
+
+for (const task of tasks) {
+  await notion.pages.create({
+    parent: { database_id: tasksDbId },
+    properties: {
+      'Task': { title: [{ text: { content: task.title } }] },
+      'Status': { select: { name: task.completed ? 'Done' : 'To Do' } },
+      'Source': { select: { name: 'OpenSpec' } }
+    }
+  })
+}
+```
+
+### Generate Changelog
+```typescript
+// Query completed tasks
+const completed = await notion.databases.query({
+  database_id: tasksDbId,
+  filter: {
+    and: [
+      { property: 'Status', select: { equals: 'Done' } },
+      { property: 'Completed', date: { after: '2024-01-01' } }
+    ]
+  }
+})
+
+// Generate CHANGELOG.md entries
+const entries = completed.results.map(task => 
+  `- ${task.properties.Task.title[0].plain_text}`
+)
+```
+
+<!-- NOTION:END -->
+

package/templates/modules/PLAYWRIGHT.md

@@ -0,0 +1,90 @@
+<!-- PLAYWRIGHT:START -->
+# Playwright MCP Instructions
+
+**CRITICAL**: Use MCP Playwright for automated browser testing and web automation.
+
+## Core Operations
+
+### Navigation & Screenshots
+```typescript
+await playwright.navigate({ url: "https://example.com" });
+await playwright.takeScreenshot({ fullPage: true, filename: "page.png" });
+```
+
+### Interaction
+```typescript
+// Click
+await playwright.click({ element: "Submit Button", ref: "button[type='submit']" });
+
+// Type
+await playwright.type({ element: "Search", ref: "#search", text: "query" });
+
+// Fill form
+await playwright.fillForm({
+  fields: [
+    { name: "Email", type: "textbox", ref: "#email", value: "user@example.com" },
+    { name: "Password", type: "textbox", ref: "#password", value: "secret" }
+  ]
+});
+```
+
+### DOM & Monitoring
+```typescript
+// Get accessibility tree
+const snapshot = await playwright.snapshot();
+
+// Console errors
+const errors = await playwright.getConsoleMessages({ onlyErrors: true });
+
+// Network requests
+const requests = await playwright.getNetworkRequests();
+```
+
+## Common Patterns
+
+### Login Flow
+```typescript
+1. navigate to login page
+2. fillForm with credentials
+3. click submit button
+4. waitFor dashboard text
+5. verify success via snapshot
+```
+
+### Error Detection
+```typescript
+const errors = await playwright.getConsoleMessages({ onlyErrors: true });
+if (errors.length > 0) {
+  await playwright.takeScreenshot({ filename: "error-state.png" });
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Wait for specific conditions (not time delays)
+- Use descriptive element names
+- Handle dialogs (`handleDialog`)
+- Check console errors after actions
+- Take screenshots at critical points
+
+❌ **DON'T:**
+- Use hard-coded delays
+- Use generic element selectors
+- Ignore console errors
+- Use relative file paths (uploads)
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-playwright"]
+    }
+  }
+}
+```
+
+<!-- PLAYWRIGHT:END -->

package/templates/modules/RULEBOOK_MCP.md

@@ -0,0 +1,156 @@
+<!-- RULEBOOK_MCP:START -->
+# Rulebook MCP Server Instructions
+
+**CRITICAL**: Use MCP Rulebook server to manage tasks programmatically instead of executing terminal commands.
+
+## Core Functions
+
+### 1. rulebook_task_create
+Create a new Rulebook task with OpenSpec-compatible format:
+```
+rulebook_task_create({
+  taskId: "add-feature-name",
+  proposal: {
+    why: "Users need this feature...",
+    whatChanges: "Add feature with X, Y, Z",
+    impact: {
+      affectedSpecs: ["specs/module/spec.md"],
+      affectedCode: ["src/module/"],
+      breakingChange: false,
+      userBenefit: "Better user experience"
+    }
+  }
+})
+```
+
+### 2. rulebook_task_list
+List all tasks with optional filters:
+```
+rulebook_task_list({
+  status: "in-progress",
+  includeArchived: false
+})
+```
+
+### 3. rulebook_task_show
+Show detailed task information:
+```
+rulebook_task_show({
+  taskId: "add-feature-name"
+})
+```
+
+### 4. rulebook_task_update
+Update task status or progress:
+```
+rulebook_task_update({
+  taskId: "add-feature-name",
+  status: "in-progress",
+  progress: 50
+})
+```
+
+### 5. rulebook_task_validate
+Validate task format against OpenSpec requirements:
+```
+rulebook_task_validate({
+  taskId: "add-feature-name"
+})
+```
+
+### 6. rulebook_task_archive
+Archive completed task and apply spec deltas:
+```
+rulebook_task_archive({
+  taskId: "add-feature-name",
+  skipValidation: false
+})
+```
+
+## Workflow
+
+**When creating tasks:**
+```
+1. Use rulebook_task_create instead of terminal command
+2. Provide complete proposal with why/whatChanges/impact
+3. Verify task creation with rulebook_task_show
+```
+
+**When managing task progress:**
+```
+1. Use rulebook_task_list to see all tasks
+2. Update status with rulebook_task_update as work progresses
+3. Validate format with rulebook_task_validate before archiving
+4. Archive completed tasks with rulebook_task_archive
+```
+
+**Before archiving:**
+```
+1. Always run rulebook_task_validate first
+2. Fix any validation errors
+3. Ensure all tasks in tasks.md are completed
+4. Archive with skipValidation: false
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use MCP functions instead of terminal commands for task management
+- Always validate tasks before archiving
+- Update task status as work progresses
+- Provide complete proposal information when creating tasks
+- Check task details with rulebook_task_show before operations
+
+❌ **DON'T:**
+- Execute `rulebook task create` commands in terminal
+- Archive tasks without validation
+- Skip proposal content when creating tasks
+- Use terminal commands when MCP functions are available
+
+## Configuration
+
+The Rulebook MCP server is configured in `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rulebook": {
+      "command": "node",
+      "args": ["dist/mcp/rulebook-server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+For production (npx):
+```json
+{
+  "mcpServers": {
+    "rulebook": {
+      "command": "npx",
+      "args": ["-y", "@hivehub/rulebook@latest", "mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Integration
+
+The MCP server integrates seamlessly with:
+- Cursor IDE (via `.cursor/mcp.json`)
+- Claude Desktop (via config file)
+- Other MCP-compatible clients
+
+All task operations are available through MCP functions, eliminating the need for terminal command execution.
+
+## Documentation
+
+For complete API documentation, see:
+- `/docs/MCP_SERVER.md` - Full API reference
+- `/docs/guides/MCP_SERVER_SETUP.md` - Setup guide
+- `/README.md` - General project information
+
+<!-- RULEBOOK_MCP:END -->
+