agentci/AGENTS.md

# Agent CI repository instructions

## Scope

- These instructions apply to the whole repository. A nested `AGENTS.md` adds or overrides
  instructions for its subtree; `opencode/AGENTS.md` contains runtime-specific guidance.
- Agent CI is a private Gitea webhook service that turns issue and pull-request comments into
  durable OpenCode workflows. Read `README.md` before changing command behavior, persistence,
  recovery, deployment, or the security boundary.
- Keep changes focused. Preserve unrelated work in a dirty worktree and do not rewrite code outside
  the requested change merely for consistency.

## Repository map

- `src/agentci/engine/`: immutable domain models and events, the pure reducer, SQLite persistence,
  task claiming, and the `JobRun` event interface.
- `src/agentci/application/`: runtime composition, durable control/job queues, task handlers,
  recovery, and comment reconciliation.
- `src/agentci/workflows/`: planning, implementation, review, and pull-request orchestration.
- `src/agentci/integrations/`: Gitea, Git, OpenCode, CodeGraph, and development external effects.
- `src/agentci/api/`: FastAPI construction, lifespan, dependencies, errors, and HTTP routes.
- `src/agentci/config/` and `src/agentci/observability/`: settings and structured logging.
- `src/agentci/prompts/` and `src/agentci/prompts/schemas/`: model prompts and structured-output
  contracts; keep these concerns outside Python orchestration.
- `src/agentci/migrations/`: ordered SQLite migrations.
- `tests/`: pytest suite, generally organized by module or behavior.
- `compose.yaml`, `Dockerfile`, `scripts/`, `install-scripts/`, and `opencode/`: deployment and
  trusted runtime configuration.

## Setup and commands

Use Python 3.13 or newer and `uv`. Run commands from the repository root.

```sh
uv sync
```

Run the narrowest relevant test while iterating:

```sh
uv run pytest tests/test_<area>.py
uv run pytest tests/test_<area>.py::test_<behavior>
uv run pytest -k '<expression>'
```

Run the standard Python checks before completion:

```sh
uv run ruff check .
uv run pyright
uv run pytest
```

Coverage is diagnostic and has no required threshold:

```sh
uv run pytest --cov=agentci --cov-branch
```

For deployment-related changes, also run:

```sh
docker compose config
```

Run `docker compose build` when changing dependencies, the image, runtime scripts, installers, or
OpenCode configuration. It may require network access and takes longer than the normal checks.

## Engineering conventions

- Target Python 3.13, keep lines at or below 100 characters, and follow the Ruff and Pyright settings
  in `pyproject.toml`. Use type annotations and existing modern Python patterns.
- Keep jobs and workflows immutable. Domain snapshots use frozen dataclasses; create updated values
  rather than mutating state in place.
- Keep `engine/reducer.py` pure: no I/O, clocks, logging, or external calls. Express state changes as
  events and task requests.
- Apply state transitions, event persistence, and resulting task creation atomically through
  `Repository`. The `jobs` table is the authoritative snapshot; timestamps are storage metadata.
- Keep side effects in the worker, workflows, or top-level integration modules. Pass workflow
  dependencies explicitly through `WorkflowServices` and progress through `JobRun`.
- Preserve webhook/event idempotency, per-target FIFO execution, bounded unrelated concurrency, and
  deterministic comment reconciliation.
- Preserve restart semantics: queued work may resume, but an active partially executed model turn is
  failed and its sessions are aborted rather than replayed.
- Use structured logging fields such as `operation`, `job_id`, `stage`, and task identifiers. Never
  log credentials, secret contents, authorization headers, or private prompt data.
- Add a new numbered migration for schema changes. Never edit a migration that may already have been
  applied.
- Keep prompts and JSON schemas synchronized. Add or update tests when changing either contract.
- Declare dependencies in `pyproject.toml` and let `uv` update `uv.lock`; do not edit the lockfile by
  hand.

## Testing conventions

- Add regression tests for behavior changes, especially reducer transitions, persistence and
  idempotency, restart recovery, queue ordering, webhook security, and integration error handling.
- Prefer behavior-oriented test names, table-driven `pytest.mark.parametrize` cases, `tmp_path` for
  filesystem/database isolation, and fake clients or `httpx.MockTransport` for external services.
- Async tests run with `asyncio_mode = "auto"`; do not add an asyncio marker solely to make a test
  asynchronous.
- Assert externally meaningful state, emitted events/tasks, ordering, rendered comments, and safe
  error text rather than private implementation details.
- Do not make the default unit suite depend on live Gitea, OpenCode, provider credentials, Docker,
  or network access.

## Security and operational boundaries

- Never commit or expose `.env`, `secrets/`, tokens, passwords, provider credentials, runtime data
  directories, databases, cloned private repositories, or Docker volume contents. Do not send
  secrets or private repository content to external search or research services.
- Preserve webhook HMAC verification, bot-comment filtering, requester write-permission checks, and
  secret-file loading.
- OpenCode is not an OS sandbox. Do not weaken its permissions, enable repository-local configuration
  or external skills, expose its server to the host, add privileged/capability settings, or add
  writable host mounts beyond the documented `./data/agentci` and `./data/opencode` state directories
  without an explicit security review.
- `install-scripts/` is trusted operator code. Keep scripts idempotent, path-safe, and compatible with
  the sanitized environment documented in `install-scripts/README.md`; never pass Agent CI or Gitea
  credentials to them.
- Git pushes performed by Agent CI must remain non-forcing.
- Do not run provider authentication, start/restart deployment services, modify production data, or
  perform other live operations unless the user explicitly requests it.
- Do not edit or commit generated/local state in `.venv/`, `.pytest_cache/`, `.ruff_cache/`,
  `.codegraph/`, `__pycache__/`, `dist/`, `data/`, or `secrets/`.

## Completion expectations

- Run focused tests first, then all applicable standard checks. If a check cannot run, report the
  exact command and reason.
- Update `README.md`, `.env.example`, and relevant operational documentation when changing commands,
  configuration, deployment, recovery behavior, or security assumptions.
- Summarize behavior changes, validation performed, and any migration, compatibility, or security
  implications in the final response or pull-request description.