Add AGENTS.md, symlink CLAUDE.md to it

[3uzbcqje]

Ran claude /init in this repo, merged the generated CLAUDE.md into AGENTS.md, and replaced CLAUDE.md with a symlink to AGENTS.md.

Part of a sweep across all non-fork repos in 3uzbcqje, devopscoop, and 6j0-org to give every repo a single agent-instructions file that all tools read.

🤖 Generated with Claude Code

https://claude.ai/code/session_015UvT1zcFsTdKbKcFbdkFiD

[claude]

This describes the prod path as working, but the tag it writes points at an image that was never pushed.

docker/metadata-action's type=sha produces sha-<7> from the PR's head commit — on pull_request events the action overrides GITHUB_SHA with github.event.pull_request.head.sha. The push-to-main run then writes:

yq -i ".image.tag = \"sha-${GITHUB_SHA::7}\"" test-app.helm_values.yaml

where GITHUB_SHA is the new merge/squash commit on main — a SHA nothing was ever built for, since every build step in docker.yml is gated on github.event_name == 'pull_request'. GitHub's merge always creates a new commit, so this can never coincide with the PR-run tag.

The same mismatch hits the dev path inside the PR run itself: build-push-action tags with the head SHA, while the adjacent yq step three steps later writes ${GITHUB_SHA::7}, which on pull_request is the refs/pull/N/merge SHA. Two different SHAs, one image.

This is a pre-existing docker.yml bug, not something this PR introduces. But AGENTS.md is the file future agents will trust over reading the workflow, and as written it asserts the opposite of what happens — including the instruction to preserve it ("Removing the PR-time push would silently break prod deploys"). Suggest documenting the tag mismatch as a known break instead, so an agent that notices it doesn't "fix" the doc back.

[claude]

apt installs curl, not yq. The actual step is:

apt update && apt install -y --no-install-recommends curl
curl -sL -o /usr/local/bin/yq "https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64" && chmod +x /usr/local/bin/yq

yq comes from a pinned GitHub release binary. The conclusion is right — the step does fail unprivileged on a hosted runner — but the cause is misattributed, and there are two root-path operations, not one: apt update/apt install, and the write to /usr/local/bin. An agent sent to fix "installs yq via apt" will go looking for a line that doesn't exist.

[claude]

Minor portability note on the symlink (mode 120000): it resolves correctly on Linux/macOS — I confirmed the checkout in CI reads through it to the 4878-byte AGENTS.md.

On Windows it won't. Git for Windows sets core.symlinks=false unless the user enabled symlinks at install time (needs Developer Mode or admin), and checks the entry out as a regular 9-byte text file containing the literal string AGENTS.md. Claude Code then loads a CLAUDE.md whose entire content is the word AGENTS.md — no error, no warning, just silently empty instructions. Same failure mode for any tool that reads the path without resolving links.

If Windows checkouts are in scope for this sweep, a regular file containing Claude Code's import directive is portable and keeps the single source of truth:

Suggested change

	AGENTS.md
	@AGENTS.md

Not a blocker if the repos are Linux/macOS only.

[claude]

Review

Docs-only PR, so the review is about whether the claims in AGENTS.md are accurate — an agent-instructions file gets trusted over reading the source, so a wrong claim here propagates. I checked every factual assertion against the tracked tree.

Most of it holds up. Verified accurate: no source code / no scripts / one devDependency; no tsconfig.json; .yarn/releases/ absent so Yarn comes from Corepack; .pnp.* gitignored and zero-installs off; .editorconfig contents; the typescript.tsdk path in .vscode/settings.json; the node:21-alpine3.19 base and the yarn.lock package.json-before-yarn install layer split; the pull_request-gating of every build step in docker.yml; the DEPLOY_PAT / GitOps flow and the evanstucker-hates-2fa vs 3uzbcqje org drift; both Claude workflow rationales (they match the inline comments); full-SHA pinning of actions/checkout and claude-code-action; the .gitattributes claims.

Three things to fix:

1. The docker.yml prod-deploy description is inverted (AGENTS.md L66-69) — the doc says the push-to-main path reuses an image the PR run already pushed. It doesn't: metadata-action's type=sha tags with the PR head SHA, while the yq bump writes a 7-char prefix of GITHUB_SHA, which is the merge-ref SHA on the PR run and the new main commit SHA on push. Neither deploy tag resolves to an image that was actually pushed. Pre-existing workflow bug, but the doc currently tells agents the mechanism works and to preserve it.
2. yq is not installed via apt (L75-77) — apt installs curl; yq is a pinned release binary fetched with that curl. The "fails without root on a hosted runner" conclusion is correct, just attributed to the wrong line.
3. Symlink portability (CLAUDE.md) — works on Linux/macOS (verified in this checkout), but degrades silently to a 9-byte text stub on Windows without core.symlinks. @AGENTS.md is a portable alternative if Windows matters for this sweep.

No security issues. Nothing leaks secret material, and the doc actively documents the workflow permission scoping as intentional, which is the right instinct for a file like this.

One note on the PR description: it says CLAUDE.md was "merged into" AGENTS.md and "replaced with a symlink", but CLAUDE.md didn't exist on main — both files are new here. Doesn't affect the diff, just worth knowing if this description is being reused across the sweep.