fix(agentsmd): import nested AGENTS.md files and stop competing for .agents/skills/

[dyoshikawa]

Background

The AGENTS.md standard has had no normative change in 4+ months (spec repo agentsmd/agents.md, no releases or tags, last commit 2026-03-12 and site-only). Re-checked against https://agents.md/ on 2026-07-27: the standard defines a root AGENTS.md, plain Markdown with no frontmatter, and nested AGENTS.md in subdirectories with nearest-file-wins precedence — and defines no .agents/ subdirectory conventions and no global scope.

Two pre-existing divergences, both reproduced before fixing.

1. Nested AGENTS.md files were silently dropped on import

Nested files are the standard's only scoping mechanism: "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions."

Export already honored them via agentsmd.subprojectPath. Import did not — it enumerated the root file plus .agents/memories/** and nothing else:

$ ls AGENTS.md packages/api/AGENTS.md
$ rulesync import --targets agentsmd --features rules
Imported 1 file(s) total (1 rules)     # packages/api/AGENTS.md is gone, no warning

AgentsMdRule now exposes getNestedFileGlobs, a new optional hook the RulesProcessor uses to enumerate rule files by pattern rather than at a fixed path (the existing getExtraFixedFiles hook only covers known paths). Each match imports to .rulesync/rules/<directory-with-hyphens>.md carrying agentsmd.subprojectPath, so generate puts it back where it came from.

Two deliberate constraints:

• Import only. The matches are hand-authored files anywhere in the tree, not files under a rulesync-owned directory, so enumerating them for --delete would sweep away work rulesync never wrote.
• Hidden directories and node_modules/ are skipped. An AGENTS.md inside a dot-directory is another tool's generated output (rulesync writes several itself); one under node_modules/ describes somebody else's project.

fromFile also stops treating a modular file literally named AGENTS.md under .agents/memories/ as the project root file — it previously read <root>/AGENTS.md instead of the memory file.

After:

$ rulesync import --targets agentsmd --features rules
Imported 2 file(s) total (2 rules)
$ cat .rulesync/rules/packages-api.md
---
root: false
targets: ['*']
globs: [packages/api/**/*]
agentsmd:
  subprojectPath: packages/api
---
# API
$ rulesync generate --targets agentsmd --features rules
    AGENTS.md
    packages/api/AGENTS.md

2. The simulated agentsmd skills writer degraded .agents/skills/

.agents/skills/ is not an AGENTS.md convention — it is the Agent Skills project location. Nine targets write there, because they all implement that convention; each native one writes its own documented frontmatter, so enabling several and reordering --targets can change which optional keys survive. That is inherent to several tools sharing one path.

agentsmd is the exception, and the one this PR fixes. Its skills support is simulated — the AGENTS.md standard defines no skills at all — so it has no frontmatter model of its own, yet it overwrote the native output with a bare name/description pair:

$ rulesync generate --targets agentsmd,agentsskills --features skills --simulate-skills
Written 2 skills
    .agents/skills/demo/SKILL.md
    .agents/skills/demo/SKILL.md     # written twice

...and with the targets reversed, the simulated writer ran last and stripped license, compatibility, metadata and allowed-tools.

It now emits exactly what agentsskills emits, through the same toSpecConformantAgentSkillFields helper, so both orders produce one identical file:

$ rulesync generate --targets agentsskills,agentsmd --features skills --simulate-skills
Written 1 skill
    .agents/skills/demo/SKILL.md     # license and allowed-tools intact

The rule enforced here is narrow and defensible: a simulated writer must not degrade a path a native target owns. Making the eight native targets share one frontmatter block instead is a design decision about which rulesync block feeds a shared file, not a bug fix — a partial answer would make their generate → import round trip lossy, so it is deliberately out of scope.

Dropping the agentsmd skills convention outright was the issue's other option. agentsmd is the only simulated-skills target, so removing it would leave --simulate-skills with nothing to do — a much larger product change than this issue calls for.

Tests

• src/features/rules/agentsmd-rule.test.ts — the glob set, nested import, the subproject round trip, and that neither the root file nor a .agents/memories/AGENTS.md is mistaken for a subproject.
• src/features/skills/agentsmd-skill.test.ts — the simulated writer's frontmatter equals the native writer's for the same input.
• src/e2e/e2e-rules.spec.ts — nested import → generate round trip, with node_modules/ and .agents/ proven excluded.

Security review outcomes

The scan walks the whole project, so it was reviewed for that. It does not follow symbolic links — a link committed to a repository could otherwise pull a file from outside the project (a key, a dotfile) into version-controlled .rulesync/ — and it honors .gitignore, so a vendored dependency's rule file is not copied into a tracked directory. A subproject that would claim the reserved overview.md name gets an -agents suffix (compared case-insensitively), because overwriting the root rule would make the next --delete remove the project's AGENTS.md.

pnpm cicheck passes.

Closes #2428

[dyoshikawa]

@dyoshikawa Thank you!