Rulebook

npm version npm downloads License Node.js TypeScript

Tests Build

Tool-agnostic AI development framework. One init generates AGENTS.md — the universal standard every AI coding agent reads — plus Claude Code integration, quality gates, spec-driven task management, and an MCP server. Auto-detects 28 languages.

v7 — built to assist frontier models, never to anchor them. ~3.4k tokens of session overhead (was ~15k in v6, −77%), 5 consolidated MCP tools, one path-only guard hook, zero permission prompts for routine work, and orchestration (subagents/parallelism/teams) that is never blocked or mandated. Measured, budgeted in CI, and documented in docs/analysis/v7-performance/. Upgrading from v6? See the migration guide — update --dry-run shows the plan first.

---

Quick Start

# Initialize — auto-detects languages and sets up rules, gates, and MCP
npx @hivehub/rulebook@latest init

# Update an existing project to the latest rules
npx @hivehub/rulebook@latest update

# Apply the recommended Claude Code setup (MCP, permissions, statusline)
npx @hivehub/rulebook@latest claude

Then, inside Claude Code, spec a feature and let the backlog implement itself (workflows are opt-in — rulebook claude --workflows installs them):

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

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

---

Why Rulebook

AI coding agents produce inconsistent, error-prone code without clear guidelines. Rulebook gives every agent the same rules from a single source of truth — and stays tool-agnostic by generating the AGENTS.md standard that Claude Code, Cursor, Codex, Gemini, Copilot, and other agents read natively. No per-tool adapters to maintain.

What	How
Universal rules	AGENTS.md + CLAUDE.md generated from one source — read natively by any AGENTS.md-aware agent
Quality gates	Pre-commit (lint, type-check, format) + pre-push (build, tests) hooks — language-aware, cross-platform
Spec-driven tasks	OpenSpec-compatible tasks with a docs + tests tail — check it or archive with a one-line waiver
6 MCP tools	rulebook_task / _memory / _session / _skill / _rules / _workspace — action-parameterized, ~3.6 KB of schemas total
Lean by design	One path-only guard hook, full-autonomy permissions, no content regexes, no ceremony for small fixes
28 languages	Auto-detected with confidence scores; language-specific templates and CI/CD workflows

---

Core Features

Modular rules

Rulebook generates a thin @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

AGENTS.md is the portable, tool-agnostic output. Path-scoped rules in .claude/rules/ load only when the agent touches matching files (e.g. TypeScript rules for .ts files). A small set of always-on rules enforce core behaviors: diagnostic-first, fail-twice-escalate, no-deferred, no-shortcuts, sequential-editing.

Task management

Spec-driven development in an OpenSpec-compatible format — phase-prefixed task IDs, a mandatory tail (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), and specs/ (SHALL/MUST requirements with Given/When/Then scenarios).

Knowledge, decisions & learnings

Lightweight, file-based project memory — plain markdown, searchable, committed with your repo.

rulebook knowledge list      # patterns and anti-patterns
rulebook decision list       # architecture decision records
rulebook learn list          # captured implementation learnings

Structural enforcement

A single PreToolUse hook blocks forbidden patterns at the tool level — before edits reach disk: deferred/skip/later/TODO in tasks.md, stubs/placeholders/HACK/FIXME in source, and manual task-file creation in .rulebook/tasks/. Cross-platform (Node.js, no jq dependency), and short-circuits in pure bash so a normal edit costs ~one process spawn.

Multi-project workspace

One MCP server manages every project 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.

---

Multi-Agent Workflows

Orchestrated Claude Code Workflow scripts are opt-in (agents and workflows no longer install by default — native harness agents cover the roles). When installed into .claude/workflows/, each fans work across bundled agents with cost-tiered models — haiku for read-only steps, sonnet for implementation, opus for the final review gate.

