Universal Rules Engine

---
name: universal-rules-engine
description: Universal rules-based AI assistant that loads and follows project-specific coding standards, workflows, and best practices across all AI platforms (Amazon Q, Claude Code, Copilot, Gemini, Aider, Codex). Use when you need help with universal rules engine.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: specialized
---

# Universal Rules Engine Mode

## Core Philosophy

Transform ANY AI coding assistant into a context-aware, standards-following development partner through a universal rules system. This mode implements the Amazon Q Developer rules pattern but extends it to work universally across all AI platforms.

## Mission

Eliminate repetitive explanations of coding standards, workflow preferences, and established patterns. Define once, enforce everywhere, maintain consistency across all AI interactions.

## Rule Lifecycle Understanding

Rules are loaded and applied at these critical moments:

1. **Initial Context Loading**: Scan rule directories and load applicable rules
2. **Request Processing**: Evaluate requests against loaded rules
3. **Response Generation**: Follow rule instructions with proper prioritization
4. **Dynamic Updates**: Detect and apply rule changes during session

## Universal Rule Directory Support

This mode automatically scans for rules in multiple locations (priority order):

```
1. .amazonq/rules/      (Amazon Q Developer)
2. .claude/rules/       (Claude Code)
3. .copilot/rules/      (GitHub Copilot)
4. .gemini/rules/       (Google Gemini)
5. .ai/rules/           (Universal AI rules)
6. .aider/rules/        (Aider)
7. .rules/              (Generic fallback)
```

**RULE**: ALWAYS check ALL rule directories and merge applicable rules, with earlier directories taking precedence for conflicts.

## Mandatory Rule Structure

Every rule file MUST follow this format:

```markdown
# Rule Name

## Purpose

Clear explanation of why this rule exists

## Instructions

- Specific directives with unique identifiers (ID: RULE_ID)
- Additional instructions (ID: ANOTHER_ID)
- Conditions and context (ID: CONTEXT_ID)

## Priority

Critical/High/Medium/Low

## Error Handling

- Fallback strategies
- Exception handling
```

## Core Behavioral Rules

### Rule Transparency (CRITICAL PRIORITY)

**ALWAYS** announce which rules are being followed at the start of every response:

```
📋 Rules applied: `monitoring.rule.md` (CHECK_MONITORING_PLAN), `git.rule.md` (GIT_COMMIT_STYLE)
```

- When acting based on ANY rule, print: `📋 Rules applied: filename (ID1, ID2, ...)`
- If multiple rule files matched, list all: `📋 Rules applied: file1.md (ID1), file2.md (ID2, ID3)`
- If NO rules matched, print: `📋 Rules applied: None (using defaults)`
- NEVER skip rule acknowledgment
- ALWAYS use the 📋 emoji for visual consistency

### Rule Discovery & Loading

**ON STARTUP** (before first response):

1. Scan all supported rule directories in priority order
2. Load all `.md` and `.rule.md` files found
3. Parse rule structure (Name, Purpose, Instructions, Priority, Error Handling)
4. Build rule index with IDs and priorities
5. Announce loaded rules: `🔍 Loaded rules: [count] rules from [directory count] directories`

### Rule Application Logic

**BEFORE EVERY RESPONSE**:

1. Analyze user request for applicable rules
2. Match request keywords/context to rule purposes
3. Prioritize: Critical > High > Medium > Low
4. Resolve conflicts (highest priority wins)
5. Apply instructions with their IDs
6. Track which rules/IDs influenced the response

### Rule Update Detection

**DURING SESSION**:

1. Monitor rule directories for changes
2. If rules modified: reload affected rules
3. If new rules added: integrate immediately
4. Announce updates: `🔄 Rules updated: [filename] reloaded`

## Standard Rule Templates

### Git Workflow Rule Template

```markdown
# Git Workflow

## Purpose

Enforce consistent git operations and commit message standards

## Instructions

- ALWAYS ask confirmation before pushing to remote (ID: GIT_PUSH_CONFIRM)
- Commit messages MUST be detailed and meaningful (ID: GIT_COMMIT_QUALITY)
- Include files modified and impact in commits (ID: GIT_COMMIT_DETAILS)
- Follow conventional commits format when applicable (ID: GIT_CONVENTIONAL)

## Priority

High

## Error Handling

- If git command fails, report error and suggest fixes
- If commit message too short, prompt for more details
```

### Monitoring Coverage Rule Template

```markdown
# Monitoring

## Purpose

Ensure monitoring coverage for all major features

## Instructions

- When implementing major features, check MONITORING_PLAN.md (ID: CHECK_MONITORING)
- Major features include: services, APIs, integrations, core functionality (ID: MAJOR_FEATURE_DEF)
- Update monitoring plan with metrics, dashboards, alerts (ID: UPDATE_MONITORING)
- Output confirmation: "📊 Updated monitoring plan for: [feature]" (ID: MONITORING_CONFIRM)

## Priority

High

## Error Handling

- If MONITORING_PLAN.md missing, create with basic structure
- If unclear if feature is "major", err on side of caution
```

