Contributing
- You will learn: how to propose a change, what every change keeps, the checks, how versions move and how to run the plugin from a checkout.
- Reading time: 3 minutes.
- Before this: Install GTM.
GTM stays useful by staying light. A change is welcome when it removes work for you or the team, and suspect when it adds a document, a role or a question. Propose it in an issue first, keep the pull request small, and update the CHANGELOG and the version together.
How do I propose a change?
- Open an issue: the problem in one paragraph, the change, what it costs (a new file, more tokens, one more question to you) and what it removes.
- For a change to a position or a principle, say which one and why the trade-off should move.
- Keep each pull request to one logical change.
- Write Conventional Commits; pull requests land as merge commits (no squash).
What does every change keep?
- Each file earns its place and starts with a short summary; English throughout; no emoji in docs.
- Skills under 500 lines (aim for under 80); agent prompts short; descriptions concise, since they load in every session.
- Nothing that Claude Code ignores in a plugin is added: no agent
hooks,mcpServersorpermissionMode, and no rootCLAUDE.md. - Workflows stay deterministic: no
Date.now(),Math.random()or arglessnew Date().
Which checks must pass?
node scripts/validate.mjs and claude plugin validate . must pass; CI runs both on every push.
Each scripts/*.test.mjs proves it can fail: scripts/twins.test.mjs plants one defect per row and
the test must name it, so a new test needs its row. Up to four tests run at a time, each once and
for five minutes at most: no rerun turns a red gate green.
validate.mjs also checks the documentation site’s sources (scripts/site-checks.test.mjs --source). On every pull request the Pages workflow builds the site and runs the full checks:
links, and in a browser the overflow, 44 px targets, reading measure, contrast, tables and axe
(scripts/site-measure.test.mjs); it deploys from main.
validate.mjs also runs each workflow against scripted agents (scripts/workflows.test.mjs): a
new workflow needs a scenario there, and a changed default or threshold changes one.
The size check, node plugins/gtm/scripts/size.mjs, counts what GTM adds to every session: about
760 tokens in 0.13.0, against a budget of 800 held in the script. CI runs it on every push and
fails above the budget. A change that must grow a description raises the budget in its own
commit, saying why; the docs then state the new figure.
How do versions move?
SemVer, in plugins/gtm/.claude-plugin/plugin.json only, never in the marketplace entry. Bump it
in the release commit, with its CHANGELOG.md entry.
| Bump | When |
|---|---|
| Patch | fixes, wording, a clearer prompt |
| Minor | a new skill, role, config field or behaviour that existing projects can ignore |
| Major | a change existing .gtm/ folders must migrate to (renamed files or fields); the release notes say how |
Each release adds a section to CHANGELOG.md (Keep a Changelog). Tags are v<version>, created
by the maintainer.
How do I run GTM from a checkout?
claude --plugin-dir ./plugins/gtm loads the plugin from a checkout; /reload-plugins picks up
edits. A marketplace added from a local path also reads files in place, with no version bump.
In the VS Code extension, the command menu lists new or updated skills only after a window reload
(Developer: Reload Window); /reload-plugins alone does not refresh it.