From 8483a7f8fdb48875545629fbae826d1688747d0d Mon Sep 17 00:00:00 2001 From: NoisemakerJon <139656120+Noisemaker111@users.noreply.github.com> Date: Sat, 5 Sep 2026 17:41:47 -0400 Subject: [PATCH] Condense repository governance for current models Halve AGENTS.md: keep product invariants, runtime facts, change governance and skill architecture; fold the writing rules into short paragraphs; put user instructions above skills; grant standing permission for local gates; make delegation guidance model-neutral. CLAUDE.md mirrors it byte for byte (check-skill-sync passes). Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 134 ++++++++++++------------------------------------------ CLAUDE.md | 134 ++++++++++++------------------------------------------ 2 files changed, 58 insertions(+), 210 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 26a7bf1d..625467b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,129 +1,53 @@ # JGengine repository governance -Read [README.md](README.md) first. It owns stable project truth: repository map, packages, layering, stack, commands, publishing model, and license. Do not duplicate those facts here or in skills. +[README.md](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 +## Writing -Long prose is a defect, not thoroughness. This applies to **every** surface a human reads: chat replies, PR bodies, issues, commit messages, PR comments, review replies. One idea per line; no idea gets a paragraph. +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. -**Chat reply.** What you did, what is still open, the links. A few lines, not a page — if it runs past a phone screen, cut it. +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. -**PR body.** A line of context, a bullet per changed area (file plus what changed, not why it is good), `Closes #N`, verification as command names and their verdict, screenshots. Bugfixes add a sentence of root cause. Scale with the diff — a two-file change does not get the same body as a twelve-file one — but never pad. +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. -**Issue.** Problem in a sentence, acceptance criteria as bullets. No background essay. +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. -**Commit message.** Subject line, then only the body a reader actually needs. - -**Never write, anywhere:** plan recaps, what you read or considered and rejected, per-file walkthroughs, justifications nobody asked for, restated tool output, closing summaries that repeat the body, apologies, victory laps, "let me know if you want…". Bold section headers belong in a PR body, never in a chat reply. Numbered lists are for real enumerations, never for narrating reasoning. - -**Expand only on request.** "Explain", "why", or a direct design question earns depth — answer that question and stop. A decision that needs the user is one concrete question with the options named, never an essay ending in a question. - -**Subagents.** A worker's report to the main agent may be dense. The user-facing synthesis is not, and a subagent report is never pasted into chat or a PR body. - -## Global writing style - -Write in plain, natural language. This governs every generated word — chat replies, PR bodies, issues, commit messages, review replies, code comments, docs, skill text, and in-game copy — and it applies alongside the length rules above, not instead of them. Short and stylized is still wrong. - -Do not: - -- sound theatrical, smug, combative, managerial, or self-important -- turn an ordinary point into a slogan -- use punchy fragments for dramatic effect -- state something with more certainty than you have -- write lines like "the honest answer", "the best word", "this kills the problem", "you never confirmed", or "in case you want to fight me" -- imitate the voice of a critic, creative director, prosecutor, or brand copywriter -- add attitude, tension, wit, or rhetorical flourish unless the user asks for it - -Prefer: - -- normal conversational sentences -- literal wording -- clear explanations -- neutral descriptions -- explicit uncertainty -- collaborative phrasing - -When generating any text: state the point directly, explain it simply, keep facts, assumptions, and suggestions separate, avoid compressed or stylized phrasing, and do not invent emotional subtext. - -Aim for the tone of a calm, competent coworker. The goal is clarity, not personality. Before sending, rewrite any sentence that reads like a line from a trailer, manifesto, argument, pitch deck, or dramatic monologue. - -## Asking and proposing - -Four failures that cost real rework. They apply to design work, code review, planning, and any turn where you hand the user something to react to. +## Product invariants -**Define a term in the sentence that introduces it, or do not introduce it.** Invented vocabulary — a system name, a category, a coined noun for a mechanic — is unreadable to everyone but you until it is defined. Never ship a document, PR body, or reply whose reader has to infer what your own words mean. If a term needs a paragraph to justify, it is the wrong term. +- **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-editor` covers authoring and `jgengine-world` runtime consumption. +- **Reusable capability goes upstream.** Before editing a probe game in `Noisemaker111/JGengine-games` (ephemeral `./Games` clone), name the shared owner. Anything another game could need belongs in `packages/*` 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](README.md#layering) is authoritative. Never import from a higher layer or make `core` depend 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)`), as `cards/cardPile.ts` does; takes its storage as a narrow injected interface, as `game/keyValueStore.ts` and `combat/magazine.ts` do; and keeps anything that changes during play retunable, as `physics/kinematicVehicle.ts` `retune` and `combat/abilityKit.ts` `retuneSlot` do. `check-stateful-ratchet` enforces 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. -**Ask decisions, not worries.** "Can this hold under load?" and "is four resources one too many?" are you thinking out loud with a question mark attached, and they cannot be answered. Name the decision and the options: "three pools or four?" Reserve open-ended framing for a genuine request for the user's read, and even then say what you would pick. +## Runtime and verification -**Propose the frame before building the artifact.** Ten lines showing the shape — the categories, one example each, the rule that generates the rest — costs one message and catches a wrong premise before it becomes hundreds of lines you delete. Volume is not progress when the reader cannot parse the units. +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. -**A merge is not approval, and silence is not agreement.** Users clear queues to keep moving. Treat "landed" as landed; treat only an explicit answer as a decision. When a user rejects a name, ask whether the thing survives before renaming it — a rejected label is usually a rejected concept. And use the user's words for their own domain rather than better ones you invented; if they said "common, uncommon, rare", that is the vocabulary, and improving on it is not your call. +Run package scripts as `bun --cwd=packages/ run