Roblox Change Control

Roblox Change Control (firebit house rules)

Overview

firebit game repos are wired directly to the live game: a GitHub workflow deploys on push, and a monetization sync tool mints real products for real money. Several ordinary-looking actions therefore have real-money or live-player consequences. This skill is the canonical statement of the four owner hard rules, the taxonomy of change types with their gates, and the enforcement hooks that back them. Rules were confirmed by the owner 2026-07-05 in the firebit house-stack reference project and apply to every project on the house stack.

When to use

• Before any git push, git commit, merge, or branch operation.
• Before running rblxsync in any mode, or editing rblxsync.yml / rblxsync-lock.yml.
• Before deleting, refactoring, or "cleaning up" code that looks unused.
• Before changing any number in src/Shared/Data/ (costs, rewards, durations, HP, spawn rates, XP curves).
• When a PostToolUse hook blocks an edit or injects a plan/board reminder and you want to know why.

When NOT to use

• Deciding how to run builds, rblxsync, or asphalt operationally → roblox-run-and-operate.
• The evidence bar for a tuning change (what counts as proof) → roblox-research-methodology; analysis recipes → roblox-proof-and-analysis-toolkit.
• Which flags/config axes exist and how to add one → roblox-config-and-flags.
• The plan/board lifecycle procedure itself → the project's CLAUDE.md owns it (statuses, checkbox timing, archive steps). This skill only explains why it exists and what happens when it is skipped.

The four hard rules (owner-confirmed 2026-07-05)

Rule 1 — NEVER push to origin main or production

Why: the boilerplate .github/workflows/deploy.yml triggers on push to branches main and production. It runs npm run build:deps, resolves universe/place IDs from repo variables (DEV_* for main, PRODUCTION_* for production), then runs rojo upload for each place project (e.g. lobby.project.json, level.project.json) — publishing the places straight to Roblox. A push IS a deploy. There is no staging step, no approval gate.

Verify in the current project before assuming an exception:

sed -n '1,12p' .github/workflows/deploy.yml
grep -n "rojo upload" .github/workflows/deploy.yml

Practice: commits stay local. Local main being ahead of origin/main is often deliberate, not drift — check git status -sb before "helping". Commit only when the owner asks; push only when the owner does it or explicitly asks you to.

Rule 2 — NEVER run rblxsync run against the live universe

Why: rblxsync matches resources by case-sensitive NAME — the manifest header in rblxsync.yml states that a name that doesn't match what's live on Roblox will create a duplicate live product on sync. Badge creation costs 100 Robux each (a Roblox platform fee), charged to the account named in badge_payment_source — typically the owner's personal account. A run mints real Developer Products, Game Passes, and Badges that cannot be un-minted.

Agents MAY: edit rblxsync.yml, run rblxsync validate, run rblxsync run --dry-run. Owner-only: rblxsync run (and rblxsync export, which needs live credentials). Exception: the owner explicitly requests the run in this session.

Verify the stakes in the current project:

sed -n '1,20p' rblxsync.yml
grep -n "badge_payment_source" rblxsync.yml

Rule 3 — NEVER refactor, "clean up", or delete flag-gated dormant code

Code gated off behind a false flag in src/Shared/Class/FeatureFlags.luau is dormant by decision, not dead by accident. It often has live Roblox products still attached to it (declared on Roblox but intentionally absent from rblxsync.yml), and it is the re-enable path for a shelved feature. Deleting it strands live products and destroys that path.

Before touching anything that looks unused:

grep -nE "= false" src/Shared/Class/FeatureFlags.luau
grep -rn "<FlagName>" src/   # find what the flag gates

If dead-looking code blocks your task, mention it in your report; do not remove it.

Case study (shipped firebit game, 2026): an entire earlier era of the game — base-building, minigames, a player market — remained in the repo behind false flags, with its monetization products deliberately left out of rblxsync.yml so they'd stay live-but-untouched on Roblox. Any "dead code cleanup" pass would have stranded real purchased products and erased the re-enable path.

