rulebook-ai

A Rulebook-AI Pack is a self-contained directory. To pass validation, the root directory must contain only the following items. Any extra files or directories at the root (like tests/ or docs/) will cause validation to fail; such content must be moved inside standard directories like memory_starters/docs/.

Required Files/Directories

• manifest.yaml: Metadata for the pack.
• README.md: Description and usage.
• rules/: The universal source for AI assistant rules.

Optional Files/Directories

• memory_starters/: Starter files for the user's memory/ directory.
• tool_starters/: Starter scripts for the user's tools/ directory.

Example Layout

my-awesome-pack/
├── manifest.yaml
├── README.md
├── rules/
│   ├── 01-rules/
│   │   ├── 00-meta.md
│   │   └── 01-principles.md
│   ├── 02-rules-architect/
│   │   └── 01-planning.md
│   └── 03-rules-code/
│       └── 01-coding.md
├── memory_starters/
│   └── docs/
│       └── new-feature-template.md
└── tool_starters/
    └── my-custom-script.py

The READ_ARCHITECTURE rule set is designed to guide AI assistants in parsing and understanding solution architecture from a specific file: /memory/docs/architecture.md.

When this rule is active, the AI is instructed to:

1. Load and parse the complete Mermaid diagram within the file.
2. Extract key architectural details, including module boundaries, relationships, data flow patterns, system interfaces, and component dependencies.
3. Validate changes against the established architectural constraints.
4. Enforce separation of concerns to ensure new code does not violate the defined architecture.

Error Handling Behavior:

• If /memory/docs/architecture.md is missing, the AI must STOP and notify the user.
• If the Mermaid diagram fails to parse, the AI must REQUEST clarification.
• If an architectural violation is detected, the AI must WARN the user.

READ_ARCHITECTURE: |
  File: /memory/docs/architecture.md @architecture.md
  Required parsing:
  1. Load and parse complete Mermaid diagram
  2. Extract and understand:
     - Module boundaries and relationships
     - Data flow patterns
     - System interfaces
     - Component dependencies
  3. Validate any changes against architectural constraints
  4. Ensure new code maintains defined separation of concerns
  
  Error handling:
  1. If file not found: STOP and notify user
  2. If diagram parse fails: REQUEST clarification
  3. If architectural violation detected: WARN user

The project follows the modern Python src layout. This structure separates the main package code from tests and configuration files, ensuring that imports work correctly and the package is ready for distribution.

Directory Layout

• src/rulebook_ai/: Contains the main package code.
  • __init__.py: Package initialization.
  • __main__.py: Enables running the package via python -m rulebook_ai.
  • core.py: Contains the business logic, specifically the RuleManager class.
  • cli.py: Defines the command-line interface.
• tests/integration/: Contains integration tests (e.g., test_rule_manager.py, test_cli_commands.py).
• rule_sets/: Stores rule templates for various AI assistants.
• memory_starters/: Contains memory bank templates.
• tool_starters/: Contains tool integration examples.
• pyproject.toml: The declarative project configuration file.

rulebook-ai/
├── src/rulebook_ai/          # Main package (src layout)
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # Allow python -m rulebook_ai
│   ├── core.py               # Business logic (RuleManager class)
│   └── cli.py                # Command-line interface
├── tests/integration/        # Integration tests only
│   ├── conftest.py           # Shared test fixtures
│   ├── test_package_installation.py
│   ├── test_rule_manager.py
│   ├── test_cli_commands.py
│   └── test_tools_integration.py
├── rule_sets/                # Rule templates for AI assistants
├── memory_starters/          # Memory bank templates
├── tool_starters/            # Tool integration examples
├── pyproject.toml            # Project configuration
└── README.md                 # Project documentation

Light-Spec operates on a dual-system model: Procedural Rules (how the AI acts) and Contextual Memory (what the AI knows).

1. Procedural Rules (The 'How')

Rules are stored in .rulebook-ai/packs/light-spec/rules/ and define systematic workflows. The project sync command translates these into assistant-specific formats:

• Cursor: .mdc files in .cursor/rules/.
• RooCode: Mode-specific rules in .roo/rules-architect/ or .roo/rules-code/.
• Windsurf: .md files in .windsurf/rules/.
• Single-file assistants: A single concatenated file.

2. Contextual Memory (The 'What')

The memory/ directory is a user-owned space for persistent, structured knowledge. It includes PRDs, architecture docs, and task plans. This acts as the AI's long-term project 'second brain'.

Prompting Patterns

To get the best results, use file references (e.g., @filename) to connect rules and memory:

• Planning: "Add a 'Refactor Auth' task to @memory/tasks/tasks_plan.md with a short description."
• Context Lookup: "What database did we choose in @memory/docs/architecture.md?"
• Implementation: "Follow @.rulebook-ai/packs/light-spec/rules/03-rules-code/01-code_v1.md to build the login flow described in @memory/tasks/active_context.md."