Replace monorepo paths in installable content with {platform_home_dir}

[williamthorsen]

Description

Problem

Several content files installed by the agents installer contain raw packages/agents/content/... paths that resolve only inside this monorepo. When the installed content runs in another repo (or under another platform home), these references break:

• The changelog-writer subagent reads packages/agents/content/skills/_data/lede-voice.md at runtime (lines 12 and 37 of packages/agents/content/subagents/changelog-writer.md). Outside the monorepo, the doctrine file lives only at the platform-installed path (e.g., ~/.claude/skills/_data/lede-voice.md), so every audit-mode invocation in another repo hits a dead path and produces unverified output. This critically breaks the changelog-audit workflow.
• The bb-pr-inline-comment skill documents a CLI invocation that hardcodes the monorepo path to its companion script (packages/agents/content/skills/bb-pr-inline-comment/SKILL.md:60).
• The orchestrate skill resolves {lookup-path} to {repo-root}/packages/agents/content/skills/orchestrate/_data/reviewer-context-packages.md (lines 519 and 544 of packages/agents/content/skills/orchestrate/SKILL.md). The lookup table is installed alongside the skill, so this path is wrong outside the monorepo and wrong inside the monorepo when orchestrate runs from a working directory in another repository.
• The resolve-frontmatter.sh error message at line 161 directs the user to packages/agents/content/skills/_data/artifact-conventions.md § Subagent dispatch precondition, a path that does not exist on disk in installed contexts.

Context

The install pipeline already provides the right primitive. rewriteTemplateVariables in packages/agents/src/lib/path-rewriter.ts expands {platform_home_dir} to ~/.claude (or the platform-equivalent home) at install time. Most subagent prompts opt in correctly, e.g., packages/agents/content/subagents/planner.md:128. The companion link-rewriter, rewriteMarkdownPaths, handles [text](target) Markdown link syntax automatically; the broken references are bare strings inside inline-code spans or shell invocations, which the template-variable rewriter is meant to cover but requires author opt-in.

A sibling regression test, packages/agents/src/__tests__/script-invocation-conventions.test.ts, already enforces the {platform_home_dir}/scripts/ prefix for executable invocations of known helper scripts. The same approach extends naturally to raw packages/agents/content/... cross-references.

Considerations

Not every packages/agents/content/ reference is a bug. An audit of installable content identified five files whose references are intentional source-tree citations rather than runtime paths:

• _partials/README.md:23: prose describing the partial system's source-tree containment rule.
• skills/common-mistakes/SKILL.md:70: prose explaining the installed-versus-source relationship.
• skills/_data/ticket-id-extraction.md:38: pointer to the canonical implementation in source.
• skills/_data/artifact-conventions.md:227-229: dispatcher lookup table whose source-tree paths are intentional.
• skills/orchestrate/_data/reviewer-context-packages.md:12: pointer to the helper script source.

These should be preserved and treated as the canonical allowlist for the new regression test.

The install pipeline currently template-expands .md files only, so shell scripts cannot use {platform_home_dir} directly. Rather than extend the pipeline to cover .sh files for one rare-hit error message, the resolve-frontmatter.sh case is fixed by dropping the path prefix from the error string. The filename and section anchor are sufficient for the reader to locate the reference in any install context.

Proposed solution

1. Convert each runtime reference to the template form, except for the shell-script error message, which is fixed by dropping the path prefix so the string resolves the same way in every install context.
2. Add a regression test that walks installable content under content/skills/ and content/subagents/ and rejects raw packages/agents/content/ strings outside a file-level allowlist of intentional source citations.
3. Add a short authoring note to packages/agents/content/_partials/README.md covering when to use {platform_home_dir}, when a Markdown link is sufficient, and when a bare path is acceptable.

Acceptance criteria

Must have

• packages/agents/content/subagents/changelog-writer.md references the lede-voice doctrine via {platform_home_dir}/skills/_data/lede-voice.md in both locations.
• packages/agents/content/skills/bb-pr-inline-comment/SKILL.md invokes its companion script via {platform_home_dir}/skills/bb-pr-inline-comment/bb-pr-inline-comment.sh in the example at line 60.
• packages/agents/content/skills/orchestrate/SKILL.md resolves {lookup-path} to {platform_home_dir}/skills/orchestrate/_data/reviewer-context-packages.md in both locations.
• The resolve-frontmatter.sh error message at line 161 refers to artifact-conventions.md § Subagent dispatch precondition without the packages/agents/content/skills/_data/ prefix.
• After a fresh install, every rewritten reference contains the expanded absolute path (~/.claude/... on Claude Code, platform-equivalent elsewhere).
• Audit-mode invocation of changelog-writer in a repository other than this monorepo successfully loads the doctrine.

Should have

• A new regression test walks installable content under content/skills/ and content/subagents/ and fails when any line contains a raw packages/agents/content/ string outside a file-level allowlist defined in the test.
• The allowlist covers exactly the five files identified in the Considerations section.
• packages/agents/content/_partials/README.md contains a short authoring note describing when to use {platform_home_dir}, when to use a Markdown link, and when a bare packages/agents/content/ reference is acceptable.
• New and modified behavior in this change is covered by tests.