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:

{
  "mcpServers": {
    "rulebook": {
      "command": "node",
      "args": ["dist/mcp/rulebook-server.js"],
      "env": {}
    }
  }
}

For production (npx):

{
  "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