An AGENTS.md router can ship with links that resolve to nothing

[MariusStorhaug]

An AGENTS.md router is the first file an agent reads in a repository, and it is a list of links to somewhere else. When those links rot, the router silently stops routing: the agent reads a page of destinations, follows one, gets a 404, and proceeds without the standard it was supposed to load. The failure is invisible because the router still looks correct.

PSModule/Template-PSModule shows the shape of it. Six of the nine links in its AGENTS.md return 404, including five pointing at a psmodule.github.io/docs/ site that has never existed. Because that repository is a template, every module repository created from it inherits the dead router.

Current state

The Markdown standard already documents the gap:

What it does not cover yet: a published-site URL such as https://msxorg.github.io/docs/…, which is the canonical form for a repository that publishes to GitHub Pages. Nothing verifies those today — see #150.

So the standard asks authors to write published-site URLs, names them canonical, and verifies every link form except that one. Test-CrossRepositoryLink.ps1 resolves github.com and raw.githubusercontent.com targets in the organizations MSX controls; Test-DocumentationLink.ps1 resolves relative links inside a checkout. A router built entirely from published-site URLs is checked by neither.

Why a router deserves its own treatment

#150 covers published-URL checking in general. This issue is about the case where the absence of that check does the most damage:

• A router has no content of its own, so a dead link is total loss for that destination rather than a degraded page.
• Routers are inherited. A template repository's router is copied into every repository generated from it, and the copies are never re-verified.
• The reader is usually an agent, which does not report a broken link the way a human does. It proceeds with less context and no signal that context was missing.

Proposed resolution

Options, in rough order of directness:

• Extend the cross-repository link check to resolve published-site URLs for the sites MSX controls — msx.no/docs, and the psmodule.io per-repository sites — following redirects and treating a 404 as a failure. This is Check the published-URL links the Markdown standard also asks authors to write #150 with the router as the motivating case.
• Add a router-specific check that runs against AGENTS.md and the client route files, so a repository cannot merge a router whose destinations do not resolve.
• State in the Agentic Development standard that a router's links are verified, and say by what. The standard currently specifies the router's shape and contents but not that its destinations must resolve.

Whichever route is taken, the outcome to aim for: a repository cannot ship a router that points at nothing, and a template cannot propagate one.

---

Technical details

Link check against PSModule/Template-PSModule's AGENTS.md on main:

Link	Status
psmodule.github.io/docs/Modules/Process-PSModule/template-quickstart/	404
psmodule.github.io/docs/Modules/Repository-Defaults/	404
psmodule.github.io/docs/Modules/Process-PSModule/module-anatomy/	404
psmodule.github.io/docs/Modules/Process-PSModule/build-test-pack-publish/	404
psmodule.github.io/docs/Modules/Standards/	404
msxorg.github.io/docs/Ways-of-Working/Agentic-Development/	404
msxorg.github.io/docs/Ways-of-Working/	200
msxorg.github.io/docs/Coding-Standards/	200
github.com/PSModule/memory	200

Two distinct causes:

• psmodule.github.io/docs/ is not a site. There is no PSModule/docs repository. The real pages live in PSModule/Process-PSModule/docs/content/ and publish to psmodule.io/Process-PSModule/…. The whole path prefix was invented.
• Ways-of-Working/Agentic-Development/ moved to Capabilities/agentic-development/ in this repository. A page move in docs broke a link in a repository that docs governs, and nothing reported it.

The second cause is the more general one: any page move here can break a router anywhere, and the move is made without visibility into who points at the old path.

Relevant issues (or links)

Related work

• References Check the published-URL links the Markdown standard also asks authors to write #150 — the general published-URL checking gap this depends on.
• References ⚙️ [Maintenance]: New module repositories ship the Claude Code and Copilot agent routes PSModule/Template-PSModule#50 — where the dead router was found.