Skip to content

Add AGENTS.md as canonical agent guidance#543

Merged
evaleev merged 2 commits into
masterfrom
evaleev/feature/agents-md-v1
Apr 29, 2026
Merged

Add AGENTS.md as canonical agent guidance#543
evaleev merged 2 commits into
masterfrom
evaleev/feature/agents-md-v1

Conversation

@evaleev

@evaleev evaleev commented Apr 29, 2026

Copy link
Copy Markdown
Member

Summary

  • Introduces AGENTS.md as the canonical agent guidance for TiledArray, modeled on the convention recently adopted in m-a-d-n-e-s-s/madness#690. CLAUDE.md is a symlink to it; no vendor-specific variant. MADWorld-level invariants (initialization, SafeMPI, World lifetime, archive format, thread budgeting, rank pinning, …) are deferred to MADNESS's own AGENTS.md rather than restated here, to keep the two from drifting.
  • The TA-specific content focuses on what's hard to grep out of the codebase: 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), expression DSL with the dataflow / observing-op / world.await / gop.fence synchronization ladder, multi-World composition, project-level CMake/MPI invariants TA forces on MADNESS (DISABLE_WORLD_GET_DEFAULT, MPI_THREAD_MULTIPLE, MADNESS commit pin, TA_ASSERT_POLICY ABI implications), and PR-review hotspots the narrow CI matrix won't catch.
  • Bumps the MADNESS pin (external/versions.cmake) to dd8f5daa4f so the cross-link to MADNESS's AGENTS.md resolves against a tree that contains it.
  • Bundles a small DistArray::truncate null-friendly guard (no-op on uninitialized arrays) — present on the branch and not large enough to split out.

Test plan

  • Render AGENTS.md on GitHub — verify the env-var table, code block in the Synchronization section, and the cross-link to MADNESS AGENTS.md.
  • Confirm CLAUDE.md is recognized as a symlink (mode 120000) on GitHub and resolves to AGENTS.md.
  • CI green for the truncate change (the AGENTS.md commit carries [skip ci], but the truncate commit triggers normal CI); existing dist_array.cpp unit tests cover the affected path.

evaleev added 2 commits April 24, 2026 10:58
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
evaleev merged commit ca3d0b8 into master Apr 29, 2026
1 check passed
@evaleev
evaleev deleted the evaleev/feature/agents-md-v1 branch April 29, 2026 19:12
@justusc

justusc commented Apr 29, 2026

Copy link
Copy Markdown
Member

@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.

@evaleev

evaleev commented Apr 30, 2026

Copy link
Copy Markdown
Member Author

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants