Imported from xklob/Hexagons-Bestagons-Tower-Defense (AGENTS.md). Install upstream with npx skills add xklob/Hexagons-Bestagons-Tower-Defense. Copyright stays with the author.

Repository Guidelines

ExecPlans

When writing complex features or significant refactors, use an ExecPlan as described in PLANS.md. Save plans in plans/ with the next two-digit number in the filename only, such as 01-feature-name.md, and keep their progress, decisions, discoveries, and outcomes current while work proceeds. When creating, revising, or materially expanding an ExecPlan, use .agents/skills/grill-me/SKILL.md to pressure-test scope, milestones, risks, validation, and durable-doc impacts before seeking milestone approval. Do not reuse a fixed milestone or checkbox count: small plans should stay compact, while more complex projects should add more independently verifiable milestones and Progress items as they add subsystems, UI states, validation gates, design decisions, migration steps, browser evidence, or approval points. For ExecPlans that include code changes, include Vitest coverage baselines from npm run coverage before implementation and again before completion, plus a final code-file line-count review before calling the plan complete. EDHB strongly prefers hand-written non-test TypeScript, JavaScript, and similar source files below 600 lines, and hand-written HTML or CSS files below 2000 lines; test files may exceed 600 lines when that keeps related behavior coverage readable in one place. If the coverage comparison shows an unexplained drop of 2 percentage points or more in any headline metric, or a meaningful drop in the changed area, add or strengthen tests before marking the plan complete. If the line-count review finds an over-limit non-test file, or a changed non-test file close enough to its limit that maintainability is at risk, recommend a refactor, file split, helper extraction, or library addition as appropriate. Do not implement that follow-up unless the user explicitly approves it.

For substantial UI additions, UI refactors, major responsive/layout changes, or design-direction choices, use .agents/skills/ui-mockups/SKILL.md during planning before UI implementation begins. Save generated mockup options under plans/<name-of-plan>/mockups/, present the options to the user, and record the selected or hybrid direction in the ExecPlan before editing UI code. Do not use this workflow for small visual fixes, copy tweaks, or already-approved designs.

Planning and Change Intake

Treat user change requests as proposals until they have been checked against the repository's current boundaries, existing plans, maintainability needs, and long-term product direction. If a requested change would add technical debt, obscure ownership, inflate future context, weaken testability, reduce project grok-ability, or conflict with the current architecture or control documents, push back with concrete reasons or offer cleaner alternatives before proceeding.

When creating any plan, including a small one, gather as much relevant information from the user as practical before locking the approach. Ask as many targeted questions as needed about feature scope, future impacts, validation expectations, documentation needs, migration paths, and likely follow-up work. Offer alternatives and explain tradeoffs where the user's initial request may not lead to clean code or durable design.

Strongly prefer doing the work correctly over doing it quickly, even when the correct path is initially more technically complex or requires more up-front design. Planning updates, features, and refactors should not be treated as quick or light tasks; they should account for maintainability, future feature additions, context bloat, and how easily a technically strong newcomer can understand the resulting system.

Core Documents

Treat the root documentation files as durable project control documents:

README.md explains what EDHB is, how to run it, and how to validate changes.
PRODUCT.md captures the current user-visible product state, workflows, capability boundaries, and important limitations.
ROADMAP.md captures intended product direction, planned capabilities, strategic priorities, and explicit non-priorities.
PLANS.md defines how ExecPlans must be written and maintained.
DESIGN.md captures the future semantic design system in descriptive language.
ARCHITECTURE.md captures the high-level codemap, architectural boundaries, and invariants.
CODESTYLE.md captures code formatting, file-size, naming, commenting, and code-file documentation standards.

When a change materially affects current capabilities, workflows, scope boundaries, or important limitations, update PRODUCT.md in the same change. When a change materially affects future direction or priorities, update ROADMAP.md. When a change materially affects design language, update DESIGN.md. When a change materially affects structure, ownership, extension points, or system boundaries, update ARCHITECTURE.md. When a change materially affects code style, file-size expectations, naming, comments, or code-file documentation standards, update CODESTYLE.md.

