# ai-rulez.yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v1.schema.json

metadata:
  name: "My Project"
  version: "1.0.0"
  description: "AI assistant configuration for my project"

# Define reusable target groups (optional)
targets:
  claude-files:
    - "CLAUDE.md"
    - ".claude/**/*.md"
  
  cursor-files:
    - ".cursor/**/*.mdc"
    - ".cursorrules"
  
  docs:
    - "docs/*.md"
    - "*.md"

# Include shared configurations (remote or local)
includes:
  # Organization standards from GitHub
  - "https://raw.githubusercontent.com/myorg/standards/main/backend.yaml"
  # Team-specific rules
  - "./team-rules.yaml"
  # Personal preferences (not committed to git)
  - "./ai-rulez.local.yaml"

# Output configurations - where to generate files
outputs:
  # Claude - single markdown file
  - path: "CLAUDE.md"
    template: "default"  # Built-in template
  
  # Cursor - new directory format with .mdc files
  - path: ".cursor/rules/"
    type: "rule"
    naming_scheme: "rules.mdc"  # All rules in one file named rules.mdc
  
  # Windsurf
  - path: ".windsurfrules"
  
  # Generate individual agent files for Claude
  - path: ".claude/agents/"
    type: "agent"
    naming_scheme: "{name}.md"  # One file per agent
  
  # Custom output with inline template
  - file: "CONTRIBUTING.md"
    template: |
      # Contributing to {{.ProjectName}}
      
      ## Priority Guidelines (8+ priority)
      {{range .Rules}}{{if ge .Priority 8}}
      ### {{.Name}}
      {{.Content}}
      {{end}}{{end}}

# Define specialized AI agents (sub-agents for Claude)
agents:
  - name: "code-reviewer"
    id: "reviewer-001"  # Optional: for precise matching in overrides
    description: "Reviews code for quality and security"
    priority: 10  # Higher priority agents appear first
    targets: ["@claude-files"]  # Only for Claude using named target
    tools:  # Tools the agent can use
      - "read_file"
      - "search"
      - "grep"
    system_prompt: |
      You are a senior code reviewer focusing on:
      - Code quality and maintainability
      - Security vulnerabilities
      - Performance implications
      - Best practices
      
      Always provide constructive feedback with specific suggestions.

  - name: "test-writer"
    id: "tester-001"
    description: "Writes comprehensive tests"
    priority: 8
    targets: ["@claude-files"]  # Only for Claude
    tools:
      - "read_file"
      - "write_file"
      - "run_command"
    system_prompt: |
      You are a test automation expert. Write tests that:
      - Cover edge cases
      - Are readable and maintainable
      - Follow testing best practices
      - Achieve high code coverage

# Rules - your coding standards and guidelines
rules:
  - name: "Code Quality"
    id: "quality-001"  # Optional: for precise matching
    priority: 10  # 1-10, higher = more important
    # No targets = applies to all outputs (default behavior)
    content: |
      - Write clean, readable, and maintainable code
      - Follow SOLID principles
      - Keep functions small and focused
      - Use meaningful variable names
  
  - name: "Claude-Specific Instructions"
    priority: 9
    targets: ["CLAUDE.md"]  # Only for Claude (inline target)
    content: |
      - Use Claude's Task tool for specialized operations
      - Leverage MCP tools when available
      - Follow structured reasoning approach
  
  - name: "Cursor-Specific Instructions"
    priority: 9
    targets: ["@cursor-files"]  # Only for Cursor (named target)
    content: |
      - Use Cursor's AI features for code generation
      - Leverage Cursor's context awareness
      - Follow Cursor's best practices
  
  - name: "Testing Standards"
    id: "testing-001"
    priority: 9
    targets: ["@docs", "*.md"]  # Mix named and inline targets
    content: |
      - Write unit tests for all new features
      - Maintain minimum 80% code coverage
      - Use TDD when appropriate
      - Test edge cases and error conditions
  
  - name: "Documentation"
    priority: 7
    content: |
      - Document all public APIs
      - Include usage examples
      - Keep README up to date
      - Use clear commit messages

# Sections - informational content that appears before rules
sections:
  - title: "Project Overview"
    priority: 100  # Sections typically have higher priority to appear first
    content: |
      ## Architecture
      
      This project follows a microservices architecture with:
      - Frontend: React + TypeScript
      - Backend: Node.js + Express
      - Database: PostgreSQL
      
      ## Development Workflow
      
      1. Create feature branch from main
      2. Write tests first (TDD)
      3. Implement feature
      4. Run linters and tests
      5. Create PR for review

  - title: "Agent Usage Instructions"
    priority: 95
    content: |
      ## Using AI Agents
      
      This project includes specialized agents in `.claude/agents/`:
      - **code-reviewer**: For code reviews and quality checks
      - **test-writer**: For generating test cases
      
      Use these agents by referencing their specific prompts for domain tasks.

# User-specific overrides (highest priority)
userRulez:
  - name: "Personal Preferences"
    content: |
      - Use 2 spaces for indentation (not 4)
      - Prefer const over let
      - Always use semicolons in JavaScript
  
  # Override an existing rule by ID
  - id: "testing-001"
    content: |
      - Write unit tests for all new features
      - Maintain minimum 90% code coverage (personal goal)
      - Use TDD always (not just when appropriate)
      - Test edge cases and error conditions

rules:
  - name: "Claude-Only Rule"
    targets: ["CLAUDE.md"]  # Only appears in CLAUDE.md
    content: "This rule only applies to Claude"
  
  - name: "Markdown Files"
    targets: ["*.md"]  # Appears in all .md files
    content: "This rule applies to all markdown files"
  
  - name: "Universal Rule"
    # No targets = appears in all outputs (default)
    content: "This rule applies everywhere"

# Define named target groups
targets:
  claude-files:
    - "CLAUDE.md"
    - ".claude/**/*.md"
  
  docs:
    - "docs/*.md"
    - "README.md"

# Reference named targets
rules:
  - name: "Claude-Specific"
    targets: ["@claude-files"]  # Uses named target
    content: "Only for Claude files"
  
  - name: "Mixed Targets"
    targets: ["@docs", "*.txt"]  # Mix named and inline
    content: "Appears in docs and text files"

agents:
  - name: "code-reviewer"
    targets: ["@claude-files"]  # Agent only for Claude
    description: "Reviews code quality"

includes:
  # Public GitHub configurations
  - "https://raw.githubusercontent.com/myorg/standards/main/backend.yaml"
  
  # Private API endpoints
  - "https://api.company.com/ai-rules/security.yaml"
  
  # Local overrides
  - "./team-rules.yaml"
  - "./ai-rulez.local.yaml"  # Personal preferences (gitignored)

outputs:
  # Agents with custom naming
  - path: ".claude/agents/"
    type: "agent"
    naming_scheme: "{priority:02d}-{name}.md"
  
  # Rules organized by priority
  - path: "docs/rules/"
    type: "rule"
    naming_scheme: "rule-{index:03d}-{name}.md"

outputs:
  # External template file
  - file: "docs/handbook.md"
    template: "@templates/handbook.tmpl"

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v1.6.0
    hooks:
      - id: ai-rulez-validate    # Validate configuration
      - id: ai-rulez-generate    # Auto-generate files

# lefthook.yml
pre-commit:
  commands:
    ai-rulez:
      run: npx -y ai-rulez@latest generate