llm-ide-rules 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

llm_ide_rules/__init__.py

@@ -12,9 +12,18 @@ from llm_ide_rules.commands.explode import explode_main
 from llm_ide_rules.commands.implode import cursor, github, claude, gemini, opencode
 from llm_ide_rules.commands.download import download_main
 from llm_ide_rules.commands.delete import delete_main
+from llm_ide_rules.commands.config import config_main
 from llm_ide_rules.commands.mcp import mcp_app
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
+
+
+def version_callback(value: bool):
+    """Callback to display the version and exit."""
+    if value:
+        print(f"llm-ide-rules version {__version__}")
+        raise typer.Exit()
+
 
 app = typer.Typer(
     name="llm_ide_rules",
@@ -31,6 +40,15 @@ def main_callback(
             "--verbose", "-v", help="Enable verbose logging (sets LOG_LEVEL=DEBUG)"
         ),
     ] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            help="Show the version and exit",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = None,
 ):
     """Global CLI options."""
     if verbose:
@@ -48,6 +66,7 @@ app.command("download", help="Download LLM instruction files from GitHub reposit
     download_main
 )
 app.command("delete", help="Remove downloaded LLM instruction files")(delete_main)
+app.command("config", help="Configure agents to use AGENTS.md")(config_main)
 
 # Create implode sub-typer
 implode_app = typer.Typer(help="Bundle rule files into a single instruction file")

llm_ide_rules/agents/__init__.py

@@ -6,6 +6,8 @@ from llm_ide_rules.agents.github import GitHubAgent
 from llm_ide_rules.agents.claude import ClaudeAgent
 from llm_ide_rules.agents.gemini import GeminiAgent
 from llm_ide_rules.agents.opencode import OpenCodeAgent
