llm-ide-rules 0.7.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.7.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

@@ -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,12 +58,21 @@ 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
@@ -278,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

@@ -77,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
@@ -93,6 +94,7 @@ 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(
@@ -101,8 +103,17 @@ class ClaudeAgent(BaseAgent):
         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 from rules."""
-        content = self.build_root_doc_content(general_lines, rules_sections)
-        if content.strip():
-            (output_dir / "CLAUDE.md").write_text(content)
+        """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

@@ -56,18 +56,20 @@ class CursorAgent(BaseAgent):
             if not file_content:
                 continue
 
-            # Extract header from file content before stripping it
             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)
 
-            # Use extracted header if available, otherwise resolve from filename
             if extracted_header:
                 header = extracted_header
             else:
@@ -77,6 +79,8 @@ class CursorAgent(BaseAgent):
 
             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")
@@ -87,6 +91,21 @@ 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] | None = None
     ) -> bool:
@@ -136,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
 ---
 """
@@ -174,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(
@@ -197,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

@@ -82,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
@@ -124,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:
@@ -170,8 +172,30 @@ class GeminiAgent(BaseAgent):
         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 GEMINI.md from rules."""
-        content = self.build_root_doc_content(general_lines, rules_sections)
-        if content.strip():
-            (output_dir / "GEMINI.md").write_text(content)
+        """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

llm_ide_rules/agents/github.py

@@ -57,17 +57,21 @@ class GitHubAgent(BaseAgent):
                 content_parts.append("\n\n")
 
         for instr_file in ordered_instructions:
-            content = instr_file.read_text().strip()
-            if not content:
+            file_content = instr_file.read_text().strip()
+            if not file_content:
                 continue
 
-            content = strip_yaml_frontmatter(content)
+            apply_to_pattern = self._extract_apply_to_from_frontmatter(file_content)
+
+            content = strip_yaml_frontmatter(file_content)
             content = strip_header(content)
             base_stem = instr_file.stem.replace(".instructions", "")
             header = resolve_header_from_stem(
                 base_stem, section_globs if section_globs else {}
             )
             content_parts.append(f"## {header}\n\n")
+            if apply_to_pattern:
+                content_parts.append(f"globs: {apply_to_pattern}\n\n")
             content_parts.append(content)
             content_parts.append("\n\n")
 
@@ -77,6 +81,21 @@ class GitHubAgent(BaseAgent):
         output_file.write_text("".join(content_parts))
         return True
 
+    def _extract_apply_to_from_frontmatter(self, content: str) -> str | None:
+        """Extract applyTo 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("applyTo:"):
+                apply_to_value = lines[i][8:].strip().strip('"').strip("'")
+                return apply_to_value if apply_to_value else None
+
+        return None
+
     def bundle_commands(
         self, output_file: Path, section_globs: dict[str, str | None] | None = None
     ) -> bool:
@@ -141,6 +160,7 @@ class GitHubAgent(BaseAgent):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """Write a GitHub instruction file (.instructions.md) with YAML frontmatter."""
         extension = self.rule_extension or ".instructions.md"
@@ -172,6 +192,7 @@ applyTo: "{glob_pattern}"
         )
 
         frontmatter = f"---\nmode: 'agent'\ndescription: '{description}'\n---\n"
+        filepath.parent.mkdir(parents=True, exist_ok=True)
         filepath.write_text(frontmatter + "".join(filtered_content))
 
     def write_general_instructions(
@@ -210,3 +231,13 @@ applyTo: "{glob_pattern}"
             args=config.get("args", []),
             env=config.get("env"),
         )
+
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """Configure VS Code to use AGENTS.md."""
+        from llm_ide_rules.utils import modify_json_file
+
+        settings_path = base_dir / ".vscode" / "settings.json"
+
+        updates = {"chat.useAgentsMdFile": True, "chat.useNestedAgentsMdFiles": True}
+
+        return modify_json_file(settings_path, updates)

llm_ide_rules/agents/opencode.py

@@ -79,6 +79,7 @@ class OpenCodeAgent(BaseAgent):
         filename: str,
         rules_dir: Path,
         glob_pattern: str | None = None,
+        description: str | None = None,
     ) -> None:
         """OpenCode doesn't support rules."""
         pass
