Our experiments show that AI agents working on this driver benefit from having access to a Markdown version of the virtio specification, broken down into subsections.
Our experiments also show that the prompt below consistently works with fronteer models. The prompt assumes that Python and Pandoc are installed on the local machine.
## Goal
Obtain a copy of the virtio specification optimized for consumption by AI
agents.
## Source
The latest virtio specification is at
https://docs.oasis-open.org/virtio/virtio/v1.4/virtio-v1.4.html
## Process
Follow the steps below to obtain a cleaned up specification.
1. Create a `local/virtio-spec/` directory, if it does not already exist.
2. Download the source specification to the `local/virtio-spec/` directory, as
`all.html`.
3. Use the `pandoc` invocation pattern below to convert the specification to
Markdown, and save it as `local/virtio-spec/all.md`.
```bash
pandoc --from=html --to=markdown-smart --wrap=auto --markdown-headings=atx \
--columns=80 all.html -o all.md
```
4. Read the specification's table of contents, which is roughly at the beginning
of the file.
5. Write a shell command or Python script that extracts the table of contents to
`local/virtio-spec/toc.md`.
* Validation: Run the script and read the output file.
* Iteration: If necessary, fix the script and iterate.
6. Write a shell command or Python script that extracts each top-level section
to `local/virtio-spec/section{section_number_or_letter}.md`.
* Example: section 3 goes to `local/virtio-spec/section3.md`.
* Validation: run the script and read the first, second, next-to-last and
last output file.
* Iteration: If necessary, fix the script and iterate.
7. Write a shell command or Python script that extracts each transport subsection
to `local/virtio-spec/transport-{transport_type}-section{section_and_subsection}.md`.
* Examples: `local/virtio-spec/transport-pci-section4_1.md`,
`local/virtio-spec/transport-mmio-section4_2.md`.
* Validation: run the script and read the first, second, next-to-last and
last output file.
* Iteration: If necessary, fix the script and iterate.
8. Write a shell command or Python script that extracts each device subsection
to `local/virtio-spec/{device_type}-section{section_and_subsection}.md`.
* Examples: `local/virtio-spec/net-section5_1.md`,
`local/virtio-spec/block-section5_2.md`.
* Validation: run the script and read the first, second, next-to-last and
last output file.
* Iteration: If necessary, fix the script and iterate.
9. Write a summary of the directory's contents in
`local/virtio-spec/overview.md`. Your primary audience is AI agents.