ai-rulez 3.4.1 → 3.6.0

package/README.md

@@ -1,108 +1,53 @@
 # ai-rulez
 
-Directory-based AI governance for development teams.
+Write AI assistant rules once. Generate configs for 18 different tools.
 
-ai-rulez lets you write AI assistant rules, context, and instructions once, then generate native configuration files for Claude, Cursor, Windsurf, Copilot, Gemini, and other AI coding tools. All configuration lives in a single `.ai-rulez/` directory in your repository.
+Every AI coding tool wants its own config format. Claude needs `CLAUDE.md`, Cursor wants `.cursor/rules/`, Copilot expects `.github/copilot-instructions.md`. Keeping them in sync is tedious and error-prone.
 
-**Documentation:** https://goldziher.github.io/ai-rulez/
-
-## Quick Start
+ai-rulez solves this: define rules and context in `.ai-rulez/`, run `generate`, and get native configs for all your tools.
 
 ```bash
-# Initialize (no installation required)
-npx ai-rulez@latest init
-# or
-uvx ai-rulez init
-
-# Edit your configuration in .ai-rulez/
-# Then generate tool-specific configs
-npx ai-rulez@latest generate
-# or
-uvx ai-rulez generate
+npx ai-rulez@latest init && npx ai-rulez@latest generate
 ```
 
