Agent Rules Kit v1.0

Bootstrap of Cursor rules (.mdc) and mirror documentation (.md) for AI agent-guided projects.

What is Agent Rules Kit?

Agent Rules Kit is a CLI tool that facilitates the installation and configuration of rules for Cursor AI, the AI-powered IDE. The rules help AI agents better understand the structure, patterns, and best practices of different technology stacks.

🎉 New Architecture

We've completely redesigned the internal architecture to provide a more maintainable and extensible system:

• Service-Based Architecture: Replaced the helper-based system with a clean service-oriented architecture that enhances maintainability and extensibility
• Automatic Backups: Smart backup system that preserves your custom rules when updating
• Enhanced Debug Mode: Better visibility into the rule generation process with standardized logging
• Improved Testing Framework: More robust testing with better mocking and service isolation
• React Architecture Options: Now includes support for atomic design and feature-sliced design
• Better State Management Support: Enhanced support for modern state management libraries

🎉 New Features in Version 1.0

• 🚀 Quick setup of rules for different frameworks and stacks
• 🔍 Automatic framework version detection
• 🏗️ Support for multiple architectural styles
• 📚 Mirror documentation generation for human reference
• 🧩 Modular system for easy expansion to new frameworks
• 💾 Automatic backups of existing rules
• 🔄 Version-specific rule overlays

Supported Stacks

• Laravel (v8-12)
• Next.js (v12-14)
• React (v17-18)
• Angular (v14-17)
• NestJS
• Vue (v2-3)
• Nuxt (v2-3)
• Astro
• Generic (for any project)

Implementation Status

Stack	Status	Features
		Multiple architectures, version detection, casting rules
		App & Pages router support, version detection, testing docs
		Signals support, base project structure
		Base project structure, patterns documentation
		Architecture options, state management, testing guidelines
		Testing guidelines, architecture concepts
		Testing guidelines, architecture concepts
		Basic configuration
		Best practices, file operations, code standards, extensibility docs

Enhanced Extensibility: Detailed documentation has been added on how to extend Agent Rules Kit with new services, making it easier to contribute new stacks and features.

Installation

Option 1: Run directly (Recommended)

No installation needed, run directly with:

npx agent-rules-kit
# or
pnpx agent-rules-kit

This will execute the latest version from npm without installing it globally.

Option 2: Global installation

npm install -g agent-rules-kit
# Then run
agent-rules-kit

Option 3: Development/Contribution

git clone https://github.com/tecnomanu/agent-rules-kit.git
cd agent-rules-kit
pnpm install
pnpm start

Basic Usage

Run the command in your project root:

npx agent-rules-kit

Follow the interactive instructions to select the stack, architecture, and other options.

Available Options

• Stack Selection: Choose the main framework or technology for your project
• Global Rules: Include general best practice rules
• Cursor Directory: Specify the location of the Cursor directory
• Project Path: Define the relative path if the project is not in the root
• Mirror Documentation: Generate .md files that reflect the rules for human reference
• Debug Mode: Enable detailed logging for troubleshooting

Supported Architectures

Laravel

• Standard: Traditional MVC structure with Repositories
• DDD (Domain-Driven Design): Business domain organization
• Hexagonal: Ports and adapters architecture

Next.js

• App Router: For Next.js 13+ projects
• Pages Router: Traditional router
• Hybrid: Both router types

React

• Standard: Component-based organization
• Atomic Design: Atoms, molecules, organisms, templates, pages
• Feature-Sliced Design: Features-first organization

State Management (React)

• Context API: Built-in React state management
• Redux: Predictable state container
• MobX: Simple, scalable state management
• Recoil: Experimental state management library by Facebook
• Zustand: Lightweight state management solution

File Structure

Rules are installed in:

.cursor/rules/rules-kit/
├── global/     # Global best practice rules
└── [stack]/    # Stack-specific rules

Mirror documentation is generated in:

docs/
├── global/
└── [stack]/

Project Architecture

The codebase is organized using a comprehensive service-oriented architecture:

cli/
├── index.js                # Entry point
├── services/               # Services directory
│   ├── base-service.js     # Base class with shared functionality across all services
│   ├── cli-service.js      # CLI interface and user interaction management
│   ├── config-service.js   # Configuration loading, validation and management
│   ├── file-service.js     # File operations and template processing
│   ├── stack-service.js    # Core stack functionality and orchestration
│   ├── laravel-service.js  # Laravel-specific implementations
│   ├── nextjs-service.js   # Next.js-specific implementations
│   └── react-service.js    # React-specific implementations
└── version-detector.js     # Framework version detection utilities

Service-Oriented Design

Each service has specific responsibilities:

• BaseService: Provides common utilities like debugging, file operations, and shared functions
• FileService: Handles all file operations, template processing, and MDC conversion
• ConfigService: Manages configuration from kit-config.json and default settings
• CLIService: Standardizes user interaction, messaging, and prompts
• Stack-specific Services: Implement specialized processing for each framework

Key benefits of this architecture:

• High Cohesion: Services have clear, focused responsibilities
• Low Coupling: Services communicate through well-defined interfaces
• Extensibility: New stacks can be added by creating new service classes
• Testability: Isolated services are easier to test independently
• Maintainability: Consistent patterns and organization across the codebase

For more details on the service architecture, see docs/services-architecture.md.

Advanced Configuration

Template Files

Templates for all stacks are located in:

templates/
├── global/              # Global rules
└── stacks/
    ├── laravel/
    │   ├── base/        # Laravel base rules
    │   ├── architectures/
    │   │   ├── standard/  # Standard architecture rules
    │   │   ├── ddd/       # DDD architecture rules
    │   │   └── hexagonal/ # Hexagonal architecture rules
    │   └── v10-11/      # Laravel 10-11 specific rules
    ├── nextjs/
    │   └── ...
    └── ...

Kit Configuration

The main configuration is in templates/kit-config.json, where it defines:

• Version ranges for each stack
• File patterns for specific rules
• Architecture configurations

Development

Prerequisites

• Node.js 16+
• pnpm (preferred) or npm

Development Installation

git clone https://github.com/tecnomanu/agent-rules-kit.git
cd agent-rules-kit
pnpm install

Available Commands

pnpm start           # Run the CLI
pnpm test            # Run tests
pnpm run lint        # Lint code
pnpm run test -- --update  # Update snapshots

License

ISC