williamthorsen · williamthorsen · May 18, 2026 · May 18, 2026
diff --git a/packages/agents/content/scripts/README.md b/packages/agents/content/scripts/README.md
@@ -0,0 +1,33 @@
+# Helper scripts
+
+Shared shell helpers consumed by skills and subagents. The install pipeline copies (or symlinks) each `.sh` file in this directory into `~/<platform_home>/scripts/` for every platform target (e.g., `~/.claude/scripts/`, `~/.codex/scripts/`).
+
+Non-`.sh` files in this directory (such as this README) are not installed.
+
+## Invocation convention
+
+Agent-facing content must invoke these scripts using the `{platform_home_dir}/scripts/` template prefix:
+
+```
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill my-skill --interactive false` via Bash.
+```
+
+At install time, `{platform_home_dir}` expands to `~/.claude`, `~/.codex`, `~/.opencode`, or the equivalent per target platform, producing an explicit absolute path the agent can execute.
+
+Bare invocations (e.g., `` Run `resolve-frontmatter.sh ...` ``) do not resolve at runtime: The install directory is not on `$PATH`, and only the launcher set (`claude.sh`, `rovo.sh`, etc.) is symlinked into `/usr/local/bin`. An agent that encounters a bare invocation typically guesses a path and fails before succeeding, wasting tool calls.
+
+Prose mentions of script names that are not invocations (e.g., ``"the `describe-change.sh` script renders titles"``) do not need the prefix.
+
+## Scripts
+
+- `describe-change.sh`: Renders titles for commits, tickets, PRs, and merges from declarative templates.
+- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
+- `resolve-frontmatter.sh`: Emits canonical artifact frontmatter (YAML or JSON) with provenance, ticket, branch, commit, and PR fields.
+- `resolve-merge-options.sh`: Resolves merge-method and squash-title inputs from CLI overrides, label maps, and commit majority.
+- `resolve-reviewer-context.sh`: Assembles the reviewer context block from a coder-emitted sidecar and a static lookup table.
+
+## Drift detection
+
+The regression test at `packages/agents/src/__tests__/script-invocation-conventions.test.ts` walks every `.md` file under `content/skills/` and `content/subagents/` and fails when any executable invocation of a known helper script lacks the `{platform_home_dir}/scripts/` prefix.
+
+When adding a new helper script, append its filename to the `KNOWN_SCRIPTS` array in the test file.
diff --git a/packages/agents/content/skills/create-devlog/SKILL.md b/packages/agents/content/skills/create-devlog/SKILL.md
@@ -91,7 +91,7 @@ Resolve `$run_id_arg` from the `--run-id={id}` argument (empty when not supplied
 Run via Bash, substituting the resolved arguments:
 
 ```bash
-resolve-frontmatter.sh \
+{platform_home_dir}/scripts/resolve-frontmatter.sh \
   --skill create-devlog \
   --interactive true \
   --model "$MODEL_ID" \

diff --git a/packages/agents/content/skills/create-ticket/SKILL.md b/packages/agents/content/skills/create-ticket/SKILL.md
@@ -153,7 +153,7 @@ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill create-ticket --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill create-ticket --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/design-and-plan/SKILL.md b/packages/agents/content/skills/design-and-plan/SKILL.md
@@ -204,7 +204,7 @@ Present the plan to the user. Revise until approved.
 
 2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
 
-   Run `resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body.
+   Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body.
 
    If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/ex-post-facto/SKILL.md b/packages/agents/content/skills/ex-post-facto/SKILL.md
@@ -67,7 +67,7 @@ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill ex-post-facto --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill ex-post-facto --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/orchestrate/SKILL.md b/packages/agents/content/skills/orchestrate/SKILL.md
@@ -715,7 +715,7 @@ Include:
 
 This section governs the frontmatter resolution for both orchestrator-written artifacts — the run-manifest (step 5) and the run-summary (Phase 5) — which use identical field-resolution logic.
 
-Run `resolve-frontmatter.sh --skill orchestrate --interactive false` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill orchestrate --interactive false` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/orchestrate/modules/review-cycle.md b/packages/agents/content/skills/orchestrate/modules/review-cycle.md
@@ -45,7 +45,7 @@ Sub-phase state is recorded via `emit_event` calls at the points described in ea
 
 Every reviewer dispatch and re-dispatch in this module includes a conditional `## Reviewer context` block in its prompt. This sub-section defines how the block is computed; each dispatch site below references it. Do not inline this logic at the dispatch sites — keep the assembly definition single-sourced here.
 
