security-game/AGENTS.md

AGENTS.md

Purpose

This document defines the development and collaboration workflow for agents and human contributors working on the security guard game.

The project should be developed in small, reviewable steps. Agents must keep planning, task status, session memory, and project documentation up to date as work progresses.

Source-of-Truth Files

• PLAN.md — The general product and game-design plan. Update it when the intended scope, mechanics, or priorities change.
• TODO.md — The active task list. Organize work into sections and use checkbox items for every actionable task.
• DONE.md — Completed task sections moved from TODO.md. Preserve the original section structure and checkboxes when moving finished work.
• MEMORY.md — Persistent session memory for important decisions, discoveries, unresolved questions, constraints, and useful implementation context.
• README.md — Root-level documentation for the project. It should explain what the game is, how to work on it, how to run it, and where to find project information.
• AGENTS.md — This collaboration and agent workflow guide.

Required Workflow

1. Start by Inspecting the Repository

Before making changes, an agent should:

• Read AGENTS.md.
• Read PLAN.md and README.md if they exist.
• Read the relevant sections of TODO.md and MEMORY.md.
• Inspect the repository structure and existing implementation before proposing changes.
• Check the current version-control status when available.

If TODO.md, DONE.md, or MEMORY.md does not exist, create it using the recommended format in this document before continuing.

Do not assume that a task is unimplemented without checking the code and documentation first.

2. Maintain TODO.md

All planned implementation work must be represented in TODO.md.

• Use headings to group related work into sections.
• Use checkbox items for each concrete task.
• Keep tasks small enough to complete and review independently.
• Add new tasks when discoveries expand the scope.
• When starting a task, claim it for the agent workflow by changing [ ] to [-]. Keep it [-] while implementation or verification is in progress; only change it to [x] after the work and relevant checks are finished. If work is abandoned or blocked, leave a clear note and return the item to [ ] (or add a follow-up task).
• Mark a task complete only after the implementation and relevant verification are finished.
• If any verification check fails, do not mark the task complete. Fix the failure, or if it cannot be fixed, add a follow-up task to TODO.md, record the failure in MEMORY.md, and report it in the handoff summary.
• Do not use prose status updates as a substitute for checkboxes.
• Revisit TODO.md regularly and mark checkbox items as complete [x] when the corresponding work is finished.

Recommended format:

# TODO

## Core Gameplay

- [ ] Add player movement controls.
- [-] Implement NPC approach behavior. (claimed; implementation/verification in progress)
- [x] Define escalation levels.

## Documentation

- [ ] Document the test procedure in `README.md`.

3. Move Completed Sections to DONE.md

When every task in a TODO.md section is complete:

1. Verify the work and update the checkbox items to [x].
2. Move the entire completed section, including its heading and checklist, to DONE.md.
3. Remove that section from TODO.md.
4. Add a short completion note or date when useful.

Do not move partially completed sections. Leave them in TODO.md until all of their tasks are complete, or split the section into smaller sections first.

4. Maintain MEMORY.md

Use MEMORY.md for information that should persist between sessions but does not belong in the general plan or task list.

Record items such as:

• Important design and architecture decisions
• Current implementation state
• Known bugs and workarounds
• Commands needed to run, test, or build the project
• Decisions that future agents should not revisit unnecessarily
• Open questions and assumptions
• Files or systems that need special care

Keep memory concise and factual. Remove obsolete entries instead of allowing contradictory notes to accumulate.

Recommended format:

# MEMORY

## Decisions

- The emergency response is a rare last-resort system, not a general combat mechanic.

## Current State

- The game-design document exists in `PLAN.md`.

## Open Questions

- Choose the game engine before implementing the prototype.

5. Maintain PLAN.md

PLAN.md describes what the project should achieve at a high level. It should contain the intended player experience, major systems, scope, and design constraints.

• Update it when the project direction changes.
• Avoid using it as a detailed progress log.
• Convert actionable implementation work from the plan into tasks in TODO.md.
• Keep the plan consistent with decisions recorded in MEMORY.md.

6. Maintain the Root README.md

The root-level README.md is the project’s public-facing technical and project overview. It should document:

• The game’s premise and current status
• The planned or implemented features
• Required tools and dependencies
• Setup instructions
• Run, build, and test commands
• Basic project structure
• Development workflow
• Links to PLAN.md, TODO.md, DONE.md, MEMORY.md, and this file where appropriate
• Known limitations and contribution guidance

Update README.md whenever setup instructions, commands, project structure, or user-facing behavior changes.

7. Implement in Small Increments

For each task:

1. Select or create a task in TODO.md.
2. Inspect the relevant files and dependencies.
3. Make the smallest coherent change that completes the task.
4. Run the relevant tests, checks, or manual verification.
5. Update documentation and MEMORY.md if the change creates lasting context.
6. Mark the task complete.
7. Move its section to DONE.md when the entire section is complete.
8. Commit the changes to the version control system with a descriptive message.
9. If a section from TODO.md has been fully completed, create a new version or tag in the version control system to mark the milestone.
10. Push the committed changes to the shared repository if applicable.
11. Note the new version or tag created in the version control system in any relevant documentation or handoff summary.

Avoid unrelated refactors unless they are required for the task or explicitly approved.

Collaboration Rules

• Prefer clear, reversible changes over broad rewrites.
• Preserve existing behavior unless the task requires changing it.
• Explain assumptions when requirements are ambiguous.
• Do not claim a task is complete without verification.
• Keep documentation synchronized with the implementation.
• Mention files changed and checks run in handoff summaries.
• Leave follow-up work as checkbox items in TODO.md rather than hiding it in prose.
• If blocked, document the blocker in MEMORY.md and add a corresponding task to TODO.md.
• Avoid overwriting another contributor’s work; inspect recent changes before editing shared files.

Verification Expectations

Before handing off work, an agent must run every check below that applies to the changed files. Automated tests and formatting/linting/type checks apply to any change to source code. A smoke test applies to any change that affects runtime behavior. Documentation-only changes require only the documentation check. Skipped checks must be listed with a reason.

• Run automated tests.
• Run formatting, linting, or type checks.
• Start the game or application and perform a basic smoke test.
• Check that documentation and task status reflect the actual state.
• Review the final diff for accidental changes or unfinished markers.

If a check cannot be run, state why and record the missing verification in MEMORY.md or TODO.md.

Handoff Format

A useful handoff should include:

• A brief summary of what changed
• Files added or modified
• Tests or checks that were run
• Any known issues or unverified behavior
• The next recommended task from TODO.md

Safety and Design Constraints

The game should emphasize observation, communication, de-escalation, and proportionate responses. Emergency assistance and weapons must remain rare last-resort mechanics with meaningful consequences, not default solutions for ordinary NPC behavior.