Skip to content

Agent Guidance

Screeps Lab is an architectural foundation for a private Screeps testing and orchestration environment. Treat this repository as the lab system, not as the primary colony bot.

Repository Rules

  • Keep Screeps Lab as a single monorepo.
  • Do not create nested Git repositories.
  • Do not add Git submodules without an explicit architectural decision.
  • Keep the real Screeps repository external, commonly as a sibling checkout such as ../screeps.
  • Do not commit generated server state, run artifacts, local subject checkouts, credentials, or secrets.
  • Keep Overlord independent of any one subject repository.
  • Prefer adapters and interfaces over direct assumptions about the primary Screeps bot.

Working Practices

  • Prefer narrow, testable changes.
  • Update documentation alongside architectural changes.
  • Record consequential architectural decisions in DECISIONS.md.
  • Do not claim functionality is implemented when it is only planned.
  • Run available validation before committing.
  • Do not deploy to any public Screeps environment unless explicitly authorized.

Node and Driver Snapshot Compatibility

  • Use the repository-supported Node version from .nvmrc; do not run the private-server stack with an arbitrary system Node.
  • Treat node_modules/@screeps/driver/build/runtime.snapshot.bin as a generated, V8-version-specific environment artifact, not as a Screeps MMO world snapshot.
  • Before blaming scenario logic or subject code for a V8 compatibility failure, verify or prepare the driver snapshot with the repository scripts.
  • Never edit, refresh, or invalidate an imported MMO JSON snapshot to resolve a driver V8 snapshot error.

Validation and Operator-Run Simulation Policy

  • Implement requested changes on an appropriate feature branch.
  • Run normal engineering validation before committing, including relevant unit tests, static checks, formatting or whitespace checks, and focused, deterministic integration tests.
  • Use a practical 15-minute budget for validation commands executed by an agent.
  • Short local private-server smoke checks are allowed when they are expected to complete comfortably within that budget.
  • Do not spend an extended agent session waiting for long scenario runs, regression suites, economy-cycle simulations, soak tests, or other private-server execution whose primary cost is waiting for Screeps ticks.

When meaningful validation is expected to exceed approximately 15 minutes:

  1. Validate the implementation with unit tests, fixtures, mocks, contract tests, and the shortest representative private-server gate available.
  2. Commit the focused implementation with a clean working tree.
  3. Do not run the long scenario or suite. Give the operator the exact command or commands to run manually instead.
  4. State the expected result, exit code, terminal classification, assertions, telemetry, and artifact paths the operator should inspect.
  5. Stop and await the operator's reported result before fixing follow-up failures, merging, creating or updating a baseline, or declaring the milestone fully validated.

Do not weaken scenario coverage merely to keep execution within the agent budget. Keep realistic long-running scenarios intact and delegate their execution to the operator.

Never leave a private server, scenario, or suite process running after the agent task ends. Do not deploy to the public Screeps MMO. Do not merge unless explicitly authorized after operator validation.

Overlord is a working title. Use it where helpful, but avoid treating the name as final product branding.