[SreecharanGundaboluAMD]

Motivation

MIOpen is the only major component in the super-repo without agent guidance. The root AGENTS.md lists entry points for hipBLASLt, TensileLite, hipDNN, the MIOpen provider, rocKE, rocRoller, StinkyTofu and rocBLAS, but has no row for projects/miopen/. Agents and new contributors have no single place that describes the architecture, build/test workflow, or the integration points that fail silently when missed:

• Adding a convolution solver: registration in src/solver.cpp, SolverContainer membership in src/mlo_dir_conv.cpp, and the Fin AnySolver case in src/fin/fin_interface.cpp.
• Persistent solver IDs: never renumber; use ++id when removing a solver.
• Public ABI: the five artifacts kept in sync by script/check_public_abi.py.
• gtest: MIOPEN_TEST_DISCRETE and GTEST_PARALLEL_LEVEL interaction that breaks combined-mode CTest shards.

JIRA ID : ALMIOPEN-3140

Technical Details

Docs-only change, two files:

• projects/miopen/AGENTS.md (new, 193 lines): project overview, architecture and data flow (including the optional hipDNN wrapper), key directories, development commands (rocm/miopen-dev image, standalone and super-repo preset builds), code conventions, a seven-step solver-addition checklist, important files, runtime/tooling preferences, testing/QA (naming, tiers, ABI/script checks), and a "Maintaining This File" section.
• AGENTS.md (root): adds a MIOpen row to the "Component entry points" table.

Design choices:

• The file defers to named source-of-truth files (CMake files, scripts, YAML) when they disagree, so the guidance does not become a second copy of build or test configuration.
• "Maintaining This File" tells agents to update the file in the same PR as the change it documents, verify claims before writing, link to sources of truth instead of copying values, and not edit it during unrelated work without asking the user.
• No CLAUDE.md symlink. Claude Code reads AGENTS.md directly from v2.1.277 (docs), and in its default mode a CLAUDE.md in the working directory makes it skip every AGENTS.md. A symlink here would hide the root AGENTS.md from sessions started under projects/miopen/. A symlink was briefly added and then removed in this PR; the net diff has none.
• Statements were corrected after validation in a follow-up commit (docs(miopen): correct AGENTS.md claims after validation and document dev image).
• Layout follows the other component entry points. The file supplements the root AGENTS.md and does not restate it.

Risk Assessment

Risk Level: 🟢 Low

Documentation only. 194 added lines across two Markdown files. No code, build, CI, or test files are touched.

Impacted Components

• projects/miopen/AGENTS.md (new)
• AGENTS.md (one table row)

Potential Side Effects

• AI coding agents working under projects/miopen/ will now load this file as context, so any inaccurate statement can steer them wrongly.
• No effect on build, tests, or runtime behavior.

Mitigation Steps

• The documented commands were run on gfx942 in rocm/miopen-dev (see Test Result), and the claims that did not hold were fixed (second commit).
• The file names a source of truth for each area and states that it wins on conflict.
• The maintenance section asks for updates in the same PR as the code change; CODEOWNERS already routes the file to @ROCm/miopen-reviewers.
• Revert is a plain file removal plus the one table row.

Test Plan

No code is changed, so there are no unit tests. Verification:

1. Run the repo hooks on the changed files.
2. Run the documented commands in rocm/miopen-dev:latest (ROCm 10.3, CMake 3.28.3) on a gfx942 GPU, with isolated MIOPEN_USER_DB_PATH and MIOPEN_CUSTOM_CACHE_DIR.
3. Check the remaining claims against the source, with file:line evidence.

pre-commit run --files AGENTS.md projects/miopen/AGENTS.md

Test Result

• pre-commit: passes. Trim Trailing Whitespace, Fix End of Files and Check for added large files pass; all other hooks are skipped because no files match them.
• Build:
  • The documented standalone configure works as written, and all seven named targets exist.
  • cmake --preset miopen configures.
  • MIOpenDriver and miopen_gtest build.
  • CMake 3.24 fails the standalone path and 3.25.2 passes.
• Tests:
  • miopen_gtest --gtest_filter='CPU_PerfConfigGroupWrwDeterministic_NONE.*' passes.
  • The MIOpenDriver conv example reports "Verifies OK on GPU reference".
  • Tier selections list the expected suites: -L '^quick$' gives 6, adding -LE ex_gpu gives 1, and adding -L '^ex_gpu_gfx94X$' gives 1.
  • With -DGTEST_PARALLEL_LEVEL=4 the four shards register correctly, and one shard ran 63 tests that passed, with 1 skipped.
  • --no-tests=error exits 8 on an empty selection, where plain CTest exits 0.
• ABI:
  • check_public_abi.py check-headers --require-provider passes.
  • check_public_abi.py check against an existing wrapper-OFF libMIOpen.so (built from an older commit) passes.
  • pytest script/test_check_public_abi.py passes (89 tests), and the unittest command passes (88 tests).
  • A wrapper-ON configure registers wrapper_abi_check, forwarding_failure_modes, test_forwarding_parity_scripts and the forwarding_parity label.

Not run: full test tiers (listed only), the wrapper-ON test executions (they need a wrapper-ON library build), the check_format/miopen-tidy builds, cmake --install, and the discrete test_unit_conv_solver_ConvDirectNaiveConvFwd binary (the same filter passed in miopen_gtest).

[therock-pr-bot]

✅ All Checks Passed — Ready for Review

Check	Status	Details
📝 PR Description	✅ Pass	—
⛔ Forbidden Files	✅ Pass	—
🧪 Unit Test	✅ Pass	PR does not contain code files — Unit Test auto-passed
🔎 pre-commit	✅ Pass	—
🚫 Draft PR	🔜 To Be Enabled	—
🚩 Feature Flag	🔜 To Be Enabled	—
📊 Code Coverage	🔜 To Be Enabled	—
🤖 therock-pr-bot	✅ Pass	—

🎉 All checks passed! This PR is ready for review.

📖 Need help? See the Policy FAQ for details on every check and how to fix failures.

🙋 Wish to Override Policy?

[therock-pr-bot]

🎉 All checks passed! This PR is ready for review.

[JonathanLichtnerAMD]

Reviewed against the PR-head source (docs-only, so static checks, no hardware run). The file is largely accurate: solver registration steps, ABI artifacts, routing, DB semantics, tier labels, and CI links check out. One factual error (the src/fin/ row), one missing CI-relevant note (tier time budgets), plus minor wording and pointer fixes. Two suggested fixes are included, both untested. No blockers.

Co-authored by Claude (AI).

[assistant-librarian]

TheRock Submodule Bump Activity

Newest first

• 2026-11-06 — Included in TheRock via ROCm/TheRock#9759.