# 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.