Adopt documentation-first approach for AI context

[iholder101]

What this PR does / why we need it:
Replaces the AGENTS.md/vendor-specific prompt file approach with an agent-agnostic, documentation-first strategy for providing context to AI tools.

Repositories are encouraged to maintain a documentation index file linking existing docs by topic [1], keeping project knowledge in standard markdown that serves both humans and AI tools equally. A clear separation between agent-agnostic documentation and vendor-specific tool configuration is established, and local development tool choice is left to individual contributors.

[1] This pattern is adopted by other projects (e.g., Anthropic's docs map).

Release note:

NONE

[kubevirt-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign stu-gott for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[iholder101]

/cc @EdDev @vladikr @lyarwood

[EdDev]

Thank you for this direction, replacing the AGENT.md reference with a documentation-first approach is a cleaner long-term strategy.

One structural point worth discussing: the new "Providing Context to AI Tools" section feels like it belongs in a dedicated file rather than inline here.

The existing ai-contribution-policy.md is consistently contributor-facing: it tells people what to disclose, what they're responsible for, and how reviewers should evaluate AI-assisted work. Every section addresses the same actor: a contributor submitting a PR.

The new section addresses a different actor and a different moment in time: it's repository-maintainer guidance for how to set up a repo to work well with AI tools. That's a meaningful shift in audience and scope.

There's also a practical concern: the section names concrete artifacts, i.e. AGENTS.md, .coderabbit.yaml, documentation index files. These conventions are still evolving and will need updates as tooling changes. Embedding them in a policy document means the policy gets touched for what are really tooling-hygiene updates, which is friction and noise. A dedicated ai-tooling-guidelines.md can evolve at its own cadence.

The PR already does the right structural thing on the contributor-policy side, the cross-reference (see Providing Context to AI Tools) in the
Disclosure section. It just needs to point outward to a separate file rather than downward within the same document.

How about this:

1. Move the new section into a new dedicated file (e.g., ai-tooling-guidelines.md)
2. Update the cross-reference in the Disclosure section to point to that file.

This keeps the policy document focused on its original purpose, and gives the tooling guidance room to grow without polluting the policy's change history.

[aburdenthehand]

@iholder101 Thanks for submitting this. This was new for me and I think I would need to explore it more in order to provide better feedback, but I did have a couple of questions after reading through it.

Edit: I think I agree with @EdDev about separation of concerns however I think this is also important for the contributor using AI to understand as well. It needs to be easily discoverable, which I think is what the AGENTS.md convention was aimed at iiuc.

[aburdenthehand]

Do we have the officially adopted tools listed somewhere we can link to?

[iholder101]

It is being discussed as part of kubevirt/enhancements#297, where it's planned to replace SourceryAI by CodeRabbit. I don't think there's any other list

[aburdenthehand]

Are we expecting consistency with the file names and locations across the repos? If so, we should be explicit about that.

[iholder101]

According to #444 (comment) I don't think that's necessary.

In addition, this document is more of a general statement of how we should pursue making KubeVirt better for AI agents (and humans as well). I wonder if this should be followed up with a tracker issue / VEP / something else to actually track and plan the progress of this effort.

[aburdenthehand]

In the old days I would view this as a major maintenance concern. Am I right in guessing that the plan is to use an LLM to generate this map based on a comprehensive docs scan? What does maintaining it look like?

[iholder101]

I imagine something much simpler. We can decide that documentation files should container a "frontmatter" metadata section with a short description/summary of the content (about a paragraph long).

Let's say that we have theoretical a file under ./docs/developer-guidelines/coding-style-and-conventions.md. It would look like:

---
description: "This file defines the Go conventions
and coding style that should be used by KubeVirt developers."
---

<Actual full content>

Then, a simple script could update the documentation map, which can look something like:

## docs

### developer-guidelines

This file defines the Go conventions
and coding style that should be used by KubeVirt developers.
./docs/developer-guidelines/coding-style-and-conventions.md

This is another file with a different
summary that captures its contents
./docs/developer-guidelines/another-file.md

(this is of course just an example, we can discuss the exact format).

So the file path should be used to define the doc's position in the subject tree, which paths should already reflect anyways. And the frontmatter metadata can be used in order to provide the short summary. While the doc writer can obviously use LLMs to help generate the summary, eventually the responsibility of creating it is (like anything else) on the PR owner and reviewers. We should probably eventually also enforce this with an automation.

Does this make sense? WDYT?

[kubevirt-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign stu-gott for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[EdDev]

Thank you!

[kubevirt-bot]

Pull requests that are marked with lgtm should receive a review
from an approver within 1 week.

After that period the bot marks them with the label needs-approver-review.

/label needs-approver-review