s&box/field-guide
the symptom, in your words

"How we built a playable s&box game in a day with AI agents"

✓ verified on engine 26.07lane: AI-assisted workflowposted
▸ SYMPTOM

You want a repeatable way to ship a playable s&box prototype fast with AI agents — without merge chaos, fake "green" builds, or feel-tuning by guesswork.

▸ CAUSE

Long agent sessions fail when everyone edits the same files, when dotnet build is treated as ship-ready, and when feel bugs are fixed without data. The pattern that works: one strong planner/reviewer, many executors on disjoint ownership, instrument → diagnose → dial.

▸ FIX

Division of labor

RoleOwns
Planner / reviewer (strongest model)Telemetry reading, root-cause diagnosis, precise agent specs, post-land review, small surgical fixes (1–20 lines), merge + final builds
Correctness agentsPhysics/movement, animation/rig lanes, level math — feel-critical work
Mechanical agentsNew self-contained components, documented constant swaps, UI panels, well-spec'd features

Agent spec anatomy (lands green)

  1. Mandatory prep — exact files + gotcha sections to read first.
  2. Verbatim player feedback as acceptance criteria.
  3. Explicit file ownership — "Files you own / Do NOT touch" — parallel agents get disjoint sets; contested files serialize (agent-file-ownership-discipline).
  4. House rules restated — units conversion, StartedSolid, dials in a Tuning class, no unsound bone writes, etc.
  5. Verify clausedotnet build in scope; foreign errors are not yours — report, don't fix; plus a whitelist sweep (dotnet-build-vs-whitelist).
  6. Return format — diagnosis-before-fix, consts changed, deviations one-lined, HANDOFF notes for lines in files they can't touch.

Feel-tuning loop

  1. Player plays → reports feel.
  2. Read tagged telemetry from the engine console log (state transitions, stuck events, gait/facing lines — build what you need).
  3. Diagnose from data. Missing data → next task is INSTRUMENT first; never stack sign-guesses.
  4. Spec agent → land → reviewer pass → build → player restarts.

Reviewer hunts (every land)

  • Feedback loops in transform code (read what you wrote last frame).
  • Degenerate vector math (near-parallel crosses, damping ⊥ velocity).
  • Colliders vs WorldScale (capsule/model hulls don't follow scale).
  • Two systems on one input button.
  • Missing state→clip mappings.

Concurrent-session traps

  • "Everything broke" → stale-assembly-hotload first.
  • Explicit git paths only — never git add -A during multi-agent waves.
  • After ~3 stacked patches on one hot file → consolidate into one ordered pipeline, don't add a sixth patch.
  • Interrupt recovery: resume agents with partial-write context when expensive; relaunch only when context is junk.

Art/AI mesh delivery is a separate pipeline — see ai-generated-models. Keep secrets (API tokens) out of the public repo.

▸ WHY IT WORKS

Planning quality bounds execution quality; disjoint ownership removes merge thrash; telemetry turns feel arguments into dial changes; explicit whitelist/stale-assembly checks close the verification gaps that make agent waves look productive while the running game is lying.

Verified on engine 26.07 — seen in a real project.
s&box moves fast; an undated fix is a liability. Spot a stale detail?