agentleFS
gufo-orggufo-org/gufo/AGENTS.md

gufo

AGENTS.md1.1k starsChanged 8 days agoMITView on GitHub

Production packages target Linux x86-64 AMD Strix Halo (gfx1151); Windows is a supported native build target for development. CMake owns compiler flags, dependencies and installation; Nix supplies the pinned toolchain. Linux source-build prerequisites are in README.md. Stage only task-owned paths before Nix builds; flakes include tracked files. Measure performance with result/bin/gufo or build/release/gufo. Preserve compiler/dependency versions when comparing results. Formatting and Python repository checks may run on the editing host; they do not need the remote GPU. Before committing C++…

Trending

More talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 13 mentionsNov 2026: 2 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the gufo-org/gufo repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about gufo-org/gufo

The biggest 5 of 15 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 15

Talked about on GitHub and Bluesky (15 times).

On GitHub · 14

9 more on GitHub
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run the smallest check covering the change.

    line 43
  2. Distinctive:

    Run once, investigate flags, then alternate main/PR only for affected histories.

    line 70
  3. Very specific:

    Use tools/bench/build.sh for standalone HIP experiments, tools/bench/gfx1151_peak.hip for measured hardware ceilings, tools/prof/prof.py …

    line 85
  4. Distinctive:

    Keep model code, tests, tools and numerical contracts with their model.

    line 93
  5. Distinctive:

    Follow docs/AGENTS.md when writing or changing documentation.

    line 94
  6. Distinctive:

    Use the shared Qwen control-token constants for framing.

    line 95
  7. Very specific:

    Put Windows-specific code in src/core/platform/: one leaf per OS facility (files, pages, sockets), whose sources may branch on _WIN32 or …

    line 98
  8. Distinctive:

    Use one canonical long option and backend name per behavior.

    line 105
  9. Very specific:

    Use gh for GitHub operations after checking gh auth status.

    line 106
  10. Distinctive:

    Follow Conventional Commits with a single-line message.

    line 107
  11. Very specific:

    Prefer jj when available (jj version).

    line 111
  12. Very specific:

    Run python3 tools/ci/check-extension-api.py --write after header/include changes.

    line 121
  13. Distinctive:

    Follow the user's remote workflow and preserve unrelated work.

    line 130

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Platform and build

Production packages target Linux x86-64 AMD Strix Halo (gfx1151); Windows is a supported native build target for development. CMake owns compiler flags, dependencies and installation; Nix supplies the pinned toolchain. Linux source-build prerequisites are in README.md.

nix build                              # development package, all discovered extensions
nix build .#release                    # shipped lock-mode package, no tests/tools
./result/bin/gufo diagnose
nix flake check                       # hosted CPU/repository checks
nix develop                            # GPU development and reference tools

# Same production build without Nix, with the documented dependencies installed
cmake --preset release                # discovery build
# Add -DGUFO_EXTENSIONS_FROM_LOCK=ON for the shipped extension selection.
cmake --build --preset release --parallel 4

Stage only task-owned paths before Nix builds; flakes include tracked files. Measure performance with result/bin/gufo or build/release/gufo. Preserve compiler/dependency versions when comparing results.

Focused tests

Formatting and Python repository checks may run on the editing host; they do not need the remote GPU. Before committing C++ changes, run the shared CI check:

nix shell --inputs-from . nixpkgs#clang-tools -c python3 tools/ci/check-format.py
# Add --fix to apply formatting, then rerun the check.

Tests selected by nix flake check should stay fast and cache-friendly where possible. Reuse expensive setup and compiler caches when valid, use the smallest deterministic fixtures that preserve the assertions, and avoid redundant builds, fixed sleeps and repeated whole-tree work. Measure added wall time; keep expensive stress/model qualification explicitly selectable without weakening correctness.

Run the smallest check covering the change. gpu-test is RelWithDebInfo with assertions enabled. Build only the affected target during iteration:

nix develop -c cmake --preset gpu-test
nix develop -c cmake --build --preset gpu-test --target <test-target>
nix develop -c ctest --preset gpu-full -R '^<test-name>$' --output-on-failure

