Swarmforge AGENTS.md

AGENTS.md

Scope

• These instructions apply to the entire repository until a nested AGENTS.md overrides them.
• Follow this file whenever you add or modify source, scripts, Docker assets, or skills anywhere in the repo.

Repo Overview

• Makefile orchestrates the local containers (build_opencode, run_opencode, run_ollama, etc.) and is the preferred entry point for automation.
• install.sh appends an oc helper alias that shells out to make -C <repo> run_opencode; keep it POSIX-compliant because it is sourced in user shells.
• anvil/ holds the container-side assets shared by every harness image: the Dockerfile, the container entrypoint, and the Claude-only status line (statusline.sh) with the image config layer that turns it on (claude-settings.json). The images build from the repo root (-f anvil/Dockerfile) so swarmforge/ can be copied in; .dockerignore keeps everything else out of the context.
• swarmforge/ is the Python for both sides of the container boundary: the host launcher (anvil, tongs, gitguard), and the agent translation and config merging the entrypoint runs with python3 -m. It is stdlib-only: the image installs no third-party Python and the launcher runs on the host's python3.
• bin/ holds the launcher entry points (run-anvil, tongs, git-guard). Each is a shim that puts the checkout on sys.path and calls its module's main() — the only files that resolve a path, so nothing under swarmforge/ needs to know where it sits on disk.
• opencode/ holds the OpenCode-native repo config layer (opencode.json, plus untracked plugin state); harness-neutral assets live at the top level in skills/, commands/, and agents/.
• ollama/ stores persistent Ollama state. Do not add large model blobs to git—only configuration or lightweight defaults belong here.

Coding Conventions

• Default to Bash or POSIX shell for scripts and include set -euo pipefail (or equivalent) when modifying shell entrypoints.
• Prefer make variables and targets over ad-hoc scripts so contributors can compose workflows via the existing Makefile.
• Keep Dockerfiles Debian-based (see DEBIAN_TAG) and avoid pinning GPU driver versions inside the image; rely on host NVIDIA tooling instead.
• When editing skills under skills/, ensure YAML frontmatter only contains name and description, and keep the detailed guidance in the corresponding SKILL.md body.
• swarmforge/ is layered rather than a bag of modules: yamlite is a leaf both sides of the container boundary import, the tongs modules build on each other in one direction, and the anvil modules sit on top of tongs. The unit suite fails on an import cycle, and on any file outside bin/ that loads python from a file path instead of importing it by name.
• Subagent definitions under agents/ use the unified agent format documented in README.md (## Agents); the entrypoint rewrites them per harness via swarmforge/agents/translate.py, so never hand-write harness-specific dialects there.