184 lines
7.5 KiB
Markdown
184 lines
7.5 KiB
Markdown
# 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.
|
||
- 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:
|
||
|
||
```md
|
||
# TODO
|
||
|
||
## Core Gameplay
|
||
|
||
- [ ] Add player movement controls.
|
||
- [ ] Implement NPC approach behavior.
|
||
- [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:
|
||
|
||
```md
|
||
# 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.
|
||
|
||
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.
|