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.

uv sync

Run the narrowest relevant test while iterating:

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:

uv run ruff check .
uv run pyright
uv run pytest

Coverage is diagnostic and has no required threshold:

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

For deployment-related changes, also run:

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.