--- title: "Customize the rules: locked vs your choice" slug: /workflows/customizable-rules/ markdown: /workflows/customizable-rules.md section: customize tier: 2 summary: "Which rules are locked evidence and which are per-project preferences." sources: ['customizable-rules.md'] canonical: https://unityworkflowlibrary.dev/workflows/customizable-rules/ read_first: /read-first.md --- > Read first, on every prompt: [non-destructive rules](/read-first.md). # Customize the rules: locked vs your choice > Which rules are locked evidence and which are per-project preferences. Rules in this library are of two kinds. Evidence rules record what shipped games actually did and are locked. Preference rules record how the library author likes to work and are the user's choice in their own project. Status: agent default - unconfirmed until the creator ratifies each heading. ## LOCKED-VS-CUSTOMIZABLE - **LOCKED:** a rule that is empirical evidence from shipped or played games - a bug or failure seen and fixed, a measured behaviour, a symptom -> fix pair, a "Seen in" / "Proven on" / "Verified on" / "Measured" marker. Agents never edit, weaken, or skip it. A correction comes only with new evidence, through the creator. - **CUSTOMIZABLE:** a rule that is a choice, not evidence - versioning, workflow preferences, naming style, folder layout, commit and push cadence, changelog format, process order, tone. On first encounter in a project the agent asks the user how they want it handled, instead of assuming the library default. It records the answer in the project and follows it from then on. When the user adopts or copies a section that holds one, SURFACE-PREFERENCES-ON-ADOPTION applies. - Record answers in one project-level preferences file (suggested: `.agent/preferences.md`, one row per rule id: choice, date, who chose). Read it before applying any customizable rule. - Why: evidence does not change because someone prefers otherwise; a preference applied without asking overrides the user's own project. - Check: every customizable rule the agent applied has a row in the preferences file; no locked rule appears there as "overridden". ## HOW-TO-CLASSIFY - Locked markers: measured numbers with units or counts; a named engine or SDK API and its observed behaviour; "Seen in", "Proven on", "Verified on", "Measured"; a failure described before its fix; a vendor-source or doc citation; HARD on a rule about engine, SDK, platform or legal behaviour. - Customizable markers: "prefer", "default", "convention", "style", "cadence", "layout", "format", "we use"; a rule that would be equally correct with a different choice; developer-preference rules about how sessions, commits, tabs or files are organised. - Mixed rules: the evidence part is locked, the preference part is customizable (e.g. "push after every slice" is a preference; "an unpushed slice was lost when the machine crashed" is evidence). - Tie-break: if unsure, treat it as locked AND ask the user. Never treat an unclear rule as optional. - Check: when the agent asks, it names the rule id and says which kind it judged it to be. ## DEFAULT-VERSIONING-SCHEME (customizable) - The library author's default, offered not imposed: - `MAJOR.MINOR.PATCH`. - PATCH bumps on every agent session. - PATCH is free-form with no rollover (e.g. `0.6.99` -> `0.6.100`, `0.6.140`). - MINOR is flexible and bumped at the author's discretion. - Agents ask the user before adopting or changing this scheme in their own project, and record the answer in the preferences file. ## SURFACE-PREFERENCES-ON-ADOPTION - Every preference-tagged rule carries an agent instruction: when a user adopts or copies a section that contains it, the agent surfaces that rule to the user, explains why it exists and why it is the default, and walks them through keeping or changing it. The answer is saved to `.agent/preferences.md` (rule id, choice, date, who chose) before the rule is applied. - Example - DEFAULT-VERSIONING-SCHEME: the agent says the default is PATCH bumps every agent session, the third number is free-form with no rollover (`0.6.99` -> `0.6.100`), and MINOR is flexible; why: one bump per session keeps every session traceable in `VERSION` and the changelog without arguing over size. Then it asks: keep it, or use your own scheme (e.g. roll at 99, bump MINOR per feature)? - Why: a preference copied silently becomes the user's rule without their choice, and nobody can later tell a deliberate setting from an inherited default. - Check: each preference rule in an adopted or copied section has a row in `.agent/preferences.md` and the user was shown the rule, its reason and its default before it was applied. ## Customizable areas in this repo (as of) | area | where | library default | | --- | --- | --- | | Version scheme and bump cadence | the library's version file and layout notes | PATCH per rule-changing session | | Changelog and glossary format | the library's changelog and glossary | indexed changelog, one glossary row per id | | Commit and push cadence | AUTO-COMMIT-AND-PUSH-PROGRESS, DONE-MEANS-PUSHED-TO-DEV, LIBRARY-PROMOTE-IS-COMMIT-AND-PUSH | commit and push progress automatically | | Session and tab workflow | your agent tooling | fleet tabs or pointer workers | | C# naming and code layout style | the [C# style](/workflows/csharp-style/) page (e.g. CSHARP-FULL-NAMES) | full names, one-path code shape | | Folder layout | provenance and credits file locations | a sibling clone of the rules library, project-owned asset paths | | UI look direction | the ui design page (already marked agent default - unconfirmed) | anti-default looks | | Site roles and cadence | the agent roles page | weekly cadence | ## Examples of locked rules - the audio page LISTENER-DISTANCE-SETS-THE-ROLLOFF (measured -28 to -32 dB at 31 m), GETDATA-NEEDS-A-DECOMPRESSED-CLIP, AUDIO-IMPORT-COMPARES-FIELDS-NOT-EQUALS. - the ai modelgen page MULTI-OBJECT-INPUT, STYLE-ANCHOR-LEAKS-ITS-SILHOUETTE (outline overlap 0.68). - the legality liability page items that cite law or store terms are locked as to the facts; FREE-TIER-AI-ASSETS-ARE-NOT-SHIPPABLE is a stricter project policy and therefore customizable, but the tool terms it cites are not. ## FIRST-USE-SETUP-WIZARD (planned - not implemented) - Planned: on first use in a project, the agent walks the user through every customizable area in the table above once, shows the library default for each, saves the answers to the preferences file, and from then on asks only about areas added later. Each step follows SURFACE-PREFERENCES-ON-ADOPTION (rule, why, default, keep or change). - Until it exists, agents ask one customizable rule at a time, on first encounter.