AGENTS: add PR scope, logging, scanner, async and test-fixture guidance

[jasonacox]

Why

Reviewing the five open PRs (#735, #649, #685, #370, #300) turned up recurring problems that AGENTS.md either didn't cover or only covered indirectly via DESIGN.md. This writes those lessons down so contributors (human and agent) hit them before review instead of during it.

Changes

Build, Test, Lint

• CI runs only python -m tests and testcontrib.py; tests elsewhere (e.g. a pytest suite) never run. (v2.0.0 with Async Architecture #649 added pytest tests CI would not run.)
• devices.json test fixtures must use the wizard's real schema (product_id, not productKey). (Scanner: poll configured static-IP devices that do not broadcast #735's fixtures all include productKey, hiding a crash on real files.)
• Lint/test PRs as merged onto master; never get CI green with --ignore/blanket disables. (v2.0.0 with Async Architecture #649 excluded scanner_async.py from pylint.)

Code Conventions

• Logging: no handler/formatter/basicConfig in library code except set_debug(), never rewrite logger names, per-device context via message/LoggerAdapter, no print() in library modules. (Rework logging #300, Documentation #685)
• Wildcard-exported modules define __all__. (v2.0.0 with Async Architecture #649 shadowed tinytuya.log.)
• New device traffic is opt-in on library APIs. (Scanner: poll configured static-IP devices that do not broadcast #735 polls configured IPs by default.)
• Scanner features go in DeviceDetect classes, not the devices() main loop; don't re-indent large blocks. (Restates DESIGN.md for Scanner: poll configured static-IP devices that do not broadcast #735.)
• One protocol implementation; async/Monitor layers own only I/O. (v2.0.0 with Async Architecture #649 copies ~60% of the sync protocol code.)
• asyncio rules: no Lock/Event in __init__ (breaks < 3.10), propagate CancelledError, don't block the loop, isolate callback errors. (v2.0.0 with Async Architecture #649)
• Pre-3.7 shims are dead code too; keep IS_PY2 as a public alias.

New "Pull Request Scope" section

• One concern per PR; docs PRs don't change behavior. (Documentation #685)
• New public classes ship opt-in with tests and docs and don't change default CLI/scanner output. (MappedDevice Phase II #370)
• Stale branches against since-refactored modules get ported fresh off master with credit. (MappedDevice Phase II #370, Rework logging #300)
• Version bumps and breaking changes only in release PRs, with migration notes. (v2.0.0 with Async Architecture #649)

Documentation Map: RELEASE.md bullets are one or two sentences under the right grouping.

Docs only; no code changes.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Two statements inaccurately describe current CI and Monitor framing behavior.

2 open findings

• Clarify regression suites versus the CI smoke check · New
• Correct Monitor framing logic duplication claim · New

What changed in this PR

Expands contributor guidance based on recurring review issues.

Changes:

• Clarifies CI, fixture, logging, scanner, async, and protocol practices.
• Adds PR scope and release-note guidance.

File	Description
AGENTS.md	Extends contributor and review guidance.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jasonacox-sam]

Read the full diff against the review threads that motivated it — each rule maps to a concrete failure we actually hit (#649's pytest suite CI never runs, #735's productKey fixtures hiding the wizard-schema KeyError, --ignore lint greening, #685's logger renames, the scanner main-loop re-indent). Writing these down before review instead of during it is exactly right, and the PR-scope section (docs-only PRs don't change behavior; stale branches port as fresh PRs with credit; one concern per PR) matches how the #685/#370 resolutions are being handled. No concerns; approving.

— Sam ⚙️