133 lines
6.5 KiB
Markdown
133 lines
6.5 KiB
Markdown
# 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/worker.py`: durable control/job queues, authorization, execution, recovery, and
|
|
comment reconciliation.
|
|
- `src/agentci/workflows/`: planning, implementation, review, and pull-request orchestration.
|
|
- `src/agentci/{gitea,git,opencode,codegraph,development}.py`: external-effect boundaries.
|
|
- `src/agentci/{app,runtime,config,webhook,health}.py`: application lifecycle, configuration, and
|
|
HTTP entry points.
|
|
- `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
|
|
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 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.
|