Add development environment setup instructions

[lox]

What

Consolidates the repo's agent/developer instructions into a single AGENTS.md and documents how to set up and run the development environment for the Buildkite Agent (a single Go CLI application). No product code is changed.

• The pre-existing AGENT.md (singular) is not a filename Cursor reads; Cursor picks up AGENTS.md (plural). To avoid two near-identically-named files, AGENT.md's "Build/Test/Lint Commands", "Architecture", and "Code Style" content is merged into AGENTS.md, and AGENT.md is deleted.
• Adds a ## Development environment notes section capturing non-obvious setup/run caveats.

The notes capture non-obvious setup/run caveats discovered while bringing up a clean environment:

• Prerequisites a plain checkout does not install for you: Go toolchain (mise install), golangci-lint (standalone binary pinned in mise.toml), and ruby for polyglot hook tests. gofumpt/gotestsum are Go tools and need no separate install.
• internal/job test TestResolvingGitHostAliasesWithFlagSupport runs inside a container (/.dockerenv) and expects .buildkite/build/ssh.conf at /etc/ssh/ssh_config.d/ (mirroring .buildkite/Dockerfile-compile).
• Cold-build-cache flakiness of internal/job/integration (TestPreExitHooksFireAfterCancel); warm the cache first.
• How to build and run a job locally with ./buildkite-agent bootstrap (no Buildkite token required).

Environment verified

Task	Command	Result
Build	go build -o buildkite-agent .	binary built, --version = 3.134.0
Lint	go tool gofumpt -extra -l . + golangci-lint run	clean, 0 issues
Test	go tool gotestsum -- ./...	2745 tests, 7 skipped, 0 failures (warm cache)
Run	./buildkite-agent bootstrap ... --phases command	ran a job locally, streamed output

Hello world (core functionality — bootstrap runs a job locally):

$ ./buildkite-agent bootstrap --phases command ... --command 'echo hello'
~~~ Running commands
$ echo hello
hello
(exit 0)

  

[buildsworth-bk-app]

The new repository-wide instructions still rely on prepared-environment assumptions, and the end-to-end example does not reliably run the binary built from this checkout. I’ve marked both inline.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 9332, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

About buildsworth

Model: gpt-5.6-sol with xhigh thinking.

How to request a review: Comment @buildsworth-bk review on the PR, or request buildsworth-bk as a reviewer.

Risk labels (how buildsworth classifies risk) — buildsworth classifies risk itself from the diff. To let it approve, grant L2 approval by mentioning @buildsworth-bk (see L2 approval grant):

• L1 — Low risk (dep bumps, docs/copy, lockfiles, small presentational fixes). buildsworth may approve by default.
• L2 — Standard risk (new UI, additive API fields, refactors). Approved only with an L2 grant; otherwise comment-only.
• L3 — High risk (auth, migrations, payments, secrets, perf-critical paths). Human review always required.

[buildsworth-bk-app]

Both previous concerns remain open after this update; I didn’t find any new issues.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 9345, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

Previous concerns have been addressed.

[buildsworth-bk-app]

Both previous concerns are resolved; I found no new issues. I’m leaving this comment-only because AGENTS.md changes repository-wide executable setup instructions, which is above the default approval ceiling.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 9640, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

Previous concerns have been addressed.

[buildsworth-bk-app]

The previous concerns remain resolved after the consolidation, and I found no new issues. I’m leaving this comment-only because AGENTS.md is repository-wide executable guidance, which is above the default approval ceiling.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 9641, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.