yolobox: Instructions file for Codex

AGENTS.md

This file is the working agreement for changes in this repository.

Workflow

Default workflow for this repo:

1. Make the requested code or docs change directly.
2. Verify it thoroughly.
3. Commit the change before finishing.

Whenever behavior, UX, defaults, flags, docs, or built-in agent guidance change, audit the matching user-facing surfaces in this repo and update them too:

• README.md
• the docs site under docs/
• the bundled skills under skills/
• the setup command/wizard in cmd/yolobox/main.go

Do not stop at unit tests when behavior can be exercised for real. If a change affects runtime behavior, flags, mounts, image builds, config loading, or release automation, run the actual path and verify the output.

If full end-to-end verification is blocked by the environment, state exactly what was run, what was not run, and why.

Any hard-earned lesson that changes how future work should be done belongs in AGENTS.md.

Build Commands

make build          # Build the yolobox binary
make test           # Run unit tests
make lint           # Run go vet (and golangci-lint if installed)
make image          # Build the Docker base image
make smoke-test     # Run smoke tests on container tools
make smoke-acp      # Check both ACP adapters' versions and protocol startup
make install        # Build and install to ~/.local/bin
make clean          # Remove built binary

Verification Standard

For non-trivial code changes, start here:

make clean && make build && make test
make lint
./yolobox version
./yolobox help
./yolobox config

Before any release or tag push, update CHANGELOG.md with the release's user-facing changes. Release tags must be created only from a clean, up-to-date master branch; do not tag feature branches, and push only master plus the specific release tag. make lint is also mandatory and must include the same golangci-lint coverage that CI runs. If local make lint reports golangci-lint not installed, skipping, install/run golangci-lint locally or run the CI linter equivalent before shipping.