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

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

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.

| 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