Skip to main content

ADR 0057: Use Small-Batch Agent Branches And Separate Release Identities

Status​

Accepted.

Context​

The Stage Director's Flow controls which work is Ready, and layered quality gates control the evidence needed before a checkpoint. Neither decision specified how mutating agents isolate work, how Unity-authored assets avoid unsafe concurrent edits, how accepted changes integrate, or how a source checkpoint relates to a release version and exact build.

The Circussy One history showed both sides of the problem. Tight human-agent loops, diagnostics, rollback, and coherent checkpoints produced accepted results. Long correction chains and overlapping changes made causality, ownership, and recovery expensive. A solo owner does not need GitFlow, mandatory sprints, story points, or a multi-maintainer bureaucracy, but agents still need stronger isolation and integration rules than informal chat.

Semantic Versioning alone cannot identify an exact binary or independently version save and content contracts. Automatic releases would also transfer a human product decision to commit syntax.

Decision​

Recommend a human-directed trunk-based workflow for agent-assisted game projects:

  1. map one Ready work item to one short-lived branch and isolated worktree;
  2. use one mutating agent by default and bounded, path-disjoint parallel mutation only when direction, ownership, dependencies, and prompt review are clear;
  3. declare owned and exclusive paths, treating shared Unity serialized assets, settings, middleware projects, and generated asset families as exclusive by default;
  4. use one canonical Unity integration Editor and merge Unity-owning changes serially;
  5. prefer one coherent squash merge per work item, followed by an integrated production-consumer smoke on main;
  6. use Conventional Commit syntax as optional machine-readable change language, not as automatic product authority;
  7. keep product release version, exact build identity, and data contract versions separate; and
  8. make release automation proposal-only until a human approves version, changelog, tag, build, and publication boundaries.

For a solo director, at most two simultaneous mutating agents is the default STAGE recommendation. It is a practical attention bound, not a universal empirical threshold.

The detailed operational guidance lives in Change, Concurrency, And Release Workflow. The decision remains practitioner guidance and does not add a universal artifact contract to SPEC.md.

Consequences​

  • Concurrent agents gain explicit isolation without requiring a heavyweight tracker or permanent integration branch.
  • Unity scene, prefab, configuration, audio, and generated-asset conflicts are prevented primarily through ownership rather than repaired after overlap.
  • The owner can trace one accepted work item to one reversible mainline change.
  • Exact revisions and build receipts, rather than SemVer alone, support regression diagnosis.
  • Release proposals can be automated while release authority remains human.
  • Parallel throughput is intentionally limited by human review and integration capacity.
  • Worktrees consume additional disk, and Unity worktrees may require separate imports and Libraries.
  • Projects with proven merge-safe ownership may deliberately narrow these defaults.

Rejected Alternatives​

  • Direct mutation on main by default: too little isolation for autonomous or concurrent work.
  • GitFlow and permanent develop: too much ceremony and delayed integration for the owner's small-batch workflow.
  • Unrestricted parallel agents: creates review, contract, and Unity asset contention faster than a solo owner can resolve it.
  • UnityYAMLMerge as the collaboration model: syntactic merge does not prove intended serialized state or runtime behavior.
  • Automatic version and publication on every merge: confuses checkpointing with human release acceptance.
  • One version for product, build, saves, content, and schemas: cannot express independent compatibility or reproduce an exact binary.

Evidence Boundary​

Short-lived branches, frequent integration, worktrees, protected mainlines, Conventional Commits, Semantic Versioning, and release proposals are established software practices. The Unity ownership and serial integration rules are conservative applications of serialized-asset and editor-state risks. Their combination with STAGE's Director authority is a practitioner proposal derived primarily from one owner's projects. It has not been shown to be an optimal universal game-development workflow.

Last updated on