+from llm_ide_rules.agents.agents import AgentsAgent
+from llm_ide_rules.agents.vscode import VSCodeAgent
 
 AGENTS: dict[str, type[BaseAgent]] = {
     "cursor": CursorAgent,
@@ -13,6 +15,8 @@ AGENTS: dict[str, type[BaseAgent]] = {
     "claude": ClaudeAgent,
     "gemini": GeminiAgent,
     "opencode": OpenCodeAgent,
+    "agents": AgentsAgent,
+    "vscode": VSCodeAgent,
 }
 
 

llm_ide_rules/agents/agents.py

@@ -0,0 +1,124 @@
+"""Agents documentation agent implementation."""
+
+from pathlib import Path
+import typer
+
+from llm_ide_rules.agents.base import BaseAgent
+
+
+class AgentsAgent(BaseAgent):
+    """Agent for generating AGENTS.md documentation."""
+
+    name = "agents"
+    rules_dir = None
+    commands_dir = None
+    rule_extension = None
+    command_extension = None
+
+    mcp_global_path = None
+    mcp_project_path = None
+
+    def bundle_rules(
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
+    ) -> bool:
+        """Agents doesn't support bundling rules."""
+        return False
+
+    def bundle_commands(
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
+    ) -> bool:
+        """Agents doesn't support bundling commands."""
+        return False
+
+    def write_rule(
+        self,
+        content_lines: list[str],
+        filename: str,
+        rules_dir: Path,
+        glob_pattern: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        """Agents doesn't support writing rules."""
+        pass
+
+    def write_command(
+        self,
+        content_lines: list[str],
+        filename: str,
+        commands_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """Agents doesn't support writing commands."""
+        pass
+
+    def generate_root_doc(
+        self,
+        general_lines: list[str],
+        rules_sections: dict[str, list[str]],
+        command_sections: dict[str, list[str]],
+        output_dir: Path,
+        section_globs: dict[str, str | None] | None = None,
+    ) -> None:
+        """Generate AGENTS.md files, potentially distributed based on globs."""
+        if not section_globs:
+            # Fallback to single root AGENTS.md
+            content = self.build_root_doc_content(general_lines, rules_sections)
+            if content.strip():
+                (output_dir / "AGENTS.md").write_text(content)
+            return
+
+        # Group rules by target directory
+        rules_by_dir: dict[Path, dict[str, list[str]]] = {}
+
+        # Always include root directory for rules without specific directory targets
+        rules_by_dir[output_dir] = {}
+
+        for section_name, lines in rules_sections.items():
+            target_dir = output_dir
+            glob_pattern = section_globs.get(section_name)
+
+            if glob_pattern and "**" in glob_pattern:
+                # Extract path before **
+                prefix = glob_pattern.split("**")[0].strip("/")
+                potential_dir = output_dir / prefix
+
+                # Check if directory exists, if not traverse up
+                check_dir = potential_dir
+                while not check_dir.exists() and check_dir != output_dir:
+                    check_dir = check_dir.parent
+
+                if check_dir != potential_dir:
+                    # We fell back
+                    if check_dir == output_dir:
+                        # Only warn if falling back to root from a deep path
+                        pass
+
+                    # We can log this if we want, but simple traversal is fine.
+                    # The requirement says "warn to the user".
+                    rel_potential = potential_dir.relative_to(output_dir)
+                    rel_actual = check_dir.relative_to(output_dir)
+                    typer.secho(
+                        f"Warning: Directory '{rel_potential}' for section '{section_name}' does not exist. "
+                        f"Placing in '{rel_actual}' instead.",
+                        fg=typer.colors.YELLOW,
+                        err=True,
+                    )
+
+                target_dir = check_dir
+
+            if target_dir not in rules_by_dir:
+                rules_by_dir[target_dir] = {}
+
+            rules_by_dir[target_dir][section_name] = lines
+
+        # Generate AGENTS.md for each directory
+        for target_dir, sections in rules_by_dir.items():
+            if not sections:
+                continue
+
+            # Only include general instructions in the root AGENTS.md
+            current_general_lines = general_lines if target_dir == output_dir else []
+
+            content = self.build_root_doc_content(current_general_lines, sections)
+            if content.strip():
+                (target_dir / "AGENTS.md").write_text(content)

llm_ide_rules/agents/base.py

@@ -23,14 +23,14 @@ class BaseAgent(ABC):
 
     @abstractmethod
     def bundle_rules(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle rule files into a single output file."""
         ...
 
     @abstractmethod
     def bundle_commands(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle command files into a single output file."""
         ...
@@ -42,6 +42,7 @@ class BaseAgent(ABC):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """Write a single rule file."""
         ...
@@ -57,6 +58,49 @@ class BaseAgent(ABC):
         """Write a single command file."""
         ...
 
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """Configure the agent to use AGENTS.md as context (default: no-op).
+
+        Returns:
+            bool: True if configuration was applied, False otherwise.
+        """
+        return False
+
+    def generate_root_doc(
+        self,
+        general_lines: list[str],
+        rules_sections: dict[str, list[str]],
+        command_sections: dict[str, list[str]],
+        output_dir: Path,
+        section_globs: dict[str, str | None] | None = None,
+    ) -> None:
+        """Generate a root documentation file (e.g. CLAUDE.md) if supported."""
+        pass
+
+    def build_root_doc_content(
+        self,
+        general_lines: list[str],
+        rules_sections: dict[str, list[str]],
+    ) -> str:
+        """Build the content string for a root documentation file by aggregating rules."""
+        content = []
+
+        # Add general instructions
+        if general_lines:
+            trimmed = trim_content(general_lines)
+            if trimmed:
+                content.extend(trimmed)
+                content.append("\n\n")
+
+        # Add sections in document order (dict maintains insertion order in Python 3.7+)
+        for section_name, lines in rules_sections.items():
+            trimmed = trim_content(lines)
+            if trimmed:
+                content.extend(trimmed)
+                content.append("\n\n")
+
+        return "".join(content).strip() + "\n" if content else ""
+
     def get_rules_path(self, base_dir: Path) -> Path:
         """Get the full path to the rules directory."""
         if not self.rules_dir:
@@ -155,9 +199,15 @@ def strip_toml_metadata(text: str) -> str:
 
 
 def get_ordered_files(
-    file_list: list[Path], section_globs_keys: list[str]
+    file_list: list[Path], section_globs_keys: list[str] | None = None
 ) -> list[Path]:
-    """Order files based on section_globs key order, with unmapped files at the end."""
+    """Order files based on section_globs key order, with unmapped files at the end.
+
+    If section_globs_keys is None, returns files sorted alphabetically.
+    """
+    if not section_globs_keys:
+        return sorted(file_list, key=lambda p: p.name)
+
     file_dict = {f.stem: f for f in file_list}
     ordered_files = []
 
@@ -174,9 +224,15 @@ def get_ordered_files(
 
 
 def get_ordered_files_github(
-    file_list: list[Path], section_globs_keys: list[str]
+    file_list: list[Path], section_globs_keys: list[str] | None = None
 ) -> list[Path]:
-    """Order GitHub instruction files, handling .instructions suffix."""
+    """Order GitHub instruction files, handling .instructions suffix.
+
+    If section_globs_keys is None, returns files sorted alphabetically.
+    """
+    if not section_globs_keys:
+        return sorted(file_list, key=lambda p: p.name)
+
     file_dict = {}
     for f in file_list:
         base_stem = f.stem.replace(".instructions", "")
@@ -232,6 +288,7 @@ def write_rule_file(path: Path, header_yaml: str, content_lines: list[str]) -> N
     """Write a rule file with front matter and content."""
     trimmed_content = trim_content(content_lines)
     output = header_yaml.strip() + "\n" + "".join(trimmed_content)
+    path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(output)
 
 

llm_ide_rules/agents/claude.py

@@ -23,13 +23,13 @@ class ClaudeAgent(BaseAgent):
     mcp_project_path = ".mcp.json"
 
     def bundle_rules(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Claude Code doesn't support rules, only commands."""
         return False
 
     def bundle_commands(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle Claude Code command files (.md) into a single output file."""
         commands_dir = self.commands_dir
@@ -48,7 +48,9 @@ class ClaudeAgent(BaseAgent):
         if not command_files:
             return False
 
-        ordered_commands = get_ordered_files(command_files, list(section_globs.keys()))
+        ordered_commands = get_ordered_files(
+            command_files, list(section_globs.keys()) if section_globs else None
+        )
 
         content_parts: list[str] = []
         for command_file in ordered_commands:
@@ -56,7 +58,9 @@ class ClaudeAgent(BaseAgent):
             if not content:
                 continue
 
-            header = resolve_header_from_stem(command_file.stem, section_globs)
+            header = resolve_header_from_stem(
+                command_file.stem, section_globs if section_globs else {}
+            )
             content_parts.append(f"## {header}\n\n")
             content_parts.append(content)
             content_parts.append("\n\n")
@@ -73,6 +77,7 @@ class ClaudeAgent(BaseAgent):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """Claude Code doesn't support rules."""
         pass
@@ -89,4 +94,26 @@ class ClaudeAgent(BaseAgent):
         filepath = commands_dir / f"{filename}{extension}"
 
         trimmed = trim_content(content_lines)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
         filepath.write_text("".join(trimmed))
+
+    def generate_root_doc(
+        self,
+        general_lines: list[str],
+        rules_sections: dict[str, list[str]],
+        command_sections: dict[str, list[str]],
+        output_dir: Path,
+        section_globs: dict[str, str | None] | None = None,
+    ) -> None:
+        """Generate CLAUDE.md that references AGENTS.md."""
+        (output_dir / "CLAUDE.md").write_text("@./AGENTS.md\n")
+
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """Create CLAUDE.md pointing to AGENTS.md if AGENTS.md exists and CLAUDE.md doesn't."""
+        agents_md = base_dir / "AGENTS.md"
+        claude_md = base_dir / "CLAUDE.md"
+
+        if agents_md.exists() and not claude_md.exists():
+            claude_md.write_text("@./AGENTS.md\n")
+            return True
+        return False

llm_ide_rules/agents/cursor.py

@@ -27,7 +27,7 @@ class CursorAgent(BaseAgent):
     mcp_project_path = ".cursor/mcp.json"
 
     def bundle_rules(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle Cursor rule files (.mdc) into a single output file."""
         rules_dir = self.rules_dir
@@ -45,21 +45,42 @@ class CursorAgent(BaseAgent):
         general = [f for f in rule_files if f.stem == "general"]
         others = [f for f in rule_files if f.stem != "general"]
 
-        ordered_others = get_ordered_files(others, list(section_globs.keys()))
+        ordered_others = get_ordered_files(
+            others, list(section_globs.keys()) if section_globs else None
+        )
         ordered = general + ordered_others
 
         content_parts: list[str] = []
         for rule_file in ordered:
-            content = rule_file.read_text().strip()
-            if not content:
+            file_content = rule_file.read_text().strip()
+            if not file_content:
                 continue
 
-            content = strip_yaml_frontmatter(content)
+            lines = file_content.splitlines()
+            extracted_header = None
+            glob_pattern = None
+
+            for line in lines:
+                if line.startswith("## "):
+                    extracted_header = line[3:].strip()
+                    break
+
+            glob_pattern = self._extract_glob_from_frontmatter(file_content)
+
+            content = strip_yaml_frontmatter(file_content)
             content = strip_header(content)
-            header = resolve_header_from_stem(rule_file.stem, section_globs)
+
+            if extracted_header:
+                header = extracted_header
+            else:
+                header = resolve_header_from_stem(
+                    rule_file.stem, section_globs if section_globs else {}
+                )
 
             if rule_file.stem != "general":
                 content_parts.append(f"## {header}\n\n")
+                if glob_pattern:
+                    content_parts.append(f"globs: {glob_pattern}\n\n")
 
             content_parts.append(content)
             content_parts.append("\n\n")
@@ -70,8 +91,23 @@ class CursorAgent(BaseAgent):
         output_file.write_text("".join(content_parts))
         return True
 
+    def _extract_glob_from_frontmatter(self, content: str) -> str | None:
+        """Extract glob pattern from YAML frontmatter."""
+        lines = content.splitlines()
+        if not lines or lines[0].strip() != "---":
+            return None
+
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                break
+            if lines[i].startswith("globs:"):
+                glob_value = lines[i][6:].strip()
+                return glob_value if glob_value else None
+
+        return None
+
     def bundle_commands(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle Cursor command files (.md) into a single output file."""
         commands_dir = self.commands_dir
@@ -90,7 +126,9 @@ class CursorAgent(BaseAgent):
         if not command_files:
             return False
 
-        ordered_commands = get_ordered_files(command_files, list(section_globs.keys()))
+        ordered_commands = get_ordered_files(
+            command_files, list(section_globs.keys()) if section_globs else None
+        )
 
         content_parts: list[str] = []
         for command_file in ordered_commands:
@@ -98,7 +136,9 @@ class CursorAgent(BaseAgent):
             if not content:
                 continue
 
-            header = resolve_header_from_stem(command_file.stem, section_globs)
+            header = resolve_header_from_stem(
+                command_file.stem, section_globs if section_globs else {}
+            )
             content_parts.append(f"## {header}\n\n")
             content_parts.append(content)
             content_parts.append("\n\n")
@@ -115,27 +155,32 @@ class CursorAgent(BaseAgent):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """Write a Cursor rule file (.mdc) with YAML frontmatter."""
         extension = self.rule_extension or ".mdc"
         filepath = rules_dir / f"{filename}{extension}"
 
+        desc = description or filename.replace("-", " ").title()
+
         if glob_pattern and glob_pattern != "manual":
             header_yaml = f"""---
-description:
+description: {desc}
 globs: {glob_pattern}
 alwaysApply: false
 ---
 """
         elif glob_pattern == "manual":
-            header_yaml = """---
-description:
+            header_yaml = f"""---
+description: {desc}
+globs: 
 alwaysApply: false
 ---
 """
         else:
-            header_yaml = """---
-description:
+            header_yaml = f"""---
+description: {desc}
+globs: 
 alwaysApply: true
 ---
 """
@@ -153,6 +198,7 @@ alwaysApply: true
         filepath = commands_dir / f"{filename}{extension}"
 
         trimmed = trim_content(content_lines)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
         filepath.write_text("".join(trimmed))
 
     def write_prompt(
@@ -176,3 +222,7 @@ alwaysApply: true
 
         output_parts.extend(filtered_content)
         filepath.write_text("".join(output_parts))
+
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """Cursor doesn't require explicit configuration for AGENTS.md."""
+        return False

llm_ide_rules/agents/gemini.py

@@ -27,13 +27,13 @@ class GeminiAgent(BaseAgent):
     mcp_project_path = ".gemini/settings.json"
 
     def bundle_rules(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Gemini CLI doesn't support rules, only commands."""
         return False
 
     def bundle_commands(
-        self, output_file: Path, section_globs: dict[str, str | None]
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
         """Bundle Gemini CLI command files (.toml) into a single output file."""
         commands_dir = self.commands_dir
@@ -52,7 +52,9 @@ class GeminiAgent(BaseAgent):
         if not command_files:
             return False
 
-        ordered_commands = get_ordered_files(command_files, list(section_globs.keys()))
+        ordered_commands = get_ordered_files(
+            command_files, list(section_globs.keys()) if section_globs else None
+        )
 
         content_parts: list[str] = []
         for command_file in ordered_commands:
@@ -61,7 +63,9 @@ class GeminiAgent(BaseAgent):
                 continue
 
             content = strip_toml_metadata(content)
-            header = resolve_header_from_stem(command_file.stem, section_globs)
+            header = resolve_header_from_stem(
+                command_file.stem, section_globs if section_globs else {}
+            )
             content_parts.append(f"## {header}\n\n")
             content_parts.append(content)
             content_parts.append("\n\n")
@@ -78,6 +82,7 @@ class GeminiAgent(BaseAgent):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """Gemini CLI doesn't support rules."""
         pass
@@ -120,6 +125,7 @@ class GeminiAgent(BaseAgent):
 
         # tomli-w will handle escaping and multiline strings automatically
         output = tomli_w.dumps(data)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
         filepath.write_text(output)
 
     def transform_mcp_server(self, server: McpServer) -> dict:
@@ -159,3 +165,37 @@ class GeminiAgent(BaseAgent):
 
         existing[self.mcp_root_key] = servers
         path.write_text(json.dumps(existing, indent=2))
+
+    def generate_root_doc(
+        self,
+        general_lines: list[str],
+        rules_sections: dict[str, list[str]],
+        command_sections: dict[str, list[str]],
+        output_dir: Path,
+        section_globs: dict[str, str | None] | None = None,
+    ) -> None:
+        """Gemini CLI uses AGENTS.md (generated by 'agents' agent). This is a no-op."""
+        pass
+
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """Configure Gemini CLI to use AGENTS.md."""
+        from llm_ide_rules.utils import modify_json_file
+
+        settings_path = base_dir / ".gemini" / "settings.json"
+
+        # Based on research, generic context setting might be:
+        updates = {"agent.instructionFile": "AGENTS.md"}
+
+        return modify_json_file(settings_path, updates)
+
+    def check_agents_md_config(self, base_dir: Path) -> bool:
+        """Check if Gemini CLI is configured to use AGENTS.md."""
+        settings_path = base_dir / ".gemini" / "settings.json"
+        if not settings_path.exists():
+            return False
+
+        try:
+            data = json.loads(settings_path.read_text())
+            return data.get("agent.instructionFile") == "AGENTS.md"
+        except Exception:
+            return False