# AGENTS.md — AI-assisted contributions to CORAL

CORAL is itself infrastructure for running autonomous coding agents, so we
fully expect contributors to use Claude Code, Codex, Cursor, Kiro, OpenCode,
or other agents while developing changes. This document sets the ground rules.

These rules apply to **any** PR where an AI coding agent meaningfully wrote,
refactored, or generated code, tests, or docs. If you are not sure whether
your workflow counts, it does — read on.

> **TL;DR**
> - A human author must read every changed line and be able to defend the design end-to-end.
> - No drive-by mechanical PRs (lone typo fixes, single-line style nits, batch reformat across the repo).
> - Don't open duplicate PRs against the same issue. Check first.
> - Don't dump raw agent transcripts into the PR description. Summarize.

## 1. Human accountability

- **Pure agent-authored PRs are not accepted.** A human must understand the
  change, review every line, and respond to review comments themselves —
  not by piping reviewer questions back into an agent and posting the reply.
- The submitting human is responsible for:
  - Correctness of the diff,
  - Running tests + lint locally before pushing,
  - Following up on review feedback,
  - Any regressions introduced by the change.
- "An agent wrote it" is not an explanation for design choices in review.

## 2. Scope discipline

- **Bundle agent output with substantive work.** Don't open standalone PRs
  for things like:
  - a single typo fix,
  - one isolated `ruff`-style nit,
  - reformatting a file the agent happened to touch,
  - changing a comment without changing behavior.
  Roll these into a larger PR that actually does something, or batch many
  of them into one explicit cleanup PR with a clear scope statement.
- **One concern per PR.** If your agent generated a refactor and a bug fix
  in the same run, split them.
- **Don't reformat the world.** Repo-wide formatting / import-sorting /
  rename-the-variable PRs are a "no" unless coordinated with maintainers
  first (and then they go on `.git-blame-ignore-revs`).

## 3. Duplicate-work checks

Before opening a PR, verify nobody is already on it:

```bash
gh issue view <issue_number> --repo Human-Agent-Society/CORAL --comments
gh pr list --repo Human-Agent-Society/CORAL --state open --search "<issue_number> in:body"
gh pr list --repo Human-Agent-Society/CORAL --state open --search "<short keywords>"
```

If an open PR is already in flight:

- If it looks stalled, **comment there** to check in. Don't open a parallel PR.
- If your approach is materially different, file an issue (or comment on the
  existing one) explaining the difference before submitting.

## 4. Disclosure in PR descriptions

If an agent did the bulk of the writing, say so plainly. We don't penalize
agent-assisted PRs — we just want the review framed correctly.

A minimal disclosure looks like:

> *Authored with assistance from \<tool\>. I read every changed line, ran the
> tests below locally, and verified the behavior described in the test plan.*

What **not** to do:

- Don't paste raw agent transcripts, multi-thousand-line reasoning traces,
  or hidden "system prompt" blocks. Summarize the design instead.
- Don't fabricate test results. If you didn't run it, don't claim you did.
- Don't link to private agent sessions. Reviewers can't follow those.

## 5. CORAL-specific gotchas for agents

These tend to bite AI-generated PRs in this repo specifically:

- **`.coral/private/` is hidden from agents at runtime.** Don't write code
  that assumes agents can read grader internals (answer keys, hidden test
  inputs, grader source). See `coral/workspace/project.py`.
- **The grader runs in its own venv** (`.coral/private/grader_venv/`).
  Adding a dep to `pyproject.toml` does not put it on the grader's path —
  use `grader.setup` in `task.yaml` instead.
- **Grader output must not write to `codebase_path`.** The daemon force-
  removes that directory after grading. Anything the grader wants to
  persist goes through `ScoreBundle` or `self.private_dir`.
- **Score direction matters.** `Task.maximize` controls which way is
  better — agents often flip this. Double-check against existing examples.
- **Don't commit hidden answers under `seed/`.** Anything in `seed/` ends
  up in the agent's worktree, visible to the running agent.
- **CORAL.md is generated** by `coral/template/coral_md.py` — don't hand-
  edit the rendered file in a worktree, edit the template instead.

If you're adding a new task, the [`coral-new-task` skill](.claude/skills/coral-new-task/SKILL.md)
walks through these in detail. For framework-level changes, see
[`coral-extend`](.claude/skills/coral-extend/SKILL.md); for debugging,
[`coral-debug`](.claude/skills/coral-debug/SKILL.md).

## 6. Reviewer guidance

Reviewers should:

- Flag PRs that look like raw agent output without human review (telltale
  signs: unrelated drive-by changes, invented APIs, broken imports, fake
  citations, "test plan" sections that don't match the diff).
- Ask the human author — not the agent — to explain non-obvious choices.
- Close low-value mechanical PRs with a pointer to this document.

---

By submitting a PR you confirm you've read CONTRIBUTING.md and, if
applicable, this document.
