Recursively discover AGENTS.md in subfolders, like VS Code's chat.useNestedAgentsMdFiles

[danielsogl]

Describe the feature or problem you'd like to solve

The Copilot CLI currently discovers AGENTS.md files only along the path from the current working directory up to the git root (per the resolution of #1655). Files in sibling or deeper subfolders that are not on the CWD-to-root path are not discovered when the CLI is started at the repo root.

In a monorepo started from the root, this means folder-local AGENTS.md files (e.g., frontend/AGENTS.md, backend/AGENTS.md, packages/lib-a/AGENTS.md) are invisible to the agent unless the user cds into each subfolder before starting the CLI — which defeats the point of having scoped, co-located instructions.

VS Code already solves this with the experimental setting chat.useNestedAgentsMdFiles:

"VS Code searches recursively in all subfolders of your workspace for AGENTS.md files and adds their relative path to the chat context. The agent can then decide which instructions to use based on the files being edited."

The CLI should provide the same behavior so that the same AGENTS.md layout works identically in VS Code Chat and in the CLI.

Proposed solution

Make the CLI recursively discover AGENTS.md files in all subfolders of the workspace / git root (respecting .gitignore), matching VS Code's chat.useNestedAgentsMdFiles behavior:

1. Discovery: walk the workspace (git root or CWD when not in a repo) and collect all AGENTS.md files. Honor .gitignore and skip the usual heavy directories (node_modules, .git, dist, build, etc.) by default.
2. Context exposure: add the discovered files (paths + contents, or paths only with on-demand load) to the agent's context, so the model can decide which scope applies based on the files being edited — same model-driven selection as VS Code.
3. Opt-in / opt-out parity with VS Code: ship behind a setting (e.g., useNestedAgentsMdFiles or an env var / CLI flag) so users can match VS Code's behavior. Defaulting it on would be ideal; if there are concerns about token cost on large monorepos, off-by-default with a clear toggle is acceptable.
4. Precedence: when multiple AGENTS.md files apply to a given file, deeper-nested files should take precedence over shallower ones (same direction as the existing CWD-to-root resolution).

Example prompts or workflows

Monorepo layout:

repo/                           ← git root, where the CLI is started
├── AGENTS.md                   ← repo-wide rules (already discovered)
├── frontend/
│   ├── AGENTS.md               ← React/TS conventions (NOT discovered today)
│   └── src/...
├── backend/
│   ├── AGENTS.md               ← Go service conventions (NOT discovered today)
│   └── cmd/...
└── packages/
    ├── lib-a/AGENTS.md         ← package-specific rules (NOT discovered today)
    └── lib-b/AGENTS.md         ← package-specific rules (NOT discovered today)

Today (CLI started at repo/): only the root AGENTS.md is loaded. If the user asks "add a new endpoint to backend/cmd/api", the agent doesn't see backend/AGENTS.md and won't follow its conventions unless the user manually cds into backend/ first.

Expected (with this feature): all four nested AGENTS.md files are discovered. When the agent works on a file under backend/cmd/api/, the backend/AGENTS.md rules are applied. Same behavior the user already gets in VS Code Chat with chat.useNestedAgentsMdFiles enabled.

Additional context

• Resolution of Flag for nested agents.md files along file hierarchy #1655 only covers the CWD-to-root path, which is a strict subset of what VS Code's nested-discovery setting does. Several users have already expressed surprise that the CLI does not match VS Code here.
• Related: Nested agents load ALL copilot-instructions.md, not just the ones at the nested level #2735 (nested discovery is loading copilot-instructions.md more aggressively than expected — argues for clear scoping rules whichever direction this goes).
• Related: Feature: Discover custom agents from cwd, not just git root #2504 / Support agent discovery from current working directory (nested .github/agents/) #1859 / Support discovering custom agents from subdirectories in monorepos #2245 (analogous gap for .github/agents/*.agent.md agent profiles).
• Workarounds today (symlinks from .github/instructions/, applyTo: frontmatter in instructions.md files, parent-AGENTS.md instructing the agent to read children) are brittle and inconsistent — see the workarounds section of Flag for nested agents.md files along file hierarchy #1655.
• Behavior parity between VS Code Chat and the CLI is valuable: teams document AGENTS.md once and expect both surfaces to honor it equivalently.