Eliminate relative Markdown links in installed agent guidance

[williamthorsen]

Problem

Relative Markdown links in installed agent guidance files cause agents to fail to find linked content. Fresh Claude Code sessions apply standard Markdown-relative resolution to links like skills/_data/artifact-conventions.md in ~/.agents/AGENTS.md, look under ~/.agents/ (the file's own directory), find nothing, and stop. This is at least the 8th repeat of a known failure class — prior convention-based fixes (#350, #391, #395) keep losing ground because a new session must read the convention from a file before it can resolve any links, and the convention often lives in the file the link was supposed to locate.

Context

Prior fixes established an install-time rewriting pipeline for skills:

• design-and-plan skill cannot resolve shared _data/ references #350 fixed _data/ paths in skills via the ../_data/ relative convention.
• Inject absolute paths for script references in installed skills #391 / #391 Inject absolute paths for script references in installed skills #395 introduced the {platform_home_dir} template variable for script references, plus rewritePathsInDirectory (rewrites Markdown link targets and template variables). Skills are copied+rewritten even in --link mode.

The rewriter is only wired into installSkillEntry. installSharedGuidance and installPlatformGuidance do neither rewriting nor copy-in---link-mode — which is how the current ~/.agents/AGENTS.md reached the user's filesystem still containing skills/_data/artifact-conventions.md as a bare relative path.

Beyond wiring, the shared guidance tier has an architectural constraint: ~/.agents/AGENTS.md is a single file serving all platforms, so it cannot resolve to any {platform_home_dir}-shaped target. The cleanest answer is a policy rule: shared guidance has no outbound Markdown link targets at all — it references skills by name, not by path, and the skill chain carries forward any path-level conventions.

Today, the only shared-guidance link violating this rule is the "Plan files" directive in AGENTS.md (line 78). Its intent — steer ad-hoc artifact placement into the canonical convention — is already fully covered by save-artifact (path resolution, slug generation, naming) and the plan-producing skills that call it. Replacing the file link with a one-line pointer to the skill preserves the salience without the cross-tier reference.

Solution

1. Source content changes

   • Replace the "Plan files" section in content/guidance/shared/AGENTS.md with a one-line directive: "When creating an artifact (plan, devlog, review, change summary, chat summary, etc.), invoke the save-artifact skill to resolve path and naming. Do not place artifacts in ad-hoc locations."
   • No changes to skill content: existing ../_data/… links are already handled correctly by the rewriter.
   • No changes to subagents: they have no outbound Markdown links today.

2. Installer changes

   • Wire rewritePathsInDirectory into installPlatformGuidance (preventive — CLAUDE.md and rovodev AGENTS.md have no relative links today, but catching future drift is cheap).
   • Force platform guidance to copy+transform even in --link mode (mirror the #391 Inject absolute paths for script references in installed skills #395 treatment of skills).
   • Do not wire the rewriter into installSharedGuidance. Shared guidance is governed by the policy rule below, enforced by test; rewriting it would only mask violations instead of surfacing them.

3. Validation

   • Content-policy unit test: walk every .md file under content/guidance/shared/; fail if any [text](target) has a target that is not a URL, absolute path, tilde-absolute path, or pure anchor. Catches violations at the source tier.
   • Post-install integration test: invoke installCommand into a temp dir (matching the pattern in install.test.ts); walk every installed .md under ~/.claude/ and ~/.rovodev/; fail if any [text](target) target is bare-relative (does not start with http://, https://, /, ~/, or #). Verifies the rewriter's end-to-end contract.

Acceptance criteria

• The "Plan files" section is removed from content/guidance/shared/AGENTS.md and replaced with a one-line save-artifact directive.
• installPlatformGuidance applies rewritePathsInDirectory to installed platform-guidance files.
• Platform guidance is copied+transformed in --link mode (not symlinked); manifest entries record linked: false.
• A unit test fails if any .md under content/guidance/shared/ contains an outbound Markdown link with a non-URL/non-absolute/non-anchor target.
• An integration test invokes installCommand into a temp dir and fails if any installed .md under a platform home contains a bare-relative Markdown link target.
• After a fresh install, ~/.agents/AGENTS.md contains no Markdown links with bare-relative targets, and ~/.claude/CLAUDE.md and ~/.rovodev/AGENTS.md contain only absolute targets.
• Existing tests pass; new behavior is covered by tests.