Complete Contribution Guide for OpenEnv: Agentic Workflow and PR Requirements

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 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, 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 and the design principles in .claude/docs/PRINCIPLES.md.

Step-by-Step Contribution Process

The complete contribution workflow is defined in 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:

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.

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

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:

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 – Contains the full contribution workflow, PR checklist, and RFC guidance.
• CLAUDE.md – Documents Claude Code usage, TDD enforcement mechanisms, and agentic workflow triggers.
• .claude/docs/PRINCIPLES.md – Defines the design principles that shape all contributions.
• .claude/docs/INVARIANTS.md – Lists core system invariants that must never be violated.
• 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 and .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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}