Package Exports

@hivellm/rulebook
@hivellm/rulebook/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hivellm/rulebook) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@hivellm/rulebook

Standardize AI-generated projects with automated templates, quality gates, and framework detection for 28 languages.

Why Rulebook?

Large Language Models (LLMs) for software development need clear directives to generate high-quality code consistently. Without standardized guidelines, AI-generated code can be inconsistent, error-prone, and difficult to maintain.

Rulebook solves this by providing:

📋 Comprehensive Rule Sets: Language-specific guidelines (TypeScript, Rust, Python, etc.), framework conventions (NestJS, Django, React), testing standards, linting rules, spell-checking, CI/CD pipelines, Git hooks, and version control best practices
🎯 Normalized Deliverables: Ensures consistent code quality across all AI-generated outputs
🛡️ Error Reduction: Catches issues early through automated quality gates and pre-commit/pre-push hooks
⚙️ Process Automation: Automates repetitive tasks like formatting, testing, and deployment
🔌 MCP Integration: Supports multiple Model Context Protocol (MCP) modules for enhanced AI capabilities
📊 Task Management: Built-in task management system (OpenSpec-compatible format) for structured development

By giving LLMs a clear "rulebook" to follow, you ensure that every piece of generated code meets your project's standards—automatically.

Quick Start

# New project (interactive)
npx @hivellm/rulebook@latest init

# Minimal setup (essentials only)
npx @hivellm/rulebook@latest init --minimal

# Light mode (prototypes without strict rules)
npx @hivellm/rulebook@latest init --light

# Update existing project
npx @hivellm/rulebook@latest update

What's New in v0.18.0

🎯 Built-in Task Management: OpenSpec deprecated and integrated into Rulebook's native task system
- Use rulebook task commands instead of OpenSpec
- OpenSpec-compatible format preserved
- Automatic migration from OpenSpec to Rulebook format on rulebook update
📋 RULEBOOK.md Template: New core template with task management directives and Context7 MCP requirements
🚫 Automatic .gitignore: rulebook init now creates/updates .gitignore automatically for 28 languages
🔄 Migration Support: Existing OpenSpec tasks automatically migrated to /rulebook/tasks/ format
📚 Complete Documentation: Migration guide, updated README, and comprehensive CHANGELOG

Breaking Change: OpenSpec module removed. Use rulebook task commands instead. See Migration Guide.

Key Features

🔍 Auto-Detection: Detects languages, frameworks (NestJS, React, Spring, etc.), and MCP modules
📁 Modular Architecture: Templates stored in /rulebook/ directory for better organization
- Smaller AGENTS.md files (prevents 100k+ character limits)
- QUALITY_ENFORCEMENT and Git rules moved to /rulebook/ for cleaner structure
- On-demand loading for better AI performance
- Easier maintenance and updates
📋 Simplified AGENTS.md: Clean, focused structure with only core rules and references
- Proper hierarchy with ## and ### subsections
- All modules grouped logically
- Better readability and navigation
🔗 Git Hook Automation: Optional pre-commit/pre-push hooks with language-aware quality checks
🚫 Automatic .gitignore: Creates/updates .gitignore automatically for 28 languages on rulebook init
🎯 Minimal Mode: Quick setup with just README, LICENSE, tests/, and basic CI
📝 86+ Templates: Languages, frameworks, IDEs, workflows pre-configured
🤖 AI-Optimized: Works with 23 AI assistants (Cursor, Claude, Gemini, etc.)
📦 Publication Ready: CI/CD pipelines for npm, crates.io, PyPI, Maven Central, and more
🔄 Automatic Migration: Existing projects automatically migrated to modular structure and OpenSpec tasks

What It Does

For New Projects:

Detects your language(s), frameworks, and MCP modules
Asks setup questions (or use --minimal for defaults)
Generates AGENTS.md with AI assistant rules (modular structure)
Creates /rulebook/ directory with language/framework/module templates
Creates/updates .gitignore automatically for detected languages
Optionally installs Git hooks (pre-commit/pre-push)
Creates GitHub Actions workflows
Scaffolds README, LICENSE, /docs, and /tests

