rulebook

@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

# Apply the recommended Claude Code setup (MCP, agents, workflows, settings)
npx @hivehub/rulebook@latest claude

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.

Then, inside Claude Code, spec a feature and let the backlog implement itself:

/spec rate-limit the public REST API   # asks questions, creates rulebook tasks
/rulebook-driver                        # implements every task, opus review gate

See Usage Examples for the full set of end-to-end flows.

Install globally with npm install -g @hivehub/rulebook to use rulebook directly.

---

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