Agent docs

[vloncar]

✨ oooh a shiny new template ✨

Description

AGENTS.md (added in #1514) tells an AI agent how to behave in this repository. It does not tell it how hls4ml works. An agent therefore learns the codebase by exploring it, and gets it wrong in the same few ways every time: assuming one backend's conventions hold for all of them, generalizing from Dense to layer families that share none of its structure, and quoting C synthesis estimates as if they were measured results.

This PR adds that knowledge as plain Markdown under .agents/, with AGENTS.md routing to it. Twelve documents: how a model is converted and run, a map of the pipeline, the frontends, the optimizer passes, the C++ kernels, precision and debugging, evaluating an implementation, standing up a backend, toolchain access, contributing a change, reporting an issue, and a template for site-specific setup.

Three things shaped how they are written:

• They say what is a contract and what is one backend's convention. The strategy field, the kernel typedef and the nnet_utils layout exist in the Vivado family; Quartus and oneAPI have neither, oneAPI uses pipes and its own template classes, and the symbolic backend has no kernels at all. Documentation that presents the Vivado shape as "how hls4ml works" is what sends a contributor down the wrong path.
• They contain no site-specific content. No paths, tool versions or environment assumptions. local-setup.template.md is a skeleton each group fills in for itself. If people are interested, I can provide my cvmfs-based setup that would work well for CERN people (onsite or users through lxplus/lxtunnel)
• They are assistant-neutral. Contributors use Claude Code, Codex, Copilot, Cursor and others. The documents carry front matter that is a superset of what those tools want, and .agents/agent_adapters.py renders them into each layout on demand. Generated output is git-ignored, so .agents/ stays the only copy anyone edits. Pointing an assistant straight at .agents/ also works.

Documentation about mechanisms rots faster than the code it describes, so test/pytest/test_agent_docs.py checks that every repository path these documents mention still exists, that the front matter parses, and that the links between them resolve. A renamed module fails the suite.

Relates to #1514

Type of change

• Documentation
• Build, CI or tooling

Affected areas

Backends:

• Backend-independent (core IR, optimizer, hls4ml.model)

Frontends:

• Not related to a frontend

Components:

• Packaging, build or CI

Configurations affected and exercised

Not applicable — this PR adds documentation, a helper script and a test. No conversion path is touched.

Impact on generated HLS

• This PR does not change the generated HLS for existing models.

Tests

test/pytest/test_agent_docs.py — 38 checks over the twelve documents:

• every repository path mentioned still exists, resolved against the package directory, the repository root or a path suffix, with generated-project files excluded;
• the front matter parses and carries the fields the adapter script needs;
• relative links between documents resolve.

pytest test/pytest/test_agent_docs.py

Runs in under a second and needs no toolchain. I also verified it is not vacuous: it accepts current paths and rejects renamed ones.

Test configuration: Linux, Python 3.11, pytest 9.1.1. No HLS tool involved.

AI assistance disclosure

• None — no AI tool was used.
• Assisted — completion, refactoring, docstrings, tests; design and code are mine.
• Substantial — significant AI-generated portions, reviewed and edited by me.
• Agentic — produced largely end-to-end by an AI agent from my prompts.

Tool(s) and model(s): Claude Code (Claude Opus 5)

Where it was used: Everywhere. The documents are largely from my extensive prompts with bullet points i felt are important to be included. The adapter script and the test were fully generated by the agent. All of it was reviewed and revised by me over several rounds.

If anything other than None is ticked, confirm all of the following:

• I am the author of this contribution and take full responsibility for it. I have read and understood every line and can explain and defend it in review.
• I verified the generated code against real hls4ml and HLS semantics — no invented APIs, config keys, pragmas or citations.
• All numbers, logs and test results quoted in this PR come from runs I actually performed, not from agent output.
• I have the right to submit this work under the project's licence, and to my knowledge it does not reproduce third-party code that would conflict with it.
• No AI tool is credited as an author in any commit in this branch.

Checklist

Required:

• I have read the contributing guidelines.
• I installed and ran pre-commit on the files I edited.
• I added tests under test/pytest covering this change (a bug fix should add a test that fails on main and passes here).
• I self-reviewed the full diff and it contains no leftover debug code, commented-out blocks or unrelated changes.
• The AI assistance disclosure above is complete and accurate.

If applicable:

• Documentation under docs/ updated.

Release note

Skills for agentic development (Claude, Cursor, ...)

[JanFSchulte]

Looks good and very complete to me. The agent docs should probably be required reading for all humans wanting to contribute as well, very nice :-D.