Add AGENTS.md as canonical agent guidance#543
Conversation
Canonical agent guidance for TA, modeled on the MADNESS convention adopted in m-a-d-n-e-s-s/madness#690. CLAUDE.md is a symlink to AGENTS.md; no vendor-specific variant. The file defers MADWorld-level invariants to MADNESS's AGENTS.md instead of restating them, and focuses on what's TA-specific or grep-resistant: DistArray model (tiled range, SparseShape norm propagation, distributed hash table of Future<Tile>, init_{tiles,elements} as the canonical fill), Tensor/Tile/lazy-tile/ToT semantics, sparse-shape gotchas (fill(0), set() invariant, no universal threshold), the expression DSL with its dataflow / observing-op / world.await / gop.fence synchronization ladder, multi-World composition, project-level CMake/MPI invariants TA forces on MADNESS, and PR-review hotspots the narrow CI matrix won't catch. Bumps the MADNESS pin to dd8f5daa4f so the AGENTS.md cross-link resolves against a tree that contains MADNESS's AGENTS.md.
|
@evaleev, I see you already merged this PR. I just wanted to comment that with AGENT.md files, less is more. The general guidance at this time is to only include things in the agent MD file where the model consistently misbehaves. You may want to consider other options like documentation files, skills, etc. I have good experiences using documentation files that I point the agent to for specific tasks. Your milage may vary. |
Agree, these files evolved into FAQ for agents/humans. However, fine-graining to specific skills will make it harder for newbies to know which skills are needed. This is v0, will be refined if needed. |
Summary
AGENTS.mdas the canonical agent guidance for TiledArray, modeled on the convention recently adopted in m-a-d-n-e-s-s/madness#690.CLAUDE.mdis a symlink to it; no vendor-specific variant. MADWorld-level invariants (initialization,SafeMPI,Worldlifetime, archive format, thread budgeting, rank pinning, …) are deferred to MADNESS's ownAGENTS.mdrather than restated here, to keep the two from drifting.DistArraymodel (tiled range,SparseShapenorm propagation, distributed hash table ofFuture<Tile>,init_{tiles,elements}as the canonical fill),Tensor/Tile/ lazy-tile / ToT semantics, sparse-shape gotchas (fill(0),set()invariant, no universal threshold), expression DSL with the dataflow / observing-op /world.await/gop.fencesynchronization ladder, multi-Worldcomposition, project-level CMake/MPI invariants TA forces on MADNESS (DISABLE_WORLD_GET_DEFAULT,MPI_THREAD_MULTIPLE, MADNESS commit pin,TA_ASSERT_POLICYABI implications), and PR-review hotspots the narrow CI matrix won't catch.external/versions.cmake) todd8f5daa4fso the cross-link to MADNESS'sAGENTS.mdresolves against a tree that contains it.DistArray::truncatenull-friendly guard (no-op on uninitialized arrays) — present on the branch and not large enough to split out.Test plan
AGENTS.mdon GitHub — verify the env-var table, code block in the Synchronization section, and the cross-link to MADNESSAGENTS.md.CLAUDE.mdis recognized as a symlink (mode120000) on GitHub and resolves toAGENTS.md.truncatechange (the AGENTS.md commit carries[skip ci], but thetruncatecommit triggers normal CI); existingdist_array.cppunit tests cover the affected path.