Beebot

Imported from SafJNest/Beebot (AGENTS.md). Install upstream with npx skills add SafJNest/Beebot. Copyright stays with the author.

Beebot agent instructions

Repository context

This repository contains Shopify integrations, Java services, GraphQL integrations, Algolia, MySQL/MariaDB, Redis, Express and LoL API code.

Java code uses the com.safjnest package. LoL domain models belong under com.safjnest.lol.model; Spring owns controllers, configuration and HTTP errors only.

Primary stack:

• Shopify Liquid, CSS, vanilla JavaScript and Custom Elements;
• Java backend;
• GraphQL Storefront API;
• Algolia;
• MySQL/MariaDB and Redis with Jedis 5.1.0;
• Express and Next.js for LoL dashboards.

JavaScript style

• Treat Custom Elements as Java-like classes with explicit structure.
• Use the member order: static constants, getters/setters, static factory, constructor, lifecycle callbacks, other methods.
• Do not use private # fields.
• Prefer inline conditionals with && and !condition && when they remain readable.
• Use async/await, never .then().
• Use try/catch in connectedCallback when lifecycle work is asynchronous.
• Fetch with res.text() and DOMParser where the existing integration requires parsed HTML.
• Keep magic numbers in static class constants.
• Build parts[] with one innerHTML assignment instead of repeated DOM appends.
• Prefer CSS selectors and pseudo-classes for state; use JavaScript only for dynamic numeric CSS custom properties.

Java style

• Use switch expressions with -> and grouped cases.
• Use static utility classes for stateless utilities.
• Prefer static factories for conversions and model construction.
• Use final for immutable fields.
• Use List.of or Arrays.asList for static constants.
• Do not use Lombok in operational classes.
• Do not introduce dependency injection frameworks.
• Do not wrap values in Optional.
• Prefer a loop when it is clearer than a stream.
• Avoid unnecessary refactors and comments.

Data changes and presentation stability

• Changes to data, data models, persisted documents, API payloads or data flow must not change the existing presentation or style unless a style refactor is explicitly requested.
• Keep commands, embeds, views, field names, field order, text, formatting, components and layout exactly as they are when only the data source or data structure changes.
• New values may be added for persistence, API responses or other consumers without displaying them. If they must be displayed, use the existing presentation patterns and change only the minimum required surface.
• A request such as “add these values and show them like this” explicitly authorizes the requested presentation change; otherwise do not redesign or restyle existing output.

Service layout

In every modified service:

1. constants;
2. fields and constructors;
3. public methods;
4. one large separator comment;
5. private methods.

The separator is the only structural comment required. Remove comments that do not explain a necessary invariant or non-obvious external behavior.

Canonical LoL data

• Summoner is the canonical identity model.
• Rank is the canonical ranked-queue model. Do not introduce SummonerRank or keep it as an alias.
• Mastery is the canonical champion mastery model. Do not introduce ChampionMastery or keep it as an alias.
• riotId remains a String. Do not add a RiotId record or class unless an accepted ADR explicitly requires it.
• SummonerView is the complete profile projection.
• SummonerLeaderboard wraps one SummonerView with leaderboard position data.
• Match is the complete match model.
• Participant is the complete global participant model.
• MatchResult is the lightweight match projection used by lists and overviews.

Use existing utilities before adding new mapping logic, especially ChampionUtils, LaneTypeUtils, GameQueueTypeUtils, LeagueShardUtils, TierDivisionUtils and LeagueHandler.

API boundaries

• Domain and API success models belong in lol.model.
• Spring DTOs are restricted to HTTP errors and infrastructure-specific representations.
• Do not create a second DTO for a concept already represented by a canonical model.
• Controllers should return canonical models directly unless an accepted ADR documents an HTTP-only wrapper.

API synchronization rule

• Every update to LoL models, services, persisted data, parameters or business behavior must include a review of the affected API endpoints.
• When the change affects an exposed contract, update the controller, canonical response model and API documentation in the same task.
• No LoL change is complete until the API surface and its documentation are synchronized with the new behavior; if the change is internal-only, explicitly verify that no API update is required.

Documentation synchronization rule

• Every change to models, data structures, persistence, filters, services, commands, embeds, caches, API behavior or ownership must review the relevant documentation in the same task.
• Update the canonical source-of-truth document, ADR, API documentation or Mongo documentation whenever the changed behavior is covered there.
• Documentation is part of the implementation gate: a task is incomplete while its affected documentation is stale or the reason for no documentation change is not recorded.
• When a change is internal-only, explicitly record that the public API, presentation and relevant documentation remain unchanged.
• When data changes but presentation must remain stable, document the new data source and keep the existing command, embed, view, field order, text, formatting and layout unchanged unless a style change was explicitly requested.

Agent workflow

Read these files before changing LoL architecture:

1. this file;
2. docs/architecture/README.md;
3. the relevant accepted ADR;
4. docs/HANDBOOK.md §5-§7 for operational steps (command/endpoint/service/model/queue/mongo/cache);
5. CodeGraph — codegraph status → if stale codegraph sync → codegraph explore <symbol> + codegraph impact <symbol> for blast radius before touching code.

The source-of-truth agent proposes and maintains architecture decisions. The main agent reviews ownership, boundaries, tests and the handoff before approving the next task.

Global agents (Cursor / Claude Code / Codex / Opencode) live in .agents/agents/ (canonical) and are shimmed to .cursor/rules/, .claude/agents/, .codex/agents/, .opencode/agent/. Skills live in .agents/skills/beebot-handbook/. Never edit the shim — edit .agents/agents/*.md.

CodeGraph is mandatory: no LoL change without up-to-date explore/impact. If codegraph status reports a stale or missing index, the agent must sync before proceeding.

Agents must stop and report a conflict instead of silently changing an ADR or an unrelated owner.