If you introduce a new root-level ALLCAPS.md file, treat it as a new control document by default. Define its purpose inside the file, update this section, update PLANS.md if ExecPlans must read or validate it, and state what changes must keep it in sync.

Project Structure & Module Organization

Keep runtime TypeScript code in src/, mirror tests in tests/, keep static assets in assets/, and leave long-lived documentation in the repository root.

Current code layout:

src/backend/game/ owns public run control, generated map settings and board construction, custom-authored map validation and board construction, scenario tooling, state construction, snapshots, and shared types.
src/backend/simulation/ owns tick orchestration, pathfinding, collision, and simulation constants.
src/backend/math/ owns small reusable math helpers.
src/frontend/ owns the Pixi.js battlefield renderer, DOM command shell, browser setup/editor state, frontend-only UI copy, and styling.
index.html and vite.config.ts own the local browser entry point and Vite build/dev-server setup.
scripts/stitch-mockups.mjs and scripts/stitch-mockups/ own the Google Stitch UI mockup generation workflow for contributor planning.
tests/ owns Vitest behavior tests, Playwright browser workflow tests, and Node-based tests for contributor tooling.
.agents/skills/ owns repo-local agent workflows, including browser automation discovery, screenshot UX review, underspecified-work clarification, ExecPlan pressure-testing, and pre-implementation UI mockup generation.
.codex/config.toml owns project-scoped Codex defaults. The current default model is gpt-5.5.

Do not add another frontend framework, rendering stack, browser runtime, or persistence layer unless the requested work explicitly calls for it or an approved ExecPlan covers it.

Build, Test, and Development Commands

