2026-April-12 - 2.7.15444

Add comprehensive AGENTS.md documentation across the project (#14215)

* Add AGENTS.md for lib/java-extras

Document the general-purpose Java utility library: package layout,
key classes (FileUtils, IntegerMap, Retriable, Interruptibles, PerfTimer),
conventions (Lombok @UtilityClass, checked exception wrapping, Optional
over null), and gotchas.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/test-common

Document the shared test utility library: CustomMatcher builder,
IsInstant and CollectionMatchers, TestDataFileReader with fallback
path resolution, JsonUtil, Swing test helpers, and RSA key loading.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/xml-reader

Document the annotation-driven XML-to-POJO mapping library: entry points
(XmlMapper, XmlScanner), annotation system (@Tag, @Attribute, @TagList,
@BodyText, @LegacyXml), validation rules, attribute defaults and
nullability, StAX parsing flow, and exception hierarchy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/swing-lib

Document the Swing UI utility library: 20+ fluent builder classes,
EDT and thread safety utilities (SwingAction, EventThreadJOptionPane),
key binding system with cross-platform support, MVVM-like event queue,
and notable utility classes (FileChooser, AutoCompletion, IntTextField).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/websocket-client

Document the WebSocket client library built on Java 11+ stdlib: source
file inventory, message envelope serialization pattern, connection
lifecycle (connect, queuing, keep-alive, close, termination), threading
model, conventions, and gotchas.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/websocket-server

Document the WebSocket server library: architecture layers
(StandaloneWebsocketServer, GenericWebSocket, WebSocketMessagingBus),
session management, message broadcasting, bad-message rate limiting,
and editing guidelines.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/feign-common

Document the shared Feign HTTP client infrastructure: HttpClient factory
with project-wide defaults (timeouts, retry, Gson codecs), custom
JsonEncoder/JsonDecoder with Instant epoch.nano format, conventions,
and gotchas around the singleton decoder and timestamp format.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for lib/

Overview of the shared utility library modules: feign-common, java-extras,
swing-lib, swing-lib-test-support, test-common, websocket-client,
websocket-server, and xml-reader.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/domain-data

Document the shared domain value objects: UserName, PlayerChatId, ApiKey,
SystemId, ChatParticipant, LobbyGame, LobbyConstants, SystemIdLoader,
and PlayerEmailValidation. Leaf module with no internal dependencies.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/map-data

Document map file parsing: XML game data POJOs (17 classes with JAXB
and custom annotations), YAML map metadata (MapDescriptionYaml), and
HTML game notes support.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/game-relay-server

Document the WebSocket message relay: architecture (GameRelayServer,
StandaloneWebsocketServer, WebSocketMessagingBus), message broadcasting,
session tracking, and ban checking.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for http-clients/lobby-client

Document the Feign-based lobby server API client: architecture layers,
client construction pattern, authentication headers, full endpoint tables
for all 6 API categories, WebSocket connection facades (PlayerToLobby,
GameToLobby), and WebSocket message types.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for http-clients/

Overview of the HTTP client libraries with pointer to lobby-client's
detailed documentation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for the battle subsystem

Document the step-based combat resolution system: architecture overview
(IBattle, AbstractBattle, BattleTracker, BattleDelegate), 5 battle types,
15-step execution order state machine, fire/change/retreat step
subdirectories, BattleState/BattleActions interfaces, casualty selection
system, and compatibility warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/game-core

Document the core game engine module: full package structure, delegate
system (18+ delegates, class hierarchy, remote interfaces), messaging
layer (hub-spoke RMI, @RemoteActionCode serialization, threading),
engine framework (IGame hierarchy, startup subsystem, map management),
UI layer (tile-based rendering, 11-layer DrawLevel, ActionPanel),
attachment system (full class hierarchy with property groups), AI
package (ProAi, FastAi, WeakAi), and compatibility warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/ai

Document the AI player module: FlowFieldAi (influence diffusion algorithm
with Lanchester's Laws), DoesNothingAi (passive AI delegating to WeakAi),
package structure, key concepts, and clarification that the default
strategic AIs (ProAi, FastAi, WeakAi) live in game-core.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/game-headed

Document the desktop GUI client: HeadedGameRunner entry point, CLI
startup modes, package structure, TripleAFrame main window layout,
ActionPanel hierarchy for turn phases, lobby UI (login/registration,
game browser, player actions), moderator toolbox (7 admin tabs),
and game setup panels.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/game-headless

Document the headless game server (bot): HeadlessGameRunner entry point,
startup sequence, required system properties and environment variables,
package structure, architecture, and Shadow JAR / Docker build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/smoke-testing

Document the end-to-end smoke tests: test inventory (ParseGameXmlsTest,
GameSaveCompatibilityTest, GameSaveTest, AiGameTest), build configuration
with save game downloads, headless test setup patterns, and step-by-step
game execution utilities.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for game-app/

Overview of the main application layer: module map, dependency flow,
and shared conventions (triplea-java-library plugin, Checkstyle, PMD,
JaCoCo).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for .build/

Document the static analysis configuration: Checkstyle rules, PMD
rules, and custom style checks with their include files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for docs/

Document the project documentation directory: layout by audience
(admin, development, infrastructure, map-making), key documents for
AI agents, and staleness notes for legacy docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add AGENTS.md for gradle/build-logic

Document the custom Gradle convention plugins: triplea-java-library
(Java 21, Spotless, Google Java Format) and failure-summary-plugin
(collects and reports test failures across subprojects).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add root AGENTS.md for the TripleA project

Top-level project documentation tying together all module AGENTS.md files:
project overview, module dependency graph, build commands, code conventions
(Google Java Style, Lombok, Optional, immutability), testing patterns
(JUnit 5, Hamcrest, Mockito, WireMock, test fixtures), architecture
concepts (GameData, Delegates, Changes, Attachments), compatibility
constraints (save-game serialization, @RemoteActionCode), and domain
terms glossary.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>