how to contribute development workflow

Development workflow

The cycle for any change is branch, code, test, pull request, merge. This page describes the concrete steps and the git rules that keep multiple agents working in the same worktree safe.

Branch to merge

1. Create a feature branch from main.
2. Make your change and run npm run check. For tests, run them from the package root (see Testing).
3. Update the affected package CHANGELOG.md.
4. Open a pull request against main. Reviewers analyze the PR without pulling it locally.
5. If the requester approves, create a feature branch, pull the PR, rebase on main, apply requested adjustments, commit, merge into main, push, close the PR, and leave a comment in the contributor's tone.
6. Never merge PRs yourself; the requester decides when a branch is ready.

Git rules for parallel agents

Multiple agents may edit the same worktree at once. The rules in AGENTS.md are mandatory:

• Only commit files you changed in this session.
• Stage with git add <specific-file-paths>, never git add -A or git add ., which sweep up other agents' work.
• Before committing, run git status and verify you are staging only your files.
• Forbidden operations that destroy other agents' uncommitted work: git reset --hard, git checkout ., git clean -fd, git stash, and git commit --no-verify.
• Push with git pull --rebase && git push. Never force push. If a rebase conflicts, resolve conflicts only in your own files; if a conflict is in a file you did not modify, abort and ask.
• Include fixes #<number> or closes #<number> in the commit message when a related issue or PR exists.

Commit conventions

• Commit messages use conventional prefixes such as fix(ai): description.
• Adding a provider, fixing a bug, or shipping a new package follows the format in AGENTS.md; commits reference the issue or PR they close.

Changelog discipline

• Each package has its own packages/*/CHANGELOG.md.
• New entries always go under ## [Unreleased] as a flat list of past-tense bullets, one bullet per line. No ### Added / ### Changed / ### Fixed / ### Removed subsections.
• Never modify already-released version sections; each is immutable once released.
• Internal fixes cite the issue: Fixed foo bar ([#123](https://github.com/PrimeIntellect-ai/prime-agent/issues/123)). External contributions cite the PR and author.
• Read the full [Unreleased] section before adding so you do not duplicate an existing bullet.

Release process

All packages share one version (lockstep versioning); every release updates them together. There are no major releases.

• npm run release:patch for bug fixes and new features.
• npm run release:minor for API breaking changes.

The scripts/release.mjs script handles the version bump, CHANGELOG finalization, commit, tag, publish, and adding a fresh [Unreleased] section. Before running it, make sure every change since the last release is documented in the [Unreleased] section of each affected package's CHANGELOG.md.

Related pages

• How to contribute, finding work and definition of done
• Testing, how to run tests
• Patterns and conventions, code style and changelog format
• Tooling, check commands and scripts
• Getting started, prerequisites and install