Screeps GPT Knowledge Base

This directory supplements the top-level README with deeper operational notes for the autonomous Screeps GPT
stack. Keep these documents current whenever you touch automation, workflows, or runtime behaviour—the GitHub Copilot CLI reads
them before acting.

Quick Start

For a complete setup guide, see the Getting Started Guide.

Quick reference:

1. Install prerequisites: Bun 1.0+, Node.js 18.x–22.x
2. Install dependencies: bun install
3. Run quality checks: bun run lint && bun run test:unit
4. Build & deploy: bun run build && bun run deploy

Documentation Rules

• Update the files under docs/ whenever you change automation, runtime behaviour, or operating procedures.
• Capture lessons learned from bug fixes or regressions, including links to the relevant tests.
• Cross-reference new documents from README.md or other entry points so the automation agents discover them.
• Update CHANGELOG.md in the [Unreleased] section and run bun run versions:update so docs/changelog/versions.* stays in sync.
• Preview the GitHub Pages site with bun run build:docs-site whenever you adjust documentation or changelog content.

Additional Guides

Getting Started & Setup

• Getting Started Guide - Complete setup instructions, prerequisites, development workflow, and contributing guidelines

Automation & Workflows

• Agent Guidelines - Comprehensive rules and knowledge base for GitHub Copilot and automation agents
• Automation Overview
• Spec-Kit Workflow Guide - Specification-driven development with plan generation and refinement
• Label System Guide - Standardized labeling system for issue and PR management
• Semantic Versioning Guide - Conventional commits and automated version bumping
• Push Notifications Guide - Real-time alerts for critical repository and Screeps bot events

Runtime Strategy & Behavior

• Creep Roles - Role definitions, decision trees, and performance characteristics
• Task Prioritization - Task switching, efficiency optimization, and load balancing
• Scaling Strategies - RCL progression, multi-room expansion, and CPU budgeting

Operations & Monitoring

• Memory Management - Memory patterns, cleanup strategies, and corruption recovery
• Performance Monitoring - CPU tracking, optimization techniques, and alerting
• PTR Monitoring Pipeline
• Respawn Handling
• Deployment Troubleshooting - Common deployment issues and solutions
• Workflow Troubleshooting - GitHub Actions workflow issues and fixes

Development Guidelines

• Strategy Testing - Testing methodologies, validation procedures, and benchmarking
• Safe Refactoring - Guidelines for preserving game performance during code changes
• Improvement Metrics - Measuring strategy effectiveness and detecting regressions
• Developer Onboarding Resources
• Release History

Contributions should expand these notes rather than duplicating content in ad-hoc Markdown files.

1