Description
Installed subagents reference helper scripts through the literal {platform_home_dir} template token instead of a runnable path. The deployed orchestrated-coder.md, for example, contains Run {platform_home_dir}/scripts/describe-change.sh ..., which points at a directory that does not exist. An agent following that instruction cannot find the script, so it guesses or silently skips the step.
The root cause is an install-pipeline gap. rewritePathsInFile and rewritePathsInDirectory expand {platform_home_dir} to the platform home (~/.claude, ~/.codex, and so on), and the installer applies them when installing skills and shared guidance. The subagent installer does not: its pipeline expands includes, merges frontmatter, rewrites tool names, and injects a provenance marker, but never rewrites paths. Every {platform_home_dir} in a subagent body is therefore written verbatim.
This affects all subagent files that reference scripts, not only describe-change.sh. Eleven subagents carry the token today, and orchestrated-coder.md alone references two scripts (describe-change.sh and resolve-frontmatter.sh) the same broken way. path-rewriter.test.ts proves the rewriter works in isolation, but no test checks that an installed subagent contains an expanded path, which is why the gap shipped undetected.
A content defect in orchestrated-coder.md compounds the symptom. The "Commit formatting" hard-gate rule for rendering the commit title named describe-change.sh in prose with no runnable command, cross-referenced title-templates.md unnecessarily, and carried a silent "fall back to the bare title" clause that downgraded a hard-gate requirement without surfacing the downgrade. The observed effect was orchestrated commits shipping without the configured {scope}|{type}: prefix, undetected until PR review.
The goal is unambiguous script references: after install, every script a subagent names appears as an absolute path rather than a literal {platform_home_dir} token.
Implementation notes
The fix belongs in installSubagents (packages/agents/src/commands/install.ts); the shared-guidance installer already shows the pattern, applying rewritePathsInFile(destPath, entry, platformConfig.homeDir, platformConfig.homeDir) to each .md file. Subagents currently have no relative markdown links, so the meaningful transform is the {platform_home_dir} expansion; applying the shared rewriter keeps parity with skills and guidance and future-proofs against links added later.
Exercise install against a temporary directory (as platform.test.ts does), never a real platform home. To reproduce the bug: install to a temp directory, then grep an installed subagent for {platform_home_dir}: the token is present, unexpanded.
Acceptance criteria
Must have
Description
Installed subagents reference helper scripts through the literal
{platform_home_dir}template token instead of a runnable path. The deployedorchestrated-coder.md, for example, containsRun{platform_home_dir}/scripts/describe-change.sh ..., which points at a directory that does not exist. An agent following that instruction cannot find the script, so it guesses or silently skips the step.The root cause is an install-pipeline gap.
rewritePathsInFileandrewritePathsInDirectoryexpand{platform_home_dir}to the platform home (~/.claude,~/.codex, and so on), and the installer applies them when installing skills and shared guidance. The subagent installer does not: its pipeline expands includes, merges frontmatter, rewrites tool names, and injects a provenance marker, but never rewrites paths. Every{platform_home_dir}in a subagent body is therefore written verbatim.This affects all subagent files that reference scripts, not only
describe-change.sh. Eleven subagents carry the token today, andorchestrated-coder.mdalone references two scripts (describe-change.shandresolve-frontmatter.sh) the same broken way.path-rewriter.test.tsproves the rewriter works in isolation, but no test checks that an installed subagent contains an expanded path, which is why the gap shipped undetected.A content defect in
orchestrated-coder.mdcompounds the symptom. The "Commit formatting" hard-gate rule for rendering the commit title nameddescribe-change.shin prose with no runnable command, cross-referencedtitle-templates.mdunnecessarily, and carried a silent "fall back to the bare title" clause that downgraded a hard-gate requirement without surfacing the downgrade. The observed effect was orchestrated commits shipping without the configured{scope}|{type}:prefix, undetected until PR review.The goal is unambiguous script references: after install, every script a subagent names appears as an absolute path rather than a literal
{platform_home_dir}token.Implementation notes
The fix belongs in
installSubagents(packages/agents/src/commands/install.ts); the shared-guidance installer already shows the pattern, applyingrewritePathsInFile(destPath, entry, platformConfig.homeDir, platformConfig.homeDir)to each.mdfile. Subagents currently have no relative markdown links, so the meaningful transform is the{platform_home_dir}expansion; applying the shared rewriter keeps parity with skills and guidance and future-proofs against links added later.Exercise install against a temporary directory (as
platform.test.tsdoes), never a real platform home. To reproduce the bug: install to a temp directory, then grep an installed subagent for{platform_home_dir}: the token is present, unexpanded.Acceptance criteria
Must have
{platform_home_dir}and rewrites markdown paths in subagent bodies, matching the treatment skills and shared guidance already receive.{platform_home_dir}token; every script reference is expanded to an absolute, well-formed path for the target platform (for example,~/.claude/scripts/describe-change.sh). Whether the referenced file is actually present at that path is out of scope here and is tracked in Add a validator that checks all agent- and skill-referenced files resolve after install #790.orchestrated-coder.md's commit-title rule invokesdescribe-change.shthrough the templated script path and readscommit_titlefrom the JSON output. The silent "fall back to the bare title" clause is removed, with no replacement failure-handling added.orchestrated-coder.md.{platform_home_dir}token, covering subagent install output generally rather than a single file.