hermes-agent/AGENTS.md

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