[Feature] Enhanced AI Rules System with Directory-Based Organization

[Heziode]

Enhanced AI Rules System with Directory-Based Organization

Summary

Enhance Void's AI rules system by introducing a modern directory-based approach similar to Cursor and Windsurf, while maintaining backward compatibility with the existing single-file approach mentioned in issue #227.

Current State

Based on issue #227, Void currently supports a single rule file approach. While this works for basic use cases, it lacks the flexibility and organization needed for complex projects and modern development workflows.

Proposed Enhancement

Directory-Based Rules System

Implement a new .void/rules/ directory structure that allows developers to:

1. Organize rules by scope and context

   project/
   ├── .void/
   │   └── rules/
   │       ├── global.md              # Project-wide rules
   │       ├── backend/
   │       │   ├── api-standards.md   # Backend-specific rules
   │       │   └── database.md        # Database-related rules
   │       ├── frontend/
   │       │   ├── react-patterns.md  # React component rules
   │       │   └── styling.md         # CSS/styling rules
   │       └── testing/
   │           └── standards.md       # Testing guidelines
   

2. Support multiple rule types

   • Always Applied: Rules that are included in every AI interaction
   • Context-Sensitive: Rules applied based on file patterns or project context
   • On-Demand: Rules that can be manually invoked or referenced

3. Modern rule format (inspired by Cursor's .mdc format)

   ---
   description: "React component development guidelines"
   globs: ["**/*.tsx", "**/*.jsx"]
   priority: high
   auto_apply: true
   ---
   
   # React Development Rules
   
   ## Component Standards
   - Use functional components with hooks
   - Implement proper TypeScript interfaces
   - Follow naming conventions: PascalCase for components
   
   ## File References
   @tsconfig.json
   @src/types/common.ts
   
   ## Code Examples
   ```tsx
   // Preferred component structure
   interface ComponentProps {
     title: string;
     children: React.ReactNode;
   }
   
   export const MyComponent: React.FC<ComponentProps> = ({ title, children }) => {
     return <div>{title}{children}</div>;
   };
   ```
   

Key Features

1. Hierarchical Rule Application

• Rules can be organized in nested directories
• Child directory rules inherit and can override parent rules
• Clear precedence system for rule conflicts

2. Smart Context Awareness

• Automatic rule selection based on:
  • File patterns (glob matching)
  • Current working directory
  • File types being edited
  • Project structure analysis

3. Rule Management Interface

• Command palette integration: "Void: New Rule", "Void: Edit Rules"
• Rules explorer in sidebar showing active/inactive rules
• Visual indicators for applied rules in status bar

4. Team Collaboration Features

• Version control friendly (rules stored as markdown files)
• Shared team rules through git
• Rule templates and sharing system

Implementation Strategy

Phase 1: Core Infrastructure

• [ ] Create .void/rules/ directory structure
• [ ] Implement rule parser for markdown format with frontmatter
• [ ] Add glob pattern matching for context-sensitive rules
• [ ] Create rule management service

Phase 2: Integration

• [ ] Integrate with existing AI system (chat, autocomplete, agent mode)
• [ ] Add command palette commands for rule management
• [ ] Implement rule precedence and inheritance system

Phase 3: User Experience

• [ ] Create rules explorer UI component
• [ ] Add rule status indicators
• [ ] Implement rule templates and quick-start guides

Phase 4: Advanced Features

• [ ] Rule performance analytics
• [ ] Smart rule suggestions based on project analysis
• [ ] Integration with community rule sharing

Backward Compatibility

To ensure smooth migration from issue #227's single-file approach:

1. Continue supporting existing formats:

   • Legacy single-file configurations .voidrules

2. Automatic migration tool:

   • Convert existing rule files to new directory structure
   • Provide migration assistant in settings

3. Graceful fallback:

   • If .void/rules/ doesn't exist, fall back to legacy format
   • Clear documentation for migration path

Benefits

For Individual Developers

• Better Organization: Rules organized by context and scope
• Improved Maintainability: Easier to update and manage rules
• Enhanced Productivity: Context-aware rule application reduces cognitive load

For Teams

• Consistency: Shared rules ensure consistent AI behavior across team
• Collaboration: Version-controlled rules enable team collaboration
• Scalability: Hierarchical system scales with project complexity

For Complex Projects

• Monorepo Support: Different rules for different parts of the codebase
• Context Sensitivity: Rules applied based on current working context
• Flexibility: Mix of always-applied and context-specific rules

Technical Considerations

File Format

• Use Markdown with YAML frontmatter (similar to Cursor's .mdc format)
• Support for file references (@filename.ext)
• Code examples with syntax highlighting

Performance

• Lazy loading of rules
• Caching system for frequently used rules
• Incremental parsing for large rule sets

Security

• Validate rule content to prevent malicious code injection
• Sandboxed rule execution environment
• User permission system for global vs project rules

Documentation & Examples

Provide comprehensive documentation including:

• Migration guide from single-file system
• Rule writing best practices
• Template library for common scenarios
• Integration examples for popular frameworks

Testing Strategy

• Unit tests for rule parsing and application logic
• Integration tests with AI system
• Performance benchmarks for large rule sets
• User acceptance testing for migration scenarios

---

This enhancement positions Void as a competitive alternative to Cursor and Windsurf while maintaining its open-source values and providing superior flexibility for complex development workflows.

[andrewpareles]

project/
├── .void/
│   └── rules/
│       ├── global.md              # Project-wide rules
│       ├── backend/
│       │   ├── api-standards.md   # Backend-specific rules
│       │   └── database.md        # Database-related rules
│       ├── frontend/
│       │   ├── react-patterns.md  # React component rules
│       │   └── styling.md         # CSS/styling rules
│       └── testing/
│           └── standards.md       # Testing guidelines

Implementing something like this is the same as just having a docs/ folder and telling the LLM to look at the relevant parts of it using tools. Not sure there's anything for us to do, we already have this functionality.

[Heziode]

Here the goal is doing it automatically by setting a trigger mode (manual, automatic (IA Choose), pattern, etc). If you think it is not relevant, you can close the issue ;)

[RPainter8West]

I would love it if there could be a configuration that worked across editors. Instead of .void or .cursor at the root of the project, have a generic .ai/rules folder so when I'm on a team of people with different editors, we could share our project rules.

If void allowed for configuring the folder(s) where rules are found, then this would be a start.

[chirino]

Why not just adopt the cursor style so that we avoid inventing yet another rule format?

[0x101011]

Its Necessary methods to support large-scale engineering，we need it badly