Skip to content

docs: add AGENTS.md#4482

Merged
turbolent merged 3 commits into
masterfrom
docs/add-agents-md
Apr 24, 2026
Merged

docs: add AGENTS.md#4482
turbolent merged 3 commits into
masterfrom
docs/add-agents-md

Conversation

@Aliserag

@Aliserag Aliserag commented Apr 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds AGENTS.md — the open standard (agents.md, Linux-Foundation-backed, adopted by 60K+ repos) that guides AI coding agents (Claude Code, Codex, Cursor, Copilot, Windsurf, Gemini CLI) on a per-repo basis.

How this file was generated

Authored via an evidence-based generator skill with a strict verify-before-claim protocol:

  • Every build/test command traced to an actual target in Makefile / package.json / equivalent
  • Every file path verified via Glob/Read
  • Every version number pulled from go.mod / package.json / foundry.toml / etc.
  • Every count (targets, scripts, directories) re-executed with the precise command before writing
  • Every line-number citation re-read before writing
  • Internal consistency sweep (no contradictions between sections)
  • Iterated with self-scoring on Coverage / Evidence / Specificity / Conciseness until all four axes reached 10/10

What AGENTS.md contains

  • Overview grounded in README + actual source
  • Build and test commands (only ones that exist in the manifest)
  • Architecture map (real directory layout, real contract/module names)
  • Conventions & gotchas (non-obvious rules verified in source)
  • Files not to modify (generated / vendored / lockfiles)

Test plan

  • File renders on GitHub
  • Every command verified against the relevant manifest
  • Every path verified to exist
  • No approximations or invented commands

@Aliserag
docs: add AGENTS.md
6d9959a 
Adds the AGENTS.md open-standard file for AI coding agents (agents.md).
Every claim evidence-backed against Makefile, package.json, source tree,
or equivalent manifest. Zero fabrication.
@github-actions

github-actions Bot commented Apr 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

@github-actions

github-actions Bot commented Apr 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Benchstat comparison

  • Base branch: onflow:master
  • Base commit: f2a0f41
Results

old.txtnew.txt
time/opdelta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-41.18µs ± 0%1.32µs ± 0%~(p=1.000 n=1+1)
ByteArrayValueToByteSlice-485.9ns ± 0%78.6ns ± 0%~(p=1.000 n=1+1)
ByteSliceToByteArrayValue-4926ns ± 0%1061ns ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-4402µs ± 0%382µs ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-43.40µs ± 0%3.45µs ± 0%~(p=1.000 n=1+1)
Emit-44.56ms ± 0%4.62ms ± 0%~(p=1.000 n=1+1)
EnumTransfer-41.36µs ± 0%1.46µs ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-4270ns ± 0%268ns ± 0%~(p=1.000 n=1+1)
ExportType/simple_type-478.2ns ± 0%77.8ns ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-422.9µs ± 0%23.6µs ± 0%~(p=1.000 n=1+1)
InterpretRecursionFib-42.41ms ± 0%2.39ms ± 0%~(p=1.000 n=1+1)
NewInterpreter/new_interpreter-4881ns ± 0%870ns ± 0%~(p=1.000 n=1+1)
NewInterpreter/new_sub-interpreter-4332ns ± 0%331ns ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-4647µs ± 0%631µs ± 0%~(p=1.000 n=1+1)
RuntimeFungibleTokenTransferVM-4694µs ± 0%713µs ± 0%~(p=1.000 n=1+1)
RuntimeResourceDictionaryValues-42.75ms ± 0%2.81ms ± 0%~(p=1.000 n=1+1)
RuntimeResourceTracking-410.0ms ± 0%9.8ms ± 0%~(p=1.000 n=1+1)
RuntimeScriptNoop-414.9µs ± 0%15.1µs ± 0%~(p=1.000 n=1+1)
RuntimeVMInvokeContractImperativeFib-442.4µs ± 0%44.4µs ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-461.9ns ± 0%59.7ns ± 0%~(p=1.000 n=1+1)
 
