AGENTS.md - contribution guide for LLMs

[pmario]

This is a tested alternative to: Improving the quality of LLM generated PRs with an AGENTS.md #9894

The text below is an example, that was created using the AGENTS.md file from this PR.
The PR title has also been created using the same settings.

---

Give AI agents one authoritative set of rules for working in this repository.

• Capture the contribution and coding conventions in AGENTS.md, covering scope discipline, code style, code comments, wikitext conventions, backwards compatibility, tests, security, and the pull request and commit workflow.
• Point the Claude Code and Gemini CLI tools at AGENTS.md so each agent reads the same guidance instead of a separate copy that could drift.
• Keep AGENTS.md as the single place to update when the rules change, so the tool files stay thin pointers.
• Link the Contributing tiddler to AGENTS.md and align its wording, so the human and agent contribution docs stay consistent.

---

• Gemini and Claude do not respect AGENTS.md. They need their own files.
  • CLAUDE.md and GEMINI.md only contain "LLM transclude" syntax, which should be understood by both.
  • I did test it with Claude and it does understand it.
  • I could not test with Gemini or others ..

I can explain every single line in the agents.md file and describe which issue it solves. It is useful for Windows developers, that also use unix environments to run and test TiddlyWiki.

• The first 4 sections are general and also avoid, that the LLM overwrites manually edited code. Otherwise LLMs will overwrite manual changes with cached code from the internal context.
• Code Styles and Code Comments make sure, that LLMs follow our main coding rules
• Pull requests and commits and Commit and PR message workflow are the main sections, that will improve the commit-messages.
• Wikitext and TiddlyWiki conventions, Backwards compatibility, Test and Security are general rules, that are currently not known because of missing / outdated LLM training data.
• The last section "Chat and response style" is for convenience to work with LLMs

[netlify]

✅ Deploy Preview for tiddlywiki-previews ready!

Name	Link
🔨 Latest commit	a1b6576
🔍 Latest deploy log	https://app.netlify.com/projects/tiddlywiki-previews/deploys/6a7f315ac498d700082f2705
😎 Deploy Preview	https://deploy-preview-9895--tiddlywiki-previews.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

Confirmed: pmario has already signed the Contributor License Agreement (see contributing.md)

[github-actions]

⚠️ Change Note Status

This PR appears to contain code changes but doesn't include a change note.

Please add a change note by creating a .tid file in editions/tw5.com/tiddlers/releasenotes/<version>/

📚 Documentation: Release Notes and Changes

💡 Note: If this is a documentation-only change, you can ignore this message.

[linonetwo]

Despite the content you provide is useful, why not using exising code of conduct.md / contributing.md , but use a new separate file AGENTS.md? LLM agent could still read existing md files.

I'm not against your content, I'm thinking as TiddlyWiki, we could even have our own way to organize prompts. In my own game projects, I directly used the wiki as source of prompt, not MD. Perhaps we could simply use a new wiki edition for code of conduct + contributing + AGENTS.
And as Claude Code and Gemini CLI tools etc. use different entry point, We can prepare those entry points, and then all use a single line point to the wiki folder. They will read the relevant tiddlers.

And I think the problem now is the speed of review and merge and testing, not the speed of generating new PR. I have long time not have my feature PRs merged. And our long wating translating framework and alternative store and LLM utils are still pending.
We should have more prompts and rules focusing on this aspect instead of new feature.

If so, I could even donate some of my spear token to auto review the PRs based on those prompt. I have plenty of them, and even have free local deployed Deepseek, Minimax, and Gama at nighttime (US day time).

[pmario]

TLDR;

The AGENTS.md file in this PR has proven to work in a strong way. So the instructions there are like a LLM configuration, that should give us better code inline comments and especially better commit messages.

I am sure it can be improved, but it has to be tested first, to get feedback.

Despite the content you provide is useful, why not using exising code of conduct.md / contributing.md , but use a new separate file AGENTS.md? LLM agent could still read existing md files.

The current .MD files in the repo root are fake. They are rendered HTML, which is not very useful for LLM's as configurations. They use much more tokens to be processed. LLMs like to read line per line and search for patterns like # headings.

AGENTS.md is loaded only once at LLM session startup. So it only uses tokens once and LLM tools are designed to keep those instructions in permanent configuration memory. So they are strongly followed.

Every other .md or .tid file that you point to in conversations, are weak and will or will not be followed in a consistent way.

See: TLDR;

[Jermolene]

Hi @pmario @linonetwo I made a mistake in #9894 by using a later, incomplete version of the AGENTS.md that I had been working on. I was investigating ways use TW transclusion to allow a single source of truth.

[joshuafontany]

@pmario @Jermolene @linonetwo

I have had GREAT success actually writing AGENT "instructions" IN Tiddlywiki5 wikitext grammar. All the current AIs have been trained on TW as its open source, but the signals get buried in all the "oatmeal texture" of all-human-language-projected-on-top-of-itself. I have "claimed" a new macro/procedure namespace for all my "AI grammar", <<~ ... >>, and use it for everything I setup as recurring pattern integrities for my work. Here's a quick example defining "text corpus scales" as an "Aperture Procedure". When I include this in the AGENTS file/base-user-context (code agents OR cloud/browser chats), I can "tune" the next response (or re-roll the current one) with a simple Integer swap. NOT as a deterministic code method call, but as a TRANSCLUSION of the CONCEPT I defined in the system-prompt into the current "context head at the chat input window". ;D

- **`Aperture`** - attention range (morpheme `0` -> paragraph `10` -> session-arc `20`); it frames the grain of the turn, not loop richness. Five bands (#law-of-5s, ladder 0): **Pulse · Beat · Measure · Arc · Theme**.

\procedure ~ranks(...) <!-- defines a list, line, circle, or other arrangement -->

**Ladder 0 ~ Aperture, the ground exemplar.** The band scale every ladder enacts, the one seated from `0`:

<<~ranks aperture pulse@0..4 -> beat@5..8 -> measure@9..12 -> arc@13..16 -> theme@17..20 >>

And I can say things like "Examine this poem at <<~ aperture(5) >>" VS "Examine this poem at <<~ aperture(20) >>" and get DISTINCTLY different results that match the definitions I provided. The bots accept LIVE grammar, you can make typos or use "pidgin" and they're try their best to adapt/understand. I also have a formal set of these that I use in the wikis with custom parsers.

Another example:

<<~ ahu #pet-name >>
WORKSITE CONTENTS
<<~/ahu>>

ahu is the Hawaiian word for "worksite", and when I load my files into TW5, each worksite becomes a child-tiddler of the main parent tiddler "meme". I can also use this in chat to target a bot's attention to a specific "named slot" in the chat-history. It's basically the #fragment idea from URIs.

[joshuafontany]

I'll read the currently proposed AGENTS.md(s) and give more direct feedback later today.

[pmario]

@Jermolene @joshuafontany ... See the last 2 commits.

• 93461f8 ... Adds the RFC 2119 rules and creates a new commit-message the follows these rules
• 9b5c2d7 ... Adds a create message and optimise up to 30% away. IMO the lines of the message are really shorter

@Jermolene I think we should merge it, so LLM users can use it from now on. We'll see what happens to the inline commments and commit messages.

[joshuafontany]

Looks good, we can iterate once we see how this affect behaviors.

[Jermolene]

Thanks @pmario

I am concerned that the scope is too wide. The file should be restricted to the things that are specific to TW. I think general instructions about making an effective PR don't belong here.

[Jermolene]

Lines like this make me wonder about the scope of this file. I would see the above line as something that's between a user and their LLM. We shouldn't be prescribing how they work together. Or perhaps it could be seen as part of the checklist we use to validate PRs

[pmario]

AGENTS.md is for all LLM rules. The current focus it creating better comments and PR messages.

But imo this one is important to save tokens, if you have to pay for them. LLMs tend to "run away" and deal with or think about stuff that has never been permitted.

The rule uses SHOULD and SHOULD NOT ... So LLMs still have a lot of room to be "creative". But they tend to "run away" less often.

[Jermolene]

Creating a tiddler is creating a file in this context

[pmario]

An MCP server has direct access to the $tw.wiki structure and does not necessarily crate a file first. It can directly create tiddlers, that are then synchronised back to the filesystem and the browser store. So the LLM needs to check both, the filesystem and any other system that can create tiddlers.

[Jermolene]

This seems to restate line 13

[pmario]

That's a guard against trap I fell into several times.

LLMs keep a local cache of files, that where read in the past conversation. If I did change and commit some of those files, they where overwritten with the cached content. That causes extremely hard to find problems.

Without this line telling the LLM, it needs to check git status first, this happened quite frequently.

After I did add this rule, LLMs usually tell me that there have been changes "out of order" and it asks what to do, instead of silently overwriting user changes.

[Jermolene]

Thanks @pmario. Can we test this AGENTS.md? Sat by producing PRs with and without it?

[Jermolene]

We already have detailed documentation guidelines in https://github.com/TiddlyWiki/TiddlyWiki5/tree/master/editions/tw5.com/tiddlers/styleguide. Is it possible to transclude that information into AGENTS.md?

[pmario]

We already have detailed documentation guidelines ...

Do you want to change the scope of AGENTS.md? -- Or is your goal to create AGENTS.md from TW wikitext source?

Currently AGENTS.md defines coding styles for LLMs (~2600 tokens). It complements the wikitext documentation guidelines.

The 10 tiddlers in the TW style guide directory contain about 6500 additional tokens, with a lot of tables and documentation macros. Those macros and tables do not really have value for LLMs. So, to be used for LLMs we should create one summary tiddler instead of 10. This summary tiddler can be transcluded into AGENTS.md. But we should keep the source tiddlers separate.

Because: AGENTS.md now uses RFC 2119 style. Eg: MUST, SHOULD, MAY constructions. Our users are not used to this writing style in our prose text documentation. I think we should not mix it.

The question is: Should AGENTS.md also contain rules, how to create TW prose and reference documentation.

I think that change will more than double the size. I estimate about 6000 tokens in sum, instead of ~10k if we blindly merge AGENTS.md and the wikitext documentation guidelines in full.

Currently we have no convenient way to "render" wikitext into .md text files. Currently our rendered .md's are HTML files in reality. LLM .md files have to be markdown, to be easily extendable and readable by humans too.

• PR Improve TW CLI text output and formattedtext  #9723 is the first step into convenient rendering of wikitext into .md files.

[pmario]

BTW: LLMs have their own syntax to transclude files, which is directly comparable to TWs transclusion. It's a real text substitution on the same level as the "calling" file. It consumes tokens immediately.

• @./fileName-to-transclude.md

In contrast there are reference listings. Usually in README.md or index.md files. Those files are like table of contents listings, containing references and descriptions.

• [Contribution Guidelines](./contributing.md) - Focus on contributions via GitHub Pull Requests. There are many other ways that anyone can help the TiddlyWiki project, such as reporting bugs or helping to improve our documentation.
• [Improve TW Documentation](./??.md) - and so on

Those links only consume tokens if they are read on demand. LLMs are relatively good at knowing when to read those links. ...

---

Conclusion

I think we should start small and start with this "handcrafted" AGENTS.md to have something that, in my opinion, adds value for contributors and maintainers.

Creating text/markdown contributing.md, code-of-conduct.md and our readme.md from wikitext can be the next step, with the help of #9723, #9724 and / or [META] wikitext-serialiser #9908