fix linting and ensure claude reads agents file every time

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

Author: marythought

AGENTS.md

@@ -32,9 +32,29 @@ Prefer `make` targets at repo root:
 
 ## Testing Guidelines
 
-- Unit tests: `*_test.go` next to code; run `make test`.
-- BDD tests: run `cd tests-bdd && go test ./...` (requires Docker; feature files are `tests-bdd/features/*.feature`).
-- Integration tests may require the compose stack; follow module README(s) under `service/`.
+### Required Tests Before Committing
+
+**CRITICAL**: All Go code changes must pass these checks before being marked as complete:
+
+1. **Linting**: `golangci-lint run ./path/to/changed/files.go`
+   - Must pass with 0 issues
+   - Fixes common issues: formatting, shadowing, unused code, suspicious constructs
+   - Never let the user discover linting issues from CI
+
+2. **Unit Tests**: `go test ./...` (or `make test` from repo root)
+   - All existing tests must continue to pass
+   - Add tests for new functionality
+
+3. **README Code Block Tests**:
+   - SDK README examples: `cd sdk && go test -run TestREADMECodeBlocks`
+   - Ensures documentation examples remain compilable
+
+### Test Types
+
+- **Unit tests**: `*_test.go` next to code; run `make test`.
+- **BDD tests**: run `cd tests-bdd && go test ./...` (requires Docker; feature files are `tests-bdd/features/*.feature`).
+- **Integration tests** may require the compose stack; follow module README(s) under `service/`.
+- **README tests**: verify code examples in documentation compile and work correctly.
 
 ## Commit & Pull Request Guidelines
 

CLAUDE.md

@@ -0,0 +1,43 @@
+# Claude Code Instructions
+
+## Overview
+
+This file provides instructions for AI agents working on the OpenTDF Platform codebase.
+
+**For complete repository guidelines, coding standards, and development workflow, see [AGENTS.md](AGENTS.md).**
+
+## Critical Requirements
+
+### Before Completing ANY Go Code Changes
+
+**MANDATORY CHECKS** - Run these before marking work as complete:
+
+1. **Linting**: `golangci-lint run ./path/to/changed/files.go`
+   - Must pass with 0 issues
+   - User should NEVER discover linting issues from CI
+
+2. **Unit Tests**: `go test ./...` or `make test`
+   - All existing tests must pass
+   - Add tests for new functionality
+
+3. **README Tests** (if SDK changes): `cd sdk && go test -run TestREADMECodeBlocks`
+   - Ensures documentation examples remain compilable
+
+### Formatting
+
+- Run `gofumpt -w <files>` on all changed Go files before completing
+- Use tabs for indentation (Go standard)
+
+### Key Guidelines from AGENTS.md
+
+- **Project Structure**: Go workspace with multiple modules (service, sdk, lib/*)
+- **Build Commands**: Use `make` targets (build, test, lint, fmt)
+- **Commit Style**: Conventional Commits with DCO sign-off (`git commit -s`)
+- **Testing**: Unit tests, BDD tests, integration tests - see AGENTS.md for details
+
+## Remember
+
+✅ Run linting checks proactively - don't let CI catch issues
+✅ Test changes locally before marking complete
+✅ Follow patterns and conventions in AGENTS.md
+✅ Update documentation when changing APIs

sdk/readme_test.go

@@ -73,7 +73,7 @@ func formatBlockName(index int, code string) string {
 	}
 
 	// Try to find a meaningful identifier in the first few lines
-	for _, line := range lines[:min(5, len(lines))] {
+	for _, line := range lines[:minInt(5, len(lines))] {
 		line = strings.TrimSpace(line)
 		if strings.HasPrefix(line, "package ") {
 			return strings.TrimPrefix(line, "package ")
@@ -89,15 +89,11 @@ func formatBlockName(index int, code string) string {
 // testCodeBlock attempts to compile a code block.
 func testCodeBlock(t *testing.T, code string) error {
 	// Create a temporary directory
-	tmpDir, err := os.MkdirTemp("", "readme-test-*")
-	if err != nil {
-		return err
-	}
-	defer os.RemoveAll(tmpDir)
+	tmpDir := t.TempDir()
 
 	// Write the code to main.go
 	mainPath := filepath.Join(tmpDir, "main.go")
-	if err := os.WriteFile(mainPath, []byte(code), 0644); err != nil {
+	if err := os.WriteFile(mainPath, []byte(code), 0o644); err != nil {
 		return err
 	}
 
@@ -111,7 +107,7 @@ func testCodeBlock(t *testing.T, code string) error {
 
 	// Get the absolute path to the platform directory
 	// When running from sdk directory, we need to go up one level
-	platformDir, err := filepath.Abs(filepath.Join(".."))
+	platformDir, err := filepath.Abs("..")
 	if err != nil {
 		return err
 	}
@@ -124,9 +120,9 @@ func testCodeBlock(t *testing.T, code string) error {
 	}
 
 	for _, replace := range replacements {
-		cmd := exec.Command("go", "mod", "edit", "-replace", replace)
-		cmd.Dir = tmpDir
-		if output, err := cmd.CombinedOutput(); err != nil {
+		editCmd := exec.Command("go", "mod", "edit", "-replace", replace)
+		editCmd.Dir = tmpDir
+		if output, err := editCmd.CombinedOutput(); err != nil {
 			t.Logf("go mod edit output: %s", output)
 			return err
 		}
@@ -153,7 +149,7 @@ func testCodeBlock(t *testing.T, code string) error {
 	return nil
 }
 
-func min(a, b int) int {
+func minInt(a, b int) int {
 	if a < b {
 		return a
 	}