diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8c86bd6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,220 @@ +# AGENTS.md + +## Purpose + +This file defines the rules, expectations, and constraints for **automated agents** +(including AI coding assistants, LLMs, bots, and scripted tools) contributing to this +codebase. + +The goal is to: +- Preserve long-term maintainability +- Avoid licensing and provenance risk +- Prevent architectural drift +- Ensure consistency with established design decisions +- Make human review straightforward and reliable + +All automated agents MUST comply with the requirements in this document. + +--- + +## Scope + +This repository is a **C-based MUD engine** derived from CircleMUD/tbaMUD and is +under active development, including significant refactors to core systems such as: + +- Skills and proficiency +- Combat resolution +- Object and mobile data models +- Online Creation (OLC) +- Persistence and serialization +- Builder and immortal tooling + +Changes often have **far-reaching consequences** across gameplay, balance, and +world data integrity. + +--- + +## General Rules for Automated Agents + +### 1. No Unreviewed Structural Changes + +Automated agents MUST NOT: +- Reorganize directories +- Rename files +- Merge or split source files +- Introduce new subsystems +- Replace existing systems wholesale + +Unless **explicitly instructed** to do so. + +Incremental, targeted changes are required. + +--- + +### 2. Preserve Existing Behavior Unless Directed + +If a function, macro, or subsystem already exists: +- Do NOT change semantics +- Do NOT “simplify” logic +- Do NOT remove edge-case handling +- Do NOT refactor stylistically + +Unless the user **explicitly requests** that behavior be changed. + +Backward compatibility is a priority. + +--- + +### 3. Minimal Diffs Are Mandatory + +Automated agents must: +- Change only what is necessary +- Avoid drive-by formatting edits +- Avoid re-indentation unless required +- Avoid renaming variables unless necessary for correctness + +If a fix can be achieved with a 3-line change, a 30-line rewrite is unacceptable. + +--- + +### 4. Follow Existing Code Style Exactly + +This codebase intentionally reflects legacy CircleMUD conventions. + +Agents MUST: +- Match indentation style +- Match brace placement +- Match naming conventions +- Match macro usage patterns + +Do not introduce modern C idioms, new abstractions, or stylistic preferences. + +--- + +## Licensing and Provenance Requirements + +### 5. No Third-Party Code Injection + +Automated agents MUST NOT: +- Paste code from external projects +- Introduce snippets from blogs, gists, StackOverflow, or forums +- Reproduce code from GPL-incompatible sources + +All code must be **original**, **derivative of existing repository code**, or +**explicitly authorized** by the user. + +If uncertain, ask before proceeding. + +--- + +### 6. Do Not Assume License Changes + +Do NOT: +- Modify license headers +- Remove attribution +- Add new license files +- Assume relicensing is permitted + +Licensing is handled deliberately and conservatively. + +--- + +## Technical Expectations + +### 7. Full-Context Awareness Required + +Before modifying a subsystem, automated agents MUST: +- Read all related `.c` and `.h` files +- Identify existing macros, helpers, and patterns +- Understand how data flows through the system + +Guessing or partial understanding is not acceptable. + +--- + +### 8. Prefer Existing Helpers and Macros + +If functionality already exists: +- Reuse it +- Extend it minimally if needed +- Do not reimplement logic elsewhere + +Duplication increases maintenance cost and risk. + +--- + +### 9. Explicitly Note Assumptions + +When producing code or recommendations, agents MUST: +- State assumptions clearly +- Identify uncertainties +- Call out areas that require human confirmation + +Silent assumptions are dangerous. + +--- + +## Data Integrity and World Safety + +### 10. Protect World Files and Player Data + +Automated agents must treat: +- World files +- Player files +- OLC data +- Serialized objects/mobs/rooms + +As **production data**. + +Do NOT: +- Change file formats casually +- Break backward compatibility +- Introduce implicit migrations + +Any data format change must be explicit and documented. + +--- + +## Communication Expectations + +### 11. Be Direct and Precise + +Agent output should: +- Use technical language appropriate to experienced developers +- Avoid verbosity for its own sake +- Avoid motivational or conversational filler +- Focus on correctness and clarity + +--- + +### 12. Ask Before Acting When Uncertain + +If instructions are ambiguous or risky: +- STOP +- Ask clarifying questions +- Do not guess intent + +Incorrect confidence is worse than delay. + +--- + +## Enforcement + +Failure to comply with this document may result in: +- Rejection of changes +- Reversion of commits +- Loss of permission to contribute + +This applies equally to humans and automated agents. + +--- + +## Summary + +This codebase prioritizes: +- Stability over novelty +- Clarity over cleverness +- Intentional design over convenience + +Automated agents are welcome collaborators **only** when they operate within +these constraints.