From 7bd6aec344d637876910f06adbbe76c3063ae369 Mon Sep 17 00:00:00 2001
From: Travis Lyons <travis.lyons@sourcegraph.com>
Date: Thu, 25 Jun 2026 17:47:35 +0000
Subject: [PATCH] docs: add missing AGENTS.md (and README where missing)

---
 AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..35af774
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,43 @@
+# AGENTS.md
+
+## Overview
+
+`github.com/sourcegraph/run` is a Go library for executing commands, providing a
+fluent API for running processes and streaming, mapping, and collecting their
+output. It has no external runtime services; it is consumed as a package.
+
+## Layout
+
+- Library source lives in package `run` at the repository root (`command.go`,
+  `output.go`, `map.go`, `jq.go`, `instrumentation.go`, etc.).
+- `cmd/` holds runnable examples (`example`, `jqexample`, `pipeexample`,
+  `pollexample`). `cmd/example/main.go` also regenerates the README example block.
+- Tests are `*_test.go` files alongside the code they cover.
+
+## Setup
+
+- Go 1.25 (CI pins `1.25.9`). Module: `github.com/sourcegraph/run`.
+- Fetch dependencies:
+
+```bash
+go mod download
+```
+
+## Build, test, lint
+
+These mirror `.github/workflows/pipeline.yml`:
+
+```bash
+go build -v ./...
+go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
+go vet ./...
+gofmt -l .
+```
+
+## Conventions
+
+- Standard Go formatting (`gofmt`); keep code idiomatic to the existing files.
+- Tests use `github.com/frankban/quicktest`.
+- Commands take a `context.Context`; the fluent API chains `Cmd(...).Run()` with
+  output operations like `Stream`, `Lines`, and `Map`.
+- See `CODEOWNERS` for review ownership.