Rule 4 — NEVER change economy/difficulty/tuning numbers on a guess

Every tuning change requires three things stated in the plan file before the edit:

1. Rationale — why this number, not just "feels wrong".
2. Predicted metric — what should move, in which direction, by roughly how much.
3. Evidence path — telemetry field or playtest scenario that will confirm or refute it.

The evidence bar and hunch→result discipline live in roblox-research-methodology. Tuning surfaces are the *Data.luau and constants modules under src/Shared/Data/ (session/day-cycle config, reward tables, difficulty curves, NPC stats) and the prices in rblxsync.yml. "Placeholder — tune freely" comments in code lower the stakes but do not waive the rationale requirement.

Change taxonomy

Committing (any class): only when the owner asks. Working-tree changes accumulating uncommitted on local main is a normal state in these repos.

Enforcement that already exists — hooks are not noise

.claude/settings.json in each project wires real enforcement. When a hook fires, it is telling you something specific:

Confirm the wiring in the current project: jq '.hooks' .claude/settings.json.

Why the plan/board discipline exists (failure evidence)

The project's CLAUDE.md owns the rules (plan before code, check boxes same-turn, archive on done). The reason they are non-negotiable is observed drift, not theory.

Case study (shipped firebit game, 2026-07): an audit found zero plans ever archived despite multiple Done-lane board cards; of 33 plan files only 5 were active, roughly 10 were stale — shipped features with unchecked boxes, a plan referencing a file that no longer existed, and diagnosed bugs on no board lane at all. Each skipped same-turn update compounded into a board nobody could trust.

Audit your own project's drift the same way:

ls -la docs/plans/archive/
grep -L "status: done" docs/plans/*.md | xargs grep -l "\[x\]" 2>/dev/null   # checked boxes, not archived
grep -l "status: active" docs/plans/*.md

That drift is exactly what "a plan file that disagrees with reality is a bug" means in practice.

Rationalization table

Red flags — thoughts that mean STOP

• "It's just a tiny push."
• "I'll sync rblxsync to be helpful."
• "This legacy code is dead anyway."
• "This number is obviously wrong."
• "No one will notice if I skip the plan file this once."
• "I'll rename this product to something cleaner."
• "The hook is being annoying, I'll work around it."

If any of these appear in your reasoning, stop, re-read the matching rule above, and either take the agent-safe portion (edit + validate + dry-run + plan note) or report the blocker to the owner.

Common mistakes

• Treating rblxsync run --dry-run success as license to run the real sync. It is not.
• Editing rblxsync-lock.yml or src/Shared/Data/Monetization/Generated.luau by hand — both are tool-written outputs (Generated.luau says "Do not edit").
• "Fixing" or loosening scripts/luau-analyze-hook.sh to make a failing edit pass.
• Creating a new .luau file and then fighting the hook — regenerate the sourcemap instead (roblox-build-and-env).
• Renaming a product in rblxsync.yml to match code style — name IS identity; change code to match the yml, or flag it for the owner.
• Interpreting "commits stay local" as "never commit" — commit when the owner asks; just never push.

Provenance and maintenance

Derived 2026-07-05 from the firebit house-stack reference project; the rules are standing convention for all firebit projects. Re-verify the volatile facts against the CURRENT project repo before relying on them:

# Rule 1: deploy trigger and what it publishes
sed -n '1,12p' .github/workflows/deploy.yml && grep -n "rojo upload" .github/workflows/deploy.yml
# Rule 2: name-matching warning and badge fee source
sed -n '1,20p' rblxsync.yml && grep -n "badge_payment_source" rblxsync.yml
# Rule 3: which flags are off, and what they gate
grep -nE "= false" src/Shared/Class/FeatureFlags.luau
# Hooks still wired
jq '.hooks' .claude/settings.json
grep -n "exit 2" scripts/luau-analyze-hook.sh
# Local-vs-origin state before any commit talk
git status -sb | head -1 && git log origin/main..main --oneline
# Plan-discipline drift
ls -la docs/plans/archive/ && grep -l "status: active" docs/plans/*.md