Save this content to: AGENTS.md

# AGENTS.md

Guide for AI agents working on this project.

## Project

Eris is a PHP library for property-based testing, integrating with PHPUnit.

## Repository Layout

- `src/` — library source code (PSR-4 namespace `Eris\`)
- `test/` — unit and end-to-end tests (shares the `Eris\` namespace)
- `examples/` — example test cases demonstrating library usage
- `docs/` — documentation source
- `.docker/` — Dockerfile used by `docker-compose.yml`
- `.agents/skills/` — agent skills (one folder per skill with a `SKILL.md`); `.claude/skills` is a symlink to it

## Requirements

- Docker

> **Prefer Docker over the host PHP installation.** All commands below should be run inside a Docker container to avoid dependency on the PHP version installed on the host machine.

## Starting a Docker Shell

Use `make` to spin up a shell inside a container for a specific PHP version:

```bash
make run-php-8.1   # PHP 8.1
make run-php-8.2   # PHP 8.2
make run-php-8.3   # PHP 8.3
make run-php-8.4   # PHP 8.4
make run-php-8.5   # PHP 8.5
```

The project root is mounted at `/usr/src/eris` inside the container. All subsequent commands should be run from that path.

## Setup

```bash
composer install
```

## Running Tests

Run the full test suite:

```bash
vendor/bin/phpunit test
```

Or via Composer:

```bash
composer test
```

Run only a specific test suite (defined in `phpunit.xml`):

```bash
vendor/bin/phpunit --testsuite Full
vendor/bin/phpunit --testsuite Examples
vendor/bin/phpunit --testsuite EndToEnd
```

Run a single test file:

```bash
vendor/bin/phpunit test/SampleTest.php
```

## Static Analysis

```bash
composer static
```

This runs both PHPStan and Psalm.

## Code Style

```bash
composer cs
```

Runs `php-cs-fixer` to fix code style issues.

## Refactoring

```bash
composer rector
```

## Changelog

Update `CHANGELOG.md` (under `[Unreleased]`) for every non-trivial change that could affect the library users, e.g. new features, behaviour changes, fixes, and supported PHP/PHPUnit versions. Follow the existing format and reference the PR or issue number.

## Agent Skills

Skills live in `.agents/skills/`. Create each new skill as `.agents/skills/<skill-name>/SKILL.md`, with a frontmatter declaring `name` and `description`. Do not create skills directly in `.claude/skills`: it is a symlink to `.agents/skills`.

Available skills:

- `check-ci` — fetch and analyse the latest failed CI run on the current branch
- `read-issue` — fetch a GitHub issue with its comments and load it as context