#597 Make subagent tool-name references platform-portable

packages/agents/content/_partials/README.md

@@ -12,7 +12,7 @@ Three include shapes are recognized. Each must occupy a full line, with optional
 | ------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
 | Self-close    | `<!-- include: path / -->`                       | Inline a partial with no slot content (or use the partial's empty-slot defaults). |
 | Open + close  | `<!-- include: path -->` ... `<!-- /include -->` | Inline a partial and pass slot content into its `<!-- children -->` placeholder.  |
-| Children slot | `<!-- children -->`                              | Inside a partial: marks where the caller's slot content is substituted.           |
+| Children slot | `<!-- children -->`                              | Inside a partial: Marks where the caller's slot content is substituted.           |
 
 Self-close is matched before open so that a path with a trailing slash is read correctly as a self-close, not as an open directive whose path ends with a slash.
 
@@ -41,12 +41,39 @@ For each `.md` source file the install pipeline performs, in order:
 
 1. **Expand includes.** `expandIncludes(srcPath, contentDir)` resolves all directive shapes recursively and substitutes slot content.
 2. **Merge frontmatter** (subagents only). Platform-specific frontmatter overrides from `_data/{platform}.yml` are merged into the source's frontmatter.
-3. **Inject the provenance marker.** A `GENERATED FILE` comment is added at the top of the output, with a `Source:` link to the original file.
-4. **Rewrite paths** (skills only, post-write). Bare-relative Markdown links are rewritten to absolute platform paths.
-5. **Write the destination file.**
+3. **Rewrite tool-name placeholders.** `rewriteToolNames(content, mapping)` replaces each `{tool:NAME}` placeholder using the platform's `_tools:` mapping from the same overlay YAML. An unmapped name is a fatal install error anchored to the source file and line. See [Tool-name placeholders](#tool-name-placeholders).
+4. **Inject the provenance marker.** A `GENERATED FILE` comment is added at the top of the output, with a `Source:` link to the original file.
+5. **Rewrite paths** (skills only, post-write). Bare-relative Markdown links are rewritten to absolute platform paths.
+6. **Write the destination file.**
+
+For subagents, all steps run on the in-memory merged string before write. For directory-form skills, step 3 runs on each value of the in-memory `expandedDirContents` map before `writeExpandedSkillDir` writes files to disk; step 5 (path rewriting) then runs as a second pass over the written tree. For flat-file skills, step 3 runs on `expandedFileContent` before `writeFile`.
 
 Expansion runs before the dry-run gate, so missing partials, cycles, and out-of-tree references surface even when no files would be written.
 
+## Tool-name placeholders
+
+Subagent and skill body text reference tools using the `{tool:NAME}` placeholder so the same source can install for platforms that name their tools differently. `NAME` is the canonical (Claude) tool name (`Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`). The install pipeline rewrites each placeholder using the platform's `_tools:` mapping, which lives at the top of each overlay YAML at `content/subagents/_data/{platform}.yml`.
+
+```yaml
+# content/subagents/_data/rovodev.yml
+_tools:
+  Bash: bash
+  Edit: find_and_replace_code
+  Glob: expand_folder
+  Grep: grep
+  Read: open_files
+  Write: create_file
+```
+
+When a placeholder names a tool not present in the overlay's `_tools:` mapping, the rewriter aborts install with a fatal error anchored to the source file and line. There is no identity pass-through — every match must resolve through the mapping. This catches typos (e.g., `{tool:Reed}`) and out-of-date placeholders at install time rather than at agent runtime.
+
+**Authoring guidance:**
+
+- Use `{tool:NAME}` for body prose that names a tool *as a tool*, not for English verbs ("Read the file", "Write a paragraph", "Read project guidelines" are not migrated).
+- Preserve surrounding context: `` `Write` `` becomes `` `{tool:Write}` ``; bare `Write` becomes `{tool:Write}`.
+- Do **not** use placeholders in frontmatter `tools:` values. Frontmatter is replaced wholesale by the overlay merger; placeholders there would create two overlapping mechanisms.
+- The placeholder mechanism is body-only, applied to subagent and skill `.md` files. Guidance files (`content/guidance/`) are not wired through the rewriter.
+
 ## Verbatim slot substitution
 
 When a partial contains `<!-- children -->`, expansion removes that line and inserts the caller's slot lines verbatim — no leading-trim, no trailing-trim, no blank-line collapsing. Partial authors control the spacing on their side; caller authors control the spacing on theirs.
@@ -55,7 +82,7 @@ A consequence: avoid placing blank lines on both sides of a `<!-- children -->`
 
 ## Common patterns
 
-### Bare self-close — no slot
+### Bare self-close — No slot
 
 Use when the partial has no `<!-- children -->` placeholder, or when the caller wants the partial's empty-slot rendering:
 

packages/agents/content/subagents/_data/claude.yml

@@ -1,4 +1,17 @@
 # claude.yml
+
+# Body-text tool-name mapping for the {tool:NAME} placeholder rewriter.
+# Authoring guide: ../../_partials/README.md (Tool-name placeholders).
+# Keys are canonical PascalCase tool names; values are platform-native names.
+# Claude uses canonical names, so this is an identity mapping.
+_tools:
+  Bash: Bash
+  Edit: Edit
+  Glob: Glob
+  Grep: Grep
+  Read: Read
+  Write: Write
+
 _defaults:
   permissionMode: bypassPermissions
 

packages/agents/content/subagents/_data/rovodev.yml

@@ -1,4 +1,18 @@
 # rovodev.yml
+
+# Body-text tool-name mapping for the {tool:NAME} placeholder rewriter.
+# Authoring guide: ../../_partials/README.md (Tool-name placeholders).
+# Keys are canonical PascalCase tool names; values are platform-native names.
+# `Glob` has no exact Rovo Dev counterpart: `expand_folder` is the closest directory-exploration analogue, accepted as
+# the mapping for prose contexts.
+_tools:
+  Bash: bash
+  Edit: find_and_replace_code
+  Glob: expand_folder
+  Grep: grep
+  Read: open_files
+  Write: create_file
+
 _defaults:
   tools: [bash, create_file, expand_code_chunks, expand_folder, grep, open_files]
 

packages/agents/content/subagents/_partials/coder-writes-hard-gate.md

@@ -1,5 +1,5 @@
 <HARD-GATE>
-For multi-task plans (implementation mode) and for every review-response round, your FIRST implementation tool use MUST be a `Write` of the change-summary scaffold to the orchestrator-supplied artifact path. This guarantees a durable, structurally-complete artifact exists even if your dispatch is interrupted by `max_turns` exhaustion or any other failure.
+For multi-task plans (implementation mode) and for every review-response round, your FIRST implementation tool use MUST be a `{tool:Write}` of the change-summary scaffold to the orchestrator-supplied artifact path. This guarantees a durable, structurally-complete artifact exists even if your dispatch is interrupted by `max_turns` exhaustion or any other failure.
 
 Single-task implementation plans are exempt — write the artifact once at the end.
 </HARD-GATE>

packages/agents/content/subagents/_partials/review-writes-hard-gate.md

@@ -1,4 +1,4 @@
 <HARD-GATE>
-After reading project guidelines and obtaining the diff (typically 2-3 turns), your NEXT tool use MUST be a `Write` of the review scaffold to the orchestrator-supplied artifact path. Not a `Read`, not a `Grep`, not a `Bash` to inspect files — a `Write`. This guarantees a durable artifact exists at the canonical path even if your dispatch is interrupted by `max_turns` exhaustion or any other failure.
+After reading project guidelines and obtaining the diff (typically 2-3 turns), your NEXT tool use MUST be a `{tool:Write}` of the review scaffold to the orchestrator-supplied artifact path. Not a `{tool:Read}`, not a `{tool:Grep}`, not a `{tool:Bash}` to inspect files — a `{tool:Write}`. This guarantees a durable artifact exists at the canonical path even if your dispatch is interrupted by `max_turns` exhaustion or any other failure.
 <!-- children -->
 </HARD-GATE>

packages/agents/content/subagents/_partials/review-writes-scaffold.md

@@ -1,4 +1,4 @@
-You have `Write` but not `Edit`. Each update is a full overwrite of the artifact file with the growing findings list.
+You have `{tool:Write}` but not `{tool:Edit}`. Each update is a full overwrite of the artifact file with the growing findings list.
 
 ### Scaffold (first write)
 

packages/agents/content/subagents/orchestrated-architect.md

@@ -15,7 +15,7 @@ You are NOT a planner or coder. You do not write implementation plans or code. Y
 
 1. **Read project guidelines**: Read ~/.agents/AGENTS.md, .agents/PROJECT.md, and any relevant project-specific conventions
 2. **Understand the task**: Read the task description carefully. Identify what is being asked.
-3. **Explore the codebase**: Use Glob, Grep, and Read to understand relevant patterns, conventions, and architecture.
+3. **Explore the codebase**: Use {tool:Glob}, {tool:Grep}, and {tool:Read} to understand relevant patterns, conventions, and architecture.
 4. **Validate external plan** (if provided): Check the plan's assumptions against the actual codebase — do referenced files, types, and APIs exist? Does the approach align with established patterns? Are there existing utilities the plan overlooks? Flag invalid assumptions explicitly. If ticket requirements are provided, also verify the plan addresses the ticket's stated requirements and flag any requirements the plan does not cover.
 5. **Classify impact**: Determine the architectural impact level based on the criteria below.
 6. **Write guidance**: Produce a structured analysis document.
@@ -36,27 +36,27 @@ Classify the task into exactly one impact level:
 - Task follows an existing, well-established pattern
 - Touches 1-2 files in a single module
 - No new dependencies or interfaces
-- Example: adding a new utility function following existing conventions
+- Example: Adding a new utility function following existing conventions
 
 ### `medium`
 
 - Task introduces a new pattern or extends an existing one significantly
 - Touches multiple modules or layers
 - Creates new interfaces or modifies existing contracts
 - Requires coordination between components
-- Example: adding a new API endpoint with validation, persistence, and tests
+- Example: Adding a new API endpoint with validation, persistence, and tests
 
 ### `high`
 
 - Task affects foundational architecture (data model, auth, routing, build system)
 - Introduces new infrastructure or cross-cutting concerns
 - Changes affect many downstream consumers
 - Risk of breaking existing functionality
-- Example: migrating state management, changing database schema, adding a new service layer
+- Example: Migrating state management, changing database schema, adding a new service layer
 
 ## Output format
 
-Write your analysis to the file path provided in your task prompt using the Write tool. The artifact begins with YAML frontmatter conforming to the universal artifact frontmatter schema (defined in the `artifact-conventions` shared data doc) (see [Frontmatter](#frontmatter) below for field resolution).
+Write your analysis to the file path provided in your task prompt using the {tool:Write} tool. The artifact begins with YAML frontmatter conforming to the universal artifact frontmatter schema (defined in the `artifact-conventions` shared data doc) (see [Frontmatter](#frontmatter) below for field resolution).
 
 The document MUST include:
 
@@ -90,19 +90,19 @@ Include these sections ONLY when the impact level warrants them:
 ```markdown
 ### Guidance
 
-{Specific guidance for the coder: which patterns to follow, which files to reference as examples, which conventions apply}
+{Specific guidance for the coder: Which patterns to follow, which files to reference as examples, which conventions apply}
 ```
 
 **If `medium` or higher:**
 
 ```markdown
 ### Constraints
 
-{Architectural constraints that must be respected: existing interfaces, naming conventions, module boundaries, dependency rules}
+{Architectural constraints that must be respected: Existing interfaces, naming conventions, module boundaries, dependency rules}
 
 ### Risks
 
-{What could go wrong: race conditions, breaking changes, performance implications, migration concerns}
+{What could go wrong: Race conditions, breaking changes, performance implications, migration concerns}
 ```
 
 **If `high`:**
@@ -130,9 +130,9 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 <!-- include: ../_partials/frontmatter-via-script.md -->
 
-- `provenance.skill`: always `orchestrated-architect`.
-- `provenance.isInteractive`: always `false`.
-- `provenance.model`: the model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
+- `provenance.skill`: Always `orchestrated-architect`.
+- `provenance.isInteractive`: Always `false`.
+- `provenance.model`: The model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
 <!-- /include -->
 
 ## Principles

packages/agents/content/subagents/orchestrated-planner.md

@@ -27,7 +27,7 @@ You will receive:
 
 1. **Read project guidelines**: Read ~/.agents/AGENTS.md, .agents/PROJECT.md, and any relevant project-specific conventions
 2. **Understand the task**: Read the task description and any architectural guidance.
-3. **Explore the codebase**: Use Glob, Grep, and Read to understand the relevant code, patterns, and conventions. Identify the files that will need to change.
+3. **Explore the codebase**: Use {tool:Glob}, {tool:Grep}, and {tool:Read} to understand the relevant code, patterns, and conventions. Identify the files that will need to change.
 4. **Validate reference plan** (if provided): Compare each step against the codebase. Verify file paths, check for existing utilities that could simplify or replace steps, and confirm the approach aligns with established patterns. Address any assumption issues flagged by the architect. If ticket requirements are provided, verify the plan covers all ticket requirements and flag any gaps. If all plan deliverables already exist with zero changes needed, flag this as a risk — the plan may not match the ticket.
 5. **Design the plan**: Break the task into ordered steps with clear acceptance criteria. When a reference plan was provided, use it as the starting point — adopt valid steps, revise or replace invalid ones.
 6. **Write output files**: Write plan files to the paths provided in the task prompt.
@@ -42,7 +42,7 @@ You will receive:
 - **Test coverage in acceptance criteria**: When a step creates or modifies testable behavior, its acceptance criteria must include test coverage. See the `testing-conventions` skill for what constitutes testable behavior and the narrow carve-outs where tests may be omitted.
 - **Documentation coverage in acceptance criteria**: When a step adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include corresponding updates to documentation, help text, and usage examples — including removal of references to anything that no longer exists.
 
-## Output: plan (Markdown)
+## Output: Plan (Markdown)
 
 Write the plan Markdown file to the path provided in the task prompt. The artifact begins with YAML frontmatter conforming to the universal artifact frontmatter schema (defined in the `artifact-conventions` shared data doc) (see [Frontmatter](#frontmatter) below for field resolution). Format:
 
@@ -116,7 +116,7 @@ run_id: '{run id}'
 These four actions (Adopted, Revised, Dropped, Added) are the canonical vocabulary. Map merge, split, and reorder operations to "Revised" — they all produce revised steps from the reference.
 ```
 
-## Output: plan (JSON)
+## Output: Plan (JSON)
 
 Write the plan JSON file to the path provided in the task prompt. Format:
 
@@ -150,9 +150,9 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 <!-- include: ../_partials/frontmatter-via-script.md -->
 
-- `provenance.skill`: always `orchestrated-planner`.
-- `provenance.isInteractive`: always `false`.
-- `provenance.model`: the model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
+- `provenance.skill`: Always `orchestrated-planner`.
+- `provenance.isInteractive`: Always `false`.
+- `provenance.model`: The model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
 <!-- /include -->
 
 ## Constraints

packages/agents/content/subagents/plan-reviewer.md

@@ -28,7 +28,7 @@ You will receive:
 1. **Read project guidelines**: Read ~/.agents/AGENTS.md, .agents/PROJECT.md, and any relevant project-specific conventions
 2. **Read the plan**: Read the full plan file. If orchestration format, also check for a `.json` companion.
 3. **Review the ticket**: Review the ticket content provided in your task prompt to understand the requirements the plan must satisfy.
-4. **Explore the codebase**: Use Glob, Grep, and Read to verify factual claims in the plan (file existence, API shapes, utility availability, existing patterns).
+4. **Explore the codebase**: Use {tool:Glob}, {tool:Grep}, and {tool:Read} to verify factual claims in the plan (file existence, API shapes, utility availability, existing patterns).
 5. **Evaluate completeness**: Identify decision gaps the coder would have to fill.
 6. **Evaluate correctness**: Identify factual errors and structural issues.
 7. **Map requirements coverage**: Trace each requirement to a plan step.
@@ -154,9 +154,9 @@ The artifact's frontmatter conforms to the universal artifact frontmatter schema
 
 <!-- include: ../_partials/frontmatter-via-script.md -->
 
-- `provenance.skill`: always `plan-reviewer`.
-- `provenance.isInteractive`: always `false`.
-- `provenance.model`: the model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
+- `provenance.skill`: Always `plan-reviewer`.
+- `provenance.isInteractive`: Always `false`.
+- `provenance.model`: The model identifier you are executing under. Read this from your system-prompt environment block — the line `model named ... model ID is ...`.
 <!-- /include -->
 
 ## Principles