alloc/opdelta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-41.08kB ± 0%1.05kB ± 0%~(p=1.000 n=1+1)
ByteArrayValueToByteSlice-432.0B ± 0%32.0B ± 0%~(all equal)
ByteSliceToByteArrayValue-4854B ± 0%854B ± 0%~(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-4144kB ± 0%144kB ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-42.46kB ± 0%2.45kB ± 0%~(p=1.000 n=1+1)
Emit-41.50MB ± 0%1.50MB ± 0%~(p=1.000 n=1+1)
EnumTransfer-4840B ± 0%849B ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-4120B ± 0%120B ± 0%~(all equal)
ExportType/simple_type-40.00B 0.00B ~(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-48.30kB ± 0%8.30kB ± 0%~(all equal)
InterpretRecursionFib-41.19MB ± 0%1.19MB ± 0%~(p=1.000 n=1+1)
NewInterpreter/new_interpreter-4976B ± 0%976B ± 0%~(all equal)
NewInterpreter/new_sub-interpreter-4232B ± 0%232B ± 0%~(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-4165kB ± 0%165kB ± 0%~(p=1.000 n=1+1)
RuntimeFungibleTokenTransferVM-4188kB ± 0%188kB ± 0%~(p=1.000 n=1+1)
RuntimeResourceDictionaryValues-41.76MB ± 0%1.76MB ± 0%~(p=1.000 n=1+1)
RuntimeResourceTracking-46.98MB ± 0%6.98MB ± 0%~(p=1.000 n=1+1)
RuntimeScriptNoop-48.08kB ± 0%8.09kB ± 0%~(p=1.000 n=1+1)
RuntimeVMInvokeContractImperativeFib-413.4kB ± 0%13.4kB ± 0%~(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-432.0B ± 0%32.0B ± 0%~(all equal)
 
allocs/opdelta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-47.00 ± 0%7.00 ± 0%~(all equal)
ByteArrayValueToByteSlice-41.00 ± 0%1.00 ± 0%~(all equal)
ByteSliceToByteArrayValue-45.00 ± 0%5.00 ± 0%~(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-42.25k ± 0%2.25k ± 0%~(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-429.0 ± 0%29.0 ± 0%~(all equal)
Emit-440.0k ± 0%40.0k ± 0%~(all equal)
EnumTransfer-413.0 ± 0%13.0 ± 0%~(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-43.00 ± 0%3.00 ± 0%~(all equal)
ExportType/simple_type-40.00 0.00 ~(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-4176 ± 0%176 ± 0%~(all equal)
InterpretRecursionFib-417.7k ± 0%17.7k ± 0%~(all equal)
NewInterpreter/new_interpreter-415.0 ± 0%15.0 ± 0%~(all equal)
NewInterpreter/new_sub-interpreter-44.00 ± 0%4.00 ± 0%~(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-43.08k ± 0%3.08k ± 0%~(all equal)
RuntimeFungibleTokenTransferVM-43.61k ± 0%3.61k ± 0%~(all equal)
RuntimeResourceDictionaryValues-436.7k ± 0%36.7k ± 0%~(p=1.000 n=1+1)
RuntimeResourceTracking-4129k ± 0%129k ± 0%~(p=1.000 n=1+1)
RuntimeScriptNoop-4114 ± 0%114 ± 0%~(all equal)
RuntimeVMInvokeContractImperativeFib-4426 ± 0%426 ± 0%~(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-41.00 ± 0%1.00 ± 0%~(all equal)
 

@Aliserag Aliserag requested a review from peterargue April 23, 2026 20:51
SupunS
SupunS reviewed Apr 23, 2026
View reviewed changes
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
@Aliserag
Address review: reference CODEOWNERS instead of duplicating contents
6c59d39 
Per review feedback on the sibling atree PR (onflow/atree#658),
reference the CODEOWNERS file rather than listing its members
inline. The hard-coded list would silently go stale when the team
rotates reviewers, since GitHub enforces CODEOWNERS but nothing
enforces AGENTS.md. Matches the pattern the surrounding bullets
already use for codecov.yml, SECURITY.md, CONTRIBUTING.md, etc.
@turbolent turbolent merged commit 95d26d9 into master Apr 24, 2026
17 checks passed
@turbolent turbolent deleted the docs/add-agents-md branch April 24, 2026 15:42
@BrewTestBot BrewTestBot mentioned this pull request May 18, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@turbolent turbolent turbolent approved these changes

@SupunS SupunS SupunS approved these changes

@peterargue peterargue Awaiting requested review from peterargue

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Aliserag @turbolent @SupunS