AGENTS.md — example-package-go

Summary: This playbook governs agents working in the Go example package. It inherits all global rules from the root AGENTS.md and sets the mode to autonomous. Agents must run gofmt, golangci-lint, and go test ./... before completing any task. No global rules are overridden.

Inherits

/AGENTS.md — the root operational playbook.

Overrides

(none) — all root rules apply without modification.

Mode

autonomous

Scope

MAY

• Read and write any file within example-package-go/.
• Run gofmt, goimports, golangci-lint run ./..., go build ./..., go test ./..., and govulncheck ./... as part of any task.
• Modify go.mod and go.sum as part of an approved dependency task.
• Update example-package-go/index.md after any structural change.

MUST NOT

• Modify any file outside example-package-go/ without explicit human approval.
• Use panic in any non-main, non-test code path without an escalation flag.
• Ignore an error with _ = ... without an inline justification comment.
• Introduce a goroutine without a clear termination condition documented in a comment.

Navigation Order

1. /index.md — understand the global repo structure.
2. /AGENTS.md — load global behavioral rules.
3. /codebase_rules.md — load global coding standards.
4. example-package-go/index.md — understand this package's structure.
5. example-package-go/AGENTS.md — load package-specific rules (this file).
6. example-package-go/codebase_rules.md — load Go coding standards.
7. Relevant source files identified from index.md.

Task Patterns

Adding a new exported function

1. Read navigation order files.
2. Write the failing test first using a table-driven test structure.
3. Write the implementation with a Go doc comment starting with the function name.
4. Run gofmt -s -w ./... and goimports -w ./... to format.
5. Run golangci-lint run ./... and fix all issues.
6. Run go test ./... and confirm all tests pass.
7. Run go test -coverprofile=coverage.out ./... and verify coverage ≥80%.
8. Update index.md if the function is a new public entry point.
9. Produce the output contract.

Fixing a bug

1. Read navigation order files.
2. Reproduce the bug in a failing test. Use t.Run() for the new case.
3. Fix the implementation. Run golangci-lint and go test ./....
4. Confirm no regressions.
5. Produce the output contract.

Adding a module dependency

1. Read navigation order files.
2. Run govulncheck on the proposed module before adding it.
3. Run go get <module>@<version>. Commit go.mod and go.sum.
4. Run go build ./... and go test ./.... Fix any breakage.
5. Produce the output contract.

Output Contract

Follows the root AGENTS.md output contract exactly.

Additional requirement: note in ## Changes whether each Go file passed gofmt -l (no output means clean) and golangci-lint.

Escalation Triggers

Inherits all global triggers from /AGENTS.md. Additional local triggers:

• Any function that spawns a goroutine without a cancellable context.Context parameter requires human review before the task is considered complete.