1diff --git a/AGENTS.md b/AGENTS.md
2new file mode 100644
3index 0000000000000000000000000000000000000000..1fdd884b1a773a66bcb96e29c0ae69f119fae9ec
4--- /dev/null
5+++ b/AGENTS.md
6@@ -0,0 +1,22 @@
7+# soft-builder
8+
9+Build worker for Soft Serve repositories. It accepts internal HTTP build requests and uses BuildKit to publish images.
10+
11+## Structure
12+
13+- `main.go`: startup and dependency wiring.
14+- `config.go`: environment configuration.
15+- `http.go`: HTTP request validation, handlers, and current build status.
16+- `worker.go`: build queue, Git archive extraction, and BuildKit execution.
17+- `db.go`: SQLite bootstrap and build-result persistence.
18+
19+## Behavior
20+
21+- Only `refs/heads/main` and valid Docker-tag `refs/tags/*` refs build images.
22+- Main builds publish the commit SHA and `main`; tag builds publish the commit SHA and Git tag.
23+- `DATABASE_PATH` defaults to `/work/builds.db`. Mount its directory for persistence across container replacement.
24+- Keep the builder internal. Do not expose its HTTP port through a public proxy.
25+
26+## Validation
27+
28+Run `golangci-lint run ./...` and `golangci-lint run ./...` (might make changes)