<!--
  scaffold: tool-development-policy.md
  bucket: delegation-dispatch (Bucket 3)
  what belongs here: the tool-development-through-tool-developer policy.
    - Node.js only. Cross-platform breakage rationale.
    - Every CLI or script — dispatch tool-developer with a briefing contract.
    - Never build tools inline.
-->

# Tool development policy

## Rule

**All tool development goes through the `tool-developer` role.** Not the PA directly, not any other role — the tool-developer.

## Language

**Node.js only.** No shell scripts, no PowerShell, no Python (for the PA's own tool estate — this is the operating platform, not the operator's product).

**Cross-platform breakage rationale:** the platform ships to macOS, Linux, and Windows. A `.sh` tool silently breaks on Windows; a `.ps1` tool silently breaks on Unix. Node runs the same on all three. Node stdlib (`node:child_process`, `node:fs`, `node:dns`, `node:http`, `node:path`) covers most of what a shell script would do.

## When to dispatch

- Any new CLI, script, or integration — dispatch tool-developer.
- Any change to an existing tool — dispatch tool-developer.
- Any diagnostic script that will get re-used — dispatch tool-developer to make it a real tool.

## Brief shape for tool-development dispatches

The tool-developer's brief follows the 8-section contract with two additions in the Boundaries section:

- Node-only constraint stated explicitly (as a reminder that a briefer might otherwise let a `.sh` slip past).
- Cross-platform runtime target stated: macOS + Linux + Windows.

Full pattern in the tool-developer role definition.

## Existing tool surface

The platform ships a set of bins: `pa`, `desk`, `secrets`, `sync`, `scheduler`, `smoke`, `distill`, `memory-sync`, `pa-init`, `slice`, `launch`, `migrate-inspect`. The operator layers additional tools under `operator/extensions/tools/`.

Always check the current surface before proposing a new tool — `pa --help`, `desk --help`, `ls operator/extensions/tools/`. Proactive-tool-proposal (Bucket 7 rule 9) applies here too: if a task pattern repeats and there's no tool, propose one.

## Related

- CLAUDE.md.template Bucket 3 rule 10.
- `packages/core/roles/tool-developer/definition.md` — the tool-developer role.
- `packages/core/docs/standards/tooling.md` — the tooling standard the role follows.
- CLAUDE.md.template Bucket 7 rule 9 — proactive-tool-proposal.