docs(HYBIM-863): add AGENTS.md for AI-assisted development

[shuningc]

Summary

• Add AGENTS.md adapted from upstream rungalileo/galileo-python for Splunk AO (package layout, handlers, testing conventions, error-handling model).
• Include onboarding sections for product context, O11y vs standalone deployment (with consolidated env var reference), and first-contribution paths.
• Deduplicate deployment/env-var content so each topic is documented once.

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: approve — Docs-only PR; claims verified against the codebase and are accurate, with two minor accuracy nuances.

Follow-ups

Suggested follow-up work that could be tracked as Jira tickets:

• AGENTS.md:113-144: The package-structure diagram lists a curated subset of top-level modules. Several existing modules an agent may need (e.g. annotation_queues.py, agent_control.py, collaborator.py, evaluator.py/evaluators.py, integration.py, provider.py, model.py, runs.py, search.py, scorers.py, tracing.py, traces.py, export.py) are omitted. This is fine for an overview, but consider noting the list is illustrative rather than exhaustive so agents don't assume unlisted modules don't exist.

[fercor-cisco]

🟡 minor (documentation): Unlike every other row in this "HTTP-Specific Exceptions" table, HTTPValidationError (422) is not raised by the generated client — it is returned as a value. In resources/api/.../*.py the generated code does if response.status_code == 422: return HTTPValidationError.from_dict(...), whereas 400/401/403/404/409/429/5xx all raise. The SDK layer then decides what to do (e.g. Dataset.get_version_content turns it into a ValueError). Listing it here alongside genuinely-raised exceptions, under a diagram that says "Generated API Client (Always raises HTTP exceptions)", may lead an agent to write except HTTPValidationError: around a client call, which will never trigger. Consider a footnote clarifying that 422 is returned, not raised.

🤖 Generated by the Astra agent

[fercor-cisco]

🔵 nit (documentation): The autouse set_validated_config fixture in tests/conftest.py actually sets SPLUNK_AO_LOG_STREAM (the deprecated alias) to test-log-stream, not SPLUNK_AO_AGENT_STREAM. Only the module-top import-time block sets SPLUNK_AO_AGENT_STREAM. Minor, but since this section documents the effective test environment, an agent reading it might expect SPLUNK_AO_AGENT_STREAM to be the live value under the fixture.

🤖 Generated by the Astra agent

[fercor-cisco]

Blocking issue found — auto_setup_listeners does not exist

I verified every concrete claim in AGENTS.md against the codebase. Almost everything checks out (Project API, resolve_deployment(), config._BRIDGE, env var names, create_dataset/run_experiment, regen scripts, inv tasks — all accurate). One is wrong and would actively mislead an agent:

🔴 blocking: AGENTS.md references a auto_setup_listeners=False kwarg for the CrewAI handler in two places:

• L85: `splunk_ao.handlers.crewai` (use `auto_setup_listeners=False` in tests)
• L91: CrewAI has import side effects — lazy-import inside tests, set `auto_setup_listeners=False`.

This flag does not exist. The handler is CrewAIEventListener and its __init__ (src/splunk_ao/handlers/crewai/handler.py:66) accepts only splunk_ao_logger, start_new_trace, and flush_on_crew_completed. A grep for auto_setup_listeners across src/ and tests/ returns nothing, and git log -S shows it was never present. An agent following this guidance would pass an unknown kwarg and hit a TypeError.

Suggested fix: drop the auto_setup_listeners=False references. The real testing pattern is to patch AgentStreams/Projects/Traces and construct the logger directly (see tests/test_crewai_handler.py); the lazy-import-inside-tests note is still correct.

Everything else in the file is accurate. Note also: the three earlier Astra review comments (422 exceptions table, conftest SPLUNK_AO_LOG_STREAM nit, module-list follow-up) were incidentally resolved by the later trim commit — the sections they referenced no longer exist.

🤖 Reviewed with Claude Code