ai-rulez 2.2.1 → 2.4.0

package/README.md

@@ -4,30 +4,45 @@
   <img src="https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/logo.png" alt="ai-rulez logo" width="200" style="border-radius: 15%; overflow: hidden;">
 </p>
 
-**One config to rule them all.**
+**AI-powered development governance. One config to rule them all.**
 
-## The Problem
+## The Complete AI Development Platform
 
-If you're using multiple AI coding assistants (Claude Code, Cursor, Windsurf, GitHub Copilot), you've probably noticed the configuration fragmentation. Each tool demands its own format - `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`. Keeping coding standards consistent across all these tools is frustrating and error-prone.
+AI-Rulez is the **definitive platform for AI-powered development governance**. Beyond just generating configuration files, it provides real-time rule enforcement, automated code quality assurance, and intelligent governance across your entire development workflow.
 
-## The Solution
+### 🚀 Two Powerful Capabilities
 
-AI-Rulez lets you write your project configuration once and automatically generates native files for every AI tool - current and future ones. It's like having a build system for AI context.
+**1. Universal Configuration Management** - Write once, deploy everywhere
+**2. AI-Powered Rule Enforcement** - Real-time governance with automated fixes
 
-<p align="center">
-  <img src="docs/assets/ai-rulez-python-demo.gif" alt="AI-Rulez Demo" width="100%">
-</p>
+## Why AI-Rulez?
 
-## Why This Matters
+Modern development teams need more than just configuration management:
 
-Development teams using AI assistants face common challenges:
-- **Multiple tools, multiple configs**: Your team uses Claude Code for reviews, Cursor for development, Copilot for completions
-- **Configuration drift**: Maintaining separate files leads to inconsistent standards across tools
-- **Monorepo complexity**: Multiple services and packages all need different AI contexts
-- **Team consistency**: Junior devs get different AI guidance than seniors
-- **Future-proofing**: New AI tools require rewriting all configurations
+### ⚠️ **The Problem**
+- **Configuration Hell**: Each AI tool needs its own format (`.cursorrules`, `CLAUDE.md`, `.windsurfrules`, etc.)
+- **Rule Enforcement Gap**: No way to automatically validate that code follows your standards
+- **Team Inconsistency**: Different developers get different AI guidance
+- **Manual Quality Control**: Time-consuming code reviews for basic rule violations
+- **Reactive Governance**: Finding issues after they're already committed
 
