Agent Rules Kit v3.x

CLI tool to bootstrap AI agent rules for multiple IDEs and frameworks. Generates optimized rules for Cursor, VS Code, Claude, and 6+ other AI coding assistants.

🎯 IDE Selection Interface

Choose from 9 supported IDEs including Cursor, VS Code/GitHub Copilot, Windsurf, Continue, Claude, and more.

What is Agent Rules Kit?

Agent Rules Kit is a CLI tool that facilitates the installation and configuration of rules for multiple AI-powered IDEs and coding assistants. The rules help AI agents better understand the structure, patterns, and best practices of different technology stacks, generating optimized configurations for each supported IDE.

🎧 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. MCP Tools Integration
6. Implementation Status
7. Contributing
8. Code of Conduct
9. License

🚀 Quick Start

Interactive Installation

# Install and run interactively
npx agent-rules-kit

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

Command Line Installation

For automated or scripted installations, use command line arguments to skip interactive prompts:

# Basic installation with auto-detection
npx agent-rules-kit --stack=laravel --version=12 --global --auto-install

# Full configuration example
npx agent-rules-kit --stack=nextjs --version=14 --architecture=app --global --mcp-tools=pampa,github --ide=cursor

# For different IDEs
npx agent-rules-kit --stack=react --version=18 --ide=vscode    # VS Code
npx agent-rules-kit --stack=laravel --version=12 --ide=claude  # Claude
npx agent-rules-kit --stack=angular --version=17 --ide=windsurf # Windsurf

📖 For complete CLI options and examples, see AGENTS.md

Your rules will be generated in the appropriate location for your chosen IDE and automatically detected!

AI Agent Integration

If you are using an AI agent, check AGENTS.md for comprehensive instructions on automated installation. Share this file with your agent so it installs the rules automatically with the correct 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

🎉 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
• 🔧 Multi-select MCP Tools integration (Since v2.0)

🔧 MCP Tools Integration

Since v2.0: Agent Rules Kit includes comprehensive support for Model Context Protocol (MCP) tools! This powerful feature allows AI agents to work more effectively with external tools and services.

What are MCP Tools?

Model Context Protocol (MCP) tools are standardized interfaces that allow AI assistants to securely connect to external data sources and services. These tools enable AI agents to:

• 🔍 Search codebases semantically with understanding of code meaning
• 🐙 Manage repositories with secure GitHub integration
• 🧠 Maintain persistent memory across conversation sessions
• 📁 Access file systems with configurable security controls
• 🔀 Perform version control operations with Git integration

Available MCP Tools

Choose from 5 popular MCP tools during installation:

| Tool | Name | Description | Best For | | ----------------- | --------------------- | ------------------------------------------------- | ------------------------------------------------------------- | | 🔍 PAMPA | Semantic Code Search | AI-powered code search with project memory | Understanding large codebases, finding relevant code patterns | | 🐙 GitHub | Repository Management | Secure GitHub API integration for file operations | Repository management, collaborative development | | 🧠 Memory | Persistent Knowledge | Long-term memory storage across sessions | Maintaining context, learning from previous interactions | | 📁 Filesystem | File Operations | Secure file system access with controls | File management, project organization | | 🔀 Git | Version Control | Repository operations and history analysis | Version control, commit management, branch operations |

Multi-Select Installation

The new multi-select interface allows you to install rules for multiple MCP tools simultaneously:

? Select MCP tools to install rules for: (Use space to select, enter to confirm)
❯◉ PAMPA - Semantic Code Search - AI-powered semantic code search and project memory system
 ◉ GitHub - Repository Management - Secure access to GitHub repositories for file operations
 ◯ Memory - Persistent Knowledge - Persistent knowledge storage and retrieval across sessions
 ◉ Filesystem - File Operations - Secure file operations with configurable access controls
 ◯ Git - Version Control - Repository operations, commit history analysis, and version control

Generated Rule Structure

