claude-plugins: Instructions file for Claude Code

CLAUDE.md — patrickdappollonio/claude-plugins

A plugin marketplace for both Claude Code and the Codex CLI. Two root manifests list the plugins under plugins/: .claude-plugin/marketplace.json (Claude Code) and .agents/plugins/marketplace.json (Codex). Each plugin in turn carries two manifests: .claude-plugin/plugin.json and .codex-plugin/plugin.json.

Hard rules

• Never add Claude/AI attribution to commits or PRs — no Co-Authored-By: Claude, no "Generated with Claude Code". This is a standing, non-negotiable constraint from the repo owner.
• Commit/push only when asked. Work on a branch, not main.
• Never hard-wrap Markdown. Every paragraph, heading, list item, and table row sits on one source line, however long; the editor wraps it for display. Do not break prose at 80 columns or any other width, and do not "fix" a long line by splitting it. This keeps diffs to the words that changed, and it keeps a line number pointing at a whole thought. npm run lint:markdown (scripts/lint-markdown-wrap.mjs) fails on any paragraph or heading that spans more than one line; CI runs it on every .md change. Code blocks, front matter, and tables are not checked, and a GitHub admonition may keep its > [!NOTE] marker on its own line above one line of text.
• Bump the plugin's version on every meaningful change, in its plugins/<name>/.claude-plugin/plugin.json, following semver: patch for fixes and doc/wording tweaks, minor for new backwards-compatible capability (a new command, fence, or skill behavior), major for breaking changes (removed/renamed commands, changed file formats or defaults users rely on). Pure repo chores that don't touch a plugin (root README, CI) don't need a bump. The version lives only in that plugin.json — there are no git tags, GitHub releases, or per-plugin versions in marketplace.json to check or update, so don't go looking. The matching plugins/<name>/.codex-plugin/plugin.json repeats that version for Codex and must be updated in the same change.
• Every plugin ships four files, and a new plugin is not done until all four exist. Codex and Claude Code never read each other's files, so a plugin missing any one of these is silently absent from that tool's marketplace — nothing fails, it just never shows up:
  1. plugins/<name>/.claude-plugin/plugin.json — the Claude Code manifest.
  2. plugins/<name>/.codex-plugin/plugin.json — the Codex manifest. Same name, version, description, author, homepage, license, and keywords, plus "skills": "./skills/" and an interface block (displayName, shortDescription, longDescription, developerName, category, capabilities, defaultPrompt). Copy a sibling plugin's file and edit it.
  3. An entry in .claude-plugin/marketplace.json (name, source, description, category, keywords, author, homepage, license).
  4. An entry in .agents/plugins/marketplace.json (name, source {"source":"local","path":"./plugins/<name>"}, the standard policy block, and a category matching the Codex manifest's interface.category). Keep the two marketplace files listing the same plugins in the same order. Before finishing any change that adds, renames, or removes a plugin, run npm run lint:marketplace (scripts/check-marketplaces.mjs, also run in CI) and expect ok. This rule exists because the three plugins added right after the Codex marketplace landed (implement-plan, planning-flow, recap) each got a Codex manifest but no Codex marketplace entry, so Codex users never saw them.
• The all bundle is the one exception to the four-file rule, and every new plugin must be added to it. plugins/all/ holds only .claude-plugin/plugin.json and a README, and appears only in .claude-plugin/marketplace.json. Its manifest lists every other plugin under dependencies, so /plugin install all@patrickdappollonio installs and enables them all. It has no Codex manifest or Codex marketplace entry because Codex has no plugin dependencies (unknown manifest keys are silently ignored, and codex plugin add takes one plugin), so a Codex bundle would install nothing; the README tells Codex users to install plugins one by one and other agents to use npx skills add … --all. Keep the dependencies as bare names: a version range makes Claude Code resolve <plugin>--v<version> git tags, which this repo does not have. When you add, rename, or remove a plugin, update the dependencies list and bump the bundle's minor (add) or major (remove/rename) version; npm run lint:marketplace fails if the list and the marketplace disagree. Do not bump the bundle when a child plugin's version changes. A dependency with no version range tracks the marketplace's latest version, so users get the child's update through the child itself; the bundle's version changes only when its own dependencies list or manifest changes.
• All install paths must stay equivalent: Claude Code marketplace, Codex marketplace, and npx skills. Claude Code and Codex install a whole plugin (every skill under plugins/<name>/skills/); npx skills add … --skill <name> installs one skill directory and nothing above it. So a skill must be self-contained: everything it needs lives inside its own skills/<skill>/ directory, and nothing in SKILL.md may reach outside it — no ../ paths, no "see the other skill's file", no reliance on a sibling skill being present, and no symlinks (a symlink out of the directory arrives as a plain text file on a Windows checkout with core.symlinks=false — a silent, broken install). Duplicating shared prose or code into each skill is the correct trade-off, as visual-docs does with the renderer. A plugin may hold several skills; each must work alone. When you add a skill, also add it to the root README's --skill name table, and phrase cross-skill references so they degrade to a name a reader can install ("the full adversarial-review skill"), never a relative path.
• Some skills carry a distilled copy of another skill, and every change to the parent must be checked against each copy. Because a skill must work alone, several of them ship a shortened version of a sibling skill as a companion file, used when the real one is not installed: implement-plan carries adversarial-review-fallback.md, appropriate-comments-fallback.md, and code-simplification-fallback.md; planning-flow carries the on-the-spot panel in plan-review.md and communication.md; recap carries communication.md; anti-slop-text carries communication.md; effective-go carries comments.md and simplification.md; planning-flow-quick carries question-format.md, verification.md, and communication.md from planning-flow, and its plan-check.md holds a one-subagent digest of planning-flow's plan reviews and of adversarial-review-fast. The too-big signs are written in both planning-flow-quick's SKILL.md and planning-flow's When to Use, and the quick plan's marker line and section names are what planning-flow (Picking up a quick plan) and implement-plan (step 0) read, so a change to either side is checked against the other. These copies do not update themselves. When you change what a skill does — its procedure, its thresholds, when it runs, what it asks — grep plugins/*/skills/*/ for the skill's name and for the rule you changed, open every digest that hits, and bring it into line in the same PR. The same applies in reverse: a change to a flow that uses a digest (when the review runs, what the pass covers) must be reflected in that digest's own text, not only in SKILL.md. A digest that describes the old behavior is a silent fork: an npx skills user of the standalone skill gets the old rule with no error. This bit us when the review cadence changed and the capacity math still budgeted a panel per fix round.
• Skills: extract whatever can be read on demand, but always keep the general guideline inline — otherwise the extraction is moot. The whole SKILL.md loads into context on every invocation, so keep it under ~500 lines. It holds what steers behavior on every pass — principles, the process outline, decision tables, rationalizations, red flags, the checklist — plus a short, self-sufficient summary of every extracted topic (the rule, the threshold, the one-line procedure). The comprehensive version — full procedures, routing tables, handoff templates, digests of other skills — goes in a .md file in the same skill directory, and the summary says exactly when to read it ("read cyclomatic-complexity.md before splitting a function"). An agent that never opens the side file must still do the right thing from the summary alone. Load-bearing discipline rules stay inline in full — an agent under pressure will skip a side file. Reference sibling files by bare filename, never a path, so every install path ships them. And the skill must insist that the agent read every companion file on first use in a session, before any other step — a dedicated section near the top listing the files, plus a red flag and a checklist item — and re-read the named file at its step. Summaries are reminders of text already read, never a substitute. code-simplification is the worked example.
• Every subagent a skill dispatches is one-shot, and more work is always a new subagent. A skill that delegates must say, inline in SKILL.md and in every prompt template it ships, that each subagent gets one self-contained task, returns its result, and ends: it never waits for a reply, for the orchestrator's next instruction, or for the user, and the orchestrator never resumes, messages, or continues it (SendMessage in Claude Code, or the equivalent). A send-back, a re-check, a re-validation, or a follow-up question is a new subagent whose prompt carries everything, including the earlier result. Prompt templates end with a line telling the subagent the task is single and nobody will send further instructions. The reason is cost: a subagent's prompt cache expires within minutes of going idle, far sooner than the main session's, so each later message to it re-reads its whole history at full price, and a long-lived orchestrator can burn most of a weekly limit this way. The same cost hits a subagent that sits silent inside its own run: a command it blocks on makes no model requests, so a test suite or build past five minutes expires its cache before it reads the result. Every skill whose subagents run commands must therefore carry the heartbeat rule inline: a command that may run past three minutes starts in the background with output and exit code going to a log, and the subagent checks it with a foreground loop capped at three minutes (for i in $(seq 18); do grep -q '^EXIT=' <log> && break; sleep 10; done) until it finishes, never a bare sleep (Claude Code refuses it), never a monitor or notification with no cap, and never by ending its run early; past about 40 minutes of expected wait, one cold restart is cheaper than the checks. The closing line of every prompt template carries the same rule in one sentence. When a skill gains a new subagent role, a loop, or a pause, check it against these rules and carry them into any digest of that skill.
• Skill frontmatter must parse as YAML and fit the Agent Skills limits. Keep name and description as non-empty strings. name is lowercase letters, digits, and single hyphens, at most 64 characters; description is at most 1024 characters (the spec's hard cap — an over-limit skill is silently skipped by some agents) with the key use case in the first sentence, because Claude Code truncates the listing text at 1536 characters. Quote or fold descriptions containing : rather than leaving them as plain YAML scalars. Keep the SKILL.md body under 500 lines. After adding or editing a skill, run npm run lint:skills, which enforces the name and description limits; CI runs the same check for every directory under plugins/*/skills/.
• The visual-docs server has no authentication. --host / 0.0.0.0 binding must stay opt-in and documented as trusted-network-only.
• Agents must never have to write code — not even a small script — to operate visual-docs. Every operation an agent performs (resolve a directory, serve, read comments, set status, lint, stop) must be a first-class node visual-docs-server.js --<command> / visual-docs-lint.js invocation that prints ready-to-read, formatted text (never JSON the agent must parse, and never something it has to curl/jq/python/node -e to consume). Keep these commands OS-agnostic as much as possible: do the platform-specific work (temp dirs via os.tmpdir(), backgrounding via detached spawn, HTTP via fetch) inside the Node CLI, so the skill only ever runs node <script> <args> — no nohup/&, no /tmp paths, no shell-only constructs. When you add an agent-facing capability, add a --command for it; don't make the agent improvise glue.