keystone.guru

Use when asked to babysit, shepherd, or keep open MRs green. One pass over every open agent MR in RaiderIO/keystone.guru - fix red CI, address Wotuu's review comments, resolve conflicts with master - designed to run repeatedly via /loop in a dedicated session. Never merges, approves, or deploys. Not for reviewing a single PR (use the review skill) or for creating MRs.

How to make and VERIFY changes to the keystoneguru-infra CDK app (the sibling RaiderIO/keystoneguru-infra repo that owns AWS: ECS services, queue workers, task sizing). Covers the repo layout, the queue-worker config surface (queue:work flags, --memory, LOG_LEVEL, per-worker desiredCount / cpu / memoryLimit), and the reliable `cdk synth` verification recipe plus the traps that silently produce no output. Use when editing ECS task definitions, queue workers, memory/CPU, or any CDK construct here, or when a worker crashes/exits (e.g. queue worker exit code 12). NOT for the app-side build/deploy pipeline (use deployment-pipeline) or the release changelog (create-release).

Operational runbook to find, download, and reproduce real Staging/Production combat log parse failures before fixing them — the internal-team API endpoints, how to pull a failure's real Raider.IO log segments, the gzip/docker-cp reproduction recipe, and the safety checklist for shipping a fix. Use when triaging CombatLogParseFailure rows, chasing a "combat log parses are failing" report, or verifying a combatlog-parsing-internals fix against real production data. Pairs with combatlog-parsing-internals (how the parser itself works) and create-github-issue / worktree-docker (how to turn a diagnosis into a shipped MR).

How a single raw WoW combat log line becomes a parsed event object — CombatLogEntry's dispatch logic, the BaseEvent/SpecialEvent/CombatEvent class hierarchy, the CombatLogVersion registry and its getVersionLong() formula, the builder-with-default-fallback pattern every version-gated class uses, and the safe procedure for registering a new WoW client build. Use when a combat log line fails to parse, when a new WoW patch needs its version registered, or when touching CombatLogEntry/CombatLogVersion/SpecialEvent/Prefix/Suffix classes. For what happens AFTER a line becomes an event (NPC/spell mapping extraction, NPC Compendium) use combatlog-data-pipeline instead. For the operational runbook to find/download/reproduce real failing logs from Staging, use combatlog-parse-failure-triage.

Generate FloorUnions and FloorUnionAreas for a dungeon facade (MDT combined view) from the per-floor images and the combined facade image, using OpenCV image registration instead of the manual GIMP overlay workflow. Use when adding facade support to a dungeon or when asked to (re)compute floor unions from map images. Not for creating the Dungeon/Floor rows themselves, and not for the JSON seeder mechanics (seeder-load/seeder-save).

Use when starting a task that should run in an isolated git worktree with its own Docker app stack, or when the user mentions worktrees, parallel branches, or running multiple checkouts side by side. Covers sh/worktree.sh (create/down/remove/list), how the isolated stack shares the main DB/redis, and how to run artisan/tests inside it. Do not use for the main development stack or generic docker-compose questions.

Verify keystone.guru pages in a real headless Chrome - reproduce rendering/JS issues, measure layout, catch page errors, and take screenshots you can view with the Read tool (and post onto a PR). Use when curl/static reasoning is not enough (JS-driven UI, bootstrap-select menus, layout/sizing bugs, "does this actually render" questions). Works from the main checkout or any worktree via its Docker stack.

Map of how keystone.guru builds and deploys — the tag-triggered GitHub Actions pipeline (frontend assets, map context, Docker images), the cross-repo deploy into RaiderIO/keystoneguru-infra (Cloudflare + S3 assets, ECR/ECS, staging/production gates), and the operational gotchas. Use when the user asks how deploys/assets/CI work, why an asset 404s, how staging/production deploy, or where a pipeline step lives. NOT for authoring a release changelog (use create-release) and NOT the legacy PHP-Deployer flow.

Use after a v* tag has been pushed and release-deploy.yml is running (or about to run), when the user wants to watch or drive a release to completion from one terminal instead of tracking release-deploy.yml, the keystoneguru-infra Deploy runs, and the manual production gate by hand. Runs sh/release-watch.sh, a re-entrant polling loop that tracks build jobs, correlates the staging/production infra runs, runs asset and HTML verification, and can approve the production gate. Use --watch-only for a pure observer with no approval prompt. Gate approval always requires the human typing the exact version string; the script (and this skill) must never approve unattended. Not for authoring the release changelog itself (create-release) or a general map of the pipeline (deployment-pipeline).

Use when the user wants to create, file, open, or raise a GitHub issue / story / ticket for this project (e.g. a follow-up task, bug report, or tech-debt item). Covers the reliable `gh` command pattern, shell-escaping pitfalls, and the project's issue conventions. Do not use when creating merge/pull requests.