For Existing Projects:

npx @hivellm/rulebook update

Automatically migrates embedded templates to modular /rulebook/ structure
Automatically migrates OpenSpec tasks to Rulebook format (if OpenSpec exists)
Merges latest templates while preserving your customizations
Updates AGENTS.md with references to modular files
Updates .gitignore with missing patterns for detected languages

Commands

Core Commands

# Project Initialization & Updates
rulebook init              # Initialize new project (interactive)
rulebook init --minimal    # Minimal setup (essentials only)
rulebook init --light      # Light mode (no quality enforcement)
rulebook init --yes        # Skip prompts, use defaults
rulebook update            # Update AGENTS.md to latest version
rulebook update --yes      # Update without confirmation
rulebook update --light    # Update in light mode

# Workflow & CI/CD
rulebook workflows         # Generate GitHub Actions workflows

# Validation & Health
rulebook validate          # Check project standards
rulebook health            # Project health score (0-100)
rulebook fix               # Auto-fix common issues

# Documentation
rulebook generate-docs     # Create /docs structure
rulebook generate-docs --yes  # Skip prompts, use defaults

# Dependencies & Coverage
rulebook check-deps        # Check outdated/vulnerable dependencies
rulebook check-coverage    # Check test coverage (default: 95%)
rulebook check-coverage -t 80  # Custom threshold

# Versioning
rulebook version <type>    # Bump version (major|minor|patch)
rulebook changelog         # Generate changelog from git commits
rulebook changelog -v 1.0.0  # Specify version

Advanced Commands (Beta)

# Real-time Monitoring
rulebook watcher           # Full-screen task monitoring UI
                          # - Live task progress tracking
                          # - Activity log with timestamps
                          # - System status monitoring
                          # - Auto-refresh every 2 seconds

# Autonomous Agent
rulebook agent             # Start AI CLI workflow automation
rulebook agent --dry-run   # Simulate without changes
rulebook agent --tool cursor-agent  # Specify CLI tool
rulebook agent --iterations 10      # Max iterations
rulebook agent --watch     # Enable watcher mode

# Task Management
rulebook task create <task-id>    # Create new task
rulebook task list [--archived]   # List all tasks
rulebook task show <task-id>      # Show task details
rulebook task validate <task-id>  # Validate task format
rulebook task archive <task-id>   # Archive completed task
rulebook tasks                     # Legacy command (deprecated, use 'task' instead)

# Configuration
rulebook config --show     # Show current config
rulebook config --set key=value  # Set config value
rulebook config --feature watcher --enable   # Enable feature
rulebook config --feature agent --disable    # Disable feature

Setup Modes

Full Mode (Default)

Complete setup with all features: Task management, Watcher, MCP modules, comprehensive workflows.

Minimal Mode

rulebook init --minimal

Essentials only: README, LICENSE, tests/, basic CI. Perfect for small teams or initial adoption.

Light Mode

rulebook init --light

Bare minimum rules: no quality enforcement, no testing requirements, no linting. Use for quick prototypes or non-production projects.

Supported Languages & Frameworks

28 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

17 Frameworks (auto-detected):

Backend: NestJS, Spring Boot, Laravel, Django, Flask, Ruby on Rails, Symfony, Zend
Frontend: Angular, React, Vue, Nuxt, Next.js, jQuery
Mobile: React Native, Flutter
Desktop: Electron

MCP Modules (12)

Core: Vectorizer • Synap • Context7 • GitHub MCP • Playwright

Services: Supabase • Notion • Atlassian • Serena • Figma • Grafana

AI Tools Supported (23)

IDEs: Cursor, Windsurf, VS Code, GitHub Copilot, Tabnine, Replit, JetBrains AI, Zed

CLI Agents: Aider, Continue, Claude, Claude Code, Gemini, Cline, Amazon Q, Auggie, CodeBuddy, Factory, OpenCode, Kilo, Codex, Codeium, Cursor CLI

Documentation

Full documentation available in /docs:

Contributing

Contributions welcome! Node.js 18+ required.

npm install
npm test
npm run build

License

Links: Issues • Discussions