show-me artifact · issue #3984

AGENTS.md loading is a map today; it can become deterministic by path

OpenHands SDK already treats root AGENTS.md as repository context and this repository uses a root map to point agents at package-level files. SmolPaws has the same shape at a larger scale. The missing piece is a deterministic file-operation trigger that loads applicable nested AGENTS.md files instead of asking the model to remember the map.

1The repository claim is accurate, with one caveat

★ Verified: software-agent-sdk has six AGENTS.md files, and the root file contains a package map instructing agents to read the closest package file when relevant. Caveat: this is prompt-guided today; nested package files are not automatically injected just because a file under that package is touched.

Claim	Evidence	Meaning
Multiple `AGENTS.md` files	Root plus SDK, subagent, tools, workspace, and agent-server files found in the checkout.	The repo already has scoped instruction documents.
Root map tells the agent where to look	AGENTS.md:152-162	The root file lists package-specific guidance and says to read the closest one.
Root repository memory is prompt policy	static.py:103-111	The SDK prompt says root `AGENTS.md` is repository memory and automatically loaded when project skills are enabled.

2SmolPaws is the same pattern made visible

Using SmolPaws' /show-me skill means producing a source-grounded, self-contained HTML page, big picture first. show-me/SKILL.md:21-26 show-me/SKILL.md:42-74

Root map

SmolPaws root AGENTS.md points to key files, group memory, and canonical identity docs. AGENTS.md:16-28

groups/{name}/AGENTS.md  → per-group memory
apps/github/             → GitHub ingress
docs/smolpaws/           → canonical identity

Local scopes

Nested files contain scoped rules: GitHub ingress deployment/tests, Slack ingress behavior, and per-group WhatsApp formatting or permissions. apps/github/AGENTS.md:1-8 groups/main/AGENTS.md:60-77

apps/github/AGENTS.md      → Worker/webhook context
groups/main/AGENTS.md      → elevated group memory
docs/smolpaws/AGENTS.md    → identity docs index

3Current SDK behavior loads root/workdir project docs, not every ancestor on touch

Today: root/workdir guidance is auto-loaded; deeper package files rely on model-followed instructions.

The implementation loads third-party files such as AGENTS.md from the working directory and, if different, the git repo root. skill.py:898-928 The file finder scans a single directory passed as repo_root, not every descendant. utils.py:332-356

4A Codex-style version would make the map executable

ⓘ Codex walks from project root down to current working directory, collects each AGENTS.md, and concatenates them root-to-leaf. Its base prompt says nested files scope to their subtree and deeper files win on conflicts. agents_md.rs:1-16 default.md:17-27

Proposed: file operations deterministically select nested docs and update model-visible context.

Minimal OpenHands shape: reuse existing project-skill rendering, but key discovery by touched_path at the tool-use seam. Run it for create/write as well as read/edit so new files get scoped guidance before content is finalized.

5Worked path examples in SmolPaws

Touched path	Deterministic AGENTS chain	Why it matters
`apps/github/src/index.ts`	`/AGENTS.md` → `apps/github/AGENTS.md`	Loads GitHub ingress deployment/test guidance without relying on the model to notice the map. apps/github/AGENTS.md:24-41
`apps/slack/src/slackHandler.ts`	`/AGENTS.md` → `apps/slack/AGENTS.md`	Brings in Slack Socket Mode, access-control, and test hints for that subtree. apps/slack/AGENTS.md:9-23
`groups/main/notes.md`	`/AGENTS.md` → `groups/main/AGENTS.md`	Loads elevated group memory and WhatsApp formatting rules only for that scope. groups/main/AGENTS.md:48-77
`docs/smolpaws/IDENTITY.md`	`/AGENTS.md` → `docs/smolpaws/AGENTS.md`	Loads identity-doc context only when editing the canonical identity subtree. docs/smolpaws/AGENTS.md:1-17

⚠ Scope rule: broad always-on root guidance is still useful, but path-scoped nested guidance should stay out of baseline context until the agent touches a matching subtree.