[FEATURE]: Context Auto-Discovery: Load AGENTS.md from Directories When Accessing Files

[Ithril-Laydec]

Feature hasn't been suggested before.

• [x] I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

In large monorepos, we have to choose what information to load into context. With a large AGENTS.md file, we load a lot of context that might not be necessary for all conversations.

Typical structure example:

monorepo/
├── AGENTS.md              # Global project rules
├── packages/
│   ├── backend/
│   │   ├── src/
│   │   └── AGENTS.md      # Backend-specific rules
│   ├── frontend/
│   │   ├── src/
│   │   └── AGENTS.md      # Frontend-specific rules
│   └── mobile/
│       ├── src/
│       └── AGENTS.md      # Mobile-specific rules

Current workaround: Manually list all instruction files in opencode.json:

{
  "instructions": [
    "AGENTS.md",
    "packages/backend/AGENTS.md",
    "packages/frontend/AGENTS.md",
    "packages/mobile/AGENTS.md"
  ]
}

Problem with this approach: This loads ALL instruction files at startup, overloading the context with irrelevant information (e.g., loading mobile rules when working on backend code). This doesn't scale and defeats the purpose of having per-module context.

---

Proposed Solution

Mimic Claude Code's auto-discovery so that when a file is read or written in a subdirectory, the relevant AGENTS.md is automatically loaded without the LLM having to manually decide to read it.

Features:

1. Loaded file cache to avoid duplicates in the same session
2. Configuration option to disable the feature if not desired
3. Two loading strategies:
   • "up": Search for AGENTS.md upward to the worktree (default)
   • "exact": Only load AGENTS.md from the exact file directory

---

Advanced Configuration

{
  "autoDiscovery": {
    "enabled": true,
    "patterns": ["AGENTS.md", "CLAUDE.md"],
    "strategy": "up" // "up" | "exact"
  }
}

---

Why This Matters

• ✅ Zero-config: Works without configuration for standard project structures
• ✅ Automatic scalability: No need to update config when adding modules
• ✅ Better context accuracy: LLM receives relevant instructions automatically
• ✅ Monorepo support: Essential for modern architectures (Next.js, Turborepo, Nx)
• ✅ Parity with Claude Code: Users expect similar behavior across AI coding tools

---

Step-by-Step Flow: "up" Strategy (Search Upward)

Structure:
monorepo/
├── AGENTS.md                    # [A] Global rules
├── packages/
│   └── backend/
│       ├── AGENTS.md            # [B] Backend rules
│       └── routes/
│           ├── AGENTS.md        # [C] Routes rules
│           └── auth.ts          # ← File being read

LLM: readFile("packages/backend/routes/auth.ts")

Step 1: Detect directory → "packages/backend/routes/"
Step 2: Search upward:
  → packages/backend/routes/AGENTS.md  ✅ [C] Found! → Load
  → packages/backend/AGENTS.md         ✅ [B] Found! → Load
  → packages/AGENTS.md                 ❌ Does not exist
  → AGENTS.md                          ✅ [A] Already loaded by system

Result: LLM receives context from [C] + [B] + [A]

---

Step-by-Step Flow: "exact" Strategy (Current Directory Only)

Same structure as before:
monorepo/
├── AGENTS.md                    # [A] Global rules
├── packages/
│   └── backend/
│       ├── AGENTS.md            # [B] Backend rules
│       └── routes/
│           ├── AGENTS.md        # [C] Routes rules
│           └── auth.ts          # ← File being read

LLM: readFile("packages/backend/routes/auth.ts")

Step 1: Detect directory → "packages/backend/routes/"
Step 2: Search ONLY in that directory:
  → packages/backend/routes/AGENTS.md  ✅ [C] Found! → Load
  → (Does NOT search in parent directories)

Result: LLM receives context from [C] + [A] (root already loaded)

When to use each strategy?

• "up" (recommended): When you want the LLM to have full module + submodule context
• "exact": When each subdirectory has completely independent context and you don't want to "inherit" rules from parent folders

---

Difference with #4479

I've read issue #4479 and consider this proposal to be complementary but not the same:

• #4479: Vertical search outside the git root (for monorepos with AGENTS.md in parent folders)
• This proposal: Horizontal search within the project (for modules with their own context)

Both features can coexist and solve different use cases in complex monorepos.

---

Implementation Offer

If this sounds good, I'd like to implement it myself or help implement it.

---