rulebook

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

Knowledge, decisions & learnings