@@ -95,6 +96,7 @@ class OpenCodeAgent(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 transform_mcp_server(self, server: McpServer) -> dict:
@@ -128,3 +130,7 @@ class OpenCodeAgent(BaseAgent):
             args=command_array[1:] if len(command_array) > 1 else [],
             env=config.get("environment"),
         )
+
+    def configure_agents_md(self, base_dir: Path) -> bool:
+        """OpenCode has native support, no configuration needed."""
+        return False

llm_ide_rules/agents/vscode.py

@@ -0,0 +1,88 @@
+"""VS Code agent implementation."""
+
+from pathlib import Path
+
+from llm_ide_rules.agents.base import BaseAgent
+from llm_ide_rules.mcp import McpServer
+
+
+class VSCodeAgent(BaseAgent):
+    """Agent for VS Code (native MCP support)."""
+
+    name = "vscode"
+    rules_dir = None  # VS Code typically uses .github (handled by GitHubAgent)
+    commands_dir = None
+    rule_extension = None
+    command_extension = None
+
+    mcp_global_path = None  # VS Code user settings are complex, focusing on workspace
+    mcp_project_path = ".vscode/mcp.json"
+    mcp_root_key = "servers"
+
+    def bundle_rules(
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
+    ) -> bool:
+        """VS Code doesn't support rules directly (uses GitHub Copilot)."""
+        return False
+
+    def bundle_commands(
+        self, output_file: Path, section_globs: dict[str, str | None] | None = None
+    ) -> bool:
+        """VS Code doesn't support commands directly."""
+        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:
+        """VS Code doesn't support rules."""
+        pass
+
+    def write_command(
+        self,
+        content_lines: list[str],
+        filename: str,
+        commands_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """VS Code doesn't support commands."""
+        pass
+
+    def transform_mcp_server(self, server: McpServer) -> dict:
+        """Transform unified server to VS Code format."""
+        # VS Code uses "env" key, similar to standard MCP
+        base = {}
+        if server.env:
+            base["env"] = server.env
+
+        if server.url:
+            # VS Code supports SSE via "url" (or "type": "sse"?)
+            # Research indicates basic MCP config in VS Code is similar to Claude
+            # but usually requires "command" for stdio.
+            # However, for remote/SSE, it might just need 'url'.
+            # Let's assume standard 'url' for now based on 'mcp.json' schema compatibility.
+            return {"url": server.url, **base}
+
+        return {
+            "command": server.command,
+            "args": server.args or [],
+            **base,
+        }
+
+    def reverse_transform_mcp_server(self, name: str, config: dict) -> McpServer:
+        """Transform VS Code config back to unified format."""
+        if "url" in config:
+            return McpServer(
+                url=config["url"],
+                env=config.get("env"),
+            )
+
+        return McpServer(
+            command=config["command"],
+            args=config.get("args", []),
+            env=config.get("env"),
+        )

llm_ide_rules/commands/config.py

@@ -0,0 +1,46 @@
+"""Command to configure agents to use AGENTS.md."""
+
+from pathlib import Path
+
+import typer
+from typing_extensions import Annotated
+
+from llm_ide_rules.agents import get_agent, get_all_agents
+
+
+def config_main(
+    agent: Annotated[
+        str | None,
+        typer.Option(help="Specific agent to configure (cursor, github, etc.)"),
+    ] = None,
+):
+    """
+    Configure agents to use AGENTS.md as their context source.
+    """
+    base_dir = Path.cwd()
+
+    agents_to_configure = []
+    if agent:
+        try:
+            agents_to_configure.append(get_agent(agent))
+        except ValueError as e:
+            typer.echo(f"Error: {e}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        agents_to_configure = get_all_agents()
+
+    for agent_inst in agents_to_configure:
+        if agent_inst.name == "agents":
+            continue
+
+        try:
+            configured = agent_inst.configure_agents_md(base_dir)
+            if configured:
+                typer.echo(
+                    typer.style(f"Configured {agent_inst.name}", fg=typer.colors.GREEN)
+                )
+            else:
+                msg = f"Skipped {agent_inst.name} (no changes needed or not applicable)"
+                typer.echo(typer.style(msg, fg=typer.colors.YELLOW))
+        except Exception as e:
+            typer.echo(f"Failed to configure {agent_inst.name}: {e}", err=True)