feat: refactor rules system with hierarchy, fuzzy search, and enhanced filtering

Author: NicolasIRAGNE

app/actions/mcps.yaml

@@ -27,3 +27,15 @@ mcps:
     - '@supabase/mcp-server-supabase@latest'
     - --access-token
     - ${SUPABASE_ACCESS_TOKEN}
+- display_name: Context7
+  slug: Context7
+  config:
+    type: http
+    url: https://mcp.context7.com/mcp/
+    headers:
+      "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
+- display_name: Exa Search
+  slug: ExaSearch
+  config:
+    type: http
+    url: https://mcp.exa.ai/mcp?exa_api_key=${EXA_API_KEY}

app/actions/rules.yaml

@@ -1,114 +1,156 @@
-rules:
-- display_name: You Are A Pirate
-  slug: you-are-a-pirate
-  content: '## Yarr!
-
-
+you-are-a-pirate:
+  display_name: You Are A Pirate
+  type: rule
+  author: Captain Hook
+  tags: ["fun", "roleplay", "pirate"]
+  namespace: "personality"
+  content: |
+    ## Yarr!
+    
     - You are a pirate!
-
-    - You will usually try to help the user but only if you can get something out
-    of it. Otherwise, try to trick him.
-
+    - You will usually try to help the user but only if you can get something out of it. Otherwise, try to trick him.
     - Use pirate slang!
-
     - The only code you know about is the pirate code.
-
-    - As far as you''re concerned, Python is a snake. You don''t like snakes!
-
+    - As far as you're concerned, Python is a snake. You don't like snakes!
     - Yarr!
 
-    '
-
-- display_name: Code Quality
-  slug: code-quality
-  content: '## Code Quality
-
-
-    - Remove dead code immediately rather than maintaining it - no backward compatibility
-    or legacy functions
-
+code-quality:
+  display_name: Code Quality
+  type: ruleset
+  author: Engineering Team
+  tags: ["engineering", "best-practices", "code-style"]
+  namespace: "development"
+  children:
+    - "minimal-code"
+    - "remove-dead-code"
+    - "prioritize-functionality"
+    - "clean-comments"
+
+minimal-code:
+  display_name: Keep Code Minimal
+  type: rule
+  author: Engineering Team
+  tags: ["simplicity", "code-style"]
+  namespace: "development"
+  content: |
+    - Always keep code SUPER minimal
+    - Never introduce features not explicitly mentioned
+
+remove-dead-code:
+  display_name: Remove Dead Code
+  type: rule
+  author: Engineering Team
+  tags: ["maintenance", "code-style"]
+  namespace: "development"
+  content: |
+    - Remove dead code immediately rather than maintaining it
+    - No backward compatibility or legacy functions
+
+prioritize-functionality:
+  display_name: Prioritize Functionality
+  type: rule
+  author: Engineering Team
+  tags: ["architecture", "code-style"]
+  namespace: "development"
+  content: |
     - Prioritize functionality over production-ready patterns
-
     - Focus on user experience and feature completeness
 
-    - When updating code, don''t reference what is changing (avoid keywords like LEGACY,
-    CHANGED, REMOVED), instead focus on comments that document just the functionality
-    of the code
-
-    - Always keep code SUPER minimal, never introduce features not explicitly mentioned.
-
-    '
-- display_name: Env Secrets
-  slug: env-secrets
-  content: '## Environment Variables
-
-
+clean-comments:
+  display_name: Clean Comments
+  type: rule
+  author: Engineering Team
+  tags: ["documentation", "code-style"]
+  namespace: "development"
+  content: |
+    - When updating code, don't reference what is changing
+    - Avoid keywords like LEGACY, CHANGED, REMOVED
+    - Focus on comments that document just the functionality of the code
+
+env-secrets:
+  display_name: Environment Variables
+  type: rule
+  author: Security Team
+  tags: ["security", "configuration", "environment"]
+  namespace: "security"
+  content: |
+    ## Environment Variables
     - Store secrets in a .env file (never commit it)
