AI agents

[Rob Beezer]

New thread. I have merged the addition of several AGENTS.md files into the
main PreTeXt repository, to help developers help AI agents to keep up with our
practices and quirks.

Rick Roesler started this off with a comprehensive PR (thanks, Rick!), several
developers made suggestions, and I incorporated a few leftovers that I had
Claude pick up from similar files I have been growing (grown at the cost of a
lot of anguish). ;-)

The eight or so new AGENTS.md files are in markdown syntax, so you can read them
(or view them rendered). I wouldn't really recommend a thorough reading, but
you might find it interesting to have a peek and do a bit of skimming.

If you have already been yelling at your AI agent to get things right and
"strengthen your memory on X", you may need/want to move any items that have
been replaced. I have some of that to do.

I expect these to evolve and improve. There is probably also still a lot of
cruft prohibiting dumb stuff older models did (I just removed a ban on the word
"fixture"). So PRs are welcome if you find AI doing things we wish it wouldn't
do. I plan to have Claude keep an independent to-do list, and then I will
address that list all at once at some convenient time.

Please report any trials or necessary chages in getting this working with your
preferred model. And report anything that feels like smoother sailing or a good
first-time experience. I have little experince with this yet, but I hope Rick R
will be able to provide counsel.

Rob

[Rob Beezer]

And just now, a few updates (minor things I thought had already gone in).

And I meant to say before. Should you like to craft a PR *without* help from
AI, you probably could still use these files to have AI do a first-pass review
on your PR before you put it up on GitHub. That might save you and me one round
of back-and-forth.

[Oscar Levin]

I'm running into two issues for my development.  

1. The instructions assume development is happening on Liniux/Mac.  Commands like `python3 ...` will not work; the prerequisites suggest installing xsltproc and jing, but I'm fairly sure the instructions don't include windows versions.  Maybe Claude is smart enough to know this.  My Claude suggested that I should add a ~/.clsude/CLAUDE.md file with windows specific instructions, which I certainly can do.  I wonder if we should think about a way of sharing that information somewhere.

2. The instructions now say that all development needs to be done using pretext/pretext, not the CLI.  That's probably good advice for anyone working on just core pretext, but I need to develop both core and the CLI at the same time often, so the CLI has documented developer setups so the CLI really can use the current files in core.  I plan to add an agents file to the CLI, which might be enough to prevent Claude from getting confused, but it does mean that I need to remember to always start my claude instance in the CLI folder.

I think these fixes seem correct, but if you have any advice or other ideas how to handle this, please let me know.

[Rob Beezer]

We should definitely support development on Windows. You could experiment with additions as suggested, and then move them into the current setup as a PR.

I tried to de-emphasize xsltproc, it is still in the Guide too many places. Maybe only needed to do the literate program for the schema. Jing can be done via a server.

It took me a very long time to get Claude to stop trying to run CLI commands, so you are seeing an (over)reaction to that. It just would never stick. Anybody else feel silly swearing in all-caps at their AI? Could you try a modification that will do what you need to do without reducing me to swearing again?

Thanks for taking this for a drive, there is a lot to learn.

Ron