# 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](/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](/index.md) — understand the global repo structure.
2. [/AGENTS.md](/AGENTS.md) — load global behavioral rules.
3. [/codebase_rules.md](/codebase_rules.md) — load global coding standards.
4. [example-package-go/index.md](index.md) — understand this package's structure.
5. [example-package-go/AGENTS.md](AGENTS.md) — load package-specific rules (this file).
6. [example-package-go/codebase_rules.md](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.