> ## Documentation Index
> Fetch the complete documentation index at: https://critiqor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Critiqor Contributing Guide: Dev Setup and Workflow

> Clone the Critiqor repo, install in editable mode, run the test suite with pytest, build with python -m build, and publish a new release to PyPI.

Critiqor is MIT-licensed and welcomes contributions. Whether you're fixing a bug, adding a test, improving documentation, or building support for a new framework, this guide covers everything you need to get started.

## Prerequisites

* **Python**: 3.10 or newer
* **Git**
* **`bun` or `npm`** (optional — only needed for local dashboard development)

## Local Dev Setup

```bash theme={null}
# Clone the repository
git clone https://github.com/web3curtis/Critiqor.git
cd Critiqor

# Install in editable mode
pip install -e .

# Verify the CLI works
critiqor help
```

Installing in editable mode (`-e`) means changes to the source files in `critiqor/` take effect immediately without reinstalling.

## Running Tests

```bash theme={null}
# Run all tests
python -m pytest tests/

# Run a specific test file
python -m pytest tests/test_core.py -v
```

The test suite uses the Python standard library `unittest` framework and is run via `pytest`. Tests cover the core wrapper, failure cause detection, CLI commands, session lifecycle, OpenClaw plugin packaging, dashboard launcher, benchmark framework, leaderboard, and more.

## Building the Package

```bash theme={null}
# Install build dependencies
pip install build

# Build source and wheel distributions
python -m build

# Output:
#   dist/critiqor-<version>-py3-none-any.whl
#   dist/critiqor-<version>.tar.gz
```

The build includes the bundled OpenClaw plugin files (`clawhub/critiqor-openclaw/*.js` and `clawhub/critiqor-openclaw/*.json`) as declared in `pyproject.toml`.

## Publishing a New Release

```bash theme={null}
# 1. Bump the version in pyproject.toml
# 2. Update CHANGELOG.md with the new version and changes

# 3. Build the package
python -m build

# 4. Upload to PyPI (requires PyPI credentials)
pip install twine
twine upload dist/*
```

## GitHub Workflow

* **Branches**: work on a feature branch, open a PR against `main`
* **PRs**: include a clear description of what the change does and why
* **CI**: tests run on Python 3.10, 3.11, 3.12, and 3.13 (per the classifiers in `pyproject.toml`)
* **Commits**: use conventional commit format where possible (`feat:`, `fix:`, `docs:`, `chore:`)

## Contribution Guidelines

* Keep changes focused and minimal — one concern per PR
* Add or update tests for any changed behaviour
* Update `CHANGELOG.md` for any user-visible changes
* The core rule: evidence-backed changes are stronger than opinion-backed ones