diff --git a/AGENTS.md b/AGENTS.md
index 8630fd3..0f046b4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,12 +18,15 @@ This repository uses an implementation-first workflow for all feature work.
    - Update `skills/climate.md` and `skills/climate-generator/SKILL.md` when
      command set or workflows change.
 6. **Validate locally**
-   - Run:
-     - `go build ./...`
-     - `go test ./...`
+   - Run `make verify` (fmt-check + vet + build + lint + `go test -race`).
+     This mirrors the CI pipeline and is mandatory before every push.
    - Run targeted tests during development for faster feedback.
 7. **Validate CI health**
    - Ensure PR checks are green before merge.
+   - After merge, confirm CI on `main` is green:
+     `gh run list --branch main --workflow CI --limit 1`.
+   - A task is not done until post-merge CI on `main` is green. If it is red,
+     fixing it is part of the same task — do not stop or hand off.
 8. **Commit discipline**
    - Small, meaningful commits with clear messages.
 9. **Push and PR hygiene**
@@ -33,6 +36,11 @@ This repository uses an implementation-first workflow for all feature work.
 ## Quality rules
 
 - Do not remove or weaken unrelated tests.
+- Tests must be hermetic: they must not depend on the developer's machine or
+  global state. Tests that shell out to external tools (e.g. `git`) must set
+  the environment explicitly (`t.Setenv` for `GIT_AUTHOR_*`/`GIT_COMMITTER_*`,
+  temp `HOME`, etc.) so they pass on a bare CI runner. "Passes on my machine"
+  is not evidence.
 - Do not introduce breaking CLI changes without docs + migration notes.
 - Prefer deterministic behavior (sorted output, stable iteration).
 - Keep generated/manifest behavior backward compatible where practical.
@@ -43,6 +51,6 @@ This repository uses an implementation-first workflow for all feature work.
 - [ ] README/docs updated
 - [ ] Skills updated
 - [ ] Tests added/updated
-- [ ] `go build ./...` passes
-- [ ] `go test ./...` passes
-- [ ] CI checks green
+- [ ] `make verify` passes locally
+- [ ] PR CI checks green
+- [ ] Post-merge CI on `main` green (`gh run list --branch main --workflow CI --limit 1`)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..714dc47
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,26 @@
+# climate — Claude Code instructions
+
+Follow `AGENTS.md` (implementation-first workflow). Key rules for this repo:
+
+## Definition of Done (non-negotiable)
+
+A task is **not done** until:
+1. `make verify` passes locally (fmt-check + vet + build + lint + `go test -race`).
+2. PR CI checks are green.
+3. **Post-merge CI on `main` is green** — check with:
+   `gh run list --branch main --workflow CI --limit 1`
+   If it is red after your merge, fixing it is part of the same task. Do not stop.
+
+## Hermetic tests
+
+Tests must pass on a bare Linux CI runner, not just this Mac:
+- Any test that shells out to `git` must set identity via `t.Setenv`
+  (`GIT_AUTHOR_NAME/EMAIL`, `GIT_COMMITTER_NAME/EMAIL`) and pin branches
+  (`git init --bare --initial-branch=main`) — macOS masks both failure modes.
+- Reproduce CI locally before pushing:
+  `env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null go test -race ./...`
+
+## Debugging red CI
+
+Use `gh`: `gh run list --workflow CI`, `gh run view <id> --log-failed`.
+`CI Auto-Fix` workflow only fixes gofmt/lint — test failures need a human/agent.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..2e97e2e
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,29 @@
+GOFLAGS ?=
+
+.PHONY: build test fmt fmt-check lint vet verify
+
+build:
+	go build ./...
+
+test:
+	go test -race -coverprofile=coverage.out ./...
+
+fmt:
+	gofmt -w .
+
+fmt-check:
+	@unformatted="$$(gofmt -l .)"; \
+	if [ -n "$$unformatted" ]; then \
+		echo "These files are not gofmt-formatted:"; \
+		echo "$$unformatted"; \
+		exit 1; \
+	fi
+
+lint:
+	golangci-lint run
+
+vet:
+	go vet ./...
+
+# Full pre-push gate: mirrors the CI pipeline. Run before every push.
+verify: fmt-check vet build lint test