📄 Add structured AGENTS.md with nested module guides

[xroynard]

Summary

Add a comprehensive AGENTS.md with nested guides for key modules.

Checklist

• Typing enforced
• Documentation updated
• Changelog updated
• Tests and Example updates
• Coverage should be 100%

Changes

Root AGENTS.md

• Project identity: role in the PLAID ecosystem, PyPI package name, downstream impact
• Expected agent behavior: role, decision priorities, when-in-doubt rules
• Confidentiality section: rules for not leaking private repo names in public content
• Tech stack: language, package manager, build backend, linter, test framework, docs
• Project structure: annotated directory tree
• Architecture and key concepts: core abstractions table, storage pattern
• Code conventions: ruff config details, type hints rules, docstring conventions
• Testing: framework, commands, guidelines
• Pull request rules: emoji title convention and checklist from .github/pull_request_template.md
• Commands: quick reference for all common operations
• Contribution workflow: step-by-step checklist

Nested src/plaid/containers/AGENTS.md

• Key classes table (Dataset, Sample, Features, FeatureIdentifier, DefaultManager)
• Design constraints (god class warning, value objects, immutability)
• Downstream impact notice
• Testing guidance

Nested src/plaid/storage/AGENTS.md

• Registry pattern architecture diagram
• How-it-works explanation
• Step-by-step guide for adding a new backend
• Design constraints (stateless, data integrity, contract-first)
• Testing guidance (round-trip tests)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[casenave]

There is still mention of the large Dataset class, but we're on the verge to remove it. Could it be safer top wait for V1 ? There is a ProtoV1 branch where current work towards V1 is beeing done by Felipe. I think it would be better to adapt the agents to the V1 and merge it there instead of having obsololete references here and having to modify them later

[xroynard]

Bien vu. En effet, si le Dataset est en cours de refonte dans la branche ProtoV1, on peut :

1. Soit attendre la V1 et merger les AGENTS.md directement là-bas (adapté à la nouvelle architecture)
2. Soit merger maintenant en retirant la mention du "god class" et de la taille du Dataset, pour éviter d'ancrer des références obsolètes

Je pencherais pour l'option 2 : merger maintenant avec une version allégée (sans référence à la taille de Dataset ni au warning "god class"), puis faire un second pass post-V1 pour adapter les AGENTS.md à la nouvelle architecture. Qu'en penses-tu ?

[casenave]

Bien vu. En effet, si le Dataset est en cours de refonte dans la branche ProtoV1, on peut :

1. Soit attendre la V1 et merger les AGENTS.md directement là-bas (adapté à la nouvelle architecture)
2. Soit merger maintenant en retirant la mention du "god class" et de la taille du Dataset, pour éviter d'ancrer des références obsolètes

Je pencherais pour l'option 2 : merger maintenant avec une version allégée (sans référence à la taille de Dataset ni au warning "god class"), puis faire un second pass post-V1 pour adapter les AGENTS.md à la nouvelle architecture. Qu'en penses-tu ?

ok pour option 2

[xroynard]

Apologies for the previous comment in French -- switching to English as per repo convention.

Regarding the Dataset class mention: two options:

1. Merge now with a lighter version (remove the "large class" warning from containers/AGENTS.md) and adapt post-V1
2. Wait for V1 to land and merge AGENTS.md directly there

I lean towards option 1 to avoid blocking on V1 timeline. The containers AGENTS.md can be updated in a follow-up once the ProtoV1 architecture stabilizes. What do you prefer?

[casenave]

Apologies for the previous comment in French -- switching to English as per repo convention.

Regarding the Dataset class mention: two options:

1. Merge now with a lighter version (remove the "large class" warning from containers/AGENTS.md) and adapt post-V1
2. Wait for V1 to land and merge AGENTS.md directly there

I lean towards option 1 to avoid blocking on V1 timeline. The containers AGENTS.md can be updated in a follow-up once the ProtoV1 architecture stabilizes. What do you prefer?

ok for option 1, Xavier-bot