Extend the agent workflow with docs and changelog maintenance

AGENTS.md

@@ -14,6 +14,14 @@ The project should be developed in small, reviewable steps. Agents must keep pla
 - `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.
+- `CHANGELOG.md` — The version history of user-facing changes. Keep an entry for each patch, minor, and major version.
+- `docs/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
+- `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
+- `docs/gameplay.md` — Gameplay systems, venues, and the escalation model.
+- `docs/asset-tooling.md` — Asset pipelines, model tools, and screenshot gates.
+- `docs/getting-started.md` — Setup, run/test commands, and the controls table.
+- `docs/smoke-checklist.md` — The manual smoke-test checklist.
+- `docs/adr/` — Architecture Decision Records.
 
 ## Required Workflow
 
@@ -75,6 +83,8 @@ When every task in a `TODO.md` section is complete:
 
 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.
 
+When a completed section represents shipped functionality, also record the new capability in `docs/development-status.md` so the implemented-features list stays accurate, and write a matching entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
+
 ### 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.
@@ -82,7 +92,7 @@ Use `MEMORY.md` for information that should persist between sessions but does no
 Record items such as:
 
 - Important design and architecture decisions
-- Current implementation state
+- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/development-status.md`, not here)
 - Known bugs and workarounds
 - Commands needed to run, test, or build the project
 - Decisions that future agents should not revisit unnecessarily
@@ -132,9 +142,27 @@ The root-level `README.md` is the project’s public-facing technical and projec
 - 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.
+Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
 
-### 7. Implement in Small Increments
+### 7. Maintain `CHANGELOG.md`
+
+The root-level `CHANGELOG.md` records the user-facing changes for every release. It exists so players and contributors can see what changed between versions without reading the commit log.
+
+- Add an entry for every patch, minor, and major version change.
+- Follow Semantic Versioning (`major.minor.patch`): bump major for breaking or vision-level changes, minor for new features, and patch for fixes and small polish.
+- Group each entry under `Added`, `Changed`, `Fixed`, and `Removed` headings, and date every entry.
+- Describe changes in user-facing terms, not as raw commit messages.
+- Add the entry when its work ships. If the version number is not yet known, record it under `Unreleased` and move it into a numbered version when the version is tagged.
+
+When a full level-2 section in `TODO.md` is implemented, completed, and moved to `DONE.md`:
+
+1. Verify the work and mark every checkbox in the section `[x]`.
+2. Use the section heading and its completed items to describe the changes and write a `CHANGELOG.md` entry under the next appropriate version.
+3. Move the section to `DONE.md`.
+
+Do not move a completed section to `DONE.md` without adding its `CHANGELOG.md` entry.
+
+### 8. Implement in Small Increments
 
 For each task:
 
@@ -142,11 +170,11 @@ For each task:
 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.
+5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
 6. Mark the task complete.
-7. Move its section to `DONE.md` when the entire section is complete.
+7. Move its section to `DONE.md` when the entire section is complete (after recording its `CHANGELOG.md` entry).
 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.
+9. If a section from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` entry is in place, then 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.