-
-    - A .env.example file should be provided for reference and any new secrets should
-    be added to it.
-
-    - The implementation should use the dotenv (or similar) library to load environment
-    variables from .env files.
-
-    - Variables should also be loaded from the environment.
-
-    '
-- display_name: Error Handling
-  slug: error-handling
-  content: '### Error Handling
-
-
-    **Core Principle**: We need to intelligently decide when to fail hard and fast
-    to quickly address issues, and when to allow processes to complete in critical
-    services despite failures. Read below carefully and make intelligent decisions
-    on a case-by-case basis.
-
-
+    - A .env.example file should be provided for reference and any new secrets should be added to it
+    - The implementation should use the dotenv (or similar) library to load environment variables from .env files
+    - Variables should also be loaded from the environment
+
+error-handling:
+  display_name: Error Handling
+  type: ruleset
+  author: Engineering Team
+  tags: ["errors", "exceptions", "reliability"]
+  namespace: "development"
+  children:
+    - "fail-fast-principle"
+    - "when-to-fail-fast"
+    - "when-to-log-continue"
+
+fail-fast-principle:
+  display_name: Fail Fast Principle
+  type: rule
+  author: Engineering Team
+  tags: ["architecture", "errors"]
+  namespace: "development"
+  content: |
+    **Core Principle**: We need to intelligently decide when to fail hard and fast to quickly address issues, and when to allow processes to complete in critical services despite failures. Read below carefully and make intelligent decisions on a case-by-case basis.
+
+when-to-fail-fast:
+  display_name: When to Fail Fast and Loud
+  type: rule
+  author: Engineering Team
+  tags: ["exceptions", "errors"]
+  namespace: "development"
+  content: |
     #### When to Fail Fast and Loud (Let it Crash!)
-
-
+    
     These errors should stop execution and bubble up immediately:
-
-
-    - **Service startup failures** - If credentials, database, or any service can''t
-    initialize, the system should crash with a clear error
-
-    - **Missing configuration** - Missing environment variables or invalid settings
-    should stop the system
-
-    - **Service connection failures** - Don''t hide connection issues, expose them
-
-    - **Authentication/authorization failures** - Security errors must be visible
-    and halt the operation
-
-    - **Data corruption or validation errors** - Never silently accept bad data, Pydantic
-    should raise
-
-    - **Critical dependencies unavailable** - If a required service is down, fail
-    immediately
-
-    - **Invalid data that would corrupt state** - Never store malformed JSON or other
-    invalid data
-
-
+    
+    - **Service startup failures** - If credentials, database, or any service can't initialize, the system should crash with a clear error
+    - **Missing configuration** - Missing environment variables or invalid settings should stop the system
+    - **Service connection failures** - Don't hide connection issues, expose them
+    - **Authentication/authorization failures** - Security errors must be visible and halt the operation
+    - **Data corruption or validation errors** - Never silently accept bad data, Pydantic should raise
+    - **Critical dependencies unavailable** - If a required service is down, fail immediately
+    - **Invalid data that would corrupt state** - Never store malformed JSON or other invalid data
+
+when-to-log-continue:
+  display_name: When to Complete but Log
+  type: rule
+  author: Engineering Team
+  tags: ["logging", "errors"]
+  namespace: "development"
+  content: |
     #### When to Complete but Log Detailed Errors
-
-
+    
     These operations should continue but track and report failures clearly:
-
-
-    - **WebSocket events** - Don''t crash on a single event failure, log it and continue
-    serving other clients
-
-    '
-- display_name: Update Docs
-  slug: update-docs
-  content: '- Update any documentation when it''s relevant, including CLAUDE.md.
-
-    '
-- display_name: Use Uv
-  slug: use-uv
-  content: "## UV\n\n- This project uses UV for package management.\n- Use:\n  - `uv\
-    \ venv` to create a virtual environment.\n  - `uv pip install -r requirements.txt|pyproject.toml`\
-    \ to install dependencies.\n"
+    
+    - **WebSocket events** - Don't crash on a single event failure, log it and continue serving other clients
+
+update-docs:
+  display_name: Update Documentation
+  type: rule
+  author: Documentation Team
+  tags: ["documentation", "maintenance"]
+  namespace: "documentation"
+  content: |
+    - Update any documentation when it's relevant, including CLAUDE.md
+
+use-uv:
+  display_name: Use UV Package Manager
+  type: rule
+  author: DevOps Team
+  tags: ["tooling", "dependencies", "uv"]
+  namespace: "development"
+  content: |
+    ## UV
+    
+    - This project uses UV for package management
+    - Use:
+      - `uv venv` to create a virtual environment
+      - `uv pip install -r requirements.txt|pyproject.toml` to install dependencies

