docs(skill): always use the plannotator tool over the CLI when you have it

[backnotprop]

The failure

In a Claude Code session where the mod had registered the plannotator tool (listed as mcp__plannotator__plannotator, deferred behind tool search), Claude was asked for an approval and ran plannotator annotate <file> --gate --json through Bash instead of calling the tool. The skill's tool rule was one hedged sentence. Directly under it, a table headed "Run" listed only CLI commands, including that exact command. The annotate section's strongest instruction was "always add --gate --json", with no tool form for approvals.

The change (one file: apps/skills/core/plannotator/SKILL.md)

There is still one skill for every agent, distributed as before. Nothing changes in the installers, the per-host files, or the tool contract.

• A new section near the top, "If you have a plannotator tool, always use it":
  • Check your tools first, and always call the tool instead of annotate / review / last.
  • Approvals are covered: { "action": "annotate", "target": "<file>", "gate": true }, not --gate --json.
  • It says the tool can be listed with a prefix (mcp__plannotator__plannotator) and can need loading through tool search.
  • The tool returns at once: end your turn and wait, and do not also run the CLI, poll, or reopen the session.
  • It lists what still needs the CLI: archive, guide, sessions, review flags other than --base, annotate flags other than --gate / --markdown, and strict exit-code gates.
• The table header now reads "Run (CLI, when you have no plannotator tool)".
• The annotate approval sentence gives the tool form first ("gate": true) and --gate --json as the fallback.
• One "Do not" line: do not run annotate / review / last through a shell when you have the tool.
• The frontmatter description and the intro sentence no longer present Plannotator as CLI-only.

Reviewed from the clean-room proposal: kept vs cut

Kept: the strong top rule, the approval form with gate: true, the end-your-turn-and-wait behavior, the note on prefixed and deferred tools, the tool form at the two places that pulled Claude to the CLI (the table and the annotate approval sentence), the "Do not" line, and the description/intro wording.

Cut:

• The 6-row intent→input table. The tool's own description and schema already document every input once it is loaded. The one mapping that matters (approval) is written out inline.
• "Any tool whose name ends in plannotator". It is an open heuristic that could match an unrelated tool. The rule names the real prefixed form instead.
• The tool description changes in both contract files. The current description already says to use the tool instead of the CLI and documents gate: true. Because the tool is deferred, the skill is what the agent reads before it loads the tool. Leaving the description alone also avoids a conflict with the concurrent CONTRACT edit.
• The Session-model prefix ("the tool never blocks"). That section describes the CLI, and the top rule already says the tool returns at once.
• The tool form in annotate-last. The "Do not" line and the top rule already cover last, and { "action": "last" } is in the tool description.

Fact checks against the code: the tool takes only action, target, gate (annotate only), and options.base / options.markdown (packages/shared/plannotator-tool.ts). So --diff-type, --patch-file, --app / --static, --tailscale, and the strict flags all really are CLI-only. The decision "arrives later as a message" on the only host that registers the tool today (the Claude Code mod). The wording stays host-neutral for Pi and OpenCode when they adopt the tool.

Tests

bun test apps/hook/server/plannotator-skill-reference.test.ts apps/hook/hooks/mod/tool.test.ts packages/shared/plannotator-tool.test.ts apps/pi-extension/bundled-skill.test.ts: 19 pass, 0 fail. The skill still contains plannotator annotate <file> --gate --json, which the freshness test pins. Every flag the new text mentions exists in the CLI. apps/marketing/src/pages/llms.txt.ts still strips the opening summary line as before.