rulebook-ai

• For bug report, use issues or use rulebook-ai command rulebook-ai bug-report
• For real-time chat, community support, and to share your ideas, Join our Discord
• Have specific feedback or want a personal demo? Book a Chat on my Calendar

Rulebook-AI: The AI Environment Manager

rulebook-ai is a command-line tool for packaging and deploying consistent, expert environments—rules, context, and tools—to your favorite AI coding assistants.

Stop wasting time re-explaining your project’s architecture or manually copy-pasting instructions between different AIs. With rulebook-ai, you define your AI’s environment once, and deploy it anywhere.

The Problem: AI Assistants are Generic and Isolated

AI coding assistants are powerful, but they operate in a vacuum.

1. They are forgetful: They have no long-term memory of your project’s specific architecture, libraries, or goals.
2. They are inconsistent: Instructions you give to Cursor don’t work in Gemini, and your Copilot context is siloed.
3. They are unspecialized: An AI’s general knowledge is not enough for expert-level tasks. A great “React developer” AI needs different rules, context, and tools than a great “DevOps engineer” AI.

The Solution: Portable and Composable AI Environments

rulebook-ai solves this by treating an AI’s entire operational context as a portable Environment that you can manage like code. An Environment consists of three parts:

• Rules: The AI’s operating instructions and workflows.
• Context: A persistent knowledge base (your project’s “memory”).
• Tools: Helper scripts the AI can use to perform tasks.

These environments are packaged into versionable, shareable Packs.

Why rulebook-ai is the Answer

Quick Start with uvx

# 1. Install uv if you don't have it yet
curl -fsSL https://astral.sh/uv/install.sh | bash

# 2. Add a pack to your project (e.g., the light-spec starter pack)
uvx rulebook-ai packs add light-spec

# 3. Sync the environment to your workspace
uvx rulebook-ai project sync

This will create a .rulebook-ai directory to manage state, and populate memory/ and tools/ with starters. It also generates the assistant-specific rule files (e.g., .cursor/rules/, GEMINI.md).

For a more detailed walkthrough of all features, see the Step-by-Step Tutorial.

Supported AI Assistants

rulebook-ai supports generating rule files for multiple AI coding assistants. Supported assistants include: Cursor, Windsurf, Cline, RooCode, Kilo Code, Warp, GitHub Copilot, Claude Code, Codex CLI, and Gemini CLI.

For detailed per‑assistant behavior, file locations, and format notes, see: memory/docs/user_guide/supported_assistants.md.

You can generate rules for one or more assistants using the --assistant flag, for example:

rulebook-ai project sync --assistant cursor copilot

Or generate rules for all supported assistants with:

rulebook-ai project sync --all

How It Works: The Pack System

The core of rulebook-ai is a simple, powerful workflow:

1. Add Packs: You add one or more Packs to your project’s library. A pack can be built-in, from the community, or from your own local directory.
2. Sync Project: You run rulebook-ai project sync. The tool reads your selected packs, copies over any starter memory/ and tools/, and generates the final rule files in the correct format for each AI assistant you use.

This workflow ensures your project’s “AI Environment” is explicit, versionable, and easy to manage.

Your First Environment: The Built-in Packs

rulebook-ai comes with a few packs to get you started immediately. The light-spec pack is the recommended starting point for any new project.

• light-spec:

  • Benefit: Installs a foundational software development lifecycle environment. It teaches your AI to think like a junior developer, following systematic processes for planning, coding, and debugging. It also provides starter templates for your project’s documentation (memory/).
  • Target Users: Everyone. It’s the ideal first pack to add to any project.

• medium-spec & heavy-spec:

  • Benefit: These provide more verbose rules and stricter guardrails, perfect for when you need the AI to be more cautious and detailed, such as during a complex code review or refactoring.
  • Target Users: Developers who want more explicit guidance and checks from their AI assistant.

Project Structure after Sync

• Your Environment (memory/, tools/): This is your project’s unique context. You own it, you edit it, and you commit it to version control.
• Generated Artifacts (.rulebook-ai/, .cursor/, etc.): These are managed by the CLI. They should be added to .gitignore as they can be regenerated at any time.

Contributing

Join our Discord if any questions or idea discussion about contribution. This project thrives on community contributions. You can contribute by:

• Creating and Sharing Packs: Got a great set of rules and tools for a specific framework or role? Package it up and share it! See the Pack Developer Guide.
• Reporting Bugs or Ideas: Open an Issue in the repo. The rulebook-ai bug-report command will take you there.
• Contributing the repo: go to CONTRIBUTING.md