# Contributing

Thanks for wanting to contribute.
One rule up front:

**Human-authored pull requests targeting `main` must be raised through [`no-mistakes`](https://github.com/kunchenguid/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`:

   ```sh
   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](https://kunchenguid.github.io/no-mistakes/start-here/quick-start/) for the full first-run walkthrough.

## 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:

  ```sh
  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](https://discord.gg/Wsy2NpnZDu).
