Rulebook
CLI tool to standardize AI-generated projects with templates, rules enforcement, and automation
Ask AI about Rulebook
Powered by Claude Β· Grounded in docs
I know everything about Rulebook. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@hivehub/rulebook
Tool-agnostic AI development framework. Standardize projects across Claude Code, Cursor, Gemini, Codex, Windsurf, Copilot, and OpenCode with automated templates, quality gates, persistent memory, and language detection for 28 languages and 13 MCP modules.
Quick Start
# Initialize β auto-detects languages, tools, and complexity
npx @hivehub/rulebook@latest init
# Update existing project to latest rules
npx @hivehub/rulebook@latest update
# Check project health
npx @hivehub/rulebook@latest doctor
That's it. Rulebook detects your stack, generates rules for every AI tool in your project, sets up quality gates, and configures MCP integration β all in one command.
Install globally with
npm install -g @hivehub/rulebookto userulebookdirectly.
What Rulebook Does
AI coding assistants produce inconsistent, error-prone code without clear guidelines. Rulebook gives every AI tool in your project the same set of rules β automatically.
One init, every tool configured:
| What | How |
|---|---|
| Rules for every AI tool | AGENTS.md + CLAUDE.md + .cursor/rules/ + Gemini/Copilot/Windsurf configs β all generated from a single source of truth |
| Quality gates | Pre-commit hooks (lint, type-check, format) + pre-push hooks (build, tests) β language-aware, cross-platform |
| MCP tools | Task management, persistent memory, skills, decisions, knowledge, learnings, workspace, terse compression β all via Model Context Protocol |
| Structural enforcement | PreToolUse hooks block forbidden patterns (deferred tasks, stubs/TODOs, manual task files) before edits reach disk |
| Session continuity | Persistent memory across sessions, automatic handoff at context limits, STATE.md live status |
| 28 languages | Auto-detected with confidence scores, language-specific templates and CI/CD workflows |
Core Features
Modular Rule System
Rulebook generates a modular @import chain instead of one massive file:
CLAUDE.md (thin, ~100 lines)
@imports AGENTS.md β team-shared rules
@imports AGENTS.override.md β your project overrides (survives updates)
@imports .rulebook/STATE.md β live task/health status
@imports .rulebook/PLANS.md β session scratchpad
Path-scoped rules in .claude/rules/ load only when the AI touches matching files (e.g., TypeScript rules load only for .ts files). 5 always-on rules enforce core behaviors: diagnostic-first, fail-twice-escalate, no-deferred, no-shortcuts, sequential-editing.
Persistent Memory
Context that survives across AI sessions. Decisions, bugs, patterns, and preferences are stored locally and searchable.
| Component | Technology |
|---|---|
| Storage | Plain markdown files with YAML frontmatter (one file per memory) |
| Layout | .rulebook/memory/{memories,sessions,codegraph}/<YYYY>/<MM>/... |
| Search | BM25 over file content + frontmatter tag boost (lazy inverted-index sidecar above 1K entries) |
| Privacy | Auto-redact <private> tags, local-only storage |
| Migration | One-shot legacy SQLite β markdown via rulebook memory migrate-from-db |
rulebook memory search "authentication approach" # BM25 search
rulebook memory save "Chose JWT over sessions" # Save context
rulebook memory stats # File count + size
Terse Mode β Output & Input Compression (v5.4.0)
Structurally-enforced output compression via a SessionStart hook that injects a filtered SKILL.md and a per-turn UserPromptSubmit attention anchor. Four intensity levels aligned with Rulebook's agent tiers β off for opus-class reasoning, brief for sonnet, terse for haiku, ultra for CI/automation. Auto-clarity drops compression for security warnings, destructive ops, and quality-gate failures.
/rulebook-terse # Activate using tier default
/rulebook-terse ultra # Maximum compression
/rulebook-terse off # Disable
Auto-activates after rulebook init or rulebook update β SessionStart hook writes to .rulebook/.terse-mode, UserPromptSubmit hook emits a ~45-token attention anchor per user message. Opt-out: set .rulebook/rulebook.json β "terse": {"enabled": false}. Override level: "terse": {"defaultMode": "brief"} or export RULEBOOK_TERSE_MODE=ultra.
See docs/analysis/caveman/ for the design rationale, docs/guides/rulebook-terse.md for the user guide, and templates/hooks/terse-*.sh for the hook source.
Task Management
Spec-driven development with OpenSpec-compatible format. Phase-prefixed task IDs, mandatory tail items (docs + tests + verify), and automatic archival.
rulebook task create phase1_add-auth # Create task with structure
rulebook task list # See pending work
rulebook task validate phase1_add-auth # Check format
rulebook task archive phase1_add-auth # Archive when done
Each task gets: proposal.md (why), tasks.md (checklist), specs/ (technical requirements with SHALL/MUST keywords and Given/When/Then scenarios).
Multi-Project Workspace
One MCP server manages all projects in a monorepo, with fully isolated per-project managers.
rulebook workspace init # Create workspace config
rulebook workspace add ./frontend # Add projects
rulebook mcp init --workspace # Single MCP for all
Auto-discovers from pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or *.code-workspace.
Structural Enforcement Hooks
3 PreToolUse hooks block forbidden patterns at the tool level β before edits reach disk:
| Hook | Blocks |
|---|---|
enforce-no-deferred | deferred, skip, later, TODO in tasks.md |
enforce-no-shortcuts | Stubs, placeholders, HACK/FIXME in source files |
enforce-mcp-for-tasks | Manual mkdir/Write in .rulebook/tasks/ |
Cross-platform (Node.js, no jq dependency).
MCP Server
MCP tools exposed via stdio transport. Zero configuration after rulebook mcp init.
rulebook mcp init # One-time setup β configures .mcp.json automatically
| Category | Tools | Examples |
|---|---|---|
| Tasks | CRUD + validate + archive + delete | rulebook_task_create, rulebook_task_list |
| Skills | List, show, enable, disable, search, validate | rulebook_skill_enable, rulebook_skill_search |
| Memory | Save, search, get, timeline, stats, cleanup | rulebook_memory_search, rulebook_memory_save |
| Workspace | List, status, search, tasks | rulebook_workspace_search, rulebook_workspace_tasks |
| Knowledge | Add, list, show | rulebook_knowledge_add, rulebook_knowledge_list |
| Decisions | Create, list, show, update | rulebook_decision_create, rulebook_decision_list |
| Learnings | Capture, list, promote | rulebook_learn_capture, rulebook_learn_list |
| Other | Rules list, session, codebase | rulebook_rules_list, rulebook_session_start |
All tools accept optional projectId for workspace routing.
CLI Reference
Project Setup
rulebook init # Interactive setup (auto-detects everything)
rulebook init --minimal # Essentials only
rulebook init --lean # AGENTS.md as <3KB index
rulebook init --light # No quality enforcement
rulebook update # Update to latest rules
rulebook doctor # Health checks (file sizes, broken imports, stale state)
rulebook validate # Check project standards
Task Management
rulebook task create <task-id> # Create (phase-prefixed: phase1_add-auth)
rulebook task list # List active tasks
rulebook task show <task-id> # Show details
rulebook task validate <task-id> # Validate format
rulebook task archive <task-id> # Archive completed task
rulebook task delete <task-id> # Delete permanently
Memory & Knowledge
rulebook memory search <query> # BM25 search over markdown corpus
rulebook memory save <text> # Save context
rulebook memory stats # File count + size
rulebook memory cleanup # Age-based retention (--force = 1-day cutoff)
rulebook memory migrate-from-db # One-shot legacy SQLite -> markdown
rulebook knowledge list # View patterns and anti-patterns
rulebook learn list # View captured learnings
rulebook decision list # View architecture decisions
Workspace
rulebook workspace init # Create workspace config
rulebook workspace add <path> # Add project
rulebook workspace list # List all projects
rulebook workspace status # Status with task counts
Rules & Skills
rulebook rules list # List rules by tier
rulebook rules add <rule> # Install from library
rulebook rules project # Project to all tools
rulebook skill list # List available skills
rulebook skill add <skill-id> # Enable a skill
rulebook skill show <skill-id> # Show skill details
CI/CD & Quality
rulebook workflows # Generate GitHub Actions
rulebook check-deps # Check dependencies
rulebook check-coverage # Check test coverage
rulebook version <major|minor|patch> # Bump version
Supported Stack
28 Languages: TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, C, C++, C#, PHP, Ruby, Swift, Elixir, Dart, Scala, Haskell, Julia, R, Lua, Solidity, Zig, Erlang, Ada, SAS, Lisp, Objective-C, SQL
13 MCP Modules: Vectorizer, Synap, Context7, GitHub MCP, Playwright, Memory, Supabase, Notion, Atlassian, Serena, Figma, Grafana, Sequential Thinking
23 AI Tools: Cursor, Windsurf, VS Code, GitHub Copilot, Tabnine, Replit, JetBrains AI, Zed, Aider, Continue, Claude, Claude Code, Gemini, Cline, Amazon Q, Auggie, CodeBuddy, Factory, OpenCode (first-class with MCP + commands + agents + skills), Kilo, Codex, Codeium, Cursor CLI
VSCode Extension
The Rulebook Dashboard extension provides full visibility into your AI workflow.
code --install-extension vscode-extension/rulebook-dashboard-*.vsix
| Tab | Shows |
|---|---|
| Agents | Team members with real-time status, memory state, last activity |
| Tasks | Progress bars, expandable details, Archive & Update buttons |
| Memory | Stats (count, file size, types), full-text search |
| Doctor | Health checks with auto-run |
Status bar: context usage indicator (ctx 78% with green/yellow/red), Rulebook button, indexer state.
Configuration
All config lives in .rulebook/rulebook.json:
{
"version": "5.6.0",
"mode": "full",
"features": {
"mcp": true,
"memory": true,
"multiAgent": true,
"hooks": true
}
}
Key files generated by Rulebook:
| File | Purpose |
|---|---|
AGENTS.md | Team-shared AI rules (regenerated on update) |
AGENTS.override.md | Your project overrides (survives updates) |
CLAUDE.md | Claude Code entry point with @imports |
.claude/rules/ | Path-scoped rules (language-specific + always-on) |
.claude/settings.json | Hooks and env vars for Claude Code |
.rulebook/specs/ | Detailed spec templates per language/framework |
.rulebook/STATE.md | Machine-written live status |
.rulebook/tasks/ | Active task directories |
Documentation
Full documentation in /docs:
See the full CHANGELOG for version history.
Contributing
Contributions welcome! Requires Node.js 20+.
git clone https://github.com/hivellm/rulebook.git
cd rulebook
npm install
npm test
npm run build
Acknowledgments
- OpenSpec β Influenced the task management format (delta-based specs, Given/When/Then scenarios, requirement-focused organization)
- Caveman β Grounding for the v5.4.0 terse-mode design (SessionStart + UserPromptSubmit hook pattern, intensity-filtered SKILL.md injection). See docs/analysis/caveman/ for the full analysis.
- forrestchang/andrej-karpathy-skills β Source of the four "Editing Discipline" principles (think before coding, simplicity first, surgical changes, goal-driven execution) inlined in the generated
AGENTS.md. Grounded in Andrej Karpathy's observations on common LLM coding pitfalls.
License
Apache License 2.0 Β© HiveLLM Team
Issues Β· Discussions Β· npm
