Rulebook-AI: The AI Environment Manager

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

- 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](https://discord.gg/aNmQB7JWPe) 
- Have specific feedback or want a personal demo? [Book a Chat on my Calendar](https://calendar.app.google/xx3S3CuKSBAt9d9Y7)

# 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

| Value Proposition                  | How `rulebook-ai` Delivers                                                                                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Portability Across Assistants**  | Define an environment once in a universal **Pack**. The `project sync` command automatically translates and deploys it to any supported AI (Cursor, Gemini, Copilot, etc.). Use the best AI for the job without losing context. |
| **Deep Specialization for Any Task** | Create or use packs for specific roles (**Product Manager, DevOps**) or technologies (**React, AWS, Data Science**). Instantly "onboard" your AI with the expert knowledge and tools it needs for the task at hand. |
| **Composable & Versionable Context** | Treat your AI's environment as code. Mix and match packs to build the perfect setup for any project. Use **Profiles** (named groups of packs) to instantly switch between entire configurations.                               |
| **Community-Driven Expertise**     | Don't reinvent the wheel. `rulebook-ai` is a platform for a community of experts to build and share packs, creating a public library of best practices for AI-assisted development.                                     |
| **Clean & Predictable Workspace**  | The tool cleanly separates your user-owned content (`memory/`, `tools/`) from framework-managed artifacts (`.rulebook-ai/`, generated rules), keeping your project tidy and predictable.                               |
| **Total Control Over Sources**     | Go beyond the public index. Add packs directly from any GitHub repo (`github:`) or develop and test them from your local filesystem (`local:`). You have a secure path for private packs and a seamless workflow for creating new ones. |

## Quick Start with `uvx`

```bash
# 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](memory/docs/user_guide/tutorial.md).

## 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 CL

... (truncated)