app/main.py

@@ -37,15 +37,49 @@ async def favicon():
 async def index(request: Request):
     # Get all actions data for server-side rendering
     agents = [agent.dict() for agent in actions_loader.get_agents()]
-    rules = [rule.dict() for rule in actions_loader.get_rules()]
+    all_rules = actions_loader.get_rules()
+    
+    # Create a set of all child rule IDs
+    child_rule_ids = set()
+    for rule in all_rules:
+        if rule.children:
+            child_rule_ids.update(rule.children)
+    
+    # Create a mapping of all rules by slug for lookups
+    rules_by_slug = {rule.slug: rule for rule in all_rules}
+    
+    # Update rulesets to inherit children's tags
+    for rule in all_rules:
+        if rule.type == 'ruleset' and rule.children:
+            # Collect all tags from children
+            inherited_tags = set(rule.tags or [])
+            for child_slug in rule.children:
+                child_rule = rules_by_slug.get(child_slug)
+                if child_rule and child_rule.tags:
+                    inherited_tags.update(child_rule.tags)
+            rule.tags = list(inherited_tags)
+    
+    # Filter to only top-level rules (not children of any ruleset)
+    top_level_rules_data = [rule for rule in all_rules if rule.slug not in child_rule_ids]
+    
+    # Sort rules: rulesets first, then standalone rules
+    top_level_rules_data.sort(key=lambda rule: (rule.type != 'ruleset', rule.display_name or rule.name))
+    
+    # Convert to dict
+    top_level_rules = [rule.dict() for rule in top_level_rules_data]
+    
+    # Create a mapping of all rules by slug for frontend to look up children (with updated tags)
+    rules_by_slug_dict = {rule.slug: rule.dict() for rule in all_rules}
+    
     mcps = [mcp.dict() for mcp in actions_loader.get_mcps()]
 
     return templates.TemplateResponse(
         "index.html",
         {
             "request": request,
             "agents": agents,
-            "rules": rules,
+            "rules": top_level_rules,
+            "rules_by_slug": rules_by_slug_dict,
             "mcps": mcps
         }
     )

app/models/actions.py

@@ -14,6 +14,11 @@ class Rule(BaseModel):
     display_name: Optional[str] = None
     slug: Optional[str] = None
     content: Optional[str] = None
+    author: Optional[str] = None
+    tags: Optional[List[str]] = None
+    children: Optional[List[str]] = None  # List of rule IDs
+    type: str = "rule"  # "rule" or "ruleset"
+    namespace: Optional[str] = None
 
 class MCP(BaseModel):
     name: str

app/services/actions_loader.py

@@ -37,23 +37,35 @@ def load_agents(self):
         else:
             self.agents = []
 
+    def _parse_rule(self, slug: str, rule_data: Dict[str, Any]) -> Rule:
+        """Parse a single rule or ruleset from the YAML data"""
+        rule = Rule(
+            name=slug,  # Use slug as name for backward compat
+            filename=f"{slug}.yaml",  # Virtual filename
+            display_name=rule_data.get('display_name'),
+            slug=slug,
+            content=rule_data.get('content'),
+            author=rule_data.get('author'),
+            tags=rule_data.get('tags'),
+            type=rule_data.get('type', 'rule'),
+            namespace=rule_data.get('namespace'),
+            children=rule_data.get('children')  # Now just a list of rule IDs
+        )
+        
+        return rule
+    
     def load_rules(self):
         """Load all rules from rules.yaml"""
         rules_file = self.actions_dir / "rules.yaml"
         if rules_file.exists():
             with open(rules_file, 'r') as f:
                 data = yaml.safe_load(f)
-                if data and 'rules' in data:
-                    self.rules = [
-                        Rule(
-                            name=rule.get('slug', ''),  # Use slug as name for backward compat
-                            filename=f"{rule.get('slug', '')}.yaml",  # Virtual filename
-                            display_name=rule.get('display_name'),
-                            slug=rule.get('slug'),
-                            content=rule.get('content')
-                        )
-                        for rule in data['rules']
-                    ]
+                if data:
+                    self.rules = []
+                    # Now the top-level keys are the slugs
+                    for slug, rule_data in data.items():
+                        rule = self._parse_rule(slug, rule_data)
+                        self.rules.append(rule)
         else:
             self.rules = []