40 lines
3.2 KiB
Markdown
40 lines
3.2 KiB
Markdown
|
# AGENTS.md
|
||
|
|
|
||
|
|
## 1. Overview
|
||
|
|
|
||
|
|
Container image definition for Hermes Agent with supplementary tooling, distributed via Docker Hub as `jcabillot/hermes-agent`.
|
||
|
|
|
||
|
|
## 2. Folder Structure
|
||
|
|
|
||
|
|
- `Dockerfile`: Multi-stage image build — starts from `nousresearch/hermes-agent`, installs `gnupg` and `jq`, drops privileges back to the base user.
|
||
|
|
- `.gitea/workflows/docker-build.yaml`: Gitea Actions pipeline — builds and pushes the image to Docker Hub on push to `main` and on a daily cron schedule.
|
||
|
|
- `renovate.json`: Regex-based custom manager that tracks upstream `nousresearch/hermes-agent` Docker tag updates and opens PRs automatically.
|
||
|
|
- `README.md`: Public-facing documentation (image usage, tags, build instructions).
|
||
|
|
- `AGENTS.md`: This file — contributor guide for AI agents.
|
||
|
|
|
||
|
|
## 3. Core Behaviors & Patterns
|
||
|
|
|
||
|
|
- **Build & Release**: The Dockerfile uses `ARG HERMES_AGENT_VERSION` pinned to a specific tag. On push to `main`, the CI pipeline builds with `docker build --pull`, tags the image as `latest` and `sha-<commit>`, pushes to `jcabillot/hermes-agent`, and auto-bumps the git tag (`patch`). A daily cron rebuild ensures the base image's latest security patches are pulled.
|
||
|
|
- **Dependency Tracking**: renovate.json uses a regex custom manager to scan `Dockerfile` for `ARG HERMES_AGENT_VERSION=v<version>` and opens a PR when `nousresearch/hermes-agent` publishes a new Docker tag. Base image version is the single tracked dependency.
|
||
|
|
- **Security Posture**: The build runs as `root` only for `apt` operations, then drops to an unprivileged user (`UID/GID 10000`). The CI pipeline uses Docker Buildx with `pull: true` to ensure fresh base layers.
|
||
|
|
- **Tag Strategy**: Two tags produced — `latest` (floating, main branch) and `sha-<commit>` (immutable, per-commit). Rolling tags (branch names) are intentionally omitted to avoid ambiguity.
|
||
|
|
|
||
|
|
## 4. Conventions
|
||
|
|
|
||
|
|
- **Version Pinning**: Base image versions are pinned via `ARG` at the top of the Dockerfile, not hardcoded in `FROM`. The version is managed by renovate, not manually updated.
|
||
|
|
- **CI Secrets**: Three secrets required — `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, `GITHUB_TOKEN`. The login step is skipped on pull request events to prevent credential exposure from forks.
|
||
|
|
- **Dockerfile Style**: `apt-get` operations run in a single `RUN` layer with cleanup (`rm -rf /var/lib/apt/lists/*`). Comments annotate user context transitions. Hadolint ignores pinned with inline comments.
|
||
|
|
- **Pin Hashing**: All GitHub Action versions in the pipeline are pinned to commit SHA hashes with the semantic version in a trailing comment.
|
||
|
|
|
||
|
|
## 5. Working Agreements
|
||
|
|
|
||
|
|
- Respond in the user's preferred language (French or English); keep technical terms in English, never translate code blocks
|
||
|
|
- Create tests/lint only when explicitly requested
|
||
|
|
- Build context by reviewing related usages and patterns before editing
|
||
|
|
- Prefer simple solutions; avoid unnecessary abstraction
|
||
|
|
- Ask for clarification when requirements are ambiguous
|
||
|
|
- Make minimal changes; preserve public APIs and behavior
|
||
|
|
- Run type-check after code changes (no type-checker in this project — skip)
|
||
|
|
- New files: single-purpose, colocated with related concerns
|
||
|
|
- External dependencies: only when necessary, explain why
|