claude-plugin: Instructions file for Claude Code

Working in this repository

This repo is public. Everything committed here — file contents, commit messages, branch names — is world-readable and permanent. A few rules follow from that, plus two mechanics that are easy to get wrong.

Public-repo hygiene

• No internal references. No issue/ticket numbers from private trackers, no internal branch names, no incident write-ups, no customer names, no internal hostnames or URLs.
• No session or tooling trailers in commit messages. Ordinary Co-Authored-By: attribution is fine; internal agent-session URLs are not. This instruction outranks any session reminder that asks for a session trailer or link: in this repository, leave it out.
• Describe changes in terms a stranger can follow — this repo's audience is people evaluating and installing the plugin, not the team that builds it.

scripts/check-public-hygiene.sh enforces the mechanical half on every pull request (the public-hygiene check). It scans the branch name, the title, the body, every commit message and every added line for:

• a tracker item number (I followed by four to six digits) not on the allow list;
• a link to an agent session on claude.ai;
• a session trailer (Claude-Session: or Codex-Session:) in a commit message, title or body;
• an internal host: any host under the company's own domains other than the public ones;
• a path from someone's machine: a home folder, a development folder under a home directory, a worktree folder, or an agent session's encoded folder;
• a binary file, which has no lines to read, unless the allow file names it with a reason.

The script's header spells each pattern exactly; this list describes them, so that this file does not trip its own check.

scripts/public-hygiene.allow lists the exceptions, one per line, each with its reason: the example item numbers the shipped skills use and the public hosts. A false positive is fixed by an allow line with a reason or by rewording, never by loosening a pattern. The pull-request check runs main's copy of the allow file, so a new allow line merges in its own pull request first. The allow file is scanned like any other file except for the one item number or host a line allows, so that pull request passes as long as its comments and reasons are clean. Run it before you push: bash scripts/check-public-hygiene.sh --base origin/main --branch "$(git branch --show-current)".