go/AGENTS.md

AGENTS.md

Commands

• Check: go build ./..., go vet ./..., go test -race ./..., go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...; from the project root, run the TODO check below.
• Generate: No code generation is configured; format with gofmt -w ..
• Documentation: go run ./cmd/docs check; create records with go run ./cmd/docs new adr|plan "Title". This checker repository uses its local implementation as the source of truth.

Scope and decisions

• Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it.
• Explicit user instructions win; nearer scoped rules override broader rules.
• Distinguish confirmed requirements, proposed defaults and unresolved decisions; resolve material ambiguity before dependent work.
• Proposed ADRs are context, not authority; read relevant accepted decisions before changing their scope.
• Before final review and merge, reconcile affected records against the latest target branch plus the PR, following /docs/adr/README.md.
• Documentation tier: ADRs only. Create a plan only when work needs durable execution context across areas, phases or sessions; then enable the plans tier.
• In a sandbox, request required network/cache access before first codegen; on permission/cache errors retry once with that access. Never hand-edit generated output.
• Shared databases and ports may belong to other worktrees/agents; read project rules before starting, stopping or resetting them.
• Ask before lint/autofix changes that could alter runtime behavior.
• Report commands actually run and their results; never claim an unrun check passed.
• Name branches <type>/<kebab> without agent-name prefixes.

Comments

• Document package/module purpose, ownership and boundaries, and every public/exported contract in native doc comments; document generated surfaces at their source.
• Explain why at invariants, auth decisions, concurrency/ordering, destructive edges and deliberate deviations; no narration, changelog comments or commented-out code.
• Use invariant: <property>, authz: <who and enforcement>, shortcut: <limit>, <when to upgrade> on relevant code; retain Go Deprecated: and Rust // SAFETY:.
• Every TODO needs an issue URL; reviewers recheck tagged comments on touched code.

Project map

Go module go.auvem.com/corestack.

• Docs format (the spec docs check implements): docs/docs-format.md.
• Decisions live in docs/adr/, plans in docs/plans/. Records are permanent; never rename them.
• Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the module-boundary ADR).

Go

• Default backend language is Go; follow existing package boundaries.
• Define interfaces at the consumer only when a second implementation or a test seam needs one.
• Wrap contextual errors with %w; inspect causes with errors.Is/errors.As.
• Do not add package-level mutable state or init side effects.
• Put context.Context first in parameters; never store it in a struct.
• Give every goroutine an owner and a shutdown path.
• Run gofmt, go vet ./..., tests and the project's configured linter from the owning module.
• Use .golangci.yml (revive exported/package-comments); the pinned linter command is listed above.

TODO check

Run from the project root (also enforced in CI):

find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage