☕ Support This Work

Found value in these resources?

👉 Buy me a coffee: https://www.buymeacoffee.com/ubuntupunk

If you find value in this project, please consider buying me a coffee to support my work.

That will help me maintain and improve the resources available for free

Agent Rules Generator

An interactive CLI tool to generate .agent.md, .windsurfrules, and modern .cursor/rules/ (MDC) files for AI-assisted development with Cursor AI, Windsurf, and Gemini CLI.

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features or improvements
• 📝 Improve documentation (README, guides, examples)
• 🧪 Add tests for new functionality
• 🔧 Submit pull requests with bug fixes or features
• 🍳 Create new recipes for different tech stacks
• 📋 Add project types for better inclusivity

Quick Start for Contributors:

git clone https://github.com/ubuntupunk/agent-rules-generator.git
cd agent-rules-generator
bun install
bun test  # Ensure all tests pass

See our Testing Guide and Deployment Guide for detailed contribution guidelines.

🚀 Features

• 🆕 Modern Cursor MDC Support: Generate modular .cursor/rules/*.mdc files for enhanced AI performance
• Interactive CLI: Guided setup process for creating AI assistant configuration files
• Multiple AI Platforms: Support for Cursor AI (.agent.md + .cursor/rules/), Windsurf (.windsurfrules), and Gemini CLI configuration
• Modular Rule Generation: Choose from 5 specialized rule modules (coding, architecture, testing, deployment, security)
• Path-Scoped Rules: Context-aware rules that apply to specific file patterns and directories
• Project Type Inclusivity: Supports 6 project types with tailored question flows
• Recipe System: Pre-built templates for common project types and technology stacks
• Conditional Tech Stack: Only asks relevant questions based on your project type
• Enhanced Technology Support: 20+ technology-specific guidelines and best practices
• Project Structure Analysis: Automatically detects and configures based on your project setup
• Customizable Rules: Define coding standards, workflow guidelines, and project-specific instructions
• Interactive Recipe Creator: Create new recipes with guided prompts and auto-validation
• Recipe Validation: Comprehensive validation system with auto-fix capabilities
• Gemini CLI Integration: Configure Gemini CLI to use .agent.md as context file (local or global)
• Backward Compatibility: Seamlessly supports both legacy and modern Cursor formats

🤖 Supported AI Platforms

| Platform | Icon | File Type | Configuration | |----------|------|-----------|---------------| | Cursor AI | 🔵 | .agent.md | Comprehensive markdown rules file | | Cursor AI (Modern) | 🔵 | .cursor/rules/*.mdc | NEW! Modular Multi-Document Context files | | Windsurf | 🌊 | .windsurfrules | IDE-specific configuration file | | Gemini CLI | 💎 | .gemini/settings.json | Context file configuration |

Platform-Specific Features

• Cursor AI (Legacy): Full project context, coding standards, and AI assistant instructions
• Cursor AI (Modern MDC): 🆕 Modular rules system with specialized files:
  • coding-standards.mdc - Language & formatting rules with path scoping
  • architecture.mdc - Project structure & design patterns
  • testing.mdc - Testing guidelines & framework-specific rules
  • deployment.mdc - CI/CD & deployment best practices
  • security.mdc - Security guidelines & language-specific practices
• Windsurf: IDE integration with project-specific rules and guidelines
• Gemini CLI: Automatic configuration to use .agent.md as context file

🆕 Modern Cursor MDC Format

The Multi-Document Context (MDC) format represents the latest evolution in AI assistant configuration, offering superior performance and organization compared to traditional single-file approaches.

Why MDC is Better

• 🎯 Enhanced AI Performance: Modular context provides better understanding
• 📁 Organized Structure: Separate concerns into focused rule files
• 🔍 Path-Scoped Rules: Apply rules only where relevant
• ⚡ Faster Processing: AI can load only relevant context
• 🔧 Easier Maintenance: Update specific areas without affecting others

Generated Structure

.cursor/
└── rules/
    ├── coding-standards.mdc    # Language & formatting rules
    ├── architecture.mdc        # Project structure & patterns
    ├── testing.mdc            # Testing guidelines
    ├── deployment.mdc         # CI/CD & deployment (optional)
    └── security.mdc           # Security practices (optional)

Interactive Module Selection

When choosing the MDC format, you can select which modules to generate:

• ✅ Coding Standards (recommended)
• ✅ Architecture Guidelines (recommended)
• ✅ Testing Rules (recommended)
• ⬜ Deployment & CI/CD (optional)
• ⬜ Security Guidelines (optional)

Path Scoping Example

# coding-standards.mdc
## Language: TypeScript

### Path Scope
Apply to: `src/**/*`, `lib/**/*`

### Formatting Rules
- Use 2 spaces for indentation
- Single quotes for strings
- Semicolons required

🍳 Recipe Creation & Validation

Interactive Recipe Creator

Create high-quality recipes with guided assistance:

# Start the CLI and select "Create new recipe"
agent-rules-generator

# Or use validation commands
npm run validate:remote     # Validate remote recipes
npm run validate:sample     # Generate sample recipe
node scripts/validate_recipes.js --help  # See all options

Creation Flow:

1. Basic Information - Name, description, category with validation
2. Technology Stack - Guided setup, manual entry, or package.json import
3. Optional Fields - Author, version, tags with smart defaults
4. Rules Generation - Auto-generated templates or custom rules
5. Validation & Review - Real-time validation with auto-fixes
6. Save & Integration - Flexible saving with git integration

Smart Features:

• Category-based suggestions for languages and frameworks
• Package.json detection for existing projects
• Template generation based on technology stack
• Real-time validation with 15+ quality checks
• Auto-fix functionality for common issues
• Git integration for automatic recipe tracking

Recipe Validation:

# Validate specific recipe file (JSON or YAML)
node scripts/validate_recipes.js --file recipe.json
node scripts/validate_recipes.js --file recipe.yaml

# Validate with auto-fix
node scripts/validate_recipes.js --file recipe.json --fix
node scripts/validate_recipes.js --file recipe.yaml --fix

# Validate all recipes in directory (supports mixed formats)
node scripts/validate_recipes.js --dir ./recipes

# Generate sample recipe templates
node scripts/validate_recipes.js --sample > new_recipe.json
node scripts/validate_recipes.js --sample | yaml-convert > new_recipe.yaml

Supported File Formats:

• JSON (.json) - Traditional JSON format
• YAML (.yaml, .yml) - Human-readable YAML format
• Mixed directories - Validate both formats together
• Format conversion - Built-in conversion between formats

🏗️ Architecture

The Agent Rules Generator features a modular architecture designed for maintainability and extensibility:

Core Components

agent-rules-generator/
├── index.js                           # Main entry point
├── agent_rules_cli.js                 # Core CLI orchestrator
├── package.json                       # Project configuration
├── DEPLOY.md                          # Deployment instructions
├── CHANGELOG.md                       # Version history
├── lib/                               # 13 specialized modules
│   ├── cache_manager.js               # Cache management operations
│   ├── cleanup_utils.js               # Cleanup and maintenance utilities
│   ├── file_format_handler.js         # JSON/YAML format processing
│   ├── generator_lib.js               # Template system and file generation
│   ├── project_configurator.js        # Project configuration collection
│   ├── project_types.js               # Project type logic and questions
│   ├── recipe_creator.js              # Recipe creation and validation
│   ├── recipe_manager.js              # Recipe selection and application
│   ├── recipes_lib.js                 # Recipe system with GitHub integration
│   ├── repository_manager.js          # Repository settings and testing
│   ├── tech_stack_collector.js        # Technology stack collection
│   ├── windsurf_manager.js            # Windsurf integration and menu handling
│   └── windsurf_scraper.js            # Windsurf recipe scraping and caching
├── test/                              # 13 test files (181 tests total)
│   ├── deployment.test.js             # Deployment workflow tests
│   ├── file_format_handler.test.js    # Format handling tests
│   ├── project_types.test.js          # Project type tests
│   ├── recipe_creator.test.js         # Recipe creation tests
│   ├── recipe_download.test.js        # Recipe download tests
│   ├── recipe_validation.test.js      # Recipe validation tests
│   ├── scraper_integrate_test.js      # Scraper integration tests
│   ├── template_system.test.js        # Template system tests
│   ├── windsurf_customization_flow.test.js # Windsurf flow tests
│   └── [4 additional test files]      # Other specialized tests
├── docs/                              # 13 documentation files
│   ├── NOTIFICATIONS.md               # Discord/Telegram setup guide
│   ├── testing.md                     # Testing strategy and procedures
│   ├── deployment.md                  # Deployment and CI/CD processes
│   └── [10 additional docs]           # Analysis and guides
├── scripts/                           # 4 utility scripts
│   ├── investigate_windsurf.js        # Windsurf investigation tools
│   ├── scrape_windsurf_rules.js       # Windsurf scraping utilities
│   ├── simple_windsurf_scraper.js     # Simple scraper implementation
│   └── validate_recipes.js            # Recipe validation script
├── templates/                         # Template files for generation
│   └── agent-template.md              # Base agent template
├── examples/                          # Example files
│   ├── sample_recipe.yaml             # Sample recipe format
│   └── sample_recipe_generated.yaml   # Generated recipe example
├── windsurf_recipes/                  # Cached Windsurf recipes
│   └── recipes.json                   # Recipe cache file
└── .github/                           # GitHub Actions workflows
    └── workflows/
        └── deploy.yml                 # Automated deployment pipeline

Key Design Principles

• Separation of Concerns: Each module handles a specific functionality
• Dependency Injection: Modules receive shared dependencies (inquirer, chalk, config)
• Clean Interfaces: Consistent method signatures across modules
• Testability: 99 tests with 100% pass rate
• Maintainability: No module exceeds 300 lines

Refactoring Achievement

• ✅ 45% code reduction: Main CLI reduced from 779 → 424 lines
• ✅ 13 specialized modules with clean separation of concerns
• ✅ 100% functionality preserved including the awesome startup screen
• ✅ All 181 tests passing with comprehensive coverage
• ✅ Bug fixes completed: Windsurf recipe customization flow fully functional

📋 Prerequisites

For Normal Use

• Node.js >= 14.0.0

For Development

• Node.js >= 14.0.0
• Bun >= 1.0.0 (recommended for development)
• Git (for contributing)

🛠️ Installation

For Normal Use (Recommended)

Install globally to use the CLI commands anywhere:

# Using npm (recommended)
npm install -g agent-rules-generator

# Using Bun (fast alternative)
bun add -g agent-rules-generator

# Using Yarn
yarn global add agent-rules-generator

# Using pnpm
pnpm add -g agent-rules-generator

For Development/Contributing

If you want to contribute to the project or run from source:

# Clone the repository
git clone https://github.com/ubuntupunk/agent-rules-generator.git
cd agent-rules-generator

# Install dependencies
bun install  # or npm install

# Run from source
node index.js

# Run tests
bun test  # or npm test

👨‍💻 Development Guide

Working with the Modular Architecture

The codebase is organized into specialized modules for easy development and maintenance:

Adding New Features

1. Identify the appropriate module or create a new one if needed
2. Follow the module pattern:

   class ModuleName {
     constructor(config) {
       this.config = config;
     }
        
     async methodName() {
       // Implementation
     }
   }
      
   module.exports = { ModuleName };

3. Update the main CLI to use your new module
4. Add comprehensive tests for your functionality

Module Responsibilities

• recipe_manager.js: Recipe selection, browsing, and application
• windsurf_manager.js: Windsurf-specific functionality and menus
• tech_stack_collector.js: Technology stack collection and customization
• project_configurator.js: Project information and configuration collection
• cache_manager.js: Cache operations and management
• repository_manager.js: Remote repository configuration and testing

Testing Guidelines

# Run all tests (181 tests across 13 test files)
bun test

# Run specific test suite
bun test test/template_system.test.js

# Run recipe creation tests (34 tests)
bun test test/recipe_creator.test.js

# Run recipe validation tests (15 tests)
bun test test/recipe_validation.test.js

# Run Windsurf customization flow tests (9 tests)
bun test test/windsurf_customization_flow.test.js

# Test with verbose output
bun test --verbose

Test Coverage:

• Recipe Creator: 34 tests covering suggestions, detection, templates, validation
• Recipe Validation: 15 tests covering validation rules, auto-fixes, edge cases
• Windsurf Integration: 9 tests covering customization flow and bug fixes
• Template System: 18 tests covering file generation and technology detection
• Deployment: 33 tests covering package config and CI/CD validation

Recipe Management Scripts

# Validate recipes (supports JSON and YAML)
npm run validate              # Validate local/remote recipes
npm run validate:remote       # Validate remote GitHub recipes  
npm run validate:fix          # Validate with auto-fix enabled
npm run validate:sample       # Generate sample recipe template

# Format-specific validation examples
node scripts/validate_recipes.js --file recipe.json
node scripts/validate_recipes.js --file recipe.yaml
node scripts/validate_recipes.js --dir ./recipes  # Mixed formats

Code Quality Standards

• Keep modules under 300 lines for maintainability
• Use dependency injection for shared resources
• Follow consistent naming conventions (camelCase for methods, PascalCase for classes)
• Add JSDoc comments for public methods
• Include error handling with user-friendly messages using chalk

🚀 Quick Start

1. Install globally:

   npm install -g agent-rules-generator

2. Run the generator:

   agent-rules-generator

   or

   generate-agent-rules

3. Follow the interactive prompts to configure your project

4. Choose your output format:

   • .agent.md for Cursor AI (Legacy) 🔵
   • 🆕 .cursor/rules/ for Modern Cursor MDC 🔵
   • .windsurfrules for Windsurf 🌊
   • Configure Gemini CLI 💎

The tool will create a comprehensive configuration file tailored to your project type and technology stack.

🎯 What It Does

The Agent Rules Generator creates comprehensive configuration files that help AI assistants understand your project better. These files include:

• Project Overview: Name, description, version, and type
• Technology Stack: Conditional questions based on project type (no more irrelevant questions!)
• Coding Standards: Style guides, linting rules, and conventions
• Project Structure: Directory organization and file patterns
• Development Workflow: Git workflow, branching strategy, and CI/CD processes
• Project Management: Methodology, issue tracking, and documentation practices

🏗️ Supported Project Types

The tool now supports 6 different project types with tailored question flows:

🌐 Web Applications

• Frontend frameworks (React, Vue, Angular, Svelte)
• Backend frameworks (Express, FastAPI, Django, Spring Boot)
• Databases (PostgreSQL, MongoDB, MySQL, SQLite)
• Deployment platforms (Vercel, Netlify, AWS)

⚡ CLI Tools

• CLI frameworks (Commander.js, Yargs, Inquirer.js)
• Configuration formats (JSON, YAML, TOML)
• Package managers (npm, yarn, pnpm, bun)
• No irrelevant frontend/backend questions

📚 Libraries/Packages

• Target environments (Node.js, Browser, Both)
• Build systems (TypeScript, Rollup, Webpack)
• Distribution formats (CommonJS, ESM, UMD)
• Testing frameworks (Jest, Vitest, Mocha)

📱 Mobile Applications

• Platforms (iOS, Android, Cross-platform)
• Frameworks (React Native, Flutter, Native)
• State management (Redux, Zustand, Context API)
• App store distribution

🖥️ Desktop Applications

• Frameworks (Electron, Tauri, Native)
• UI libraries (React, Vue, Svelte)
• Platform targets (Windows, macOS, Linux)
• Distribution methods

🔌 API/Backend Services

• Backend frameworks (Express, FastAPI, Django)
• Databases and data storage
• API documentation tools
• Authentication methods

🍳 Recipes & Templates

Recipe System

The tool includes a sophisticated recipe system that fetches pre-built configurations from a remote GitHub repository. This allows for:

• Easy Updates: Recipes are updated automatically
• Community Contributions: Anyone can contribute new recipes
• Technology Coverage: Recipes for all major tech stacks
• Project Type Specific: Recipes tailored to each project type

Available Recipes

• React + TypeScript + Vite
• Vue 3 + TypeScript + Vite
• Node.js + Express + PostgreSQL
• CLI Tool with Commander.js
• React Native + Expo
• Electron + React
• And many more...

Creating Custom Recipes

You can contribute new recipes by:

1. Forking the recipe repository
2. Adding your recipe YAML file
3. Submitting a pull request

🧪 Development & Testing

For Contributors

# Clone and setup
git clone https://github.com/ubuntupunk/agent-rules-generator.git
cd agent-rules-generator
bun install

# Run tests
bun test                                    # All tests (90 tests)
bun test test/recipe_download.test.js      # Recipe system (17 tests)
bun test test/template_system.test.js      # Template system (18 tests)
bun test test/deployment.test.js           # Deployment (33 tests)
bun test test/project_types.test.js        # Project types (22 tests)

# Run from source
node index.js

# Test deployment
npm pack --dry-run

Project Structure

agent-rules-generator/
├── index.js                 # Main CLI entry point
├── agent_rules_cli.js       # Core CLI application
├── lib/                     # Library modules
│   ├── generator_lib.js     # File generation logic
│   ├── recipes_lib.js       # Recipe management
│   └── project_types.js     # Project type logic
├── templates/               # Template files
├── test/                    # Test suites (90 tests)
├── docs/                    # Documentation
├── CHANGELOG.md             # Version history
└── README.md               # This file

📚 Documentation

Core Documentation

• DEPLOY.md - Quick deployment instructions
• NOTIFICATIONS.md - Discord/Telegram setup guide
• Testing Guide - Comprehensive testing information (181 tests)
• Deployment Guide - CI/CD pipeline documentation
• CHANGELOG.md - Version history and release notes

Additional Resources (13 docs total)

• Analysis documents for project types, recipes, and templates
• Deployment analysis and strategy guides
• Technical notes and implementation details

🔧 Configuration

The CLI will guide you through configuring:

Project Overview

• Project name and description
• Project type selection
• Version and metadata

Technology Stack (Conditional)

• Web Apps: Frontend, backend, database
• CLI Tools: CLI framework, config format
• Libraries: Target environment, build system
• Mobile Apps: Platform, framework, state management
• Desktop Apps: Framework, UI library, platforms
• API/Backend: Backend framework, database

Coding Standards

• Code style preferences
• Naming conventions
• Linting and formatting tools
• Documentation requirements

Project Structure

• Directory organization
• File naming patterns
• Module structure

Workflow Guidelines

• Git workflow and branching
• CI/CD processes
• Deployment procedures
• Code review practices

📝 Generated Files

.agent.md (Cursor AI - Legacy)

A comprehensive markdown file containing:

• Project context and overview
• Technology-specific guidelines
• Coding standards and conventions
• Development workflow rules
• AI assistant instructions

🆕 .cursor/rules/*.mdc (Modern Cursor MDC)

Multi-Document Context files for enhanced AI performance:

• coding-standards.mdc - Language & formatting rules with path scoping
• architecture.mdc - Project structure & design patterns
• testing.mdc - Testing guidelines & framework-specific rules
• deployment.mdc - CI/CD & deployment best practices (optional)
• security.mdc - Security guidelines & language-specific practices (optional)

Benefits over legacy format:

• 🎯 Better AI understanding through modular context
• 📁 Organized structure with separated concerns
• 🔍 Path-scoped rules that apply only where relevant
• ⚡ Faster processing by loading only relevant context

.windsurfrules (Windsurf)

A configuration file for Windsurf AI development environment with:

• Project-specific rules
• Technology guidelines
• Code generation preferences
• Quality standards

.gemini/settings.json (Gemini CLI)

Configuration for Gemini CLI to use .agent.md as context file:

• Local project configuration (.gemini/settings.json)
• Global user configuration (~/.gemini/settings.json)
• Automatic context file detection
• Seamless integration with existing .agent.md files

🎯 Benefits

Before v1.1.0 (React-Biased)

• ❌ Always assumed web applications
• ❌ Asked irrelevant frontend/backend questions for CLI tools
• ❌ Limited to 6 technology guidelines
• ❌ One-size-fits-all approach

After v1.1.0 (Inclusive)

• ✅ 6 project types supported with specific workflows
• ✅ Conditional questions - only relevant ones asked
• ✅ 20+ technologies with specific guidelines
• ✅ Context-aware messaging and defaults
• ✅ Backward compatible - existing users unaffected

📊 Version History

See CHANGELOG.md for detailed version history and release notes.

📄 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• Thanks to all contributors who help improve this tool
• Special thanks to the AI development community for feedback and suggestions
• Built with ❤️ for developers working with AI assistants

Made with ❤️ by ubuntupunk