-The block is assembled from two independent sources by the helper script `{repo-root}/packages/agents/content/scripts/resolve-reviewer-context.sh`:
+The block is assembled from two independent sources by the helper script `{platform_home_dir}/scripts/resolve-reviewer-context.sh`:
 
 1. The most recent coder-emitted sidecar artifact (`{reviewer-context-sidecar-path}`), if present.
 2. Static lookup-table entries from `{lookup-path}` whose package keys are statically imported or required by any changed file.
@@ -59,7 +59,7 @@ The block is assembled from two independent sources by the helper script `{repo-
    ```
    # Only include --sidecar when {reviewer-context-sidecar-path} is non-empty;
    # omit the flag entirely when the variable is an empty string.
-   bash {repo-root}/packages/agents/content/scripts/resolve-reviewer-context.sh \
+   bash {platform_home_dir}/scripts/resolve-reviewer-context.sh \
      --sidecar "{reviewer-context-sidecar-path}" \
      --changed-files "{run-dir}/.tmp_changed-files.txt" \
      --lookup "{lookup-path}" \

diff --git a/packages/agents/content/skills/plan-orchestrable-steps/SKILL.md b/packages/agents/content/skills/plan-orchestrable-steps/SKILL.md
@@ -86,7 +86,7 @@ When the user approves the plan:
 
 1. Resolve frontmatter fields. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
 
-   Run `resolve-frontmatter.sh --skill plan-orchestrable-steps --interactive true` via Bash. Prepend the output verbatim to the artifact body.
+   Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill plan-orchestrable-steps --interactive true` via Bash. Prepend the output verbatim to the artifact body.
 
    If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/plan/SKILL.md b/packages/agents/content/skills/plan/SKILL.md
@@ -65,7 +65,7 @@ Resolve artifact directory based on context.
 
 The artifact frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
 
-Run `resolve-frontmatter.sh --skill plan --interactive true` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill plan --interactive true` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/refine-plan/SKILL.md b/packages/agents/content/skills/refine-plan/SKILL.md
@@ -153,7 +153,7 @@ The stamp writes the full canonical schema in one atomic write: the `provenance:
 
 This site uses `--format json` because the `provenance:` Block is case-branched on the input artifact's existing provenance — see [artifact-conventions.md](../_data/artifact-conventions.md#bespoke-frontmatter-composition).
 
-Run `resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `platform`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too — do not emit `null` or empty strings.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `platform`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too — do not emit `null` or empty strings.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/respond-to-review/SKILL.md b/packages/agents/content/skills/respond-to-review/SKILL.md
@@ -37,7 +37,7 @@ Source `$MODEL_ID` from your system-prompt environment block: the line `model na
 Run via Bash:
 
 ```bash
-resolve-frontmatter.sh \
+{platform_home_dir}/scripts/resolve-frontmatter.sh \
   --skill respond-to-review \
   --interactive true \
   --model "$MODEL_ID" \

diff --git a/packages/agents/content/skills/review-branch/SKILL.md b/packages/agents/content/skills/review-branch/SKILL.md
@@ -47,7 +47,7 @@ Source `$MODEL_ID` from your system-prompt environment block: the line `model na
 Run via Bash:
 
 ```bash
-resolve-frontmatter.sh \
+{platform_home_dir}/scripts/resolve-frontmatter.sh \
   --skill review-branch \
   --interactive true \
   --model "$MODEL_ID" \

