Working on this repository

This is a Claude Code plugin marketplace. Read this before changing anything.

Layout

• skills/<plugin>/<skill>/SKILL.md: every skill, grouped by plugin. Bundled files (reference docs, scripts, templates) sit next to the SKILL.md that uses them.
• hooks/<plugin>/: hook scripts and the hooks.json that registers them. hooks/lib/ is shared by all hooks.
• .claude-plugin/marketplace.json: one entry per plugin plus the pau-skills bundle. Every entry is rooted at the repository ("source": "./", "strict": false). Never add .claude-plugin/plugin.json; it conflicts with that.
• .claude/agents/: the roster that geppetto installs, used by the batches. Change a roster agent in skills/agent-orchestration/geppetto/roster/ first, raise the roster number on every covenant marker, then update the installed copy. Never put agent files in a root agents/ folder: every plugin here would load it.
• scripts/: repository tooling. tests/: node:test suites. docs/: install guide, origins, rules, how to add a skill.

Rules

• Follow docs/ADDING-A-SKILL.md for any new skill or hook.
• After changing a hooks.json or adding a plugin folder, run node scripts/build-marketplace.mjs. Never edit the skills or hooks fields in marketplace.json by hand.
• Bundled files are referenced as ${CLAUDE_PLUGIN_ROOT}/skills/<plugin>/<skill>/<file> or ${CLAUDE_PLUGIN_ROOT}/hooks/<plugin>/<file>. A file in the skill's own folder can instead be ${CLAUDE_SKILL_DIR}/<file>, which also works when the skill is installed on its own, without the plugin. A test fails on any such path that does not exist.
• Every skill works when installed on its own, without the plugin or any other skill. A mention of another skill is an optional extra that says what to do if it is not installed. A script a skill needs from another skill is copied into its folder. tests/standalone.test.mjs checks all three.
• Scripts and hooks use the Node.js standard library only (Node 20+). A hook exits 0 on input it does not understand, unless failing closed is its purpose, and checks hookEnabled() from hooks/lib/config.mjs.
• Skills are language-neutral: never assume JavaScript; cover the common ecosystems or detect the project's tooling.
• Writing style: plain, direct English. No em or en dashes (a test enforces this), no marketing words.
• Bump the version of every plugin whose files changed, and the pau-skills bundle, in marketplace.json, and add a line to CHANGELOG.md. When a hook changes, bump pau-skills-hooks as well.
• The owner installs skills by uploading them to claude.ai (zips, one per skill, folder at the root) and hooks through pau-skills-hooks. After a merge that adds or changes a skill, hand over the zips for those skills, built on main with node scripts/pack-skills.mjs --since <main before the change>; see step 10 of "How to run a batch" in docs/backlog/how-to-run-a-batch.md. A new batch starts from the kickoff message in docs/backlog/kickoff.md.

Checks before every commit

npm test
npm run scrub
node scripts/build-marketplace.mjs --check
claude plugin validate . --strict

Prove a new test can fail with bash skills/verification/mutation-test/mutate.sh (commit first).