README.md owns stable project truth: repository map, packages, layering, stack, commands, publishing model and license. Read it and whatever the change touches; do not restate its facts here or in skills. Explicit user instructions take precedence over this file and over any skill. If a skill makes you pause, ask for confirmation, or leave requested work unfinished, name and link its SKILL.md and continue with the user's instruction.
Write short, everywhere a human reads: chat replies, PR bodies, issues, commit messages, review replies. One idea per line. A chat reply is what you did, what is still open, and the links; if it runs past a phone screen, cut it. A PR body is a line of context, a bullet per changed area, Closes #N, verification as command names with their verdict, and screenshots; a bugfix adds one sentence of root cause. An issue is the problem in a sentence plus acceptance criteria. Leave out plan recaps, what you considered and rejected, per-file walkthroughs, restated tool output, closing summaries, apologies and offers of more help. Expand only when asked to explain or why, and then answer that question and stop. A decision that needs the user is one concrete question with the options named.
Use plain, literal, conversational language in the tone of a calm coworker. Keep facts, assumptions and suggestions separate and say what you are unsure of. Rewrite any sentence that reads like a slogan, a trailer line, a pitch deck or an argument.
Define a term in the sentence that introduces it, or do not introduce it; use the user's own vocabulary for their domain. Ask decisions, not worries: name the decision and the options rather than thinking aloud with a question mark. Propose the frame before building the artifact: ten lines showing the shape catches a wrong premise before hundreds of lines exist. A merge is not approval and silence is not agreement; when a user rejects a name, ask whether the thing survives before renaming it.
Code comments default to none. JSDoc on exported public API stays, since it generates api.md and capabilities.md, and it stays tight. Inside a function body a comment earns its line only for a non-obvious why: a workaround, an invariant the types cannot express, a formula's source, a deliberate tradeoff. Delete restatements of the next line, section banners, step numbering, unlinked TODOs, commented-out code and changelog notes. Match the density of the file you are editing.
- World content is authored in the editor. Scenes, placement, terrain, paths, zones, foliage and assets live in
editor.scene.json, authored through the editor GUI or RPC/CLI. Any request that adds, moves, restyles or removes visible world content is an editor authoring task first; runtime and gameplay consume that document through shared primitives. If the editor cannot express the content, file a[FEATURE]issue before any code fallback and never hardcode geometry or coordinate arrays a scene can own.jgengine-editorcovers authoring andjgengine-worldruntime consumption. - Reusable capability goes upstream. Before editing a probe game in
Noisemaker111/JGengine-games(ephemeral./Gamesclone), name the shared owner. Anything another game could need belongs inpackages/*as a narrow, genre-agnostic seam with the game as its first adopter; game-local code is for genuinely game-specific content and feel. Extracting a primitive preserves observable play. - Every game is custom; there are no genre kits. Never build or reach for kits, presets, archetypes or "default sports car / RPG / FPS" shapes in the SDK or skills. Probe games are probes, never templates; prefer
capabilities.md, recipes or core APIs over another game's source. When two custom games would re-handroll the same glue, that glue belongs in the SDK or a skill recipe. - Respect package layering. The dependency direction in README.md is authoritative. Never import from a higher layer or make
coredepend on frameworks, rendering, browser, backend or game code. - Scale by default. Prefer serializable state, deterministic injected randomness, bounded work and allocation-aware hot paths. Avoid full-world per-frame scans and single-player-only contracts.
- Stateful primitives keep state, storage and policy reachable. A
create*factory that owns mutable state exposes a state-out method (snapshot()/state()) and its counterpart (restore(next)/reset(next)), ascards/cardPile.tsdoes; takes its storage as a narrow injected interface, asgame/keyValueStore.tsandcombat/magazine.tsdo; and keeps anything that changes during play retunable, asphysics/kinematicVehicle.tsretuneandcombat/abilityKit.tsretuneSlotdo.check-stateful-ratchetenforces the first; review covers the other two. Policy a game might vary is a callback or config field, never welded in. - Every game owns its UI composition; the engine ships the common parts. Inventory grids with real drag/stack/split, toggleable windows, vitals and stat bars, action bars, currency counters and minimaps ship in
packages/*as drop-in blocks a game wires and reskins with HudTheme tokens; reaching for them is correct use. Games own the overall look, layout, terminology, a real main menu, a settings surface and in-game credits. Judge UI by the rendered result. - Never use Kenney assets. Prefer Quaternius or KayKit for CC0 3D, game-icons.net for icons and ambientCG for PBR.
- Ports copy behavior and data, not implementation. Harvest numbers, tables, layouts, palettes, formulas and feel, then rebuild on engine seams. Credit inspiration, ports and copied permissive assets in
CREDITS.md; player-facing work also carries HUD and website credit.
A cold checkout or worktree needs bun run agent:bootstrap before build-dependent commands (installs if needed, then builds so @jgengine/* dist exists, about 2–3 minutes cold; lock-guarded, so re-invoking joins the running one). On Claude cloud sessions it starts automatically; confirm with bun run agent:bootstrap --check. Never kill a slow install: a killed bun install forces a wipe-and-reinstall loop. Read-only and documentation work does not need it.
Run package scripts as bun --cwd=packages/<pkg> run <script> (the = form). The space form prints bun-run help and exits 0 without running anything, and bun run --cwd can hit the wrong root script.
Worktrees are for local parallelism only: bun run agent:worktree -- <name> or claude --worktree <name>, both under .claude/worktrees/, never nested and never under C:\tmp. Cloud sessions are already isolated; branch from origin/main there.
Local tests, typechecks, bun run gate and bun run ship:preflight run without asking; fix failures the change caused and rerun the affected checks. Deterministic tests come first. Screenshots are for pixel claims, captured with bun run shoot / drive per jgengine-verify, never a hand-rolled Vite app; arbitrary --url pages set document.documentElement.dataset.jgCapture = "ready". After two capture failures, stop and report lower-rung evidence.
Start a task branch from current origin/main; never stack new work on a parked or merged branch, and never discard unrelated changes. Read what the smallest end-to-end change needs, then act; recon ends in a commit or an approved plan. Claim a tracked issue before implementation and close it from the PR with Closes #N.
A PR is one coherent, independently reviewable and revertible change. Combine work that shares a root cause, API migration, files or verification story; split work that is independently releasable or likely to conflict. Issue count never determines PR count. Follow the workflow skill for issue → change → verify → ship and push with a standalone git push. In the Noisemaker111 repo, enable squash auto-merge when opening the PR so GitHub lands it once CI is green; the user never merges by hand. Never enable auto-merge for another owner's repo, and never bump versions or publish npm releases unless the user explicitly asks.
Public API, workflow, convention or tooling changes update their owning skill, reference and generated artifacts in the same PR. Durable guidance belongs here, in an existing README, or in the owning skill; do not create ADRs, audit reports or freestanding design docs.
A bugfix PR body answers which engine seam, permissive default or missing contract allowed the bug, whether another consumer could hit the same class (if so the systemic fix goes upstream into packages/* or a gate so silence fails CI), and, when that reinforcement is too big for the fix, which [FEATURE] issue tracks it. Prefer making the wrong state unrepresentable over heavy process; one sentence of root cause is the ceiling of ceremony.
Completion is an evidence claim: inspect the diff against the acceptance criteria and run verification proportional to risk. Changes to a rendered surface embed before/after screenshots or a short capture in the PR body; skip only when there is genuinely no rendered surface, and say why. Behavior over time gets tried by driving the actual game before claiming it works, presented as video or stills, never a GIF and never as a video file in the conversation; jgengine-verify covers recording and pr-video.
When a task has two or more legs that do not need each other's output, delegate them to parallel subagents with disjoint files and judge their evidence rather than trusting claims; keep planning, overlapping edits and synthesis in the main agent. Route long mechanical sequences (babysitting gate runs, regenerating artifacts, commit-push-PR choreography, mass renames from an explicit list) to the cheapest capable model with exact commands and success criteria, and keep design, debugging and code authorship on the strongest available model. State the model name and ID at the start of a conversation.
jgengine is intake and routing only. Load only the domains the task needs; use each domain's capabilities.md for intent-to-import discovery, api.md for the generated export inventory, and references for deeper workflows. Each concept has one skill owner: workflow owns delivery, jgengine-verify owns evidence, improve owns backlog passes and post-fix retrospectives, ce-handoff owns session continuity, and domain skills own their package boundaries. Skill descriptions stay short and trigger-oriented; SKILL.md holds decisions and canonical workflows, not export catalogs or repeated project facts. The repository gates root mirroring, route integrity and duplicate prose.