diff --git a/packages/agents/content/skills/save-plan/SKILL.md b/packages/agents/content/skills/save-plan/SKILL.md
@@ -22,7 +22,7 @@ Save the plan from the current conversation as a ticket-scoped artifact. Useful
 
    The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema plus the [plan provenance](../_data/artifact-conventions.md#plan-provenance) extensions.
 
-   Run `resolve-frontmatter.sh --skill plan-mode --interactive true` via Bash. Prepend the output verbatim to the artifact body.
+   Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill plan-mode --interactive true` via Bash. Prepend the output verbatim to the artifact body.
 
    If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/summarize-change/SKILL.md b/packages/agents/content/skills/summarize-change/SKILL.md
@@ -104,7 +104,7 @@ Source `$MODEL_ID` from your system-prompt environment block: the line `model na
 Run via Bash:
 
 ```bash
-resolve-frontmatter.sh \
+{platform_home_dir}/scripts/resolve-frontmatter.sh \
   --skill summarize-change \
   --interactive true \
   --model "$MODEL_ID" \

diff --git a/packages/agents/content/skills/summarize-chat/SKILL.md b/packages/agents/content/skills/summarize-chat/SKILL.md
@@ -73,7 +73,7 @@ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill summarize-chat --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill summarize-chat --interactive true --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/skills/wrap-up/SKILL.md b/packages/agents/content/skills/wrap-up/SKILL.md
@@ -333,7 +333,7 @@ Prepend YAML frontmatter, then the markdown body.
 
 This site uses `--format json` because `tickets_created` is a list-of-objects extension that has no clean CLI expression; see [artifact-conventions.md](../_data/artifact-conventions.md#bespoke-frontmatter-composition).
 
-Run `resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `platform`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too — do not emit `null` or empty strings.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `platform`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too — do not emit `null` or empty strings.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/aspect-code-reviewer.md b/packages/agents/content/subagents/aspect-code-reviewer.md
@@ -71,7 +71,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill aspect-code-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill aspect-code-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/aspect-silent-failure-reviewer.md b/packages/agents/content/subagents/aspect-silent-failure-reviewer.md
@@ -65,7 +65,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill aspect-silent-failure-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill aspect-silent-failure-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/aspect-test-reviewer.md b/packages/agents/content/subagents/aspect-test-reviewer.md
@@ -74,7 +74,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill aspect-test-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill aspect-test-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/code-simplification-reviewer.md b/packages/agents/content/subagents/code-simplification-reviewer.md
@@ -66,7 +66,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill code-simplification-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill code-simplification-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/orchestrated-architect.md b/packages/agents/content/subagents/orchestrated-architect.md
@@ -115,7 +115,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill orchestrated-architect --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill orchestrated-architect --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/orchestrated-coder.md b/packages/agents/content/subagents/orchestrated-coder.md
@@ -139,7 +139,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill orchestrated-coder --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill orchestrated-coder --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/orchestrated-planner.md b/packages/agents/content/subagents/orchestrated-planner.md
@@ -135,7 +135,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill orchestrated-planner --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill orchestrated-planner --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/orchestrated-reviewer.md b/packages/agents/content/subagents/orchestrated-reviewer.md
@@ -75,7 +75,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill orchestrated-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill orchestrated-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/plan-reviewer.md b/packages/agents/content/subagents/plan-reviewer.md
@@ -139,7 +139,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill plan-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill plan-reviewer --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.
 

diff --git a/packages/agents/content/subagents/planner.md b/packages/agents/content/subagents/planner.md
@@ -125,7 +125,7 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 Source `$MODEL_ID` from your system-prompt environment block: the line `model named ... model ID is ...`.
 
-Run `resolve-frontmatter.sh --skill planner --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
+Run `{platform_home_dir}/scripts/resolve-frontmatter.sh --skill planner --interactive false --model "$MODEL_ID"` via Bash. Prepend the output verbatim to the artifact body.
 
 If the script's stderr contains `Note: PR lookup failed; proceeding without pr field.`, surface that line in your text output once.