AGENTS.md for moqui for agentic coding

Technical Discussion
1

Hello Folks,

I created a simple AGENTS.md to use with moqui. It was very effective in developing services on-the-loop hands off. It was my first successful attempt in really getting away from the computer and letting the agent work for a while and produce something useful.

I would like to create a PR for this, but before I do, sharing this here for others to review. I think the feedback loop mechanism around service testing was very useful. I need more feedback loops for UI, and I also need to work on automated tests. But I think it’s a good first step and if we commit into the code base we gain value as we work on it together.

The file is also extensible, as it has a section telling it to use component-specific AGENTS.md to expand capability.

The file can be found here AGENTS.md

2

Very nice. I’d recommend packaging some of the restart logic in a script and just tell AGENTS.md to run the script. I have a script that kills the server, erases the h2 and opensearch files, loads the database and then runs the server with the output going to the log file. I found this was more reliable. Since AGENTS.md basically gets loaded all the time it is worth making it more compact. Something I’ve been playing with on the moqui-mcp side is an Opencode agent to do screen access. This insulates the top level coding conversation from all the crufty data of the screens. The top level can just ask the agent “how much is such and such product” or “change all the prices of these products according to these rules and tell me which product IDs you change” and the top level just gets back a price or a list of product IDs even though the screen operator agent saw thousands of tokens of screen data.

3

It looks like great work, @taher . The obvious question is how are we going to resolve all the competing md files (I don’t have one)? The ones from @jenshp and @nirendra look complete, as well. And @jmochel is working on one. We could ask AI to try to combine and clean up a common version, but would we all accept it or work to make it acceptable? moqui-agent-os contains an “overlay-” convention that allow private customization, so we certainly need something like that.

I think moqui-agent-os README.md talks about spec driven code generation, but doesn’t specify anything that I know of. IMHO, that is what we should be working towards.

I like the idea of using Agent OS (moqui-agent-os) because it would allow an agnostic approach to agentic IDEs - Claude, Antigravity, etc. Someone pointed out that Agent OS is not a common tool, but I look at it sort of like the Data Model Handbook - Agent OS is mostly just a common RAG data directory structure. We will need one, might as well be Agent OS. If not Agent OS, then what? It’s the working RAG that we should be primarily concerned about - I don’t think its structure will be that important as long as we all agree on it.

I think we need a common approach to closing the loop in UI development and testing. That’s where things get tricky because browser access seems to be mostly proprietary. It could be WebMCP.dev, but I don’t know enough to say. Gemini says that you need its proprietary browser_subagent to test UI and then create scripts that Playwright can test, and it has never failed to recognize my genius, so I am tempted to believe it, but it could be that WebMCP could play that common role.

I use Antigravity, but my simple inquiry says that Claude CLI and it IDE require a subscription to its model. Is that true? If so, then I think we should avoid getting tied to a vendor for the IDE and model.

4

Great work, @taher.

@byersa raises the key question: how do we reconcile the competing approaches? Between @taher’s AGENTS.md, @jenshp’s moqui-agent-os setup, my PR #701 (AGENTS.md + CLAUDE.md in moqui-framework), the moqui-ai-skill component, and @arun.patidar’s moqui-ai-agent-skills, there’s clearly strong convergence on the idea but fragmentation in implementation.

From my experience building this out, I think the answer is a layered architecture:

  1. Framework-level (thin entry point): A minimal AGENTS.md / CLAUDE.md in moqui-framework itself. This should be compact (addressing @schue’s valid point about prompt bloat), just enough to establish Moqui conventions, anti-patterns, and pointers to deeper knowledge. My PR #701 targets this layer.

  2. Shared knowledge layer (skills/standards): A dedicated component (whether we call it moqui-ai-skill, moqui-agent-os, or something else) containing structured skill files organized by domain, entity patterns, service conventions, screen development, data model reference (Mantle UDM/USL), etc. This is where the deep context lives, and it gets loaded on-demand rather than stuffed into every prompt. This naturally solves the performance concern from that Reddit research @schue shared, you’re not injecting 140 files into every context window.

On the vendor-agnostic concern @byersa raised, I think MCP (Model Context Protocol) is the right abstraction here. My moqui-mcp work exposes entity metadata, service definitions, and query capabilities through a standardized protocol that works across Claude, Cursor, VS Code Copilot, and others. The skill files / AGENTS.md approach is also inherently tool-agnostic since most agentic IDEs now support some form of project-level instruction files.

On @schue’s sub-agent idea for screen access, that’s a really interesting pattern. Separating the screen interaction agent from the coding agent keeps context clean. I’ve been exploring something similar with a multi-agent approach (Planner → Executor → Validator) where each agent has different context depth.

I think the practical next step is: can we agree on a shared structure for the knowledge layer and start consolidating? Whether it’s moqui-agent-os’s directory conventions or a simpler skills/ folder structure, having one place where the community maintains Moqui-specific AI knowledge would be far more valuable than each of us maintaining parallel versions.

Happy to contribute the skill files I’ve built covering moqui-framework, mantle-udm, mantle-usl, SimpleScreens, and MarbleERP into whatever shared structure we agree on.

5

I think I already provided in the above version an override mechanism at the top of the file. I didn’t investigate the rest of the files, but I’ve done the minimum to cover moqui community work in that file in a way that jives with the code base, and I got success in agentic on-the-loop. I am also upgrading it with orchestration scripts for proper start / stop / restart / wait etc for a smooth workflow.

However if folks think this requires discussion, then I can shift focus on more upgrade work while this gets hashed out. I’ll defer submitting any work for now.

6

@taher, after reviewing your override mechanism, I find that the implementation in moqui-agent-os appears more comprehensive. While “more complete” doesn’t always mean “better,” I am personally cautious about providing AI with instructions that are too generalized.

I strongly encourage you to remain part of the AI discussion. We are still in the early stages where the best approach hasn’t been determined. This situation feels reminiscent of why David originally branched Moqui from OFBiz—it is easy for a project to stall when there are “too many cooks.” If we conclude that the problem is too large for individuals and too complex for an ad hoc group, we risk letting Moqui become legacy software, discarded in the wake of the Big Tech AI expansion. You correctly noted that we may need to explore various paths to find the right answer; the challenge is ensuring those paths eventually converge rather than continuing to diverge.

I suggest the following steps:

Utilize the Bi-Weekly Collaboration Calls

We should use the existing calls (https://meet.google.com/ues-nsnr-jom) to focus on these topics. There is a session this Friday at 1pm MDT. We may need to extend these meetings beyond an hour and stay focused on technical strategy rather than broader philosophical debates.

Define High-Level Objectives

We need to reach a consensus on what we want to achieve with AI. We could submit and vote on a list of goals, such as:

  1. Development driven by specifications.
  2. Independence from specific LLMs and IDEs.
  3. Full-spectrum testing with browser awareness.
  4. Future-proof architecture that allows for technological upgrades.
  5. Solutions built natively on standard Moqui artifacts and tools.

Leverage AI for Infrastructure Development

We can use our various AI model subscriptions to evaluate and merge our individual efforts into a unified, coherent set of RAG instructions.

Allow for Iterative Divergence

As you mentioned, we may need to explore different directions before we can successfully converge. It might be wise to wait for emerging technologies before making final architectural decisions.

Conduct a Comparison Runoff

If we agree on a spec-driven requirement, we can test different candidate approaches. By providing descriptions of desired end products, we can see which methodologies produce the most successful results.
(thanks to Gemini)