Workflow	What it does
rulebook-driver	Loops the backlog: next unchecked item → implement (SDD+TDD) → independent opus review gate (≤3 rounds) → document → next
spec-author	Research → draft proposal + SHALL/MUST spec → opus gap-critic returns ranked questions + gaps
feature-pipeline	research → architect (opus) → implement → test → opus review → document
bugfix	root-cause → TDD fix → opus quality-gatekeeper verdict (≤2 rounds)
review-fanout	Adversarial multi-dimension review of the diff, each finding verified, opus synthesis
release-gate	Parallel build / tests+coverage / security / docs → single go/no-go

The independent reviewers run as fresh subagents with no developer context — they see only the git diff plus the spec, so the gate is a genuine second opinion.

/rulebook-driver                              # drain the whole backlog
/spec-author { "topic": "rate-limit the public API" }
/review-fanout                                # reviews the current git diff
/release-gate                                 # go/no-go before a release

---

Claude Code Setup

rulebook claude applies the recommended Claude Code setup in one idempotent, non-interactive step.

rulebook claude                 # apply the recommended setup
rulebook claude --model opus    # same, but set the default model (default: sonnet)

It installs the MCP server entry and the Rulebook-specific skills, then layers the v7 .claude/settings.json (agents/workflows are opt-in):

Applied	Detail
Hook	ONE path-only PreToolUse guard protecting task scaffolding — nothing on Stop/UserPromptSubmit/SessionStart, no content regexes
Full-autonomy permissions	defaultMode: acceptEdits + broad allow list (Bash/Edit/Write/Agent/WebFetch/…) — ~0 permission prompts for routine work
statusLine	project dir + git branch + context meter (ctx NN%)
model	cost-aware default (sonnet)

All settings are additive and non-clobbering — existing permissions.allow, a user-authored statusLine, and an explicit model are preserved. Requires Claude Code installed (~/.claude); otherwise it no-ops with a notice.

---

MCP Server

MCP tools over stdio transport. Zero configuration after rulebook mcp init.

rulebook mcp init    # One-time setup — configures .mcp.json automatically

Tool	Actions
rulebook_task	create · list · show · update · archive (tailWaiver) · validate · delete
rulebook_memory	knowledge / learnings / decisions × add · list · show · update · promote
rulebook_session	start (plans + tasks + learnings in ONE call) · end (rotating history)
rulebook_skill	list · show · search · enable · disable · validate
rulebook_rules	list project rules
rulebook_workspace	list · status · tasks (workspace mode only)

Workspace routing is automatic: pass any file path and the server resolves the owning project (explicit projectId overrides).

---

CLI Reference

# Project setup
rulebook init                    # Interactive setup (auto-detects everything)
rulebook init --minimal          # Essentials only
rulebook init --lean             # AGENTS.md as a <3KB index
rulebook update                  # Update to the latest rules
rulebook doctor                  # Health checks (file sizes, broken imports, stale state)
rulebook claude                  # Apply the recommended Claude Code setup

# Tasks
rulebook task create <task-id>   # Create (phase-prefixed: phase1_add-auth)
rulebook task list               # List active tasks
rulebook task archive <task-id>  # Archive a completed task

# Knowledge / decisions / learnings
rulebook knowledge list
rulebook decision list
rulebook learn list

# Workspace
rulebook workspace init
rulebook workspace add <path>
rulebook workspace status

# CI/CD & quality
rulebook workflows               # Generate GitHub Actions
rulebook check-coverage          # Check test coverage
rulebook version <major|minor|patch>

---

Supported 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 — auto-detected with confidence scores, each with language-specific templates and CI/CD workflows.

---

Configuration

All config lives in .rulebook/rulebook.json:

{
  "version": "6.0.0",
  "mode": "full",
  "features": {
    "gitHooks": true,
    "templates": true,
    "parallel": true,
    "smartContinue": true
  }
}

Key files generated by Rulebook:

File	Purpose
AGENTS.md	Team-shared, tool-agnostic 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	The quality-enforcement hook + permissions for Claude Code
.rulebook/tasks/	Active task directories
.rulebook/STATE.md	Machine-written live status

---

Documentation

Full documentation in /docs:

• Usage Examples — end-to-end flows for every workflow
• Getting Started
• Best Practices

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).
• 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