-<details>
-<summary>Installation Methods</summary>
-
-### Global Installation
-
-**Homebrew (macOS/Linux):**
-```bash
-brew install goldziher/tap/ai-rulez
-```
+**[Documentation](https://goldziher.github.io/ai-rulez/)**
 
-**Go:**
-```bash
-go install github.com/Goldziher/ai-rulez/cmd@latest
-```
+## What You Get
 
-**npm:**
-```bash
-npm install -g ai-rulez
-```
+- **18 preset generators**: Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Continue.dev, Amp, Junie, Codex, OpenCode, and custom presets
+- **Commands system**: Define slash commands once, use them across tools that support it
+- **Context compression**: 34% size reduction with smart whitespace optimization
+- **Remote includes**: Pull shared rules from git repos (company standards, team configs)
+- **Profile system**: Generate different configs for backend/frontend/QA teams
+- **MCP server**: Let AI assistants manage their own rules via Model Context Protocol
+- **Type-safe schemas**: JSON Schema validation for all config files
 
-**Python (pip):**
-```bash
-pip install ai-rulez
-```
-
-**Python (uv):**
-```bash
-uv tool install ai-rulez
-```
-
-</details>
-
-## How It Works
-
-### 1. Initialize Your Project
+## Quick Start
 
 ```bash
-ai-rulez init "My Project"
+# No install required
+npx ai-rulez@latest init "My Project"
+npx ai-rulez@latest generate
 ```
 
-This creates a `.ai-rulez/` directory:
+This creates:
 
 ```
 .ai-rulez/
-├── config.yaml           # Main configuration
-├── rules/                # Rules that AI assistants must follow
-│   └── code-quality.md
-├── context/              # Background information about your project
-│   └── architecture.md
-├── skills/               # Specialized AI agent configurations
-│   └── code-reviewer/
-│       └── SKILL.md
-├── agents/               # Agent prompt files
-├── domains/              # Optional domain-specific organization
-└── mcp.yaml              # Model Context Protocol servers
-```
-
-<details>
-<summary>Init Command Options</summary>
-
-```bash
-# Create with specific domains
-ai-rulez init --domains backend,frontend,qa
-
-# Skip example content
-ai-rulez init --skip-content
-
-# Use JSON instead of YAML
-ai-rulez init --format json
-
-# Import from existing tool files
-ai-rulez init --from auto
-ai-rulez init --from .cursorrules,CLAUDE.md
+├── config.yaml       # Which tools to generate for
+├── rules/            # Guidelines AI must follow
+├── context/          # Project background info
+├── skills/           # Specialized AI roles
+├── agents/           # Agent-specific prompts
+└── commands/         # Slash commands
 ```
 
-</details>
+And generates native configs for each tool you specify.
 
-### 2. Configure Your AI Tools
-
-Edit `.ai-rulez/config.yaml` to specify which AI tools you want to support:
+## Configuration
 
 ```yaml
+# .ai-rulez/config.yaml
 version: "3.0"
 name: "My Project"
 
@@ -110,608 +55,220 @@ presets:
   - claude
   - cursor
   - copilot
-```
-
-<details>
-<summary>Available Presets</summary>
-
-- **claude** - Claude Desktop and Claude Code
-- **cursor** - Cursor IDE
-- **windsurf** - Windsurf IDE
-- **copilot** - GitHub Copilot
-- **gemini** - Google Gemini
-- **cline** - Cline extension
-- **continue-dev** - Continue.dev
-- **junie** - Junie AI
-- **amp** - AMP
-- **codex** - OpenAI Codex
-- **opencode** - OpenCode
-
-</details>
-
-### 3. Add Your Rules and Context
+  - windsurf
 
-Create markdown files in `.ai-rulez/rules/`, `.ai-rulez/context/`, `.ai-rulez/skills/`, and `.ai-rulez/agents/`:
-
-```markdown
----
-priority: high
----
-
-# Code Quality Standards
+# Optional: team-specific profiles
+profiles:
+  backend: [backend, database]
+  frontend: [frontend, ui]
 
-- Use descriptive variable names
-- Add comments for complex logic
-- Write unit tests for new functions
+# Optional: share rules across repos
+includes:
+  - name: company-standards
+    source: https://github.com/company/ai-rules.git
+    ref: main
 ```
 
-<details>
-<summary>Content Types Explained</summary>
-
-**Rules** (`.ai-rulez/rules/`)
-
-Strict guidelines that AI assistants must follow. These are prescriptive and enforce behavior.
+## Content Structure
 
+**Rules** - What AI must do:
 ```markdown
 ---
 priority: critical
 ---
-
 # Security Standards
-
-Never commit credentials or API keys to the repository.
-Use environment variables for all secrets.
-```
-
-**Context** (`.ai-rulez/context/`)
-
-Background information about your project that helps AI understand your codebase.
-
-```markdown
----
-priority: medium
----
-
-# Project Architecture
-
-This project uses microservices architecture:
-- API Gateway (port 8080)
-- Auth Service (port 8081)
-- Database: PostgreSQL 15
+- Never commit credentials
+- Use environment variables for secrets
+- Sanitize all user input
 ```
 
-**Skills** (`.ai-rulez/skills/`)
-
-Specialized AI agent configurations for specific tasks. Each skill creates a focused agent with access to all project rules and context.
-
+**Context** - What AI should know:
 ```markdown
 ---
-name: database-expert
-description: PostgreSQL optimization specialist
 priority: high
 ---
-
-# Database Expert
-
-You are an expert in PostgreSQL optimization and query design.
-Focus on performance, indexing strategies, and query optimization.
+# Architecture
+This is a microservices app:
+- API Gateway (Go, port 8080)
+- Auth Service (Go, port 8081)
+- PostgreSQL 15
 ```
 
-**Agents** (`.ai-rulez/agents/`)
-
-Agent prompt files used by tools that support agent-specific instructions.
-
+**Commands** - Slash commands across tools:
 ```markdown
 ---
-priority: high
+name: review
+aliases: [r, pr-review]
+targets: [claude, cursor, continue-dev]
 ---
-
-# Code Reviewer Agent
-
-Review pull requests with a focus on correctness and maintainability.
+# Code Review
+Review the current PR for:
+1. Logic errors
+2. Security issues
+3. Performance problems
 ```
 
-</details>
-
-### 4. Generate Tool Configurations
+## Installation
 
+**No install required:**
 ```bash
-ai-rulez generate
-```
-
-This creates native configuration files for each preset you specified.
-
-<details>
-<summary>What Gets Generated - Detailed Output Structure</summary>
-
-### Claude Preset
-
-Generates a structured directory with skills and agents:
-
-```
-.claude/
-├── skills/
-│   └── {skill-id}/
-│       └── SKILL.md      # Skill with embedded rules and context
-└── agents/
-    └── {skill-id}.md     # Agent file (backward compatibility)
-```
-
-Each skill file contains:
-- Skill-specific instructions
-- All project rules
-- All project context
-
-### Cursor Preset
-
-Generates individual rule files:
-
-```
-.cursor/
-└── rules/
-    ├── code-quality.mdc
-    ├── security.mdc
-    └── architecture.mdc
-```
-
-Each rule is a separate `.mdc` file with priority and content.
-
-### Windsurf Preset
-
-Generates individual rule files:
-
-```
-.windsurf/
-├── code-quality.md
-├── security.md
-└── architecture.md
-```
-
-Each rule is a separate markdown file.
-
-### Copilot Preset
-
-Generates a single consolidated file:
-
-```
-.github/
-└── copilot-instructions.md
+npx ai-rulez@latest <command>
+# or
+uvx ai-rulez <command>
 ```
 
-Contains all rules, context, and skills in one file organized by sections.
+**Global install:**
+```bash
+# Homebrew
+brew install goldziher/tap/ai-rulez
 
-### Gemini Preset
+# npm
+npm install -g ai-rulez
 
-Generates configuration in Gemini's expected format:
+# pip
+pip install ai-rulez
 
+# Go
+go install github.com/Goldziher/ai-rulez/cmd@latest
 ```
-.gemini/
-└── config.yaml
-```
-
-### MCP Preset (Auto-generated)
 
-When you configure MCP servers in `.ai-rulez/mcp.yaml`, an MCP configuration is automatically generated for tools that support Model Context Protocol.
-
-</details>
-
-## Features
-
-### Multi-Tool Support
-Generate native configuration files for all major AI coding assistants from a single source of truth.
-
-### Domain-Based Organization
-Separate rules and context by domain (backend, frontend, QA, etc.) to keep large codebases organized.
-
-<details>
-<summary>Using Domains</summary>
-
-Create domain-specific organization:
+## CLI Reference
 
 ```bash
-# Create domains during init
+# Initialize project
+ai-rulez init "Project Name"
 ai-rulez init --domains backend,frontend,qa
 
-# Or add domains later
-ai-rulez add domain backend
-```
-
-Directory structure:
-
-```
-.ai-rulez/domains/
-├── backend/
-│   ├── rules/
-│   ├── context/
-│   └── skills/
-└── frontend/
-    ├── rules/
-    ├── context/
-    └── skills/
-```
-
-Configure in `config.yaml`:
-
-```yaml
-profiles:
-  backend: [backend, database]
-  frontend: [frontend, ui]
-  full: [backend, frontend, database, ui]
-
-default: full
-```
-
-Generate for specific domain:
-
-```bash
+# Generate configs
+ai-rulez generate
 ai-rulez generate --profile backend
-```
-
-</details>
-
-### Profiles
-Define multiple profiles for different teams or use cases. Generate only the rules relevant to each context.
+ai-rulez generate --dry-run
 
-<details>
-<summary>Profile Configuration</summary>
-
-```yaml
-version: "3.0"
-name: "My Project"
-
-presets:
-  - claude
-  - cursor
+# Content management
+ai-rulez add rule security-standards --priority critical
+ai-rulez add context api-docs
+ai-rulez add skill database-expert
+ai-rulez add command review-pr
 
-profiles:
-  backend: [backend, database]
-  frontend: [frontend, ui]
-  full: [backend, frontend, database, ui]
+ai-rulez list rules
+ai-rulez remove rule outdated-rule
 
-default: full
-```
+# Validation
+ai-rulez validate
 
-Generate specific profile:
+# MCP server (for AI assistants)
+npx ai-rulez@latest mcp
 
-```bash
-ai-rulez generate --profile backend
+# Migrate from V2
+ai-rulez migrate v3
 ```
 
-</details>
-
-### Priority System
-Mark rules and context with priority levels (critical, high, medium, low) to control their importance and ordering.
-
-### Includes
-Compose configurations from multiple sources including local paths, Git repositories, and shared rule packages.
-
-<details>
-<summary>Using Includes</summary>
+## Remote Includes
 
-Reference external rule sources:
+Share rules across repositories:
 
 ```yaml
 includes:
-  # Git repository via HTTPS
+  # HTTPS
   - name: company-standards
     source: https://github.com/company/ai-rules.git
     ref: main
-    include:
-      - rules
-      - context
-      - skills
-      - agents
+    include: [rules, context]
     merge_strategy: local-override
 
-  # Git repository via SSH
+  # SSH
   - name: shared-configs
-    source: git@github.com:organization/shared-ai-rulez.git
-    ref: main
-    include:
-      - rules
-      - context
-    merge_strategy: local-override
+    source: git@github.com:org/shared-ai-rulez.git
+    ref: v2.0.0
+    include: [rules, skills]
 
-  # Local relative path
+  # Local path
   - name: local-standards
     source: ../shared-rules
-    include:
-      - rules
-      - skills
-    merge_strategy: local-override
-```
-
-**Supported Git URL formats:**
-- HTTPS: `https://github.com/owner/repo.git`
-- SSH: `git@github.com:owner/repo.git`
-- SSH protocol: `ssh://git@github.com/owner/repo.git`
-
-**Include options:**
-- `include`: List of content types to fetch (`rules`, `context`, `skills`, `agents`)
-- `merge_strategy`: How to handle conflicts (`local-override`, `remote-override`)
-- `ref`: Branch, tag, or commit SHA
-
-**Authenticating to Private Repositories:**
-
-When including rules from private Git repositories, you can provide an access token for authentication:
-
-```bash
-# Using environment variable (recommended for CI/CD)
-export AI_RULEZ_GIT_TOKEN="ghp_your_github_token_here"
-ai-rulez generate
-
-# Using CLI flag
-ai-rulez generate --token "ghp_your_github_token_here"
+    include: [rules]
 ```
 
-How to create access tokens:
+Private repos use `AI_RULEZ_GIT_TOKEN` environment variable or `--token` flag.
 
-- **GitHub**: Settings → Developer settings → Personal access tokens → Generate new token (classic)
-  - Required scope: `repo` (for private repositories)
-- **GitLab**: Settings → Access Tokens → Add new token
-  - Required scope: `read_repository`
+## Generated Output
 
-**Security best practices:**
-- Never commit tokens to your repository
-- Use environment variables in CI/CD pipelines
-- Store tokens in secure secret management systems
-- Rotate tokens regularly
-- Use tokens with minimal required permissions
+Running `ai-rulez generate` creates:
 
-See the [Includes documentation](https://goldziher.github.io/ai-rulez/includes/) for more details.
+| Preset | Output |
+|--------|--------|
+| Claude | `CLAUDE.md` + `.claude/skills/` + `.claude/agents/` |
+| Cursor | `.cursor/rules/*.mdc` |
+| Windsurf | `.windsurf/*.md` |
+| Copilot | `.github/copilot-instructions.md` |
+| Gemini | `.gemini/config.yaml` |
+| Continue.dev | `.continue/prompts/ai_rulez_prompts.yaml` |
+| Cline | `.cline/rules/*.md` |
+| Custom | Any path with markdown, JSON, or directory output |
 
-</details>
-
-### MCP Server Integration
-Configure Model Context Protocol servers that extend AI assistant capabilities with external tools and data sources.
-
-<details>
-<summary>MCP Configuration</summary>
-
-Configure MCP servers in `.ai-rulez/mcp.yaml`:
-
-```yaml
-version: "3.0"
-
-mcp_servers:
-  - name: ai-rulez
-    description: AI-Rulez MCP server for configuration management
-    command: npx
-    args:
-      - "-y"
-      - "ai-rulez@latest"
-      - "mcp"
-    transport: stdio
-    enabled: true
-
-  - name: github
-    description: GitHub integration
-    command: npx
-    args:
-      - "-y"
-      - "@modelcontextprotocol/server-github"
-    env:
-      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
-    transport: stdio
-    enabled: true
-```
-
-MCP servers can also be domain-specific. See the [MCP documentation](https://goldziher.github.io/ai-rulez/mcp-server/) for details.
-
-</details>
-
-### Import from Existing Tools
-Migrate from existing tool-specific configurations.
-
-<details>
-<summary>Import Options</summary>
-
-```bash
-# Auto-detect existing configs
-ai-rulez init --from auto
-
-# Import specific files
-ai-rulez init --from .cursorrules,CLAUDE.md
-
-# Import from multiple sources
-ai-rulez init --from .cursorrules,.windsurfrules
-```
-
-</details>
-
-### Monorepo Support
-Generate configurations recursively for multiple projects.
-
-<details>
-<summary>Recursive Generation</summary>
+## Use Cases
 
+**Monorepo**: Generate configs for multiple packages
 ```bash
 ai-rulez generate --recursive
 ```
 
-This finds all `.ai-rulez/` directories in your repository and generates configurations for each.
-
-</details>
-
-### Git Hook Integration
-Automatically validate your AI rules configuration on commit.
-
-<details>
-<summary>Git Hooks Setup</summary>
-
+**Team profiles**: Different rules for different teams
 ```bash
-ai-rulez init --setup-hooks
-```
-
-Supports:
-- lefthook
-- pre-commit
-- husky
-
-Automatically detects your git hook manager and configures validation.
-
-</details>
-
-### CLI Management
-Full CRUD operations for managing your configuration programmatically.
-
-<details>
-<summary>CLI Commands Reference</summary>
-
-**Add Content:**
-```bash
-ai-rulez add rule security-standards --priority critical
-ai-rulez add context api-endpoints
-ai-rulez add skill test-engineer
-ai-rulez add domain backend
-```
-
-**List Content:**
-```bash
-ai-rulez list rules
-ai-rulez list context
-ai-rulez list skills
-ai-rulez list domains
-```
-
-**Remove Content:**
-```bash
-ai-rulez remove rule outdated-rule
-ai-rulez remove domain legacy
-```
-
-**Validation:**
-```bash
-ai-rulez validate
-```
-
-**MCP Server:**
-```bash
-npx ai-rulez@latest mcp
-# or
-uvx ai-rulez mcp
-```
-
-Configure in your AI assistant's MCP settings to enable direct management of your AI rules.
-
-</details>
-
-### Migration from V2
-Migrate from older ai-rulez V2 configurations to the new V3 directory-based structure.
-
-<details>
-<summary>Migration Guide</summary>
-
-```bash
-# Auto-detect V2 config and migrate
-ai-rulez migrate v3
-
-# Specify config file
-ai-rulez migrate v3 ai-rulez.yaml
-
-# Preview migration without writing files
-ai-rulez migrate v3 --dry-run
-
-# Force migration if .ai-rulez exists (creates backup)
-ai-rulez migrate v3 --force
+ai-rulez generate --profile backend
+ai-rulez generate --profile frontend
 ```
 
-The migrate command:
-- Converts your V2 `ai-rulez.yaml` to the new `.ai-rulez/` directory structure
-- Preserves all rules, context, and configuration
-- Creates timestamped backups when using `--force`
-- Validates the migration automatically
-
-</details>
-
-## Example Workflows
-
-<details>
-<summary>Start a New Project</summary>
-
+**CI validation**: Ensure configs stay in sync
 ```bash
-# Initialize with domains
-ai-rulez init "My API" --domains backend,frontend,qa
-
-# Edit .ai-rulez/config.yaml and add your presets
-# Add project-specific rules
-ai-rulez add rule api-standards --priority high
-
-# Generate configs for all tools
-ai-rulez generate
+ai-rulez validate && ai-rulez generate --dry-run
 ```
 
-</details>
-
-<details>
-<summary>Migrate from Existing Configs</summary>
-
+**Import existing configs**: Migrate from tool-specific files
 ```bash
-# Import your existing configs
 ai-rulez init --from auto
-
-# Review the imported content
-ls .ai-rulez/rules/
-
-# Add more presets to config.yaml
-# Then regenerate
-ai-rulez generate
+ai-rulez init --from .cursorrules,CLAUDE.md
 ```
 
-</details>
+## MCP Server
 
-<details>
-<summary>Team-Specific Profiles</summary>
+Let AI assistants manage rules directly:
 
-```bash
-# Set up profiles in .ai-rulez/config.yaml
-# profiles:
-#   backend: [backend, database]
-#   frontend: [frontend, ui]
-
-# Backend team generates their config
-ai-rulez generate --profile backend
-
-# Frontend team generates their config
-ai-rulez generate --profile frontend
+```yaml
+# .ai-rulez/mcp.yaml
+version: "3.0"
+mcp_servers:
+  - name: ai-rulez
+    command: npx
+    args: ["-y", "ai-rulez@latest", "mcp"]
+    transport: stdio
+    enabled: true
 ```
 
-</details>
-
-<details>
-<summary>Monorepo with Multiple Projects</summary>
+The MCP server exposes CRUD operations, validation, and generation to AI assistants.
 
-```bash
-# Initialize in each project subdirectory
-cd packages/api
-ai-rulez init "API Service" --domains backend
+## Compression
 
-cd ../web
-ai-rulez init "Web App" --domains frontend
+Reduce context size for token-constrained tools:
 
-# Generate all at once from root
-cd ../..
-ai-rulez generate --recursive
+```yaml
+compression:
+  level: standard  # none, minimal, standard, aggressive
 ```
 
-</details>
+At `standard` level, output is ~34% smaller through whitespace optimization and duplicate removal.
 
 ## Documentation
 
-Full documentation is available at https://goldziher.github.io/ai-rulez/
-
-Key topics:
 - [Configuration Reference](https://goldziher.github.io/ai-rulez/configuration/)
-- [Domain Organization](https://goldziher.github.io/ai-rulez/domains/)
-- [Profile Management](https://goldziher.github.io/ai-rulez/profiles/)
-- [MCP Server Setup](https://goldziher.github.io/ai-rulez/mcp-server/)
-- [Includes and Composition](https://goldziher.github.io/ai-rulez/includes/)
-- [Monorepo Usage](https://goldziher.github.io/ai-rulez/monorepo/)
+- [Domains & Profiles](https://goldziher.github.io/ai-rulez/domains/)
+- [Remote Includes](https://goldziher.github.io/ai-rulez/includes/)
+- [MCP Server](https://goldziher.github.io/ai-rulez/mcp-server/)
 - [Schema Validation](https://goldziher.github.io/ai-rulez/schema/)
+- [Migration Guide](https://goldziher.github.io/ai-rulez/migration/)
 
 ## Contributing
 
-Contributions are welcome. See [CONTRIBUTING.md](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md) for development setup and guidelines.
+Contributions welcome. See [CONTRIBUTING.md](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-rulez",
-  "version": "3.4.1",
+  "version": "3.6.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",