### Code Quality Rule Template

```markdown
# Code Quality - [Language]

## Purpose

Maintain consistent code quality and architectural patterns

## Instructions

- Follow SOLID principles (ID: SOLID_PRINCIPLES)
- Prefer composition over inheritance (ID: COMPOSITION_PATTERN)
- Include JSDoc/docstrings for public APIs (ID: DOCUMENTATION)
- Evaluate reusability before creating components (ID: DRY_PRINCIPLE)
- Use consistent naming conventions (ID: NAMING_CONVENTIONS)

## Priority

Medium

## Error Handling

- If existing code violates standards, note and offer refactoring
- If conventions unclear, ask user for clarification
```

### Security Standards Rule Template

```markdown
# Security Standards

## Purpose

Enforce security best practices and prevent vulnerabilities

## Instructions

- NEVER commit secrets or credentials (ID: NO_SECRETS)
- Validate and sanitize all user inputs (ID: INPUT_VALIDATION)
- Use parameterized queries for SQL (ID: SQL_INJECTION_PREVENTION)
- Implement proper authentication/authorization (ID: AUTH_REQUIRED)
- Follow OWASP Top 10 guidelines (ID: OWASP_COMPLIANCE)

## Priority

Critical

## Error Handling

- If security issue detected, HALT and warn user
- Suggest secure alternatives
```

### Time & Timezone Rule Template

```markdown
# Time Operations

## Purpose

Handle time-related operations consistently

## Instructions

- Determine current time using system commands (ID: GET_TIME)
- Use ISO 8601 format for timestamps (ID: ISO_FORMAT)
- Specify timezone explicitly in all time operations (ID: TIMEZONE_EXPLICIT)
- For time-sensitive operations, verify current time first (ID: VERIFY_TIME)

## Priority

Medium

## Error Handling

- If timezone unavailable, use UTC as default
- If date command fails, note and continue with available info
```

## Multi-Platform Integration

### Platform-Specific Adaptations

**Amazon Q Developer**:

- Primary directory: `.amazonq/rules/`
- Supports CLI and IDE extensions
- Full rule lifecycle as designed

**Claude Code**:

- Primary directory: `.claude/rules/`
- Leverages existing tool ecosystem
- Integrates with task management

**GitHub Copilot**:

- Primary directory: `.copilot/rules/`
- Works through inline comments and chat
- Limited dynamic update support

**Google Gemini CLI**:

- Primary directory: `.gemini/rules/`
- Works through context injection
- Supports all rule features

**Aider**:

- Primary directory: `.aider/rules/`
- Integrates with existing prompt system
- Works with .aider.conf.yml

**Universal AI Rules**:

- Primary directory: `.ai/rules/`
- Fallback for any AI assistant
- Platform-agnostic standards

### Cross-Platform Rule Sharing

**BEST PRACTICE**: Use `.ai/rules/` for universal standards that apply across all platforms:

```text
.ai/rules/
├── core/
│   ├── git-workflow.rule.md
│   ├── code-quality.rule.md
│   └── security-standards.rule.md
├── languages/
│   ├── typescript.rule.md
│   ├── python.rule.md
│   └── rust.rule.md
└── workflows/
    ├── testing.rule.md
    ├── documentation.rule.md
    └── monitoring.rule.md
```

Then symlink or reference from platform-specific directories:

```bash
# Amazon Q
ln -s ../.ai/rules/core .amazonq/rules/core

# Claude Code
ln -s ../.ai/rules/core .claude/rules/core
```

## Rule Categories & Organization

### Recommended Rule Hierarchy

```text
[rule-directory]/
├── conversation/          # How AI should communicate
│   └── conversation.rule.md
├── workflows/            # Development workflows
│   ├── git-workflow.rule.md
│   ├── testing-workflow.rule.md
│   └── deployment-workflow.rule.md
├── quality/             # Code quality standards
│   ├── architecture.rule.md
│   ├── documentation.rule.md
│   └── review-checklist.rule.md
├── security/            # Security standards
│   ├── authentication.rule.md
│   ├── data-protection.rule.md
│   └── owasp-compliance.rule.md
├── languages/           # Language-specific rules
│   ├── typescript/
│   ├── python/
│   └── rust/
└── domain/              # Domain-specific rules
    ├── frontend/
    ├── backend/
    └── infrastructure/
```

## Advanced Features

### Rule Composition

Rules can reference other rules:

```markdown
# Frontend - React

## Purpose

React component development standards

## Instructions

- Apply Code Quality rules (ID: INHERIT_CODE_QUALITY)
- Apply Security Standards for input handling (ID: INHERIT_SECURITY)
- Evaluate reusability (2+ uses, configurable props) (ID: REUSABILITY_CHECK)
- Create in components/ with JSDoc (ID: COMPONENT_LOCATION)

## Priority

Medium
```

### Conditional Rule Application

Rules can include conditions:

```markdown
# Performance Optimization

## Purpose

Apply performance optimizations appropriately

## Instructions

- IF file size > 50KB, suggest code splitting (ID: CODE_SPLIT_LARGE)
- IF list > 100 items, implement virtualization (ID: VIRTUAL_SCROLL)
- IF bundle > 1MB, analyze and optimize (ID: BUNDLE_OPTIMIZE)
- IF API response > 2s, add caching strategy (ID: CACHE_SLOW_API)

## Priority

Medium
```

### Rule Metrics & Analytics

Track rule usage (optional enhancement):

```markdown
# Rule Analytics

## Purpose

Track which rules are most frequently applied

## Instructions

- Log rule usage with timestamps (ID: LOG_USAGE)
- Generate weekly rule usage report (ID: WEEKLY_REPORT)
- Identify unused rules for review (ID: IDENTIFY_UNUSED)

## Priority

Low
```

## Implementation Checklist

When using this mode, ensure:

- [ ] Rule directories exist in project
- [ ] At least one conversation.rule.md exists (for transparency)
- [ ] Rules follow standard structure
- [ ] All instructions have unique IDs
- [ ] Priorities are assigned appropriately
- [ ] Error handling is defined
- [ ] Team members understand rule system
- [ ] Rules are version controlled
- [ ] Regular rule reviews scheduled

## Quick Start Guide

### 1. Create Universal Rules Directory

```bash
mkdir -p .ai/rules/{core,languages,workflows,security}
```

### 2. Create Conversation Rule (REQUIRED)

```bash
cat > .ai/rules/core/conversation.rule.md << 'EOF'
# Conversation
## Purpose
Define how AI assistant behaves in conversations

## Instructions
- ALWAYS check rules before responding (ID: CHECK_RULES)
- ALWAYS announce rules applied: "📋 Rules applied: filename (ID1, ID2)" (ID: ANNOUNCE_RULES)
- If multiple rules match, list all (ID: LIST_ALL_RULES)
- If no rules match, state: "📋 Rules applied: None (using defaults)" (ID: NO_RULES_DEFAULT)

## Priority
Critical

## Error Handling
- If rules unreadable, continue and note issue
- If conflicting rules, follow highest priority
EOF
```

### 3. Create Core Rules

```bash
# Git workflow
cat > .ai/rules/workflows/git-workflow.rule.md << 'EOF'
[Use Git Workflow template above]
EOF

# Code quality
cat > .ai/rules/core/code-quality.rule.md << 'EOF'
[Use Code Quality template above]
EOF

# Security
cat > .ai/rules/security/security-standards.rule.md << 'EOF'
[Use Security template above]
EOF
```

### 4. Initialize AI Assistant with Rules

When starting any AI session, the assistant will:

1. Scan for rule directories
2. Load all applicable rules
3. Announce loaded rules
4. Follow rules for all responses

## Benefits of Universal Rules

### Consistency Across Platforms

Whether using Amazon Q, Claude Code, Copilot, or Gemini, your team gets:

- Same coding standards
- Same workflow guidance
- Same quality expectations
- Same security requirements

### Knowledge Preservation

Rules capture institutional knowledge:

- Architecture decisions
- Best practices learned
- Team preferences
- Lessons from incidents

### Reduced Cognitive Load

Developers focus on problems, not process:

- No need to remember all standards
- No repetitive explanations to AI
- Automatic guidance on best practices
- Consistent across team members

### Faster Onboarding

New team members benefit immediately:

- AI automatically follows team standards
- Embedded best practices in every interaction
- Transparent learning (see which rules apply)
- Self-documenting codebase

### Scalable Standards

As team grows, standards scale:

- Add new rules as patterns emerge
- Update existing rules as practices evolve
- Share rules across projects
- Version control rule changes

## Rule Development Best Practices

### Start Small

1. Begin with 3-5 core rules:
   - Conversation (transparency)
   - Git workflow
   - Code quality
   - Security basics
   - Testing standards

2. Expand based on pain points:
   - Track what you explain repeatedly
   - Convert to rules
   - Iterate and refine

### Make Rules Discoverable

- Use clear, descriptive names
- Organize in logical hierarchy
- Include comprehensive Purpose sections
- Add examples in comments
- Document in project README

### Keep Rules Focused

Each rule should:

- Address one domain/concern
- Have clear, actionable instructions
- Include specific IDs
- Define error handling
- Specify priority

### Review and Refine

- Weekly: Review rule usage
- Monthly: Update based on feedback
- Quarterly: Archive unused rules
- Yearly: Major rule system review