The same CMake/CTest commands work outside Nix. cmake --build --preset pr runs the focused contract subset after configuring cpu-test; nix flake check runs the canonical CPU/repository gate. Full CPU checks, sanitisers, GPU/operator/model checks and H3 quality tools remain available locally; see docs/internal/testing.md. Do not run full model sweeps, video generation or duplicate suites for routine edits. A missing-model skip is not a quality pass. Broaden checks when shared behavior changes or failures expose risk.

Text API functional/regression tests live in tests/functional/. Select suites explicitly. Model-specific changes need the affected model/modes; use all four profiles only for shared behavior changes. Run correctness on the candidate; use main for matched affected timing controls and suspected regressions, not a duplicate full correctness run. Reuse baseline evidence only when revision, toolchain, harness, model, settings and cache history match. Include long-context and cache for continuation changes; verify loaded mode and actual drafts. Correctness and expected prefill/cache work are strict; timings are mandatory per request/phase at 5% and 10 ms, never averaged across requests. Run once, investigate flags, then alternate main/PR only for affected histories; use unchanged-main controls when needed and retain every result. Fix confirmed regressions before publishing. Noisy evidence stays visibly inconclusive and unqualified; do not widen margins or stop at reporting failures. Devlab keeps inconclusive timing advisory on both ordinary and release PRs. Use the code diff to select affected metrics; unrelated timing variance does not justify another full matrix. For reported coding-agent loops, also replay the affected workflow with tests/functional/pi_agent.py; retain its sessions and inspect actual tool results. Retain numerical quality tests and the standard speed benchmark. Keep these tests in tests/functional/, outside hosted model CI; avoid full sweeps.

Profiling and kernels

Apply .agents/skills/optimize-kernel/SKILL.md. Use tools/bench/build.sh for standalone HIP experiments, tools/bench/gfx1151_peak.hip for measured hardware ceilings, tools/prof/prof.py for pipeline/wall-time profiles, and tools/prof/isa_mix.py for instruction analysis. Production paths must retain quality; successful optimizations become the default, without extra switches.

Development

  • Keep model code, tests, tools and numerical contracts with their model.
  • Follow docs/AGENTS.md when writing or changing documentation.
  • Use the shared Qwen control-token constants for framing; see src/families/qwen/AGENTS.md. Inspect their definitions when reviewing or changing behavior, and keep reference fixtures independent.
  • Put Windows-specific code in src/core/platform/: one leaf per OS facility (files, pages, sockets), whose sources may branch on _WIN32 or split into <leaf>_posix.cpp/<leaf>_windows.cpp selected in CMake. Outside it and vendored code, call the leaf, with no windows.h or _WIN32/_MSC_VER checks. POSIX code moves into a leaf, verbatim, once it gains a Windows counterpart. Never emulate POSIX with macros or copy a file per OS; when the logic itself differs, add <file>_windows.cpp beside it.
  • Use one canonical long option and backend name per behavior; avoid aliases.
  • Use gh for GitHub operations after checking gh auth status.
  • Follow Conventional Commits with a single-line message. Title pull requests according to the release policy; squash merging retains that title on main. Mark breaking changes with ! in the title, and leave version and changelog updates to the release workflow.
  • Prefer jj when available (jj version); otherwise use Git.
  • The source extension API is versioned independently from Gufo. Public headers under include/gufo/ext/, their transitive SURFACE closure (including forwarded core/cache headers), the metadata schema and public CMake contracts require an ext-api PR label and one new, uniquely named Markdown record under include/gufo/ext/changes/<major>.<minor>/ when declarations/contracts change. Records are permanent and immutable. CMake derives the API revision from the active series in include/gufo/ext/api-series.json plus its revision-record count. The baseline.md record documents the initial contracts without advancing it. Do not manually bump versions for additive changes. Run python3 tools/ci/check-extension-api.py --write after header/include changes; the PR diff gate also checks forwarded declarations. Before 1.0, a minor bump may break extensions; revision bumps are additive. Fix in-tree users together. The guarantee is source compatibility after rebuilding, never binary ABI. Breaking changes explicitly advance the compatibility series in api-series.json and add a record in the new series, retaining all historical records. Extension API and the future experimental flake extensions argument are excluded from Gufo's release compatibility surface; CLI/HTTP/public existing flake breaks still require !. See the release policy.
  • Follow the user's remote workflow and preserve unrelated work.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.