docs: add guidance on using pkg/logger for debug instrumentation

[Copilot]

AGENTS.md had no guidance on adding debug logs — only on enabling them. This left contributors without a clear signal to use pkg/logger instead of ad-hoc fmt.Println/log.Printf.

Changes

• AGENTS.md — new "Adding debug logs" subsection under Debugging & Logging:
  • Shows the canonical pattern: declare var log = logger.New("namespace") at package scope, call log.Debug(...) with structured key/value pairs.
  • Reinforces namespace naming conventions (cli:, workflow:, mcp:, etc.).
  • Notes that all output is DEBUG-gated — zero noise in normal operation.

var log = logger.New("cli:my_package")

func doSomething() {
    log.Debug("starting operation", "key", value)
}

[Copilot]

Pull request overview

Adds contributor guidance for debug instrumentation, but the documented example does not match the current pkg/logger API.

Changes:

• Documents logger creation and namespace conventions.
• Adds example debug logging calls.
• Explains DEBUG-gated output.

Show a summary per file

File	Description
AGENTS.md	Adds guidance for instrumenting Go code with pkg/logger.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Suppressed comments (2)

AGENTS.md:120

• *logger.Logger has no Debug method; it only provides Print and Printf (pkg/logger/logger.go:118-142), so copying this canonical example will not compile. Also use a package-unique variable name, as established by examples such as pkg/parser/import_error.go:12, so multi-file packages do not redeclare log.

var log = logger.New("cli:my_package") // one per file/package, at package scope

func doSomething() {
    log.Debug("starting operation", "key", value)

AGENTS.md:127

• The logger does not accept structured key/value fields: Print delegates to fmt.Sprint, while Printf accepts a format string. Instructing callers to pass pairs after the message describes an API that does not exist and would not produce reliably formatted fields.

- Pass structured key/value pairs after the message for queryable context.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.86.1