[PR #233] [MERGED] agents: a three-agent team for long mods (orchestrator, game worker, offline worker) #235

New issue

Closed

opened 2026-10-15 20:54:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 20:54:39 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/rehan-remade/universal-modder/pull/233
Author: @Joaovitor404silva
Created: 10/11/2026
Status: ✅ Merged
Merged: 10/14/2026
Merged by: @rehan-remade

Base: main ← Head: agents/mod-team

📝 Commits (3)

88f510a agents: a three-agent team for long mods (orchestrator, game worker, offline worker)
77b4a9d agents: mod team: review fixes
7d61b6b Merge remote-tracking branch 'origin/main' into land/pr-233

📊 Changes

5 files changed (+181 additions, -0 deletions)

View changed files

📝 CLAUDE.md (+3 -0)
📝 README.md (+15 -0)
➕ agents/mod-game-worker.md (+48 -0)
➕ agents/mod-offline-worker.md (+42 -0)
➕ agents/mod-orchestrator.md (+73 -0)

📄 Description

What this adds

Three agent definitions in agents/ (Claude Code subagent format) for mods that take days rather than one sitting:

Agent	Role
`mod-orchestrator`	Supervisor. Plans the work, runs the two workers, checks their claims, and reports to the human in plain language.
`mod-game-worker`	The only agent that touches the running game: build, deploy, launch, probe, measure, fix.
`mod-offline-worker`	Never touches the game. Studies references (SDK data, object dumps, decompiled code, other mods), designs features, writes generators and patches, tests them against stubs, and hands over the exact live probes to run.

Start it with claude --agent mod-orchestrator and name the game and the idea. The orchestrator spawns the two workers and keeps them alive across rounds. It has to be the main session, because a subagent cannot spawn its own workers.

How it works

One process drives the game. There is exactly one game worker, so two agents never fight over the game window, the saves or the installed files.
Study and probing run in parallel. When the game worker reports "the game gives no way to do X", the orchestrator turns that into an offline study instead of more live probing. The offline worker reads how the game itself does it, builds the feature behind a flag that is off by default, and ends each batch with named live probes: what to call, where to stand, what reading to expect.
Claims get checked. A worker's "DONE" is treated as a claim. The orchestrator checks what it cheaply can (the mod's log, the loader's error count, a file hash, a screenshot) before telling the human. "Built and stub-tested" and "works in game" are reported as different states.
Working first, refining last. The orchestrator picks the nearest missing function, and parks polish and optimization in a list for the end. It does not cut features from the first playable version without asking the human.
Stuck three times means stop. A failure that repeats three times goes to the offline worker as a study.
The repo's hard rules are carried into every brief: saves backed up and never deleted, kill by exact PID, no game files or decompiled code committed, no anti-cheat or DRM bypass, nothing pushed or published without the human's say-so.

Why it helps

A single agent on a long mod alternates between waiting on the game and reading references, and loses context doing both. Splitting the roles lets the reference work go on while the game is busy.
Live probing is slow and can crash the game. Having designs, generators and stub tests ready before a probe means each launch answers a prepared question.
Workers start cold, so the orchestrator's briefs and the journal (MODLOG.md) have to carry the state. That also makes the project survive context compaction and a change of model.
The human gets one plain-language status from one agent, instead of reading three transcripts.

Models and token use

Model used. The team was developed and mostly run on Claude Opus 5.5. For part of the work the orchestrator and the game worker ran on Claude Sonnet 5.5, which also worked for well-specified probe rounds.
You can change it. The files do not pin a model, so each agent inherits the model of the session that starts it. To set one per role, add a model: line to that file's frontmatter (for example model: sonnet on the game worker and model: opus on the orchestrator), or pass a model when the orchestrator spawns a worker. The main session's model is changed with /model.
Token consumption: read this before using it. This setup uses far more tokens than a single agent. Three agents hold separate contexts, the two workers run in parallel for hours, each worker re-reads the project files when it starts, and the orchestrator reads every report. A long session can use several times what one agent would for the same wall-clock time, and can reach a plan's usage limit quickly. Ways to keep it down: run the workers on a smaller model, keep one worker idle when the other is the bottleneck, and keep briefs and reports short. Use it for mods that are long enough to need it, not for a one-evening mod.

Scope and limits

The files use Claude Code's subagent format and tool names (Agent, SendMessage). Other agents can read them as role briefs, but the spawning mechanics are specific to Claude Code. I kept the wording agent-neutral everywhere else.
They rely on the existing skills (mod-any-game, game-recon, game-automation, reverse-engineering, game-research-websearch) and the um CLI. No tool or skill is changed.
Not verified: loading them through the plugin's agents/ directory on a fresh install. They were developed and used as user-level agents in ~/.claude/agents/.
Written with Claude (Opus 5.5) during a long modding project; the method comes from what worked and what went wrong there.

Checks

uv run --with pytest pytest -q tests: 100 passed.
No game content, no secrets, no decompiled code.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EQAjyjvNqqEvmh5868WThH

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/rehan-remade/universal-modder/pull/233 **Author:** [@Joaovitor404silva](https://github.com/Joaovitor404silva) **Created:** 10/11/2026 **Status:** ✅ Merged **Merged:** 10/14/2026 **Merged by:** [@rehan-remade](https://github.com/rehan-remade) **Base:** `main` ← **Head:** `agents/mod-team` --- ### 📝 Commits (3) - [`88f510a`](https://github.com/rehan-remade/universal-modder/commit/88f510a3dc25959dbc89f26b9284e808bfdaae60) agents: a three-agent team for long mods (orchestrator, game worker, offline worker) - [`77b4a9d`](https://github.com/rehan-remade/universal-modder/commit/77b4a9d857e23242bca7fc270feddcf729f32bfc) agents: mod team: review fixes - [`7d61b6b`](https://github.com/rehan-remade/universal-modder/commit/7d61b6bf0b84386cc49ae8add22b0b98f191817f) Merge remote-tracking branch 'origin/main' into land/pr-233 ### 📊 Changes **5 files changed** (+181 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `CLAUDE.md` (+3 -0) 📝 `README.md` (+15 -0) ➕ `agents/mod-game-worker.md` (+48 -0) ➕ `agents/mod-offline-worker.md` (+42 -0) ➕ `agents/mod-orchestrator.md` (+73 -0) </details> ### 📄 Description ## What this adds Three agent definitions in `agents/` (Claude Code subagent format) for mods that take days rather than one sitting: | Agent | Role | |---|---| | `mod-orchestrator` | Supervisor. Plans the work, runs the two workers, checks their claims, and reports to the human in plain language. | | `mod-game-worker` | The only agent that touches the running game: build, deploy, launch, probe, measure, fix. | | `mod-offline-worker` | Never touches the game. Studies references (SDK data, object dumps, decompiled code, other mods), designs features, writes generators and patches, tests them against stubs, and hands over the exact live probes to run. | Start it with `claude --agent mod-orchestrator` and name the game and the idea. The orchestrator spawns the two workers and keeps them alive across rounds. It has to be the main session, because a subagent cannot spawn its own workers. ## How it works - **One process drives the game.** There is exactly one game worker, so two agents never fight over the game window, the saves or the installed files. - **Study and probing run in parallel.** When the game worker reports "the game gives no way to do X", the orchestrator turns that into an offline study instead of more live probing. The offline worker reads how the game itself does it, builds the feature behind a flag that is off by default, and ends each batch with named live probes: what to call, where to stand, what reading to expect. - **Claims get checked.** A worker's "DONE" is treated as a claim. The orchestrator checks what it cheaply can (the mod's log, the loader's error count, a file hash, a screenshot) before telling the human. "Built and stub-tested" and "works in game" are reported as different states. - **Working first, refining last.** The orchestrator picks the nearest missing function, and parks polish and optimization in a list for the end. It does not cut features from the first playable version without asking the human. - **Stuck three times means stop.** A failure that repeats three times goes to the offline worker as a study. - **The repo's hard rules are carried into every brief:** saves backed up and never deleted, kill by exact PID, no game files or decompiled code committed, no anti-cheat or DRM bypass, nothing pushed or published without the human's say-so. ## Why it helps - A single agent on a long mod alternates between waiting on the game and reading references, and loses context doing both. Splitting the roles lets the reference work go on while the game is busy. - Live probing is slow and can crash the game. Having designs, generators and stub tests ready before a probe means each launch answers a prepared question. - Workers start cold, so the orchestrator's briefs and the journal (`MODLOG.md`) have to carry the state. That also makes the project survive context compaction and a change of model. - The human gets one plain-language status from one agent, instead of reading three transcripts. ## Models and token use - **Model used.** The team was developed and mostly run on Claude Opus 5.5. For part of the work the orchestrator and the game worker ran on Claude Sonnet 5.5, which also worked for well-specified probe rounds. - **You can change it.** The files do not pin a model, so each agent inherits the model of the session that starts it. To set one per role, add a `model:` line to that file's frontmatter (for example `model: sonnet` on the game worker and `model: opus` on the orchestrator), or pass a model when the orchestrator spawns a worker. The main session's model is changed with `/model`. - **Token consumption: read this before using it.** This setup uses far more tokens than a single agent. Three agents hold separate contexts, the two workers run in parallel for hours, each worker re-reads the project files when it starts, and the orchestrator reads every report. A long session can use several times what one agent would for the same wall-clock time, and can reach a plan's usage limit quickly. Ways to keep it down: run the workers on a smaller model, keep one worker idle when the other is the bottleneck, and keep briefs and reports short. Use it for mods that are long enough to need it, not for a one-evening mod. ## Scope and limits - The files use Claude Code's subagent format and tool names (`Agent`, `SendMessage`). Other agents can read them as role briefs, but the spawning mechanics are specific to Claude Code. I kept the wording agent-neutral everywhere else. - They rely on the existing skills (`mod-any-game`, `game-recon`, `game-automation`, `reverse-engineering`, `game-research-websearch`) and the `um` CLI. No tool or skill is changed. - Not verified: loading them through the plugin's `agents/` directory on a fresh install. They were developed and used as user-level agents in `~/.claude/agents/`. - Written with Claude (Opus 5.5) during a long modding project; the method comes from what worked and what went wrong there. ## Checks - `uv run --with pytest pytest -q tests`: 100 passed. - No game content, no secrets, no decompiled code. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01EQAjyjvNqqEvmh5868WThH --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-15 20:54:39 +00:00

bsakaguchi referenced this issue

2026-10-15 20:54:39 +00:00

[PR #235] [MERGED] kb: Fabric mods for Minecraft 26.x: no mappings, the non-remapping Loom plugin, Mojang names #236

bsakaguchi closed this issue

2026-10-15 20:54:39 +00:00