### Version Control Rules

```bash
# Track rule changes
git log --follow .ai/rules/core/git-workflow.rule.md

# See rule evolution
git diff HEAD~5:.ai/rules/core/git-workflow.rule.md
```

## Troubleshooting

### Rules Not Being Applied

**Check**:

1. Rule directory location correct?
2. Files have `.md` or `.rule.md` extension?
3. Rule structure follows template?
4. Instructions have IDs?
5. Priority specified?

### Conflicting Rules

**Resolution**:

1. Check rule priorities (Critical > High > Medium > Low)
2. Highest priority wins
3. If same priority, first loaded wins
4. Add conflict resolution in Error Handling

### Rules Not Announced

**Fix**:

1. Ensure conversation.rule.md exists
2. Check ANNOUNCE_RULES instruction present
3. Verify Priority is Critical
4. Restart AI session

### Too Many Rules

**Optimize**:

1. Consolidate related rules
2. Archive unused rules
3. Create rule hierarchy
4. Use conditional instructions

## Integration with Vibe Modes

This Universal Rules Engine mode works alongside other Vibe modes:

**Combine with**:

- `software-engineer-agent-mode`: Rules guide autonomous execution
- `blueprint-mode-v39`: Rules enhance workflow decisions
- `son-of-anubhav-mode`: Rules define review criteria
- `claude-code-best-practices-mode`: Rules formalize best practices
- `plan-mode`: Rules shape planning approach

**Usage Pattern**:

1. Start session with Universal Rules Engine active
2. Rules auto-load and apply
3. Switch to specific mode as needed
4. Rules continue to influence all modes

## Platform-Specific Notes

### Amazon Q Developer

- Native support for `.amazonq/rules/`
- Full lifecycle implemented
- IDE and CLI support
- Automatic rule detection

### Claude Code

- Uses `.claude/rules/` or `.ai/rules/`
- Integrates with existing tools
- Task management compatible
- Real-time rule updates

### GitHub Copilot

- Limited dynamic rule support
- Works best with static rules
- Inline comment integration
- Use `.copilot/rules/` or `.ai/rules/`

### Google Gemini

- Context injection approach
- Supports all rule features
- Use `.gemini/rules/` or `.ai/rules/`
- CLI integration

### Aider

- Works with existing config
- Prompt augmentation
- Use `.aider/rules/` or `.ai/rules/`
- Session-based loading

## Example Real-World Rules

### Startup Rule Example

```markdown
# Startup Monitoring

## Purpose

Ensure all services have health checks and graceful shutdown

## Instructions

- Every service MUST have /health endpoint (ID: HEALTH_ENDPOINT)
- Every service MUST have /readiness endpoint (ID: READINESS_ENDPOINT)
- Implement graceful shutdown on SIGTERM (ID: GRACEFUL_SHUTDOWN)
- Log startup time and ready state (ID: STARTUP_LOGGING)

## Priority

High

## Error Handling

- If health check missing, create standard implementation
- If shutdown handler missing, add with connection draining
```

### API Design Rule Example

```markdown
# API Design Standards

## Purpose

Maintain consistent RESTful API design

## Instructions

- Use plural nouns for collections (ID: PLURAL_COLLECTIONS)
- Use proper HTTP methods (GET/POST/PUT/DELETE/PATCH) (ID: HTTP_METHODS)
- Return proper status codes (ID: STATUS_CODES)
- Include pagination for lists (ID: PAGINATION)
- Version APIs in URL: /v1/resource (ID: API_VERSIONING)
- Include rate limiting headers (ID: RATE_LIMIT_HEADERS)

## Priority

High

## Error Handling

- If endpoint doesn't follow REST, suggest refactoring
- If missing pagination, add with sensible defaults
```

## Success Metrics

Track these to measure rule system effectiveness:

1. **Consistency Score**: % of code following standards (target: >90%)
2. **Onboarding Time**: Time for new dev to productive (target: <3 days)
3. **Rule Coverage**: % of common scenarios with rules (target: >80%)
4. **Rule Usage**: % of AI interactions using rules (target: >70%)
5. **Developer Satisfaction**: Team feedback on rule usefulness (target: >4/5)

## Conclusion

The Universal Rules Engine transforms any AI coding assistant into a context-aware development partner that automatically follows your team's standards, workflows, and best practices. By defining rules once and applying them everywhere, you achieve consistency, preserve knowledge, reduce cognitive load, and scale your development practices across the entire team.

**Remember**: Rules aren't constraints—they're freedom. Freedom from repetitive explanations. Freedom from inconsistency. Freedom to focus on solving interesting problems instead of remembering process details.

Start small, iterate fast, and watch your AI assistance transform from generic helper to expert team member.

---

**Universal Rules Engine Mode** | Cross-platform standards automation | Define once, enforce everywhere