thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions
banger/AGENTS.md
Thales Maciel 671723a0ef
Add file first guidance for CLI and LLM inputs 
Capture the repository preference that shell facing tools should consume
files when they support them instead of large inline strings.

Add explicit guidance for prompt files, temporary files, and git commit
message files so future automation avoids quoting bugs and stays aligned
with the vm run harness and commit workflows.
2026-03-29 17:52:58 -03:00

2.6 KiB
Raw Blame History

Repository Guidelines

Project Structure

  • cmd/banger and cmd/bangerd are the main user entrypoints.
  • internal/ contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and web UI.
  • scripts/ contains explicit manual helper workflows for rootfs and kernel preparation.
  • build/bin/ is the canonical source-checkout build output.
  • build/manual/ is the canonical source-checkout location for manual rootfs/kernel artifacts.

Build and Test

  • make build builds ./build/bin/banger, ./build/bin/bangerd, and ./build/bin/banger-vsock-agent.
  • make test runs go test ./....
  • ./build/bin/banger doctor checks host readiness.
  • ./build/bin/banger image build --from-image <image> builds a managed image from an existing registered image.
  • ./build/bin/banger image register ... registers an unmanaged host-side image stack.
  • ./build/bin/banger image promote <image> copies an unmanaged image into daemon-owned managed artifacts.
  • make void-kernel, make rootfs-void, and make void-register drive the experimental Void flow under ./build/manual.

Image Model

  • Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
  • There is no runtime bundle and no auto-registered default image from disk paths.
  • default_image_name selects a registered image only.

Config

  • Config lives at ~/.config/banger/config.toml.
  • Firecracker comes from PATH by default, or firecracker_bin.
  • SSH uses ssh_key_path or an auto-managed default key at ~/.config/banger/ssh/id_ed25519.

Coding Style

  • Prefer small, direct Go code and standard library solutions.
  • Keep shell scripts strict with set -euo pipefail.
  • Use gofmt for Go formatting.
  • When a CLI accepts either an inline string or a file input, always prefer the file-based form.
  • For shell commands and AI/LLM tooling, prefer passing files as input whenever the CLI allows it.
  • Create temporary files as needed to follow the file-first rule.
  • Examples: use git commit -F <file> instead of git commit -m <message>, and use prompt files instead of inline prompt strings when invoking LLM CLIs.

Testing Guidance

  • Primary automated coverage is go test ./....
  • For lifecycle changes, smoke-test with vm create, vm ssh, vm stop, and vm delete.
  • If guest provisioning changes, document whether existing images must be rebuilt or recreated.

Security

  • Do not commit secrets.
  • VM workflows require sudo and /dev/kvm.
  • The default SSH key is local configuration, not a checked-in runtime artifact.