The two — and only two — supported ways for an agent to generate a dungeon-route thumbnail. Use whenever you need to (re)generate, render, or inspect a route thumbnail, or when a thumbnail is missing/broken/403ing. Path B dispatches to shared Horizon (real thumbnails, visible everywhere); Path A renders your branch's code locally to inspect it. Do NOT hand-roll puppeteer, edit ThumbnailService guards, apt-install Chrome, or symlink public/storage.

Patch a released version in place without cutting a new release: upload changed non-compiled files (PHP, Blade, lang, config) to the hotfix S3 bucket with `php artisan make:hotfix`, then redeploy the SAME version so ECS overlays them at container startup. Use when a staging/production bug must be fixed now and the fix touches no compiled assets. NOT for JS/CSS/SCSS or JS-consumed translations - those are baked into the release assets and require a new release (create-release skill).

Use when asked to update / bump the Mythic Dungeon Tools (MDT) composer package to a newer version and reimport dungeon mappings. Covers the full runbook: opening a tracking GitHub issue, composer reference bump, mapping reimport for the current retail season, new POI type/template handling, test fixture rewriting, NPC translation export, and re-seeding. NOT related to the MDT import/export string services (mdt-import / mdt-export skills).

How to build a NEW custom heatmap-like feature by reusing the existing heatmap infrastructure — the HeatPlugin Leaflet layer, MapContextDungeonExplore, and grid-cell weight aggregation (e.g. the admin enemy-failure heatmap). Use when integrating a new heatmap-style overlay. For a reference of the EXISTING public heatmap feature itself, use heatmap-javascript (client) or heatmap-php (backend) instead.

Reference guide for the EXISTING public heatmap feature's JavaScript implementation. Use when modifying heatmap filters, visualization settings, the HeatPlugin, SearchHandlerHeatmap, or the embed pass-through API. For the PHP backend see heatmap-php; for building a NEW custom heatmap-like overlay that reuses this infra, see heatmap-functionality.

Reference guide for the EXISTING public heatmap feature's PHP/Laravel backend. Use when modifying heatmap controllers, form requests, DTOs, the RaiderIO service layer, the Heatmap feature flag, or the CombatLogEvent grid aggregation. For the client-side JS see heatmap-javascript; for building a NEW custom heatmap-like overlay that reuses this infra, see heatmap-functionality.

Use when the user asks to "create a release", "cut a release", "make a new release", or generate a release changelog from commit history. Composes the changelog from squash-merged commits since the last release, creates the GitHub release issue and a draft GitHub Release, and cuts the `v*` git tag. NOT the legacy JSON-seeder or PHP-Deployer flows.

Step-by-step guide for creating a new page that renders a dungeon map — blade anatomy, JS wiring, sidebar controls, map context, and hidden object groups.

How the StructuredLogging system works and when to use it — per-service Logging classes, start/end context grouping, log levels, and the Discord error alerting flow. Use when adding logging to a service, creating a new {Service}Logging class, choosing a log level, or tracing what a service did from its log output.

Expose an existing Artisan command in the admin panel's "Artisan Commands" tools section — whitelist entry, chunked-AJAX Inline Code JS, blade view, route, breadcrumb, translations, and tests. Use when asked to make an artisan command runnable from the admin panel. Not for building a whole new admin page (admin-tools-page) or a bespoke batch operation page (admin-batch-page).

The map editor's server-side CRUD layer — AjaxMappingModelBaseController, the Ajax*Controller pattern, FormRequests, routes/web.php ajax groups, broadcast events (ContextEvent/ModelChangedEvent/ModelDeletedEvent), presence channels in routes/channels.php, and the checklist for adding a new editable map-object type. Use when adding or changing an ajax map endpoint, a broadcast event, or debugging collaborative-editing sync. Not for the model versioning itself (mapping-versioned-models), the front-end Leaflet layer (new-map-view), or public API endpoints (api-endpoint).

Conventions for Artisan commands in keystone.guru — the domain subfolder layout, custom base classes (SchedulerCommand, BaseCombatLogCommand, ...), shared traits, signature naming, handle() method injection, and how scheduling works in routes/console.php (env guards, Docker stdout output). Use when creating or modifying an Artisan command or changing the schedule. Not for exposing a command in the admin panel (admin-artisan-command) or generic Laravel console questions.

Runbook for adding a new Service to app/Service — interface + implementation pair, binding in KeystoneGuruServiceProvider (bind vs scoped vs instance, env-conditional swaps), the Logging companion wired in LoggingServiceProvider, Dev/Stub variants, and the Octane/Swoole statefulness rules. Use when creating a new service class or wiring an existing one into the container. Not for repositories (repository-pattern), the logging philosophy itself (structured-logging), or deciding Service vs Logic placement (project-backend-structure).