-AI-Rulez solves this with a single `ai-rulez.yaml` that understands your project's conventions.
+### ✨ **The Solution**
+AI-Rulez provides **proactive development governance** with a single `ai-rulez.yaml` that:
+- **Generates configurations** for every AI tool automatically
+- **Enforces rules in real-time** using AI agents (Claude, Gemini, etc.)
+- **Applies automatic fixes** for code quality issues
+- **Integrates with your workflow** (Git hooks, CI/CD, pre-commit)
+- **Scales across teams** with consistent standards
+
+<p align="center">
+  <img src="docs/assets/ai-rulez-python-demo.gif" alt="AI-Rulez Configuration Demo" width="100%">
+  <br><em>📝 Configuration Management (via npx ai-rulez)</em>
+</p>
+
+<p align="center">
+  <img src="docs/assets/ai-rulez-enforce-demo.gif" alt="AI-Rulez Enforcement Demo" width="100%">
+  <br><em>🤖 AI-Powered Rule Enforcement (via uvx ai-rulez@latest)</em>
+</p>
 
 [![Go Version](https://img.shields.io/badge/Go-1.24%2B-00ADD8)](https://go.dev)
 [![NPM Version](https://img.shields.io/npm/v/ai-rulez)](https://www.npmjs.com/package/ai-rulez)
@@ -38,40 +53,58 @@ AI-Rulez solves this with a single `ai-rulez.yaml` that understands your project
 
 ---
 
-## Key Features
+## 🚀 Core Capabilities
+
+### 1. 📋 Universal Configuration Management
 
-### AI-Powered Project Analysis
-The `init` command is where AI-Rulez shines. Instead of manually writing configurations, let AI analyze your codebase:
+Write once, deploy everywhere with intelligent AI-powered project analysis:
 
 ```bash
 # AI analyzes your codebase and generates tailored config
-npx ai-rulez init "My Project" --preset popular --use-agent claude --yes
+npx ai-rulez init "My Project" --preset popular
+```
+
+**Features:**
+- **AI Project Analysis**: Automatically detects your tech stack, patterns, and conventions
+- **Universal Output Generation**: One YAML → all AI tool formats (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc.)
+- **Smart Gitignore Management**: Automatically excludes generated files from version control
+- **MCP Integration**: Auto-configure MCP servers across CLI tools (Claude, Gemini, etc.)
+- **Team Collaboration**: Remote includes, local overrides, monorepo support
+
+### 2. 🤖 AI-Powered Rule Enforcement
+
+Real-time governance with automated fixes using multiple AI agents:
+
+```bash
+# Check for violations with AI analysis
+uvx ai-rulez@latest enforce --agent claude
+
+# Automatically apply fixes
+uvx ai-rulez@latest enforce --agent claude --fix
+
+# Multi-agent review workflow
+uvx ai-rulez@latest enforce --agent gemini --review --review-agent claude
 ```
 
-This automatically:
-- Detects your tech stack (Python/Node/Go, testing frameworks, linters)
-- Identifies project patterns and conventions
-- Generates appropriate coding standards and practices
-- Creates specialized agents for different tasks (code review, testing, docs)
-- **Automatically adds all generated AI files to .gitignore** - no more committing `.cursorrules` or `CLAUDE.md` by accident
-
-### Universal Output Generation
-One YAML config generates files for every tool:
-- `CLAUDE.md` for Claude Code
-- `.cursorrules` for Cursor
-- `.windsurfrules` for Windsurf  
-- `.github/copilot-instructions.md` for GitHub Copilot
-- Custom formats for any future AI tool
-
-### Powerful Enterprise Features
-- **MCP Integration:** Automatically configure MCP servers across CLI tools (Claude, Gemini) and generate config files for others (Cursor, VS Code). One configuration, every tool connected.
-- **Team Collaboration:** Remote config includes, local overrides, and monorepo support with `--recursive`
-- **Full-Featured CLI:** Manage your entire configuration from the command line. Add rules, update agents, and generate files without ever opening a YAML file.
-- **Security & Performance:** SSRF protection, schema validation, Go-based performance with instant startup
+**Features:**
+- **Multi-Agent Support**: Claude, Gemini, AMP, Cursor, Codex, Continue.dev, Junie
+- **Automated Fixes**: AI suggests and applies code improvements
+- **Review Workflows**: Iterative improvement with quality thresholds
+- **Multiple Output Formats**: Table, JSON, CSV, summary reports
+- **CI/CD Integration**: Git hooks, pre-commit, workflow automation
+- **Quality Scoring**: 0-100% compliance with configurable thresholds
 
 ## How It Works
 
-`ai-rulez` takes your `ai-rulez.yml` file and uses it as a single source of truth to generate native configuration files for all your AI tools. Think of it as a build system for AI context—you write the source once, and it compiles to whatever format each tool needs.
+AI-Rulez operates as a **comprehensive AI development governance platform**:
+
+1. **📝 Configuration Phase**: Your `ai-rulez.yml` serves as the single source of truth
+2. **🏗️ Generation Phase**: Automatically creates native files for every AI tool
+3. **🔍 Enforcement Phase**: AI agents continuously validate code against your rules
+4. **🛠️ Fix Phase**: Automatic corrections and improvements applied in real-time
+5. **📊 Reporting Phase**: Detailed compliance reports and quality metrics
+
+Think of it as **CI/CD for code quality** - proactive governance instead of reactive fixes.
 
 ## Example: `ai-rulez.yml`
 
@@ -84,7 +117,7 @@ metadata:
 
 # Use presets for common configurations
 presets:
-  - "popular"  # Includes Claude, Cursor, Windsurf, and Copilot
+  - "popular"  # Includes Claude, Cursor, Windsurf, Copilot, and Gemini
 
 rules:
   - name: "Go Code Standards"
@@ -107,33 +140,132 @@ agents:
 # MCP servers for direct AI tool integration
 mcp_servers:
   - name: "ai-rulez"
-    command: "ai-rulez"
-    args: ["mcp"]
+    command: "npx"
+    args: ["-y", "ai-rulez@latest", "mcp"]
     description: "AI-Rulez MCP server for configuration management"
 ```
 
 Run `ai-rulez generate` → get all your configuration files, perfectly synchronized.
 
-## Quick Start
+## ⚡ Quick Start
 
+### 📋 Configuration Management
 ```bash
-# 1. AI-powered initialization (recommended)
-ai-rulez init "My Project" --preset popular --use-agent claude
+# 1. AI-powered project analysis and setup
+npx ai-rulez@latest init "My Project" --preset popular
 
-# 2. Generate all AI instruction files
-ai-rulez generate
+# 2. Generate all AI tool configuration files
+npx ai-rulez@latest generate
 
 # 3. Your AI tools now have comprehensive, project-specific context!
 ```
 
-**That's it!** The AI will analyze your codebase and generate tailored rules, documentation, and specialized agents automatically.
+### 🤖 AI-Powered Rule Enforcement
+```bash
+# 1. Check for rule violations
+uvx ai-rulez@latest enforce --agent claude --format table
+
+# 2. Get detailed analysis and suggestions
+uvx ai-rulez@latest enforce --agent claude --format json
+
+# 3. Apply automatic fixes
+uvx ai-rulez@latest enforce --agent claude --fix
+
+# 4. Set up review workflow
+uvx ai-rulez@latest enforce --agent claude --review --review-iterations 2
+```
+
+**That's it!** You now have both intelligent configuration management AND real-time rule enforcement powered by AI.
+
+---
+
+## 🗂️ .gitignore Management
+
+AI-Rulez manages your `.gitignore` to keep generated files out of version control.
+
+**Automatic updates:**
+```bash
+# During init (enabled by default)
+ai-rulez init --preset claude
+
+# During generate (optional)
+ai-rulez generate --update-gitignore
+
+# Disable if needed
+ai-rulez init --preset popular --no-gitignore
+```
+
+**What gets ignored:**
+- Generated markdown files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`)
+- AI tool directories (`.claude/`, `.cursor/`, `.windsurf/`, `.clinerules/`, etc.)
+- Config files (`.mcp.json`, `.gemini/settings.json`)
+
+All entries are added under `# AI Rules generated files` without duplicates.
+
+**Best practice:** Commit `ai-rulez.yaml` and `.gitignore`, but not the generated AI configuration files.
+
+---
+
+## 🤖 AI-Powered Rule Enforcement
+
+The killer feature that sets AI-Rulez apart: **real-time rule enforcement using AI agents**. No more manual code reviews for basic violations—let AI catch and fix issues automatically.
+
+### ✨ Key Benefits
+
+- **Proactive Quality Control**: Catch issues before they reach production
+- **Multi-Agent Support**: Claude, Gemini, AMP, Cursor, Codex—use the best AI for each task
+- **Automatic Fixes**: AI doesn't just find problems, it solves them
+- **Workflow Integration**: Git hooks, CI/CD, pre-commit—enforcement everywhere
+- **Team Consistency**: Same standards for everyone, from junior to senior devs
+
+### 🎯 Real-World Use Cases
+
+```bash
+# Prevent console.log in production builds
+ai-rulez enforce --agent claude --only-rules "no-console-output" --fix
+
+# Ensure all functions have proper error handling
+ai-rulez enforce --agent gemini --level strict --format json
+
+# Multi-agent review for critical code changes
+ai-rulez enforce --agent claude --review --review-agent gemini --review-threshold 95
+
+# Automated fixes in CI/CD pipeline
+ai-rulez enforce --agent claude --fix --format csv --output violations.csv
+```
+
+### 📊 Output Formats & Integration
+
+| Format | Use Case | Command |
+|--------|----------|---------|
+| **Table** | Human-readable terminal output | `--format table` |
+| **JSON** | API integration, detailed analysis | `--format json --pretty` |
+| **CSV** | Data analysis, reporting | `--format csv --output report.csv` |
+| **Summary** | Quick overview with scores | `--format summary` |
+
+### 🔄 Advanced Workflows
+
+**Review Pipeline**: Multi-agent validation with quality gates
+```bash
+ai-rulez enforce --agent claude --review --review-iterations 3 --review-threshold 85
+```
+
+**Fix & Verify**: Apply fixes and validate improvements
+```bash
+ai-rulez enforce --agent gemini --fix --review --require-improvement
+```
+
+**Team Standards**: Consistent enforcement across the entire codebase
+```bash
+ai-rulez enforce --include-files "src/**/*.{js,ts,py}" --level strict --agent claude
+```
 
 **Prefer manual setup?**
 ```bash
 # Basic initialization without AI assistance
-ai-rulez init "My Project" --preset popular
+ai-rulez init "My Project" --preset popular --no-agent
 
-# Add your project-specific context  
+# Add your project-specific context
 ai-rulez add rule "Tech Stack" --priority critical --content "This project uses Go and PostgreSQL."
 
 # Generate files
@@ -215,58 +347,172 @@ ai-rulez mcp
 # Or configure it automatically via your ai-rulez.yaml
 mcp_servers:
   - name: "ai-rulez"
-    command: "ai-rulez" 
-    args: ["mcp"]
+    command: "npx"
+    args: ["-y", "ai-rulez@latest", "mcp"]
     description: "Configuration management server"
 ```
 
-## Installation
+## AI-Powered Rule Enforcement
 
-### Run without installing
+AI-Rulez provides **real-time rule enforcement** using AI agents to automatically detect violations and apply fixes across your codebase.
 
-For one-off executions, you can run `ai-rulez` directly without a system-wide installation.
+<p align="center">
+  <img src="docs/assets/ai-rulez-enforce-demo.gif" alt="AI-Rulez Enforcement Demo" width="100%">
+</p>
+
+### Basic Enforcement
 
-**Go**
 ```bash
-go run github.com/Goldziher/ai-rulez/cmd@latest --help
+# Check for violations (read-only by default)
+ai-rulez enforce
+
+# Automatically apply fixes
+ai-rulez enforce --fix
+
+# Use specific AI agent
+ai-rulez enforce --agent gemini --fix
 ```
 
-**Node.js (via npx)**
+### Advanced Enforcement Options
+
 ```bash
-# Installs and runs the latest version
-npx ai-rulez@latest init
+# Enforce with specific level
+ai-rulez enforce --level strict --agent claude
+
+# Review workflow with iterative improvement
+ai-rulez enforce --review --review-iterations 3 --review-threshold 85
+
+# Multi-agent review (different agents for enforcement vs review)
+ai-rulez enforce --agent gemini --review --review-agent claude
+
+# Target specific files and rules
+ai-rulez enforce --include-files "src/**/*.js" --only-rules "no-console-output"
+
+# Output formats for automation
+ai-rulez enforce --format json --output violations.json
+ai-rulez enforce --format csv --output report.csv
+```
+
+### Supported AI Agents
+
+AI-Rulez integrates with all major AI coding assistants:
+
+- **Claude** (`claude`) - Anthropic's AI assistant
+- **Gemini** (`gemini`) - Google's AI model
+- **Cursor** (`cursor`) - AI-powered code editor
+- **AMP** (`amp`) - Sourcegraph's AI assistant
+- **Codex** (`codex`) - OpenAI's code model
+- **Continue.dev** (`continue-dev`) - Open-source coding assistant
+- **Junie** (`junie`) - JetBrains AI assistant
+
+### Enforcement Levels
+
+- **`warn`**: Log violations but don't fail (default)
+- **`error`**: Fail on violations but don't auto-fix
+- **`fix`**: Automatically apply suggested fixes
+- **`strict`**: Fail immediately on any violation
+
+### Integration with Git Hooks
+
+Add enforcement to your Git workflow:
+
+```yaml
+# .lefthook.yml
+pre-commit:
+  commands:
+    ai-rulez-enforce:
+      run: ai-rulez enforce --level error --agent gemini
+      stage_fixed: true
 ```
 
-**Python (via uvx)**
 ```bash
-# Runs ai-rulez in a temporary virtual environment
-uvx ai-rulez init
+# Or with pre-commit hooks
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: ai-rulez-enforce
+        name: AI-Rulez Enforcement
+        entry: ai-rulez enforce --level error
+        language: system
+        pass_filenames: false
 ```
 
-### Install globally
+### Review Workflow
 
-For frequent use, a global installation is recommended.
+The review system provides iterative code improvement:
 
-**Go**
 ```bash
-go install github.com/Goldziher/ai-rulez/cmd@latest
+# Enable review with quality scoring
+ai-rulez enforce --review --review-threshold 80
+
+# Multiple review iterations
+ai-rulez enforce --review --review-iterations 5
+
+# Auto-approve after reaching threshold
+ai-rulez enforce --review --review-auto-approve
+
+# Require improvement between iterations
+ai-rulez enforce --review --require-improvement
 ```
 
-**Homebrew (macOS/Linux)**
+The AI reviewer analyzes:
+- ✅ Code quality and adherence to rules
+- ✅ Suggested fixes and their appropriateness
+- ✅ Overall improvement between iterations
+- ✅ Compliance with project standards
+
+## 📦 Installation
+
+Choose your installation method based on your primary use case:
+
+### 🚀 Quick Start (No Installation)
+
+**For Configuration Management** (project setup, file generation):
+```bash
+# Node.js - Best for web/JS projects
+npx ai-rulez@latest init "My Project" --preset popular
+npx ai-rulez@latest generate
+```
+
+**For Rule Enforcement** (AI-powered validation):
+```bash
+# Python - Latest features, fastest updates
+uvx ai-rulez@latest enforce --agent claude --fix
+uvx ai-rulez@latest enforce --agent gemini --review
+```
+
+**For Go Projects**:
+```bash
+go run github.com/Goldziher/ai-rulez/cmd@latest init
+```
+
+### 🔧 Global Installation
+
+For teams and frequent usage:
+
+**Homebrew (Recommended for macOS/Linux)**
 ```bash
 brew install goldziher/tap/ai-rulez
+ai-rulez init "My Project"
+ai-rulez enforce --agent claude
 ```
 
-**npm**
+**npm (Best for Node.js teams)**
 ```bash
 npm install -g ai-rulez
 ```
 
-**pip**
+**pip (Best for Python teams)**
 ```bash
 pip install ai-rulez
 ```
 
+**Go (For Go developers)**
+```bash
+go install github.com/Goldziher/ai-rulez/cmd@latest
+```
+
 ## Pre-commit Hooks
 
 You can use `ai-rulez` with `pre-commit` to automatically validate and generate your AI configuration files.
@@ -276,7 +522,7 @@ Add the following to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Goldziher/ai-rulez
-    rev: v2.1.4
+    rev: v2.2.1
     hooks:
       - id: ai-rulez-validate
       - id: ai-rulez-generate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-rulez",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "⚡ One config to rule them all. Centralized AI assistant configuration management - generate rules for Claude, Cursor, Copilot, Windsurf and more from a single YAML file.",
   "keywords": [
     "ai",