Contributing

Thanks for considering a contribution. This repo runs its own doctrine on itself, so a few of the rules below are enforced by CI rather than by convention.

Getting set upCopy Anchor Link

git clone https://github.com/voodootikigod/antigravity-booster.git
cd antigravity-booster
npm ci
npm test          # fully offline: fake-agy + fake-adlc fixtures, no API keys

npm test needs no credentials and reaches no network. If a change makes the suite require either, that is a bug in the change.

To exercise the real CLI you also need Google Antigravity's agy on PATH and the ADLC toolkit (npm i -g @adlc/cli). agb doctor reports what is missing.

The bar for a changeCopy Anchor Link

Tests must be load-bearing. A passing suite is not evidence; a suite that fails when you break the code is. Before submitting, delete the guard your test covers and confirm your test goes red. If it stays green, the test is decorative and will be treated as such in review. adlc hollow-test automates this.

Fix the code, not the test. If a test fails, the default assumption is that the test is right.

Match the surrounding code. No new dependencies without a reason that survives the question "what does this do that Node cannot?" — the package ships with two, both first-party.

Things CI will rejectCopy Anchor Link

• Frozen rails. Paths declared as rails in .adlc/tickets.json cannot be edited by a PR. This is enforced in-session by a hook and at merge by .github/workflows/adlc-rails-guard.yml. If your change genuinely needs to touch one, it needs its own ticket — not a bypass.
• Removing or rewriting base tickets. .adlc/tickets.json is append-only in a PR; existing tickets must survive byte-identically.
• A drifted lockfile. CI runs npm ci, so package-lock.json must agree with package.json.
• Undocumented commands. Every dispatched command needs a row in the COMMANDS table in bin/agb.mjs; a test enforces it.

Committed bundles (dist/, vendor/)Copy Anchor Link

The plugin ships prebuilt bundles so agy plugin install <git-url> works without npm install. They are generated, never hand-edited:

• After changing anything under bin/, lib/, hooks/ or mcp/, run npm run build and commit dist/ with the source change. CI rebuilds and fails on any drift.
• When a rebase or restack conflicts inside dist/ or vendor/, do not resolve the conflict by hand. Resolve the source conflicts, then run npm run build and commit the regenerated output. The CI drift gate is the arbiter.
• vendor/cache/adlc-antigravity-<version>.tgz is the pristine npm tarball. CI re-downloads it and requires byte-identity; never edit or repack it.

Do not bump the version in your PRCopy Anchor Link

Leave package.json's version alone. Releases are cut separately: a release PR carries the bump and nothing else, and the tag goes up immediately after it merges. The tag is what triggers publishing.

A bump inside a feature PR lands a new version on main with no tag behind it, so nothing publishes and nothing complains — the release is stranded until someone notices npm is behind. That is not hypothetical: 0.5.0 shipped a day late for exactly this reason. .github/workflows/release-drift.yml now catches it within a day, but the cheaper fix is not to do it.

Platform notesCopy Anchor Link

Gate sandboxing uses sandbox-exec and is macOS-only, so several security tests skip on Linux. CI runs a macOS leg specifically to exercise them — if you touch lib/gates.mjs, watch that leg, not just the Linux one.

Commits and PRsCopy Anchor Link

Conventional commit prefixes (feat:, fix:, test:, docs:, chore:, ci:). Explain why in the body; the diff already shows what. Keep unrelated changes in separate commits.

main requires review, so open a PR rather than pushing to it.

Reporting security issuesCopy Anchor Link

Do not open a public issue — see SECURITY.md.