ai-rulez 1.6.1 → 2.0.1

package/README.md

@@ -1,261 +1,166 @@
 # ai-rulez ⚡
 
-> **Lightning-fast CLI tool (written in Go) for managing AI assistant rules**
+<p align="center">
+  <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>
 
-Generate configuration files for Claude, Cursor, Windsurf, and other AI assistants from a single, centralized configuration.
+**One config to rule them all.**
 
-## 🚀 Features
+Tired of manually managing rule files, subagents, and custom commands across different AI tools? `ai-rulez` gives you one `ai-rulez.yml` file to generate them all. Keep your AI context in sync, and even launch MCP servers for direct integration.
 
-- ⚡ **Blazing Fast**: Written in Go for maximum performance
-- 🔧 **Multi-Assistant Support**: Generate configs for Claude (CLAUDE.md), Cursor (.cursorrules), Windsurf (.windsurfrules), and more
-- 📝 **Single Source of Truth**: Maintain all your AI rules in one YAML configuration
-- 🎯 **Smart Templates**: Built-in templates with custom template support
-- 🔍 **Validation**: Comprehensive configuration validation
-- 🔄 **Git Integration**: Perfect for pre-commit hooks and CI/CD
-- 📦 **Node.js Integration**: Easy installation via npm
+[![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)
+[![PyPI Version](https://img.shields.io/pypi/v/ai-rulez)](https://pypi.org/project/ai-rulez/)
+[![Homebrew](https://img.shields.io/badge/Homebrew-tap-orange)](https://github.com/Goldziher/homebrew-tap)
 
-## 📦 Installation
+### 📖 **[Read the Full Documentation](https://goldziher.github.io/ai-rulez/)**
 
-### npm (Recommended)
+---
 
-```bash
-# Global installation
-npm install -g ai-rulez
+## Feature Highlights
 
-# Local project installation
-npm install --save-dev ai-rulez
-```
+`ai-rulez` is a progressive tool-box, designed to offer a centralized way to manage AI tooling for a repository.
+
+### Centralized Configuration
+- **Centralized Definitions:** Use a single `ai-rulez.yml` as the source of truth to define rules, file structures, and documentation for all your AI tools.
+- **Nested Configs & Monorepo Support:** Scale your configurations with `extends` and `includes`. Manage complex projects and monorepos with ease by using the `--recursive` flag to combine configurations from multiple files.
+  ```bash
+  # Generate rules for all projects in a monorepo
+  ai-rulez generate --recursive
+  ```
 
-The npm package automatically downloads and manages the Go binary for your platform.
+### Powerful Tooling
+- **Custom Commands:** Define custom commands that your AI assistant can execute, enabling powerful, interactive workflows.
+- **Specialized AI Agents:** Create specialized "sub-agents" with their own system prompts and tools, perfect for complex tasks like code reviews or database queries.
+- **MCP Servers:** Launch a Model Context Protocol (MCP) server to allow AI assistants to programmatically interact with your configuration.
+- **Full-Featured CLI:** Manage your entire configuration from the command line. Add rules, update agents, and generate files without ever opening a YAML file.
 
-### Other Installation Methods
+### Flexible Integrations
+- **Multi-Tool Support:** Use presets to instantly generate configurations for popular AI tools like Claude, Cursor, Copilot, Gemini, and more.
+- **Custom Tool Integration:** Don't see your favorite tool on the list? Use the `outputs` key to generate a configuration file for any tool, in any format.
 
-- **pip**: `pip install ai-rulez`
-- **Go**: `go install github.com/Goldziher/ai-rulez@latest`
-- **Homebrew**: `brew install goldziher/tap/ai-rulez` *(coming soon)*
-- **Direct Download**: Download from [GitHub Releases](https://github.com/Goldziher/ai-rulez/releases)
+## How It Works
 
-## 🎯 Quick Start
+`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.
 
-1. **Create a configuration file** (`ai-rulez.yaml`):
+## Example: `ai-rulez.yml`
 
 ```yaml
+$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
+
 metadata:
-  name: "My AI Rules"
-  version: "1.0.0"
+  name: "My SaaS Platform"
+  version: "2.0.0"
+
+# Use presets for common configurations
+presets:
+  - "popular"  # Includes Claude, Cursor, Windsurf, and Copilot
 
 rules:
-  - name: "Code Style"
-    priority: 10
-    content: |
-      - Use TypeScript strict mode
-      - Prefer functional components
-      - Use meaningful variable names
+  - name: "Go Code Standards"
+    priority: high
+    content: "Follow standard Go project layout (cmd/, internal/, pkg/). Use meaningful package names and export only what is necessary."
 
-  - name: "Testing"
-    priority: 5
+sections:
+  - name: "Project Structure"
+    priority: critical
     content: |
-      - Write unit tests for all functions
-      - Use describe/it pattern
-      - Aim for 80% code coverage
-
-outputs:
-  - file: "CLAUDE.md"
-    template: "claude"
-  - file: ".cursorrules"
-    template: "cursor"
-  - file: ".windsurfrules" 
-    template: "windsurf"
+      - `cmd/`: Main application entry point
+      - `internal/`: Private application code (business logic, data access)
+      - `pkg/`: Public-facing libraries
+
+agents:
+  - name: "go-developer"
+    description: "Go language expert for core development"
+    system_prompt: "You are an expert Go developer. Your key responsibilities include writing idiomatic Go, using proper error handling, and creating comprehensive tests."
 ```
 
-2. **Generate configuration files**:
+Run `ai-rulez generate` → get all your configuration files, perfectly synchronized.
 
-```bash
-ai-rulez generate
-```
-
-This creates `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` with your rules properly formatted for each AI assistant.
-
-## 🛠️ Commands
+## Quick Start
 
 ```bash
-# Generate all configuration files
-ai-rulez generate
-
-# Validate configuration
-ai-rulez validate
+# 1. Initialize your project with a preset (recommended)
+ai-rulez init "My Project" --preset popular
 
-# Generate recursively in subdirectories
-ai-rulez generate --recursive
+# 2. Add your project-specific context
+ai-rulez add rule "Tech Stack" --priority critical --content "This project uses Go and PostgreSQL."
 
-# Preview output without writing files
-ai-rulez generate --dry-run
-
-# Show help
-ai-rulez --help
+# 3. Generate all AI instruction files
+ai-rulez generate
 ```
 
-## 🔄 Git Integration
+## Installation
 
-### Pre-commit Hook
+### Run without installing
 
-Add to your `.pre-commit-config.yaml`:
+For one-off executions, you can run `ai-rulez` directly without a system-wide installation.
 
-```yaml
-repos:
-  - repo: https://github.com/Goldziher/ai-rulez
-    rev: v1.0.0
-    hooks:
-      - id: ai-rulez-generate
+**Go**
+```bash
+go run github.com/Goldziher/ai-rulez/cmd@latest --help
 ```
 
-### Lefthook
-
-Add to your `lefthook.yml`:
-
-```yaml
-pre-commit:
-  commands:
-    ai-rulez:
-      run: ai-rulez generate
-      files: git diff --cached --name-only
-      glob: "*.{ai-rulez,ai_rulez}.{yml,yaml}"
+**Node.js (via npx)**
+```bash
+# Installs and runs the latest version
+npx ai-rulez@latest init
 ```
 
-### npm Scripts
-
-Add to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "ai-rulez": "ai-rulez generate",
-    "ai-rulez:validate": "ai-rulez validate",
-    "ai-rulez:watch": "ai-rulez generate --recursive"
-  }
-}
+**Python (via uvx)**
+```bash
+# Runs ai-rulez in a temporary virtual environment
+uvx ai-rulez init
 ```
 
-## 📚 Configuration
-
-The tool looks for configuration files in this order:
-- `.ai-rulez.yaml`
-- `ai-rulez.yaml` 
-- `.ai_rulez.yaml`
-- `ai_rulez.yaml`
-
-### User Rules vs. Coding Rules
-
-When creating AI rules, distinguish between two types of instructions:
+### Install globally
 
-- **Coding Rules**: Technical guidelines about code quality, architecture, testing, etc.
-  - Examples: "Use TypeScript strict mode", "Write unit tests", "Follow REST conventions"
-  - Should be in the main configuration file committed to version control
+For frequent use, a global installation is recommended.
 
-- **User Rules**: Personal preferences about communication style and interaction
-  - Examples: "Be concise in responses", "Use casual tone", "Address me as 'Chief'", "Always explain your reasoning"
-  - Perfect for `.local.yaml` files (e.g., `ai-rulez.local.yaml`) as they're personal and shouldn't affect the whole team
-  - Allow individual developers to customize AI behavior without impacting others
-
-**Example local config** (`ai-rulez.local.yaml`):
-```yaml
-rules:
-  - name: "Communication Style"
-    content: "Be concise and direct. Address me as 'Boss'. Always ask for clarification before making assumptions."
-  - name: "Response Format"
-    content: "Provide code examples for every suggestion. Use bullet points for lists."
+**Go**
+```bash
+go install github.com/Goldziher/ai-rulez/cmd@latest
 ```
 
-### Configuration Schema
-
-```yaml
-metadata:
-  name: string          # Required: Project name
-  version: string       # Required: Version
-  description: string   # Optional: Description
-
-rules:
-  - name: string        # Required: Rule name
-    priority: number    # Required: Priority (1-10)
-    content: string     # Required: Rule content
-
-sections:              # Optional: Organize rules into sections
-  - title: string      # Required: Section title
-    priority: number   # Required: Section priority
-    content: string    # Required: Section content
-
-outputs:               # Required: At least one output
-  - file: string       # Required: Output filename
-    template: string   # Required: Template name or path
-
-includes:              # Optional: Include other config files
-  - path/to/other.yaml
+**Homebrew (macOS/Linux)**
+```bash
+brew install goldziher/tap/ai-rulez
 ```
 
-## 🎨 Templates
-
-Built-in templates:
-- `claude` - CLAUDE.md format
-- `cursor` - .cursorrules format  
-- `windsurf` - .windsurfrules format
-- `default` - Generic format
-
-Custom templates use Go template syntax with access to `.Rules`, `.Sections`, `.Metadata`, etc.
-
-## 🔧 Advanced Usage
-
-### Environment Variables
-
-- `AI_RULEZ_CONFIG` - Override config file path
-- `AI_RULEZ_DEBUG` - Enable debug output
-
-### Node.js API
-
-```javascript
-const { execSync } = require('child_process');
-
-// Run ai-rulez programmatically
-try {
-  const output = execSync('ai-rulez generate --dry-run', { encoding: 'utf8' });
-  console.log(output);
-} catch (error) {
-  console.error('ai-rulez failed:', error.message);
-}
+**npm**
+```bash
+npm install -g ai-rulez
 ```
 
-### npm Scripts Integration
-
-```json
-{
-  "scripts": {
-    "precommit": "ai-rulez generate",
-    "lint": "eslint . && ai-rulez validate",
-    "build": "npm run ai-rulez && npm run compile"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "ai-rulez generate"
-    }
-  }
-}
+**pip**
+```bash
+pip install ai-rulez
 ```
 
-## 🤝 Contributing
+## Pre-commit Hooks
+
+You can use `ai-rulez` with `pre-commit` to automatically validate and generate your AI configuration files.
 
-Contributions are welcome! Please see our [Contributing Guide](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md).
+Add the following to your `.pre-commit-config.yaml`:
 
-## 📄 License
+```yaml
+repos:
+  - repo: https://github.com/Goldziher/ai-rulez
+    rev: v2.0.0
+    hooks:
+      - id: ai-rulez-validate
+      - id: ai-rulez-generate
+```
 
-MIT License - see [LICENSE](https://github.com/Goldziher/ai-rulez/blob/main/LICENSE)
+---
 
-## 🔗 Links
+## Documentation
 
-- [GitHub Repository](https://github.com/Goldziher/ai-rulez)
-- [Documentation](https://github.com/Goldziher/ai-rulez#readme)
-- [Issues](https://github.com/Goldziher/ai-rulez/issues)
-- [Releases](https://github.com/Goldziher/ai-rulez/releases)
-- [PyPI Package](https://pypi.org/project/ai-rulez/)
+- **[Quick Start Guide](https://goldziher.github.io/ai-rulez/quick-start/)**
+- **[Full CLI Reference](https://goldziher.github.io/ai-rulez/cli/)**
+- **[Configuration Guide](https://goldziher.github.io/ai-rulez/configuration/)**
+- **[Migration Guide](https://goldziher.github.io/ai-rulez/migration-guide/)** - Upgrading from v1.x to v2.0
 
----
+## Contributing
 
-**Note**: This npm package is a wrapper around the Go binary. The actual tool is written in Go for maximum performance and cross-platform compatibility.
+Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) to get started.

package/bin/ai-rulez.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+const { getPlatform, getBinaryName } = require("../install");
+
+const binaryName = getBinaryName(getPlatform().os);
+const binaryPath = path.join(__dirname, "..", "bin", binaryName);
+
+function runBinary(args) {
+	const child = spawn(binaryPath, args, {
+		stdio: "inherit",
+	});
+
+	child.on("close", (code) => {
+		process.exit(code);
+	});
+}
+
+async function main() {
+	if (fs.existsSync(binaryPath)) {
+		runBinary(process.argv.slice(2));
+	} else {
+		console.log(
+			"🚀 First run detected - downloading ai-rulez binary...\n   This will only happen once and takes a few seconds.\n",
+		);
+		const { install } = require("../install");
+		try {
+			await install(true); // Pass a flag to indicate this is a post-install step
+			runBinary(process.argv.slice(2));
+		} catch (error) {
+			console.error("Failed to install or run ai-rulez:", error);
+			process.exit(1);
+		}
+	}
+}
+
+main();