diff --git a/AGENTS.md b/AGENTS.md index a555d24bc..c372469e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,55 +1,109 @@ +# Project Agent Guidelines + +This document provides guidance for AI agents and contributors working on the +docker-agent codebase. + +## Code Quality Standards + +- Write clean, self-documenting code with minimal comments +- Follow existing code style and patterns in the project +- Implement proper error handling and validation +- Consider edge cases and failure scenarios +- Ensure code is maintainable and extensible + +### Code Comments Philosophy + +Comments are only added when the code's purpose or logic is not immediately +evident. Never write comments that merely restate what the code does (e.g. +`// increment counter` above `counter++`). Comments should explain **why** +something is done a certain way, document non-obvious edge cases, or clarify +complex algorithms that cannot be simplified further. + +## Working Approach + +- Use tools to gather information rather than relying on assumptions +- Examine existing code before making changes +- Validate all changes before considering tasks complete +- Ask clarifying questions only when truly necessary +- When possible, call independent tools concurrently — it's faster + +## Validation Requirements + +Before marking work as complete: + +- [ ] Code builds successfully (`mise build`) +- [ ] All tests pass (`mise test`) +- [ ] Linter shows no new issues (`mise lint`) +- [ ] Changes meet acceptance criteria +- [ ] Code follows project patterns and conventions +- [ ] Proper error handling is implemented +- [ ] Edge cases are considered + # Development Commands ## Build and Development -- `mise build` - Build the application binary (outputs to `./bin/docker-agent`) -- `mise test` - Run Go tests (clears API keys to ensure deterministic tests) -- `mise lint` - Run golangci-lint (uses `.golangci.yml` configuration) -- `mise format` - Format code using golangci-lint fmt -- `mise dev` - Run lint, test, and build in sequence +- `mise build` — Build the application binary (outputs to `./bin/docker-agent`) +- `mise test` — Run Go tests (clears API keys to ensure deterministic tests) +- `mise lint` — Run golangci-lint (uses `.golangci.yml` configuration) +- `mise format` — Format code using golangci-lint fmt +- `mise dev` — Run lint, test, and build in sequence ## Docker and Cross-Platform Builds -- `mise build-local` - Build binary for local platform using Docker Buildx -- `mise cross` - Build binaries for multiple platforms (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64) -- `mise build-image` - Build Docker image tagged as `docker/docker-agent` -- `mise push-image` - Build and push multi-platform Docker image to registry +- `mise build-local` — Build binary for local platform using Docker Buildx +- `mise cross` — Build binaries for multiple platforms (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64) +- `mise build-image` — Build Docker image tagged as `docker/docker-agent` +- `mise push-image` — Build and push multi-platform Docker image to registry ## Running docker-agent -- `./bin/docker-agent run ` - Run agent with configuration (launches TUI by default) -- `./bin/docker-agent run -a ` - Run specific agent from multi-agent config -- `./bin/docker-agent run agentcatalog/pirate` - Run agent directly from OCI registry -- `./bin/docker-agent run --exec ` - Execute agent without TUI (non-interactive) -- `./bin/docker-agent new` - Generate new agent configuration interactively -- `./bin/docker-agent new --model openai/gpt-5` - Generate with specific model -- `./bin/docker-agent share push ./agent.yaml namespace/repo` - Push agent to OCI registry -- `./bin/docker-agent share pull namespace/repo` - Pull agent from OCI registry -- `./bin/docker agent serve mcp ./agent.yaml` - Expose agents as MCP tools -- `./bin/docker agent serve a2a ` - Start agent as A2A server -- `./bin/docker agent serve api` - Start Docker `docker-agent` API server +- `./bin/docker-agent run ` — Run agent with configuration (launches TUI by default) +- `./bin/docker-agent run -a ` — Run specific agent from multi-agent config +- `./bin/docker-agent run agentcatalog/pirate` — Run agent directly from OCI registry +- `./bin/docker-agent run --exec ` — Execute agent without TUI (non-interactive) +- `./bin/docker-agent new` — Generate new agent configuration interactively +- `./bin/docker-agent new --model openai/gpt-5` — Generate with specific model +- `./bin/docker-agent share push ./agent.yaml namespace/repo` — Push agent to OCI registry +- `./bin/docker-agent share pull namespace/repo` — Pull agent from OCI registry +- `./bin/docker agent serve mcp ./agent.yaml` — Expose agents as MCP tools +- `./bin/docker agent serve a2a ` — Start agent as A2A server +- `./bin/docker agent serve api` — Start docker-agent API server ## Debug and Development Flags -- `--debug` or `-d` - Enable debug logging (logs to `~/.cagent/cagent.debug.log`) -- `--log-file ` - Specify custom debug log location -- `--otel` or `-o` - Enable OpenTelemetry tracing +- `--debug` or `-d` — Enable debug logging (logs to `~/.cagent/cagent.debug.log`) +- `--log-file ` — Specify custom debug log location +- `--otel` or `-o` — Enable OpenTelemetry tracing - Example: `./bin/docker-agent run config.yaml --debug --log-file ./debug.log` # Testing -- Tests located alongside source files (`*_test.go`) -- Run `mise test` to execute full test suite -- E2E tests in `e2e/` directory -- Test fixtures and data in `testdata/` subdirectories - -# Agent's config yaml - -- Those config yaml follow a strict schema: ./agent-schema.json -- The schema is versioned. -- ./pkg/config/v0, ./pkg/config/v1... packages handle older versions of the config. -- ./pkg/config/latest packages handles the current, work in progress config format. -- When adding new features to the config, only add them the latest config. -- Older config types are frozen. -- When adding new features to the config, update ./agent-schema.json accordingly and create an example yaml - that demonstrates the new feature. +- Tests are located alongside source files (`*_test.go`) +- Run `mise test` to execute the full test suite +- E2E tests live in the `e2e/` directory +- Test fixtures and data live in `testdata/` subdirectories +- Use `github.com/stretchr/testify/assert` and `require` for assertions +- Cover edge cases and error conditions +- Mock external dependencies for unit tests + +# Agent Config YAML + +- Agent config files follow a strict schema: `./agent-schema.json` +- The schema is **versioned** +- `./pkg/config/v0`, `./pkg/config/v1`, ... packages handle older versions of the config +- `./pkg/config/latest` package handles the current, work-in-progress config format +- When adding new features to the config, **only add them to the latest config** +- Older config types are **frozen** — do not modify them +- When adding new features to the config: + - Update `./agent-schema.json` accordingly + - Create an example YAML that demonstrates the new feature + +# Git Practices + +- Write clear, descriptive commit messages +- Prefer [Conventional Commits](https://www.conventionalcommits.org/) format, e.g. `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:` +- Make commits logical and atomic +- Group related changes together; avoid mixing unrelated changes +- Keep branches focused on single features or fixes +- Ensure your branch is up-to-date before submitting