Tier 1 · Project setup

Customize the rules: locked vs your choice

Which rules are locked evidence and which are per-project preferences.

Markdown version

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

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 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 legal checklist distinguishes project choices from the applicable law, licence and store terms; preferences do not change those external requirements.