Initial draft of AGENTS.md

* Add support for https://agents.md/

[NO TESTS NEEDED]

Signed-off-by: Jhon Honce <jhonce@redhat.com>
See: [AGENTS.md](https://agents.md/)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644 (file)
index 0000000..594f93f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,154 @@
+# AI Agent Guide for Podman Development
+
+![PODMAN logo](https://raw.githubusercontent.com/containers/common/main/logos/podman-logo-full-vert.png)
+
+Quick reference guide for AI agents assisting with Podman development.
+
+## Project Overview
+
+**Podman** is a daemonless container engine with Docker-compatible CLI, rootless support, and native pod management.
+
+**Key Technologies**: [Cobra](https://github.com/spf13/cobra), [containers/image](https://github.com/containers/image), [containers/storage](https://github.com/containers/storage), [crun](https://github.com/containers/crun), [Go](https://golang.org), [Netavark](https://github.com/containers/netavark), [runc](https://github.com/opencontainers/runc)
+
+## Quick Start
+
+```bash
+# Build and test
+make binaries           # Build all binaries
+make validatepr         # Format, lint, and validate (required for PRs)
+make localintegration   # Run integration tests
+make localsystem        # Run system tests
+
+# Development tools
+make install.tools      # Install linters and dev tools
+```
+
+## Codebase Structure
+
+```text
+podman/
+├── cmd/podman/               # CLI commands (Cobra framework)
+├── libpod/                   # Core container/pod management (Linux only)
+├── pkg/
+│   ├── api/                  # REST API server
+│   ├── bindings/             # HTTP client (stable API)
+│   ├── domain/               # Business logic layer
+│   │   ├── entities/         # Interfaces and data structures
+│   │   ├── infra/abi/        # Local implementation
+│   │   └── infra/tunnel/     # Remote implementation
+│   └── specgen/              # Container/pod specifications
+├── test/e2e/                 # Integration tests (Ginkgo)
+├── test/system/              # System tests (BATS)
+├── docs/source/markdown/     # Man pages
+└── vendor/                   # Vendored dependencies (DO NOT EDIT)
+```
+
+## Development Patterns
+
+### CLI Command Pattern
+
+```go
+// cmd/podman/command.go
+var commandCmd = &cobra.Command{
+    Use:   "command [options] args",
+    RunE:  commandRun,
+}
+
+func commandRun(cmd *cobra.Command, args []string) error {
+    return registry.ContainerEngine().Command(registry.GetContext(), options)
+}
+```
+
+### Domain Layer Pattern
+
+```go
+// pkg/domain/infra/abi/command.go (local)
+func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
+    return ic.Libpod.Command(options)  // Direct libpod call
+}
+
+// pkg/domain/infra/tunnel/command.go (remote)
+func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
+    return bindings.Command(ic.ClientCtx, options)  // HTTP API call
+}
+```
+
+## Testing
+
+### Integration Tests ([Ginkgo](https://github.com/onsi/ginkgo))
+
+```go
+It("should work correctly", func() {
+    session := podmanTest.Podman([]string{"command", "args"})
+    session.WaitWithDefaultTimeout()
+    Expect(session).Should(Exit(0))
+})
+```
+
+### System Tests ([BATS](https://github.com/bats-core/bats-core))
+
+```bash
+@test "podman command functionality" {
+    run_podman command --option value
+    is "$output" "expected output" "description"
+}
+```
+
+## Code Standards
+
+**Official Documentation**: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+- **Formatter**: `gofumpt` (via `golangci-lint`, configured in `.golangci.yml`)
+- **Validation**: All PRs must pass `make validatepr`
+- **Commits**: Must be signed (`git commit -s`) and follow [DCO](CONTRIBUTING.md#sign-your-prs)
+- **Reviews**: Two approvals required for merge
+
+## Key Libraries
+
+- **[containers/buildah](https://github.com/containers/buildah)**: Image building
+- **[containers/common](https://github.com/containers/common)**: Shared utilities
+- **[containers/image](https://github.com/containers/image)**: Image management
+- **[containers/storage](https://github.com/containers/storage)**: Container and image storage
+- **[gorilla/mux](https://github.com/gorilla/mux)**: HTTP router and URL matcher for REST API
+- **[gorilla/schema](https://github.com/gorilla/schema)**: Form data to struct conversion
+- **[netavark](https://github.com/containers/netavark)**: Network management
+
+## Common Pitfalls for AI Agents
+
+1. **Never edit `vendor/`** - Use `go get` then `make vendor`
+2. **Platform awareness** - Consider Linux/Windows/macOS differences
+3. **Rootless vs root** - Many behaviors differ between modes
+4. **Remote vs local** - Different code paths (`abi` vs `tunnel`)
+5. **Test cleanup** - Always clean up test artifacts
+
+## Essential Commands
+
+```bash
+# Analysis
+go list -tags "$BUILDTAGS" -f '{{.Deps}}' ./cmd/podman  # Dependencies
+grep -r "pattern" --include="*.go" .                    # Find patterns
+
+# Testing
+make localintegration FOCUS_FILE=your_test.go           # Single test file
+make localintegration FOCUS="test description"          # Single test
+PODMAN_TEST_SKIP_CLEANUP=1 make localintegration        # Debug mode
+
+# Validation
+make validatepr                                         # Full validation
+make lint                                               # Linting only
+```
+
+## Documentation
+
+- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Development guidelines
+- **[DISTRO_PACKAGE.md](DISTRO_PACKAGE.md)**: Packaging guidelines for distributors
+- **[docs/CODE_STRUCTURE.md](docs/CODE_STRUCTURE.md)**: Detailed codebase structure
+- **[docs/tutorials/](docs/tutorials/)**: Step-by-step guides and tutorials
+- **[GOVERNANCE.md](GOVERNANCE.md)**: Project organization and contributor roles
+- **[LICENSE](LICENSE)**: Apache 2.0 license terms
+- **[README.md](README.md)**: Project overview
+- **[RELEASE_PROCESS.md](RELEASE_PROCESS.md)**: Release workflow (maintainers only)
+- **[rootless.md](rootless.md)**: Rootless limitations and troubleshooting
+- **[test/README.md](test/README.md)**: Testing framework details
+
+For comprehensive information, refer to the official documentation and recent commits in the [Podman repository](https://github.com/containers/podman).