Cairel - AI Development Configuration Tool

Standardize your AI-driven development workflow in minutes.

Cairel generates consistent, project-specific configurations for AI coding assistants like kiro-cli and Amazon Q Developer, eliminating manual setup and ensuring best practices across your projects.

---

Why Cairel?

The Problem: Developers manually copy/paste AI assistant rules and configurations between projects, leading to:

• ❌ Inconsistent AI behavior across projects
• ❌ Time wasted on repetitive setup
• ❌ Outdated or incomplete rule sets
• ❌ No standardization across teams

The Solution: Cairel provides:

• ✅ 23 curated, battle-tested rules for AI assistants
• ✅ Interactive wizard for project-specific configuration
• ✅ Automatic MCP server detection and setup
• ✅ Support for multiple AI tools (kiro-cli, Amazon Q Developer)
• ✅ Customizable rule selection with review step

---

Quick Start

Installation

npm install -g cairel

Initialize Your Project

cd your-project
cairel init

Follow the Interactive Wizard

🚀 Cairel - AI Development Initialization

? How would you like to configure your project?
  ❯ Quick Setup (High-level, recommended)
    Detailed Setup (Granular control)
    Custom (Select specific rules)

? What type of project is this? UI (Frontend)
? Primary language? TypeScript
? Framework? React
? Use Git for version control? Yes
? Which AI tool(s) will you use? kiro-cli
✔ Found 5 MCP server(s)
? Select MCP servers to configure: 
  ◉ amazon-q-history (/home/user/mcp-servers/amazon-q-history)
  ◉ gpt (/home/user/mcp-servers/gpt)
  ◯ web-scraper (/home/user/mcp-servers/web-scraper)

? Would you like to review and customize the rules? (y/N)

What Gets Generated

Cairel creates a complete AI configuration in your project:

For kiro-cli:

.kiro/
├── agents/
│   └── dev-agent.json      # AI agent configuration
└── steering/
    ├── context-retrieval.md
    ├── implementation-approval.md
    ├── typescript-validation.md
    ├── component-structure.md
    ├── git-management.md
    └── ... (more rules based on your project)

For Amazon Q Developer:

.amazonq/
├── cli-agents/
│   └── dev-agent.json
└── rules/
    └── ... (same rules as above)

---

Features

🎯 Three Configuration Modes

Quick Setup (Recommended)

• 6 simple questions
• Automatic rule selection based on your stack
• Perfect for most projects

Detailed Setup

• 12 questions for fine-grained control
• Configure testing, linting, UI libraries, package managers
• Ideal for complex projects

Custom Mode

• Select specific rules from all 17 available
• Full control over your configuration
• Great for specialized workflows

📋 Optional Review Step

Before generating files, optionally review and customize:

• See all selected rules with descriptions
• Toggle rules on/off with checkboxes
• Ensure you get exactly what you need

🔌 Automatic MCP Server Detection

Cairel automatically detects installed MCP servers:

• amazon-q-history (session tracking)
• gpt (ChatGPT integration)
• web-scraper (web testing)
• cypress (E2E testing)
• chakra-ui (component reference)

📦 17 Curated Rules

General (6 rules)

• Context retrieval & token optimization
• Implementation approval protocol
• Package manager safety
• Semantic versioning
• ESLint configuration
• Package.json management

TypeScript (4 rules)

• TypeScript validation
• Component structure
• React props destructuring
• Absolute imports

Git (1 rule)

• Git management & commit standards

UI (5 rules)

• Visual verification
• Mock data strategy
• Icon usage patterns
• Chakra UI v3 integration
• GlueStack UI v1 integration

Backend (1 rule)

• Multi-environment management

---

Usage Examples

Example 1: React TypeScript Frontend

cairel init
# Select: Quick Setup → UI → TypeScript → React → Yes (Git) → kiro-cli

Generated rules: context-retrieval, implementation-approval, typescript-validation, component-structure, react-props-destructuring, git-management, visual-verification, mock-data-strategy, package-manager-safety, package-json-management, absolute-imports

Example 2: Python Backend API

cairel init
# Select: Quick Setup → Backend → Python → FastAPI → Yes (Git) → Amazon Q

Generated rules: context-retrieval, implementation-approval, git-management

Example 3: Custom Configuration

cairel init
# Select: Custom → Select specific rules → Choose only what you need

---

Commands

cairel init

Initialize AI configuration for your project.

Options:

• Interactive wizard guides you through setup
• Generates agent configuration and rules
• Detects and configures MCP servers

cairel bootstrap

Show path to Cairel's project initialization template.

Use this with kiro-cli to set up comprehensive project documentation:

cairel bootstrap
# Copy the output and paste into kiro-cli

cairel update

Update existing configuration with new rules or settings.

Features:

• Backs up existing files
• Preserves custom rules
• Selective updates (rules only, agents only, or both)

cairel validate

Validate rule files and agent configurations.

cairel validate                    # Validate all
cairel validate path/to/rule.md    # Validate specific file
cairel validate --rules            # Validate rules only
cairel validate --agents           # Validate agents only

cairel list

List all available rules and their descriptions.

cairel list                        # Show all
cairel list --rules                # Rules only
cairel list --category typescript  # Filter by category

---

Configuration

Supported AI Tools

• kiro-cli: Creates .kiro/ directory structure
• Amazon Q Developer: Creates .amazonq/ directory structure
• Both: Creates both directory structures

Supported Languages

• TypeScript
• JavaScript
• Python
• Go
• Lua

Supported Frameworks

Frontend:

• React
• React Native
• Next.js
• Vue

Backend:

• Express
• Fastify
• NestJS
• Flask
• Django
• FastAPI
• Gin
• Echo
• Fiber
• Chi

---

Best Practices

1. Start with Quick Setup

Most projects work great with Quick Setup. You can always run cairel update later.

2. Review Your Rules

Use the optional review step to understand what rules will be applied.

3. Customize as Needed

Don't hesitate to use Custom mode for specialized projects.

4. Keep Rules Updated

Run cairel update periodically to get improved rules.

5. Version Control Your Configuration

Commit the generated .kiro/ or .amazonq/ directories to your repository.

---

Troubleshooting

MCP Servers Not Detected

Cairel looks for MCP servers in:

• /home/user/mcp-servers/
• ~/.mcp-servers/
• ./node_modules/@mcp/

If your servers aren't detected, you can still configure them manually in the generated dev-agent.json.

Rules Not Working as Expected

1. Validate your configuration: cairel validate
2. Check rule descriptions: cairel list
3. Review the generated files in .kiro/steering/ or .amazonq/rules/

Need to Change Configuration

Run cairel update to modify your existing setup without losing custom changes.

---

Technical Documentation

For developers and advanced users:

• Architecture - System design and components
• Development Plan - Stage-based implementation
• Progress - Development history and status
• Testing - Test suite and coverage
• Quick Reference - Technical quick reference
• Future Vision - carm package manager concept

---

Contributing

Contributions are welcome! Please see our contributing guidelines for details.

Ways to Contribute

• Submit new rules - Share your AI assistant best practices
• Report bugs - Help us improve reliability
• Suggest features - Tell us what you need
• Improve documentation - Make Cairel easier to use

---

License

MIT © JMRMEDEV

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Acknowledgments

Rules and patterns abstracted from real-world AI-driven development projects using kiro-cli and Amazon Q Developer.

---

Made with ❤️ for the AI-driven development community