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

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, agents, workflows, settings)
npx @hivehub/rulebook@latest claude

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

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 mandatory docs + tests + verify tail, driven by an opus review gate | | MCP tools | Task management, skills, decisions, knowledge, learnings, workspace — over Model Context Protocol | | Structural enforcement | A PreToolUse hook blocks stubs/TODOs/deferred tasks before edits reach disk | | 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

rulebook init/update installs orchestrated Claude Code Workflow scripts 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, skills, agent definitions, and workflows, then layers an opinionated, cost-aware .claude/settings.json:

| Applied | Detail | |---------|--------| | Hook | a single PreToolUse quality-enforcement hook (no per-turn or per-session hooks by default) | | Permissions allowlist | auto-approves safe read-only Bash (ls/cat/grep/rg/find/git status\|diff\|log\|blame/npm run type-check/npm test) + mcp__rulebook | | statusLine | shows project dir + git branch | | model | cost-aware default (sonnet; opus stays reserved for the workflow review gates) |

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

| Category | Tools | |----------|-------| | Tasks | create, list, show, update, validate, archive, delete | | Skills | list, show, enable, disable, search, validate | | Knowledge | add, list, show | | Decisions | create, list, show, update | | Learnings | capture, list, promote | | Workspace | list, status, search, tasks | | Other | rules list, session start/end |

All tools accept an 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 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