# Complete Contribution Guide for OpenEnv: Agentic Workflow and PR Requirements

> Learn the OpenEnv contribution guide. Follow the agentic workflow, fork the repo, add tests, lint with Ruff, and submit PRs passing TDD enforcement with /work-on-issue commands.

- Repository: [Hugging Face/OpenEnv](https://github.com/huggingface/OpenEnv)
- Tags: how-to-guide
- Published: 2026-06-16

---

**The contribution guide for OpenEnv defines an agentic-first workflow using Claude Code that requires contributors to fork the repository, add tests under `tests/`, lint with Ruff, and submit PRs that pass automated TDD enforcement via `/work-on-issue` commands.**

This contribution guide for OpenEnv covers the unique requirements for contributing to Hugging Face's agentic environment platform. Unlike traditional repositories, OpenEnv requires adherence to specific architectural principles documented in [`.claude/docs/PRINCIPLES.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/PRINCIPLES.md) and automated quality checks through Claude Code integration.

## The Agentic-First Workflow

OpenEnv implements a specialized **agentic-first workflow** designed around **Claude Code** integration. As documented in [`CLAUDE.md`](https://github.com/huggingface/OpenEnv/blob/main/CLAUDE.md), the repository uses agentic automation to enforce **Test-Driven Development (TDD)** and code quality standards.

The workflow activates when you invoke `/work-on-issue #<num>`, which triggers Claude to operate in TDD mode and run pre-submit checks automatically【CLAUDE.md】. This ensures all contributions align with the architectural invariants defined in [`.claude/docs/INVARIANTS.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/INVARIANTS.md) and the design principles in [`.claude/docs/PRINCIPLES.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/PRINCIPLES.md).

## Step-by-Step Contribution Process

The complete contribution workflow is defined in [`CONTRIBUTING.md`](https://github.com/huggingface/OpenEnv/blob/main/CONTRIBUTING.md) at the repository root. Follow these steps to ensure your changes meet OpenEnv's quality gates.

### 1. Fork and Branch

Create a personal fork of the repository on GitHub, then clone it locally and branch from `main`:

```bash
git clone https://github.com/<your-username>/OpenEnv.git
cd OpenEnv
git checkout -b my-feature

```

### 2. Add Tests for New Functionality

Every new feature requires corresponding unit tests in the `tests/` directory. OpenEnv maintains strict test coverage standards to preserve system invariants.

```bash

# Create test file for your feature

touch tests/test_my_feature.py

# Write pytest-compatible tests...

```

### 3. Update Documentation

API changes must be reflected in both the doc-builder files located in `docs/` and environment-specific READMEs. Documentation updates are mandatory for maintaining consistency across the platform.

### 4. Run the Test Suite

Verify your changes pass all existing and new tests using the project's `uv` toolchain:

```bash
PYTHONPATH=src:envs uv run pytest tests/ -v

```

This command ensures the source code in `src/` and environments in `envs/` are correctly integrated during testing.

### 5. Lint and Format Code

Enforce code style compliance using **Ruff** before submitting:

```bash
uv run ruff format src/ tests/ --check

```

### 6. Submit an RFC for Large Changes

For significant architectural modifications, you must open a Request for Comments (RFC) in the `rfcs/` directory before merging【CONTRIBUTING.md】. This requirement ensures major changes align with OpenEnv's long-term architectural vision.

### 7. Open a Pull Request

Push your branch and create a Pull Request on GitHub. The Claude workflow will automatically enforce TDD mode if you use the `/work-on-issue #<num>` command, running the pre-submit checks defined in the CLAUDE documentation【CLAUDE.md】.

## Key Files in the Contribution Workflow

Understanding these critical files ensures your contributions comply with OpenEnv's standards:

- **[`CONTRIBUTING.md`](https://github.com/huggingface/OpenEnv/blob/main/CONTRIBUTING.md)** – Contains the full contribution workflow, PR checklist, and RFC guidance.
- **[`CLAUDE.md`](https://github.com/huggingface/OpenEnv/blob/main/CLAUDE.md)** – Documents Claude Code usage, TDD enforcement mechanisms, and agentic workflow triggers.
- **[`.claude/docs/PRINCIPLES.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/PRINCIPLES.md)** – Defines the design principles that shape all contributions.
- **[`.claude/docs/INVARIANTS.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/INVARIANTS.md)** – Lists core system invariants that must never be violated.
- **[`rfcs/README.md`](https://github.com/huggingface/OpenEnv/blob/main/rfcs/README.md)** – Provides guidelines for writing and reviewing RFCs for large changes.
- **`tests/`** – Houses the unit and integration test suite run via `uv run pytest`.
- **`src/`** – Contains the core library code where most contributions will be made.

## Summary

Contributing to OpenEnv requires adhering to an agentic-first development process that prioritizes test-driven development and automated quality enforcement:

- Fork the repository and create feature branches from `main`
- Add unit tests in `tests/` for all new functionality
- Update documentation in `docs/` and environment READMEs for API changes
- Execute the full test suite with `PYTHONPATH=src:envs uv run pytest tests/ -v`
- Validate code formatting using `uv run ruff format src/ tests/ --check`
- Submit RFCs for architectural changes to the `rfcs/` directory
- Leverage Claude Code's `/work-on-issue` command for automated TDD enforcement

## Frequently Asked Questions

### What makes OpenEnv's contribution process different from standard GitHub workflows?

OpenEnv utilizes an **agentic-first workflow** centered on Claude Code integration. Unlike traditional projects, contributors can invoke `/work-on-issue #<num>` to activate TDD mode, which automatically enforces testing requirements and runs pre-submit checks before allowing merges【CLAUDE.md】.

### Where are the design principles and system constraints documented?

Core architectural constraints are defined in [`.claude/docs/PRINCIPLES.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/PRINCIPLES.md) and [`.claude/docs/INVARIANTS.md`](https://github.com/huggingface/OpenEnv/blob/main/.claude/docs/INVARIANTS.md). These files establish the fundamental rules that all contributions must follow to maintain system integrity and consistency with OpenEnv's agent-centric architecture.

### How do I run tests locally before submitting a PR?

Execute the test suite using the `uv` package manager with the command `PYTHONPATH=src:envs uv run pytest tests/ -v`. This ensures both the core library (`src/`) and environment modules (`envs/`) are properly loaded during test execution.

### When is an RFC required for OpenEnv contributions?

You must open an RFC in the `rfcs/` directory for **significant architectural modifications** before merging【CONTRIBUTING.md】. Large changes that affect core system invariants or modify fundamental design principles require community review through the RFC process to ensure alignment with the project's long-term vision.