Lifecycle of mapping-versioned models (Enemy, EnemyPack, EnemyPatrol, MapIcon, FloorUnion, MountableArea, ...) — the MappingVersion clone-on-create boot, the clone interfaces/trait, mapping_version_id query scoping, current-version resolution, change logs, and the full wiring checklist (including the hardcoded model lists people forget). Use when creating or modifying a model that carries mapping_version_id, or debugging missing/duplicated mapping data across versions. Not for the JSON seeder mechanics (seeder-load / seeder-save) or the Ajax editor endpoints (ajax-map-editor-crud).

How MDTExportStringService converts a DungeonRoute into a compressed MDT-importable string — object structure, Lua serialization, and export tests. Use when adding new exportable object types, debugging export output, or writing/modifying export tests. Not for the import direction (mdt-import) and not for bumping the MDT composer package (update-mdt-package).

How MDTImportStringService parses a compressed MDT string into a DungeonRoute — decoding, object conversion, warnings/errors, and import tests. Use when adding new importable object types, debugging import failures, or writing/modifying import tests. Not for the export direction (mdt-export) and not for bumping the MDT composer package (update-mdt-package).

Architectural map of the PHP backend — every app/ directory explained, the Service/Logic/Repository/Model layering, container bindings per provider, and newcomer gotchas. Use when making architectural decisions, writing a new backend feature, or deciding where a new class belongs. Do not use for front-end JavaScript or any language other than PHP, and not for generic Laravel structure questions.

The backend security model of keystone.guru and how to review it — authentication (Laratrust, Basic-auth API), authorization (Gate/policies on the write surface), CSRF posture, request-input safety, and the areas already verified safe so they are not re-investigated. Use when doing a security review, adding an endpoint, or touching auth/CSRF/SQL/authorization. Not for front-end security or dependency CVEs.

How the SimulationCraft export converts a DungeonRoute into a fight_style=DungeonRoute config string — raid buffs, enemy health scaling by key level/affixes, travel delay, and bloodlust assignment. Use when adding/removing raid buffs, changing enemy health calculation, extending the output format, adjusting travel delay logic, or debugging simulation output. Not for MDT strings (mdt-import/mdt-export).

Conventions for writing PHPUnit tests in keystone.guru — which base test case to extend, the persistent seeded test DB (no RefreshDatabase; clean up with try/finally), creating admin/non-admin users, factory gotchas, the Group/Test PHP attributes, naming, and running tests in Docker. Use when writing or editing any test (Feature or Unit). Not for generic PHPUnit questions unrelated to this project's setup.

Use when the user has two or more Toggl timesheet CSVs (typically one per machine) and wants to reconcile, combine, or deduplicate them into a single import file. Companion to the toggl-timesheet skill, which generates the per-machine CSVs.

Use when the user asks to build a timesheet, log hours, create a Toggl import, or reconstruct work done between two dates. Derives work sessions from git commits and Claude conversation history, rounds to 15-minute intervals, and produces a Toggl-compatible CSV at ~/timesheet_<range>.csv.

Conventions for building a new admin page in keystone.guru — routing, controllers, blade views, the tools landing card, the admin nav dropdown, and count badges. Use when adding a read/list or simple form admin page. For long chunked-AJAX operations (progress bar, start/pause/stop) use the admin-batch-page skill instead.

End-to-end guide to how WoW combat logs are parsed into the combatlog DB — the streaming reader, the ordered data-extractor pipeline, the observation (rolling window) vs event (audit) tables, the hourly staleness sweep, and how the NPC Compendium front-end reads the resulting feed. Use when touching combat log extraction, NPC/spell observations or events, or the NPC Compendium.

Guide for adding a RelationParser so a new model or nested relation is correctly imported from the dungeon JSON seeder files. Use when a new model/child table needs to be populated during `php artisan db:seed --class=DungeonDataSeeder`.

Guide for adding a model or nested relation to the `mapping:save` Artisan command so it is exported to the dungeon JSON seeder files. Use when a new model or child relation needs to be persisted into `database/seeders/dungeondata/` as part of the mapping export.

Fix PHPStan static analysis errors by adding type annotations and PHPDocs. Use when encountering PHPStan errors, type mismatches, missing type hints, or static analysis failures. Never ignores errors without user approval.

Complete guide to the repository pattern used in this project — file locations, naming conventions, interface shape, provider registration, and how to add a new repository for a model.

Use when adding a new admin tools page that runs a long operation as chunked AJAX requests with a progress bar, start/pause/stop controls, elapsed timer, and log output. Examples: pruning database columns by criteria, backfilling data, bulk-updating rows.

Helps writing new public API v1 endpoints in a project-compliant way. Use when the user wants to add a new API route, controller, form request, resource, or test in the `app/Http/Controllers/Api/V1/` layer.