Each selected MCP tool generates organized rules in your project:

.cursor/rules/rules-kit/mcp-tools/
├── pampa/
│   ├── pampa-mcp-usage.mdc       # Core usage patterns
│   └── pampa-best-practices.mdc  # Best practices and tips
├── github/
│   ├── github-mcp-usage.mdc      # GitHub API integration rules
│   └── github-workflow.mdc       # Workflow patterns
└── memory/
    ├── memory-mcp-usage.mdc      # Memory management rules
    └── memory-patterns.mdc       # Common memory patterns

Benefits for AI Agents

MCP Tools rules help AI agents:

1. 🎯 Use tools effectively: Clear guidelines on when and how to use each tool
2. 🛡️ Follow security best practices: Built-in security patterns and access controls
3. ⚡ Optimize performance: Efficient usage patterns to avoid rate limits and errors
4. 🔄 Handle errors gracefully: Common error scenarios and recovery strategies
5. 📖 Learn workflows: Step-by-step patterns for complex operations

Integration with Stack Rules

MCP tools rules work alongside your stack-specific rules:

• 🔀 Independent Generation: MCP rules are separate from stack rules
• 🧩 Flexible Combinations: Any stack + any combination of MCP tools
• 🎯 Focused Guidance: Tool-specific rules don't interfere with framework patterns
• 📋 Complete Coverage: Both development patterns AND tool usage covered

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

Implementation Status

| Stack | Status | Features | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | | | Since v2.0: Multi-select MCP tools (PAMPA, GitHub, Memory, Filesystem, Git), usage patterns, security guidelines, workflows | | | | 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 | | | | 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 | | | | Base project structure, best practices, naming, testing | | | | Testing guidelines, architecture concepts |

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:

| Stack | SDKs/Versions | Architectures | | ----------------------------------- | ------------------------------------------- | ------------------------------------- | | Laravel | 8, 9, 10, 11, 12 | Standard, DDD, Hexagonal | | Next.js | 12, 13, 14 | App Router, Pages Router | | Angular | 14, 15, 16, 17 | Standard, Standalone, Micro-frontends | | React | 17, 18 | Standard, Hooks, Concurrent | | Vue.js | 2, 3 | Options API, Composition API, Nuxt | | Astro | 2, 3, 4, 5 | Static, SSR, Hybrid | | React Native | 0.70, 0.71, 0.72, 0.73, 0.74 | Standard, Expo | | NestJS | 8, 9, 10 | Standard, Microservices, GraphQL | | Go | 1.20, 1.21, 1.22 | Standard, DDD, Hexagonal | | Node.js | 18, 20 | Standard | | 🆕 MCP (Model Context Protocol) | Python, TypeScript, Java, Kotlin, C#, Swift | Server, Client, Toolkit | | 🆕 Pampa | Latest | Standard |

🔥 Featured: Model Context Protocol (MCP) SDKs

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

🎯 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

Multi-IDE Installation

Agent Rules Kit can install existing rules into several IDEs and agents using the new install command. Pass the desired IDE with --target (or the alias --ide) to skip the interactive selector:

npx agent-rules-kit install --target=cursor   # or --ide=cursor

Supported targets

| Target | Path | Extension | Front matter | | ------------------------ | --------------------------------- | --------- | ------------ | | Cursor | .cursor/rules/ | .mdc | yes | | VS Code / GitHub Copilot | .github/copilot-instructions.md | .md | no | | Windsurf | .windsurf/rules/ | .md | no | | Windsurf (legacy) | .windsurfrules | .md | no | | Continue | .continue/rules/ | .md | yes | | Zed | ./.rules | .rules | no | | Claude Code | CLAUDE.md | .md | no | | Gemini Code | GEMINI.md | .md | no | | OpenAI Codex | AGENTS.md | .md | no | | Cline | .clinerules | .md | no |

The command detects .mdc files in your project (default ./rules) and writes them in the format required by the chosen target.