aru-code 0.8.0__tar.gz → 0.10.0__tar.gz

{aru_code-0.8.0/aru_code.egg-info → aru_code-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.8.0
+Version: 0.10.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -302,6 +302,31 @@ Without any `aru.json` config, aru applies safe defaults:
 
 Place an `AGENTS.md` file in your project root with custom instructions that will be appended to all agent system prompts.
 
+### Instructions (Rules)
+
+You can load additional instructions from local files, glob patterns, or remote URLs via the `instructions` field in `aru.json`:
+
+```json
+{
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/coding-standards.md",
+    "packages/*/AGENTS.md",
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+Each entry is resolved as follows:
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| **Local file** | `"CONTRIBUTING.md"` | Reads the file relative to the project root |
+| **Glob pattern** | `"docs/**/*.md"` | Expands the pattern, respects `.gitignore` |
+| **Remote URL** | `"https://example.com/rules.md"` | Fetches via HTTP (5s timeout, cached per session) |
+
+All resolved content is combined and appended to the agent's system prompt alongside `AGENTS.md`. Individual files are capped at 10KB, and the total combined size is capped at 50KB to prevent context bloat. Missing files and failed URL fetches are skipped with a warning.
+
 ### `.agents/` Directory
 
 ```
@@ -315,7 +340,7 @@ Place an `AGENTS.md` file in your project root with custom instructions that wil
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 

{aru_code-0.8.0 → aru_code-0.10.0}/README.md

@@ -255,6 +255,31 @@ Without any `aru.json` config, aru applies safe defaults:
 
 Place an `AGENTS.md` file in your project root with custom instructions that will be appended to all agent system prompts.
 
+### Instructions (Rules)
+
+You can load additional instructions from local files, glob patterns, or remote URLs via the `instructions` field in `aru.json`:
+
+```json
+{
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/coding-standards.md",
+    "packages/*/AGENTS.md",
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+Each entry is resolved as follows:
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| **Local file** | `"CONTRIBUTING.md"` | Reads the file relative to the project root |
+| **Glob pattern** | `"docs/**/*.md"` | Expands the pattern, respects `.gitignore` |
+| **Remote URL** | `"https://example.com/rules.md"` | Fetches via HTTP (5s timeout, cached per session) |
+
+All resolved content is combined and appended to the agent's system prompt alongside `AGENTS.md`. Individual files are capped at 10KB, and the total combined size is capped at 50KB to prevent context bloat. Missing files and failed URL fetches are skipped with a warning.
+
 ### `.agents/` Directory
 
 ```
@@ -268,7 +293,7 @@ Place an `AGENTS.md` file in your project root with custom instructions that wil
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 

aru_code-0.10.0/aru/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.10.0"

{aru_code-0.8.0 → aru_code-0.10.0}/aru/agent_factory.py

@@ -8,7 +8,11 @@ from aru.providers import create_model
 from aru.session import Session
 
 
-def create_general_agent(session: Session, config: AgentConfig | None = None):
+def create_general_agent(
+    session: Session,
+    config: AgentConfig | None = None,
+    model_override: str | None = None,
+):
     """Create the general-purpose agent."""
     from agno.agent import Agent
     from agno.compression.manager import CompressionManager
@@ -17,10 +21,11 @@ def create_general_agent(session: Session, config: AgentConfig | None = None):
     from aru.runtime import get_ctx
 
     extra = config.get_extra_instructions() if config else ""
+    model_ref = model_override or session.model_ref
 
     return Agent(
         name="Aru",
-        model=create_model(session.model_ref, max_tokens=8192),
+        model=create_model(model_ref, max_tokens=8192),
         tools=GENERAL_TOOLS,
         instructions=_build_instructions("general", extra),
         markdown=True,

{aru_code-0.8.0 → aru_code-0.10.0}/aru/cli.py

@@ -137,6 +137,8 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
         console.print(f"[dim]Loaded {len(config.commands)} custom command(s): {', '.join(f'/{k}' for k in config.commands)}[/dim]")
     if config.skills:
         console.print(f"[dim]Loaded {len(config.skills)} skill(s): {', '.join(config.skills.keys())}[/dim]")
+    if config.rules_instructions:
+        console.print("[dim]Loaded custom instructions from aru.json[/dim]")
     if config.custom_agents:
         primary = [k for k, v in config.custom_agents.items() if v.mode == "primary"]
         subagents = [k for k, v in config.custom_agents.items() if v.mode == "subagent"]
@@ -428,7 +430,16 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 prompt = render_command_template(cmd_def.template, cmd_args)
                 console.print(f"[bold magenta]Running /{cmd_name}...[/bold magenta]")
 
-                agent = create_general_agent(session, config)
+                if cmd_def.agent and cmd_def.agent in config.custom_agents:
+                    agent_def = config.custom_agents[cmd_def.agent]
+                    agent = create_custom_agent_instance(agent_def, session, config)
+                elif cmd_def.agent:
+                    console.print(f"[yellow]Warning: agent '{cmd_def.agent}' not found, using default[/yellow]")
+                    agent = create_general_agent(session, config, model_override=cmd_def.model)
+                elif cmd_def.model:
+                    agent = create_general_agent(session, config, model_override=cmd_def.model)
+                else:
+                    agent = create_general_agent(session, config)
                 session.add_message("user", user_input)
                 run_result = await run_agent_capture(agent, prompt, session)
                 if run_result.content:

{aru_code-0.8.0 → aru_code-0.10.0}/aru/config.py

@@ -10,12 +10,15 @@ Supports:
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+logger = logging.getLogger("aru.config")
+
 
 @dataclass
 class CustomCommand:
@@ -24,6 +27,8 @@ class CustomCommand:
     description: str
     template: str
     source_path: str
+    agent: str | None = None
+    model: str | None = None
 
 
 @dataclass
@@ -54,6 +59,92 @@ class CustomAgent:
 
 
 MAX_README_CHARS = 2000  # Reduced from 8000 to save ~1.7K tokens per request
+MAX_RULE_FILE_SIZE = 10_000  # 10KB per rule file
+URL_FETCH_TIMEOUT = 5  # seconds
+MAX_TOTAL_RULES_SIZE = 50_000  # 50KB combined cap
+
+# Module-level URL cache (session-scoped, persists for process lifetime)
+_url_cache: dict[str, str | None] = {}
+
+
+def _resolve_instructions(entries: list[str], root: Path) -> str:
+    """Resolve instruction entries (local files, glob patterns, URLs) into combined text.
+
+    Each entry is classified as:
+    - URL: starts with http:// or https://
+    - Glob: contains *, ?, or [
+    - File path: everything else (resolved relative to root)
+    """
+    from aru.tools.gitignore import is_ignored
+
+    parts: list[str] = []
+    total_size = 0
+
+    def _add_content(source: str, content: str) -> None:
+        nonlocal total_size
+        if not content.strip():
+            return
+        truncated = content[:MAX_RULE_FILE_SIZE]
+        if total_size + len(truncated) > MAX_TOTAL_RULES_SIZE:
+            remaining = MAX_TOTAL_RULES_SIZE - total_size
+            if remaining <= 0:
+                logger.warning("Total rules size cap reached, skipping: %s", source)
+                return
+            truncated = truncated[:remaining]
+            logger.warning("Total rules size cap reached, truncating: %s", source)
+        parts.append(f"## Rules: {source}\n\n{truncated}")
+        total_size += len(truncated)
+
+    def _read_file(filepath: Path, source_label: str) -> None:
+        try:
+            content = filepath.read_text(encoding="utf-8")
+            _add_content(source_label, content)
+        except (OSError, UnicodeDecodeError) as exc:
+            logger.warning("Failed to read instruction file %s: %s", filepath, exc)
+
+    for entry in entries:
+        if entry.startswith("http://") or entry.startswith("https://"):
+            # Remote URL
+            if entry in _url_cache:
+                cached = _url_cache[entry]
+                if cached is not None:
+                    _add_content(entry, cached)
+                continue
+            try:
+                import httpx
+                with httpx.Client(timeout=URL_FETCH_TIMEOUT, follow_redirects=True) as client:
+                    resp = client.get(entry)
+                    resp.raise_for_status()
+                    text = resp.text
+                _url_cache[entry] = text
+                _add_content(entry, text)
+            except Exception as exc:
+                _url_cache[entry] = None
+                logger.warning("Failed to fetch instruction URL %s: %s", entry, exc)
+
+        elif any(c in entry for c in ("*", "?", "[")):
+            # Glob pattern
+            matched = sorted(root.glob(entry))
+            for filepath in matched:
+                if not filepath.is_file():
+                    continue
+                try:
+                    rel = filepath.relative_to(root)
+                except ValueError:
+                    continue
+                if is_ignored(str(rel), str(root)):
+                    continue
+                _read_file(filepath, str(rel))
+
+        else:
+            # Local file path
+            filepath = root / entry
+            if filepath.is_file():
+                _read_file(filepath, entry)
+            else:
+                logger.warning("Instruction file not found: %s", filepath)
+
+    return "\n\n".join(parts)
 
 
 @dataclass
@@ -61,6 +152,7 @@ class AgentConfig:
     """Loaded configuration from AGENTS.md, README.md, and .agents/ directory."""
     readme_md: str = ""
     agents_md: str = ""
+    rules_instructions: str = ""
     commands: dict[str, CustomCommand] = field(default_factory=dict)
     skills: dict[str, Skill] = field(default_factory=dict)
     permissions: dict[str, Any] = field(default_factory=dict)
@@ -71,7 +163,7 @@ class AgentConfig:
 
     @property
     def has_instructions(self) -> bool:
-        return bool(self.agents_md) or bool(self.skills)
+        return bool(self.agents_md) or bool(self.skills) or bool(self.rules_instructions)
 
     def get_extra_instructions(self, active_skills: list[str] | None = None, lightweight: bool = False) -> str:
         """Build extra instructions from README.md, AGENTS.md, and active skills.
@@ -85,6 +177,8 @@ class AgentConfig:
             parts.append(f"## Project Overview (README.md)\n\n{self.readme_md}")
         if self.agents_md:
             parts.append(f"## Project Instructions (AGENTS.md)\n\n{self.agents_md}")
+        if self.rules_instructions:
+            parts.append(self.rules_instructions)
         if active_skills:
             for name in active_skills:
                 if name in self.skills:
@@ -233,6 +327,8 @@ def _load_commands(agents_dir: Path) -> dict[str, CustomCommand]:
             description=description,
             template=body,
             source_path=str(filepath),
+            agent=metadata.get("agent") or None,
+            model=metadata.get("model") or None,
         )
 
     return commands
@@ -409,6 +505,10 @@ def load_config(cwd: str | None = None) -> AgentConfig:
                         config.model_aliases = data["model_aliases"]
                     if "plan_reviewer" in data:
                         config.plan_reviewer = bool(data["plan_reviewer"])
+                    # Resolve instructions (local files, globs, URLs)
+                    if "instructions" in data and isinstance(data["instructions"], list):
+                        entries = [str(e) for e in data["instructions"] if isinstance(e, str)]
+                        config.rules_instructions = _resolve_instructions(entries, root)
                     # Agent-level permission overrides from aru.json
                     if "agent" in data and isinstance(data["agent"], dict):
                         for agent_name, agent_data in data["agent"].items():
@@ -422,26 +522,17 @@ def load_config(cwd: str | None = None) -> AgentConfig:
     return config
 
 
-def render_command_template(template: str, user_input: str) -> str:
-    """Render a command template with user input.
-
-    Replaces $INPUT with the user's arguments.
-    Also supports $SELECTION (empty if not provided) for future use.
-    """
-    result = template.replace("$INPUT", user_input)
-    result = result.replace("$SELECTION", "")
-    return result
-
-
-def render_skill_template(content: str, arguments: str) -> str:
-    """Render a skill template with argument substitution (agentskills.io).
+def render_template_arguments(
+    content: str, arguments: str, *, context_label: str = "Argument",
+) -> str:
+    """Render a template with $ARGUMENTS / $1 / $2 substitution.
 
     Supports:
     - $ARGUMENTS: Full argument string
     - $ARGUMENTS[N]: Nth argument (0-indexed)
     - $1, $2, ...: Nth argument (1-indexed, shell-style)
 
-    Also prepends an explicit argument context block so the agent cannot
+    Also prepends an explicit context block so the agent cannot
     miss or misread the user-supplied value.
     """
     parts = arguments.split() if arguments else []
@@ -465,7 +556,17 @@ def render_skill_template(content: str, arguments: str) -> str:
 
     # Prepend an explicit context block so the agent cannot miss the argument
     if arguments and arguments.strip():
-        header = f"> **Skill argument:** `{arguments.strip()}`\n> Use this value exactly where the skill instructions reference the argument.\n\n"
+        header = f"> **{context_label}:** `{arguments.strip()}`\n> Use this value exactly where the instructions reference the argument.\n\n"
         result = header + result
 
     return result
+
+
+def render_command_template(template: str, user_input: str) -> str:
+    """Render a command template with OpenCode-style argument substitution."""
+    return render_template_arguments(template, user_input, context_label="Command argument")
+
+
+def render_skill_template(content: str, arguments: str) -> str:
+    """Render a skill template with argument substitution (agentskills.io)."""
+    return render_template_arguments(content, arguments, context_label="Skill argument")

{aru_code-0.8.0 → aru_code-0.10.0/aru_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.8.0
+Version: 0.10.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -302,6 +302,31 @@ Without any `aru.json` config, aru applies safe defaults:
 
 Place an `AGENTS.md` file in your project root with custom instructions that will be appended to all agent system prompts.
 
+### Instructions (Rules)
+
+You can load additional instructions from local files, glob patterns, or remote URLs via the `instructions` field in `aru.json`:
+
+```json
+{
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/coding-standards.md",
+    "packages/*/AGENTS.md",
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+Each entry is resolved as follows:
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| **Local file** | `"CONTRIBUTING.md"` | Reads the file relative to the project root |
+| **Glob pattern** | `"docs/**/*.md"` | Expands the pattern, respects `.gitignore` |
+| **Remote URL** | `"https://example.com/rules.md"` | Fetches via HTTP (5s timeout, cached per session) |
+
+All resolved content is combined and appended to the agent's system prompt alongside `AGENTS.md`. Individual files are capped at 10KB, and the total combined size is capped at 50KB to prevent context bloat. Missing files and failed URL fetches are skipped with a warning.
+
 ### `.agents/` Directory
 
 ```
@@ -315,7 +340,7 @@ Place an `AGENTS.md` file in your project root with custom instructions that wil
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 

{aru_code-0.8.0 → aru_code-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aru-code"
-version = "0.8.0"
+version = "0.10.0"
 description = "A Claude Code clone built with Agno agents"
 readme = "README.md"
 license = "MIT"

{aru_code-0.8.0 → aru_code-0.10.0}/tests/test_config.py

@@ -1,18 +1,25 @@
 """Unit tests for aru.config module."""
 
+import json
 import pytest
 from pathlib import Path
+from unittest.mock import MagicMock, patch
 from aru.config import (
     AgentConfig,
     CustomAgent,
     CustomCommand,
+    MAX_RULE_FILE_SIZE,
+    MAX_TOTAL_RULES_SIZE,
     Skill,
     _discover_agents,
     _parse_agent_metadata,
     _parse_frontmatter,
     _parse_skill_metadata,
+    _resolve_instructions,
+    _url_cache,
     render_command_template,
     render_skill_template,
+    render_template_arguments,
     load_config,
     MAX_README_CHARS,
 )
@@ -25,13 +32,27 @@ class TestDataClasses:
         cmd = CustomCommand(
             name="test",
             description="Test command",
-            template="Do $INPUT",
+            template="Do $ARGUMENTS",
             source_path="/path/to/test.md",
         )
         assert cmd.name == "test"
         assert cmd.description == "Test command"
-        assert cmd.template == "Do $INPUT"
+        assert cmd.template == "Do $ARGUMENTS"
         assert cmd.source_path == "/path/to/test.md"
+        assert cmd.agent is None
+        assert cmd.model is None
+
+    def test_custom_command_with_agent_and_model(self):
+        cmd = CustomCommand(
+            name="review",
+            description="Review code",
+            template="Review $ARGUMENTS",
+            source_path="/path/to/review.md",
+            agent="reviewer",
+            model="anthropic/claude-sonnet-4-5",
+        )
+        assert cmd.agent == "reviewer"
+        assert cmd.model == "anthropic/claude-sonnet-4-5"
 
     def test_skill_creation(self):
         skill = Skill(
@@ -192,37 +213,57 @@ class TestParseFrontmatter:
 
 
 class TestRenderCommandTemplate:
-    """Test command template rendering."""
+    """Test command template rendering with OpenCode-style arguments."""
 
-    def test_render_with_input(self):
-        template = "Execute $INPUT in the codebase"
-        result = render_command_template(template, "refactoring")
-        assert result == "Execute refactoring in the codebase"
+    def test_render_with_arguments(self):
+        result = render_command_template("Execute $ARGUMENTS in the codebase", "refactoring")
+        assert "Execute refactoring in the codebase" in result
 
-    def test_render_multiple_input_placeholders(self):
-        template = "Run $INPUT and verify $INPUT works"
-        result = render_command_template(template, "tests")
-        assert result == "Run tests and verify tests works"
+    def test_render_positional_args(self):
+        result = render_command_template("File: $1, Line: $2", "main.py 42")
+        assert "File: main.py, Line: 42" in result
 
-    def test_render_removes_selection(self):
-        template = "Process $INPUT and $SELECTION"
-        result = render_command_template(template, "data")
-        assert result == "Process data and "
+    def test_render_indexed_args(self):
+        result = render_command_template("$ARGUMENTS[0] and $ARGUMENTS[1]", "foo bar")
+        assert "foo and bar" in result
 
     def test_render_no_placeholders(self):
         template = "Just plain text"
         result = render_command_template(template, "input")
-        assert result == "Just plain text"
+        # Header is prepended but template body is unchanged
+        assert "Just plain text" in result
 
     def test_render_empty_input(self):
-        template = "Do $INPUT now"
-        result = render_command_template(template, "")
+        result = render_command_template("Do $ARGUMENTS now", "")
         assert result == "Do  now"
 
     def test_render_with_special_characters(self):
-        template = "Run $INPUT"
-        result = render_command_template(template, "pytest -v --cov")
-        assert result == "Run pytest -v --cov"
+        result = render_command_template("Run $ARGUMENTS", "pytest -v --cov")
+        assert "Run pytest -v --cov" in result
+
+    def test_render_missing_positional(self):
+        result = render_command_template("$1 and $3", "first second")
+        assert "first and " in result
+
+    def test_command_context_header(self):
+        result = render_command_template("Do $ARGUMENTS", "something")
+        assert result.startswith("> **Command argument:**")
+
+    def test_no_header_when_empty_args(self):
+        result = render_command_template("Do $ARGUMENTS", "")
+        assert not result.startswith(">")
+
+
+class TestRenderTemplateArguments:
+    """Test the shared render_template_arguments function."""
+
+    def test_custom_context_label(self):
+        result = render_template_arguments("Do $ARGUMENTS", "test", context_label="Custom label")
+        assert "> **Custom label:** `test`" in result
+
+    def test_delegates_correctly(self):
+        result = render_template_arguments("$1 + $2 = $ARGUMENTS", "a b")
+        assert "a + b = a b" in result
 
 
 class TestLoadConfig:
@@ -268,16 +309,32 @@ class TestLoadConfig:
     def test_load_config_with_commands(self, tmp_path):
         commands_dir = tmp_path / ".agents" / "commands"
         commands_dir.mkdir(parents=True)
-        
+
         cmd_file = commands_dir / "deploy.md"
-        cmd_file.write_text("---\ndescription: Deploy the app\n---\nDeploy $INPUT")
-        
+        cmd_file.write_text("---\ndescription: Deploy the app\n---\nDeploy $ARGUMENTS")
+
         config = load_config(str(tmp_path))
         assert "deploy" in config.commands
         cmd = config.commands["deploy"]
         assert cmd.name == "deploy"
         assert cmd.description == "Deploy the app"
-        assert cmd.template == "Deploy $INPUT"
+        assert cmd.template == "Deploy $ARGUMENTS"
+        assert cmd.agent is None
+        assert cmd.model is None
+
+    def test_load_config_command_with_agent_and_model(self, tmp_path):
+        commands_dir = tmp_path / ".agents" / "commands"
+        commands_dir.mkdir(parents=True)
+
+        cmd_file = commands_dir / "review.md"
+        cmd_file.write_text(
+            "---\ndescription: Review code\nagent: reviewer\nmodel: anthropic/claude-sonnet-4-5\n---\nReview $ARGUMENTS"
+        )
+
+        config = load_config(str(tmp_path))
+        cmd = config.commands["review"]
+        assert cmd.agent == "reviewer"
+        assert cmd.model == "anthropic/claude-sonnet-4-5"
 
     def test_load_config_command_without_frontmatter(self, tmp_path):
         commands_dir = tmp_path / ".agents" / "commands"
@@ -403,7 +460,7 @@ class TestLoadConfig:
 
         commands_dir = tmp_path / ".agents" / "commands"
         commands_dir.mkdir(parents=True)
-        (commands_dir / "test.md").write_text("---\ndescription: Test\n---\nRun $INPUT")
+        (commands_dir / "test.md").write_text("---\ndescription: Test\n---\nRun $ARGUMENTS")
 
         skill_dir = tmp_path / ".agents" / "skills" / "review"
         skill_dir.mkdir(parents=True)
@@ -523,7 +580,7 @@ class TestParseSkillMetadata:
 class TestRenderSkillTemplate:
     """Test render_skill_template with argument substitution."""
 
-    _HEADER = "> **Skill argument:** `{arg}`\n> Use this value exactly where the skill instructions reference the argument.\n\n"
+    _HEADER = "> **Skill argument:** `{arg}`\n> Use this value exactly where the instructions reference the argument.\n\n"
 
     def test_arguments_substitution(self):
         result = render_skill_template("Review $ARGUMENTS carefully", "src/main.py")
@@ -801,4 +858,150 @@ class TestAgentPermissions:
         }))
         config = load_config(str(tmp_path))
         # aru.json override should win
-        assert config.custom_agents["worker"].permission == {"edit": "deny"}
+        assert config.custom_agents["worker"].permission == {"edit": "deny"}
+
+
+class TestInstructionsLoading:
+    """Test the instructions field in aru.json (rules system)."""
+
+    def setup_method(self):
+        """Clear URL cache before each test."""
+        _url_cache.clear()
+
+    def test_instructions_local_file(self, tmp_path):
+        (tmp_path / "CONTRIBUTING.md").write_text("Follow these contributing guidelines.")
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["CONTRIBUTING.md"]
+        }))
+        config = load_config(str(tmp_path))
+        assert "Follow these contributing guidelines." in config.rules_instructions
+        assert "## Rules: CONTRIBUTING.md" in config.rules_instructions
+
+    def test_instructions_glob_pattern(self, tmp_path):
+        docs = tmp_path / "docs"
+        docs.mkdir()
+        (docs / "style.md").write_text("Style guide content")
+        (docs / "api.md").write_text("API guidelines")
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["docs/*.md"]
+        }))
+        config = load_config(str(tmp_path))
+        assert "Style guide content" in config.rules_instructions
+        assert "API guidelines" in config.rules_instructions
+
+    def test_instructions_missing_file(self, tmp_path):
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["nonexistent.md"]
+        }))
+        config = load_config(str(tmp_path))
+        assert config.rules_instructions == ""
+
+    def test_instructions_file_size_cap(self, tmp_path):
+        large_content = "x" * (MAX_RULE_FILE_SIZE + 5000)
+        (tmp_path / "large.md").write_text(large_content)
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["large.md"]
+        }))
+        config = load_config(str(tmp_path))
+        # Header + content, content should be truncated
+        assert len(config.rules_instructions) < MAX_RULE_FILE_SIZE + 200  # header overhead
+
+    def test_instructions_url(self, tmp_path):
+        mock_response = MagicMock()
+        mock_response.text = "Remote rule content"
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = MagicMock()
+        mock_client.__enter__ = MagicMock(return_value=mock_client)
+        mock_client.__exit__ = MagicMock(return_value=False)
+        mock_client.get.return_value = mock_response
+
+        with patch("httpx.Client", return_value=mock_client):
+            (tmp_path / "aru.json").write_text(json.dumps({
+                "instructions": ["https://example.com/rules.md"]
+            }))
+            config = load_config(str(tmp_path))
+            assert "Remote rule content" in config.rules_instructions
+
+    def test_instructions_url_timeout(self, tmp_path):
+        import httpx
+
+        mock_client = MagicMock()
+        mock_client.__enter__ = MagicMock(return_value=mock_client)
+        mock_client.__exit__ = MagicMock(return_value=False)
+        mock_client.get.side_effect = httpx.ConnectTimeout("timeout")
+
+        with patch("httpx.Client", return_value=mock_client):
+            (tmp_path / "aru.json").write_text(json.dumps({
+                "instructions": ["https://example.com/timeout.md"]
+            }))
+            config = load_config(str(tmp_path))
+            assert config.rules_instructions == ""
+
+    def test_instructions_combined_in_extra(self, tmp_path):
+        (tmp_path / "rules.md").write_text("Custom rule")
+        (tmp_path / "AGENTS.md").write_text("Agent instructions")
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["rules.md"]
+        }))
+        config = load_config(str(tmp_path))
+        extra = config.get_extra_instructions()
+        # Both AGENTS.md and rules should be present
+        assert "Agent instructions" in extra
+        assert "Custom rule" in extra
+        # Rules should come after AGENTS.md
+        agents_pos = extra.find("Agent instructions")
+        rules_pos = extra.find("Custom rule")
+        assert agents_pos < rules_pos
+
+    def test_instructions_total_size_cap(self, tmp_path):
+        # Create files that together exceed MAX_TOTAL_RULES_SIZE
+        docs = tmp_path / "docs"
+        docs.mkdir()
+        chunk = "y" * (MAX_RULE_FILE_SIZE - 100)
+        num_files = (MAX_TOTAL_RULES_SIZE // MAX_RULE_FILE_SIZE) + 3
+        for i in range(num_files):
+            (docs / f"rule{i:02d}.md").write_text(chunk)
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": ["docs/*.md"]
+        }))
+        config = load_config(str(tmp_path))
+        assert len(config.rules_instructions) <= MAX_TOTAL_RULES_SIZE + 5000  # headers overhead
+
+    def test_instructions_empty_list(self, tmp_path):
+        (tmp_path / "aru.json").write_text(json.dumps({
+            "instructions": []
+        }))
+        config = load_config(str(tmp_path))
+        assert config.rules_instructions == ""
+
+    def test_instructions_has_instructions_property(self):
+        config = AgentConfig(rules_instructions="some rules")
+        assert config.has_instructions is True
+
+    def test_resolve_instructions_directly(self, tmp_path):
+        (tmp_path / "a.md").write_text("Content A")
+        (tmp_path / "b.md").write_text("Content B")
+        result = _resolve_instructions(["a.md", "b.md"], tmp_path)
+        assert "Content A" in result
+        assert "Content B" in result
+
+    def test_instructions_url_caching(self, tmp_path):
+        """Second call should use cache, not fetch again."""
+        mock_response = MagicMock()
+        mock_response.text = "Cached content"
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = MagicMock()
+        mock_client.__enter__ = MagicMock(return_value=mock_client)
+        mock_client.__exit__ = MagicMock(return_value=False)
+        mock_client.get.return_value = mock_response
+
+        url = "https://example.com/cached.md"
+        with patch("httpx.Client", return_value=mock_client):
+            result1 = _resolve_instructions([url], tmp_path)
+            result2 = _resolve_instructions([url], tmp_path)
+        assert "Cached content" in result1
+        assert "Cached content" in result2
+        # httpx.Client should only be called once (second uses cache)
+        assert mock_client.get.call_count == 1

aru_code-0.8.0/aru/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.8.0"