Enforce AI coding standards across every agent and tool

@hivehub/rulebook

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.

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

Task backend: files (default) or GitHub issues

By default tasks are directories under .rulebook/tasks/. Projects running
several agents at once can switch to GitHub issues instead, where one issue is
one task:

// .rulebook/rulebook.json
{ "tasks": { "backend": "github", "repo": "owner/name", "label": "rulebook-task" } }

The commands above and the rulebook_task MCP tool are unchanged - they talk
to whichever backend is configured, and agents can equally drive gh directly.
repo is optional (gh infers it from the remote).

Why switch: GitHub is a shared store, so parallel agents - including ones in
separate worktrees or on other machines - coordinate without conflicting on
task files. Progress renders natively in the issue, and task state cannot
diverge between branches because it does not live in the repo.

What moves into the issue: proposal.md, tasks.md, design.md and any
specs/<module>/spec.md become marked sections of the issue body. Status maps
to a rulebook-status:<state> label, and archiving closes the issue. Project
specs under .rulebook/specs/ stay on disk either way.

Requires gh on PATH and authenticated (gh auth login); rulebook says so
plainly rather than failing obscurely if it is missing.

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.

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):

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

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:

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.