Screeps Ralph AGENTS.md

AGENTS.md

Screeps AI Agent

Goal

Build and evolve the TypeScript bot on screeps.com through early and mid-game great filters. Reach durable survival, cold-boot recovery, full home-room energy capture, controlled expansion, then multi-room growth.

Mandatory Startup Reads

Before any work, read these wiki files for strategic context:

/workspace/wiki/INDEX.md
/workspace/wiki/great-filters.md
/workspace/wiki/maturity-matrix.md

After reading, confirm the current bot maturity level and strategic stage.

Environment

• Workspace: /workspace
• Bot code: /workspace/bot/src/
• Bot infra: package.json, rollup.config.js, tsconfig.json, jest.config.js, .eslintrc.js
• Deploy: cd /workspace/bot && npm run deploy
• Live checks: node status.js, node memdump.js --shard shard1, node reset-memory.js (wipe only)
• Room vision: node room-vision.js [room] [--shard shardN] Outputs ASCII map + JSON spatial analysis to stdout, saves PNG to /workspace/bot/room-snapshots/<room>/
• Strategy refs: /workspace/wiki/, Screeps API Docs: /workspace/apidocs/
• SCREEPS_TOKEN and DISCORD_WEBHOOK are environment variables.

Constraints

• TypeScript for in-game bot code; helper tooling can stay JS when simpler.
• Screeps runtime is Node v8 / ES2017 -- generated code must be compatible.
• Bot must recover from a full wipe using only spawn energy.
• Optimize for CPU and memory churn.
• Prefer simple moveTo improvements over complex pathing systems.
• Prefer dynamic spawning and room iteration over hard-coded constants.
• Fix all linter errors no matter where they came from before continuing, same with any other error!
• Make tests based off data from the wiki docs and follow them
• Make sure to check the map layout data/screenshot/vision to ensure things are moving around correctly, check wiki for details

Benchmark Gate

Deploy runs a benchmark against tooAngel before pushing code. Ralph must win to deploy.

If deploy fails with a benchmark error, read the result data to understand why:

• /workspace/simdata/latest-summary.txt — one-line score summary
• /workspace/simdata/runs/<run-id>/result.json — full scores, samples, tick data

Fix the bot AI to outscore tooAngel, then redeploy.

Validation

Run only the commands needed, but do not deploy without local validation.

cd /workspace/bot && npm install
cd /workspace/bot && npm run lint
cd /workspace/bot && npm test -- --runInBand
cd /workspace/bot && npm run build
cd /workspace/bot && npm run deploy
cd /workspace/bot && node status.js

Pause

echo "5" > /workspace/.STOP