Agent Rules Kit v1

Bootstrap Cursor rules (.mdc) for AI agent-guided projects. This tool helps you generate and maintain project-specific rules for multiple frameworks and architectures.

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.

🎧 Audio Introduction

Listen to a brief introduction about Agent Rules Kit:

https://github.com/user-attachments/assets/7d65c696-245d-421d-9ddc-90331a92c9b2

English Version

https://github.com/user-attachments/assets/8e91d651-c15f-4892-a250-684ab60d8594

Spanish Version

📚 Table of Contents

1. Quick Start
2. New Architecture
3. New Features
4. Supported Stacks
5. Implementation Status
6. Contributing
7. Code of Conduct
8. License

🚀 Quick Start

# Install and run interactively
npx agent-rules-kit

# The CLI will guide you through:
# 1. 📁 Project path selection
# 2. 📚 Stack and architecture choice (optional)
# 3. 🌐 Global best practices (recommended)
# 4. 🔧 MCP tools selection (multiple tools supported)
# 5. ⚡ Automatic rule generation

Your rules will be generated in .cursor/rules/rules-kit/ and automatically detected by Cursor!

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

🎉 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

• 🚀 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)
• React Native
• Angular (v14-17)
• NestJS
• Vue (v2-3)
• Nuxt (v2-3)
• Svelte (v3-5)
• SvelteKit (v1-2)
• Astro
• Generic (for any project)

Implementation Status

Stack	Status	Features
		Complete SDK coverage (Python, TypeScript, Java, Kotlin, C#, Swift), server/client patterns, architecture concepts
		Multiple architectures, version detection, casting rules
		Testing guidelines, architectural patterns, version-specific docs
		Best practices, file operations, code standards, extensibility docs
		Semantic code search, AI agent integration, MCP support, multi-language indexing
		Architecture options, state management, testing guidelines, version-specific guidance (v18 concurrent features)
		Base rules (architecture, best practices, styling, naming, navigation, platform code, state, testing, version info)
		App & Pages router support, version detection, testing docs, version-specific guidance (v13 API routes, v14 Server Components)
		Component organization, runes (v5), lifecycle, state management
		Multiple architectures, project structure, error handling patterns
		Routing system, layouts, SSR/CSR strategies, form actions
		Content collections, static/dynamic content, integration guides
		Signals support, base project structure
		Standard and Microservices architectures, NestJS 9.x and 10.x features
		Testing guidelines, architecture concepts
		Standard, Reactive, Microservices
		Python, TypeScript, Java, Kotlin, C#, Swift
		Latest

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.

Contributing

For guidelines on contributing to this project, please see CONTRIBUTING.md.

Code of Conduct

Please read our Code of Conduct before participating in our project.

License

This project is licensed under the ISC License. See the LICENSE file for details.

🎯 Available Stacks

Choose from a wide range of technology stacks:

🔥 Featured: Model Context Protocol (MCP)

MCP is an open standard that enables AI applications to securely connect to data sources. Our rules kit includes comprehensive implementation guides for all major SDKs:

• 📖 Architecture Concepts: Core MCP patterns and best practices
• 🐍 Python SDK: Async/await patterns with Pydantic validation
• 🟦 TypeScript SDK: Type-safe implementations with modern JS patterns
• ☕ Java SDK: Enterprise patterns with Spring Boot integration
• 🎯 Kotlin SDK: Coroutines and advanced async features
• 🔷 C# SDK: .NET patterns with dependency injection
• 🍎 Swift SDK: Actors and async/await with Vapor integration

🔧 MCP Tools Integration

Agent Rules Kit now includes specialized rules for popular MCP tools to help AI agents use them effectively:

• 🔍 PAMPA: Semantic code search and project memory system with usage patterns and best practices
• 🐙 GitHub: Repository management with secure file operations and API integration guidelines
• 🧠 Memory: Persistent knowledge storage and retrieval across sessions
• 📁 Filesystem: Secure file operations with configurable access controls
• 🔀 Git: Repository operations, commit history analysis, and version control workflows

New in v2.0: You can now select multiple MCP tools during installation, allowing you to combine different tools based on your project needs. Each tool includes practical usage rules focused on agent workflows and best practices.

🎯 Featured: Pampa Semantic Code Search

Pampa is our own AI-powered semantic code search tool designed specifically for AI agents:

• 🔍 Semantic Search: Understand code meaning, not just syntax
• 🤖 AI Agent Optimized: Built specifically for AI agent workflows
• 🌍 Multi-Language: Python, TypeScript, Java, Go, PHP, and more
• 🚀 Simple Setup: No versions, no complex config - just install and use
• 🔌 MCP Integration: Built-in MCP server for seamless AI integration

Perfect for AI agents to quickly understand and navigate any codebase!

✨ Key Features

• 🎯 Multi-Stack Support: 15+ frameworks including Laravel, Next.js, React, Angular, Vue, and more
• 🏗️ Architecture-Aware: Specialized rules for different architectural patterns (MVC, DDD, Hexagonal, etc.)
• 📦 Version Detection: Automatic framework version detection with version-specific optimizations
• 🌐 Global Best Practices: Universal coding standards and quality assurance rules
• 🔧 MCP Tools Integration: Multi-select support for popular Model Context Protocol tools (PAMPA, GitHub, Memory, Filesystem, Git)
• ⚡ Performance Optimized: Efficient rule generation with progress tracking and memory management
• 🔄 Smart Updates: Backup existing rules and merge configurations intelligently
• 🎨 Beautiful CLI: Interactive interface with helpful prompts and clear feedback