Skip to content

📄 Add structured AGENTS.md with nested module guides#373

Open
xroynard wants to merge 4 commits into
mainfrom
feature/agents-md
Open

📄 Add structured AGENTS.md with nested module guides#373
xroynard wants to merge 4 commits into
mainfrom
feature/agents-md

Conversation

@xroynard
Copy link
Copy Markdown
Contributor

@xroynard xroynard commented Apr 17, 2026 •
edited
Loading

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)

@xroynard xroynard requested a review from a team as a code owner April 17, 2026 22:58
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 17, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

casenave
casenave reviewed Apr 18, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@casenave casenave left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@casenave casenave changed the title docs: add structured AGENTS.md with nested module guides 📄 Add structured AGENTS.md with nested module guides Apr 18, 2026
@xroynard xroynard changed the title 📄 Add structured AGENTS.md with nested module guides 📝 docs: add structured AGENTS.md with nested module guides Apr 18, 2026
@casenave casenave changed the title 📝 docs: add structured AGENTS.md with nested module guides 📄 docs: add structured AGENTS.md with nested module guides Apr 18, 2026
@xroynard xroynard changed the title 📄 docs: add structured AGENTS.md with nested module guides 📄 Add structured AGENTS.md with nested module guides Apr 18, 2026
@xroynard
Copy link
Copy Markdown
Contributor Author

xroynard commented Apr 18, 2026

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
Copy link
Copy Markdown
Member

casenave commented Apr 18, 2026

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
Copy link
Copy Markdown
Contributor Author

xroynard commented Apr 18, 2026

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
Copy link
Copy Markdown
Member

casenave commented Apr 18, 2026

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

xroynard added 4 commits June 5, 2026 20:41
@xroynard
docs: add structured AGENTS.md with nested module guides
a51ac95 
Add a comprehensive root AGENTS.md following modeles_d_agents best practices,
plus nested AGENTS.md files for the containers and storage modules.
@xroynard
docs: remove private repo names from public AGENTS.md, add PR rules a…
2ae10f5 
…nd confidentiality section

- Remove all mentions of scimm and maestro (private repos) from public-facing content
- Add confidentiality section warning agents not to mention private repos
- Add PR title emoji rules from .github/pull_request_template.md
- Add PR checklist reference
@xroynard
docs: add communication rules (English, direct tone)
8da3198
@xroynard
📄 docs(agents): update AGENTS.md files for v1.0.0 structure
406bf21 
Sync the root, containers and storage AGENTS.md with the post-V1 repo:
- root: fix project tree (drop removed bridges/pipelines/post/examples,
  add cli/types/viewer/downloadable_examples), fix Core abstractions table
  (Dataset/Features/FeatureIdentifier removed -> Sample/Infos/ProblemDefinition),
  doc tooling Sphinx -> Zensical, build command -> docs/generate_doc.sh
- containers: Dataset/Features/FeatureIdentifier no longer exist; document Sample
  (pydantic BaseModel), DefaultManager and utils helpers
- storage: add backend_api.py (BackendModule Protocol) and the BACKENDS registry
@xroynard xroynard force-pushed the feature/agents-md branch from 8298dfd to 406bf21 Compare June 5, 2026 20:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@casenave casenave casenave left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@xroynard @casenave