docs: update agents md

[pradystar]

Summary

• Replace AGENTS.md with current repository wide development guidance
• Add ARCHITECTURE.md covering SDK boundaries, telemetry paths, configuration and testing
• Add CLAUDE.md importing the shared agent instructions
• Document approval requirements for commands, workflows, Git operations and subagents

[shuningc]

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

Verdict: request_changes — The A2A/ADK lint commands listed as non-mutating actually rewrite files (ruff fix = true in both subpackage configs), which contradicts the permission model this PR is establishing; several other factual claims about paths, lockfiles, and export flow are inaccurate.

General Comments

• 🟡 minor (documentation): These docs are instruction files an agent will treat as authoritative, so factual drift is the main risk rather than prose quality. Most claims check out (Poetry 2.4.1, Python 3.11–3.14, root CI on Linux/macOS/Windows, pytest 9, OTel 1.38, galileo-core ^4.4.0, resolve_deployment() behavior, flush()/terminate() semantics, NormalizingSpanExporter in exporter/config.py), and replacing the stale SPLUNK_AO_SF_TOKEN guidance with the real SPLUNK_AO_O11Y_TOKEN/SPLUNK_AO_O11Y_API_TOKEN pair is a genuine correctness fix. The remaining issues are concentrated in a few specific claims flagged inline.

One process suggestion: since the value of these files depends entirely on staying true, consider noting in CONTRIBUTING.md (or the change workflow section) that AGENTS.md/ARCHITECTURE.md need updating when telemetry paths, env vars, or package layout change. Otherwise this content will drift silently and agents will act on stale invariants — exactly the failure mode the old SPLUNK_AO_SF_TOKEN line represented.

Follow-ups

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

• docs/domain-entity-rename.md:1-1: ARCHITECTURE.md states "docs/ contains repository documentation", but docs/ holds a single file (domain-entity-rename.md) while generated API references land in the gitignored .generated_docs/ (see .github/workflows/publish-docs.yaml:31-36). Consider either consolidating repository docs under docs/ so the statement is substantive, or trimming the claim. Not blocking — the sentence does distinguish generated output from checked-in docs.
• AGENTS.md:9-10: The permission model gates every project command behind explicit approval, including read-only ones like poetry run pytest and poetry run mypy. This is a deliberate policy choice and outside this review's scope, but it will produce a lot of approval round-trips for ordinary test-driven work. Worth revisiting whether a small allowlist of non-mutating verification commands (targeted pytest, mypy, ruff check --no-fix) could be pre-approved while keeping installs, lock updates, codegen, and Git/workflow operations gated.

[pradystar]

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

Verdict: request_changes — The A2A/ADK lint commands listed as non-mutating actually rewrite files (ruff fix = true in both subpackage configs), which contradicts the permission model this PR is establishing; several other factual claims about paths, lockfiles, and export flow are inaccurate.

General Comments

• 🟡 minor (documentation): These docs are instruction files an agent will treat as authoritative, so factual drift is the main risk rather than prose quality. Most claims check out (Poetry 2.4.1, Python 3.11–3.14, root CI on Linux/macOS/Windows, pytest 9, OTel 1.38, galileo-core ^4.4.0, resolve_deployment() behavior, flush()/terminate() semantics, NormalizingSpanExporter in exporter/config.py), and replacing the stale SPLUNK_AO_SF_TOKEN guidance with the real SPLUNK_AO_O11Y_TOKEN/SPLUNK_AO_O11Y_API_TOKEN pair is a genuine correctness fix. The remaining issues are concentrated in a few specific claims flagged inline.

One process suggestion: since the value of these files depends entirely on staying true, consider noting in CONTRIBUTING.md (or the change workflow section) that AGENTS.md/ARCHITECTURE.md need updating when telemetry paths, env vars, or package layout change. Otherwise this content will drift silently and agents will act on stale invariants — exactly the failure mode the old SPLUNK_AO_SF_TOKEN line represented.

Follow-ups

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

• docs/domain-entity-rename.md:1-1: ARCHITECTURE.md states "docs/ contains repository documentation", but docs/ holds a single file (domain-entity-rename.md) while generated API references land in the gitignored .generated_docs/ (see .github/workflows/publish-docs.yaml:31-36). Consider either consolidating repository docs under docs/ so the statement is substantive, or trimming the claim. Not blocking — the sentence does distinguish generated output from checked-in docs.
• AGENTS.md:9-10: The permission model gates every project command behind explicit approval, including read-only ones like poetry run pytest and poetry run mypy. This is a deliberate policy choice and outside this review's scope, but it will produce a lot of approval round-trips for ordinary test-driven work. Worth revisiting whether a small allowlist of non-mutating verification commands (targeted pytest, mypy, ruff check --no-fix) could be pre-approved while keeping installs, lock updates, codegen, and Git/workflow operations gated.

1. Updated Ruff commands with --no-fix and clearer “without source rewrites” wording.
2. Process suggestion addressed AGENTS.md now requires AGENTS.md and ARCHITECTURE.md to be updated alongside changes to package layout, authentication variables, telemetry paths, or documented lifecycle invariants.
3. No change for followups.