Contributing

Thanks for wanting to contribute. One rule up front:

Human-authored pull requests targeting main must be raised through no-mistakes. We require this to reduce the maintainer's burden of reviewing and merging contributions.

no-mistakes puts a local git proxy in front of your real remote. Pushing through it runs an AI-driven review/test/build pipeline in an isolated worktree, forwards the push to the configured target only after every check passes, and opens a clean PR automatically. Fork-based contributions require no-mistakes v1.30.1 or newer.

A GitHub Actions check (Require no-mistakes) runs on PRs targeting main and fails if the body is missing the deterministic signature that no-mistakes writes. The release and dependency bots are exempt so their automation keeps working, but regular contributor PRs without the signature will not be reviewed or merged.

A second GitHub Actions check (Guard generated files) fails PRs that hand-edit release-please-generated files. Release-please PRs are exempt because they are the only place those files should change.

Workflow

1. Fork the repo, then clone the parent repo or set your local origin back to the parent repo (git@github.com:kunchenguid/axi.git).

2. Create a branch and make your changes.

3. Initialize or refresh the gate with your fork as the push target: no-mistakes init --fork-url git@github.com:<you>/axi.git.

4. Commit your changes.

5. Push through the gate instead of pushing to origin:

   git push no-mistakes
   

6. Run no-mistakes to attach to the pipeline, watch findings, and auto-fix or review as needed.

7. Once the pipeline passes, it pushes your branch to your fork and opens the PR against this repo for you.

See the no-mistakes quick start for the full first-run walkthrough.

Adding your AXI to the catalog

The catalog has one source of truth: catalog.yaml. The tables in README.md and on axi.md are generated from it.

1. Add one entry for your AXI to the community list in catalog.yaml.
2. Run pnpm run docs:gen to regenerate README.md and docs/index.html.
3. Commit all three files and open your PR through the workflow above.

Do not hand-edit the generated table regions (marked with generated:... comments); the docs-check CI job fails on drift.

Repo conventions

• AXI is a pnpm monorepo for the AXI docs, benchmark harnesses, installable agent skills, and the axi-sdk-js package.

• Use Node 24 locally to match CI.

• The SDK package lives in packages/axi-sdk-js.

• Unit tests use Vitest and are co-located under test/.

• Use pnpm for package scripts.

• Run the same gate commands that CI runs before pushing:

  pnpm install --frozen-lockfile
  pnpm run format:check
  pnpm run lint
  pnpm --dir packages/axi-sdk-js run build
  pnpm --dir packages/axi-sdk-js test
  

• packages/axi-sdk-js/dist/ is generated by pnpm --dir packages/axi-sdk-js run build and is intentionally not committed.

• Do not hand-edit packages/axi-sdk-js/CHANGELOG.md or .release-please-manifest.json.

• The Guard generated files check enforces that rule on pull requests to main.

• Those files are regenerated by release-please from conventional commit messages.

• If you want your change to appear in release notes, use a conventional commit message such as feat:, fix:, or docs:.

• If you touch bench-browser/ or bench-github/, also run that package's relevant scripts before pushing.

Questions

Open an issue, or talk to me on Discord.