npm install installs local dependencies.
npm test runs the Vitest test suite and the Node-based contributor-tooling tests.
npm run test:unit runs the Vitest test suite.
npm run test:tooling runs the Node-based contributor-tooling tests.
npm run test:e2e runs Playwright Chromium workflow tests against the browser frontend.
npm run coverage runs Vitest with V8 coverage over TypeScript source and writes reports under coverage/.
npm run coverage:check runs coverage and enforces the 90% line, function, and branch gates for src/frontend/**, src/backend/**, and aggregate src/**.
npm run typecheck runs strict TypeScript checks without emitting files.
npm run build emits the package to dist/.
npm run build:frontend emits the browser frontend bundle to dist/frontend/.
npm run dev starts the local Vite dev server for the browser frontend.
npm run dev:e2e starts the Vite frontend on a fixed strict port for Playwright.
npm run stitch:mockups -- --plan <plan-stem> --prompt-file <prompt.md> --reference <sample-path> --variants 4 --device DESKTOP generates Google Stitch UI mockup options for substantial UI work when Stitch credentials are configured.
npm run validate runs typecheck, tests, Playwright E2E workflows, package build, and frontend build in order.
git status shows pending changes before commit or review.
rg --files --hidden -g '!.git/**' lists the current file set quickly.

Run npm run validate before calling simulation or frontend changes complete. For ExecPlan-driven code changes, also run npm run coverage at the start and end of implementation, record the headline line, function, branch, and statement percentages in the plan, and treat a significant unexplained drop as a missing-test problem. Use npm run coverage:check before completion when the plan needs to prove the 90% frontend/backend/source line, function, and branch gates.

Playwright frontend workflow tests may use the read-only ?edhbTest=1 browser bridge to inspect snapshots and translate Pixi canvas tile ids to screen coordinates. They must still drive gameplay through DOM buttons and canvas clicks; do not add bridge methods that enqueue commands, advance ticks, or mutate frontend/backend state without an approved ExecPlan.

Browser and Visual Validation

Use the local agent-browser skill for browser interaction and screenshots whenever work changes src/frontend/, index.html, vite.config.ts, browser-visible styling, rendered documentation, or backend snapshot fields that can affect frontend layout or presentation. Before running browser commands, load its current workflow with agent-browser skills get core.

For UI changes, start the Vite dev server with npm run dev, capture several screenshots across desktop, tablet/narrow desktop, and mobile-sized viewports, then use the local review-ui-screenshots skill for a deliberate inspection pass. Inspect for regressions, awkward spacing, overlaps, clipping, unreadable text, missing states, and small quality-of-life issues. Also exercise important interactive states such as selected tiles, disabled buttons, active waves, notices, and any newly changed workflow.

Apply the UX quality bar from DESIGN.md during that inspection. Do not stop at "nothing overlaps"; check every screenshot section by section, including board state, command panels, setup controls, tower/action panels, targeting controls, notices, and responsive rearrangements. Verify whether controls are centered or intentionally aligned, whether buttons have enough padding from panel borders, whether repeated spacing feels consistent, whether disabled states still read as controls, and whether the interface would pass a professional product-design review.

For ExecPlan-driven frontend work, make baseline capture an explicit first implementation step before changing frontend-visible code. Save before screenshots under the plan artifact directory, using paths such as plans/06-pixi-canvas-hud/screenshots/before-implementation-1.png. After implementation, repeat the same interaction points and viewport sizes with paths such as plans/06-pixi-canvas-hud/screenshots/after-implementation-1.png. If work has already started, capture the baseline from a clean checkout, detached worktree, or other reproducible pre-change source when practical; if that is impossible, document the limitation in the ExecPlan. List the exact before and after screenshot paths in the ExecPlan, compare them with review-ui-screenshots before calling the plan complete, and fix any visible regressions or obvious UX issues that the comparison reveals.

UI Mockups and Stitch

Use the repo-local ui-mockups skill when planning meaningful UI work that needs design options before implementation. Load .agents/skills/ui-mockups/SKILL.md, read the active ExecPlan and DESIGN.md, prepare a feature prompt, and run npm run stitch:mockups when Google Stitch credentials are available. The command writes options to plans/<name-of-plan>/mockups/, writes index.html for browser preview, prints a clickable preview link, and accepts local reference images, HTML/CSS files, or Google Stitch export bundles. When running under WSL, that preview link must use file://wsl.localhost/<distro>/... rather than file:///home/... so Windows 11 browsers can open it. Reference samples guide style by default; they should not control layout or content unless the user explicitly asks for that.

Before copying a supplied sample into the repository, confirm it contains no secrets or restricted third-party material. Before deciding Stitch credentials are unavailable, check for an untracked repo-root .env file and load it into the current shell with set -a; . ./.env; set +a without printing secret values. If STITCH_API_KEY or the OAuth variables from .env.example are still unavailable after that, explain that live Stitch generation was not run instead of inventing mockup artifacts. Mockups are pre-implementation decision artifacts and do not replace the before/after screenshot and review-ui-screenshots workflow required for implemented frontend-visible changes.

Coding Style & Naming Conventions

Use CODESTYLE.md as the source of truth for formatting, file size, naming, comments, and code-file documentation. It also records the code-level simulation boundary rules that implementation work must preserve.

Testing Guidelines

New behavior should ship with tests. Prefer tests that drive the simulation through RunController; direct tests of helpers such as pathfinding or collision are appropriate when the algorithm itself is the behavior under test.

Tests should cover deterministic replay when a change affects tick order, command handling, pathing, projectiles, damage, cleanup, rewards, or snapshots.

ExecPlan-driven code changes should compare npm run coverage before and after implementation. Add tests before completion when coverage drops significantly, especially when the drop is in files or behavior touched by the plan. Coverage-sensitive plans should pass npm run coverage:check, which enforces 90% lines, functions, and branches for frontend, backend, and aggregate source. Coverage is a guardrail, not a substitute for behavior-focused tests or Playwright workflow tests when browser interaction is the risk.

Commit & Pull Request Guidelines

Follow the existing concise imperative commit style, such as Initial commit.

Pull requests should explain:

What changed
Why it changed
How it was validated

Include screenshots when a change affects rendered output or documentation presentation.

Hexagons-Bestagons-Tower-Defense

About