Imported from nacretion/aureole (AGENTS.md). Install upstream with npx skills add nacretion/aureole. Copyright stays with the author.

AUREOLE Development Contract

Product

AUREOLE is a single-player real-time-with-pause strategy and management game about restoring a damaged Dyson sphere, supporting a growing native civilization, and financing development through interstellar tourism.

The immediate objective is a compact vertical slice, not the full game.

Required workflow

Before editing:

1. Read the relevant files in docs/.
2. Inspect existing implementation and tests.
3. State a minimal file-level plan.
4. Identify scope risks.
5. Prefer the smallest complete change.

After editing:

1. Run python3 tools/doctor.py.
2. Run relevant EditMode tests when Unity is available.
3. Run PlayMode tests when Unity behaviour changed.
4. Report exact commands and outcomes.
5. Never claim a test passed unless it was executed.
6. Update documentation when architecture or observable behaviour changed.

Dependency direction

Presentation -> Application -> Simulation
Editor may depend on all runtime assemblies.
Tests depend only on the assembly under test and test framework.

Aureole.Simulation must never reference:

• UnityEngine
• UnityEditor
• MonoBehaviour
• GameObject
• ScriptableObject
• scene objects
• frame time
• global mutable state

Simulation

• One simulation tick represents one in-game hour unless an ADR changes it.
• Simulation advances through explicit commands or runner steps.
• Fixed simulation ordering must be visible in code.
• Random behaviour requires an injected seeded source.
• Never read wall-clock time inside simulation.
• Never use DateTime.Now, Random.Shared, Unity random, or hidden global state.
• All simulation state must be serializable without Unity object references.
• Every simulation bug fix requires a regression test.

Language compatibility

• Unity 6000.3 uses C# 9.0.
• Use block-scoped namespaces; file-scoped namespaces are C# 10 and forbidden.
• Avoid init-only setters unless the required compatibility shim is explicitly approved.
• Prefer conservative syntax that Unity and IL2CPP both support.

Unity

• Keep business logic out of MonoBehaviour.
• Do not use FindObjectOfType, global scene searches, or implicit singleton discovery.
• Prefer private serialized fields for presentation references.
• Do not create a singleton without a recorded architecture decision.
• Do not hand-edit scenes or prefabs as YAML.
• Use Editor scripts for repetitive asset and scene creation.
• Preserve .meta files after Unity generates them.
• Avoid per-frame allocations in hot presentation paths.

Content

• Runtime simulation receives immutable plain C# definitions.
• ScriptableObject may be used only as authoring data and must be converted at the application boundary.
• Do not hardcode content balance in presentation classes.
• Stable content identifiers must not depend on localized names or asset paths.

Testing

New simulation behaviour must cover:

• normal operation;
• zero and boundary values;
• insufficient resources where relevant;
• save/restore where state is persistent;
• deterministic replay where events or randomness are involved.

Tests must express game rules, not implementation details.

Scope control

Do not add speculative frameworks for future systems. Do not add packages unless the active task requires one and the user approves it. Do not expand a milestone into economy, population, tourism, politics, research, or ECS unless explicitly requested.