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.
- `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, tutorial, venues and the escalation model.
- `docs/venues.md` — Real-site evidence, game mapping and venue simplifications.
- `docs/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
- `docs/blender-assets.md` — Blender library operation and asset roles.
- `docs/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
- `docs/getting-started.md` — Setup, run/test commands, and the controls table.
- `docs/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
- `docs/adr/` — Architecture Decision Records.

## Priority and Versioning

`TODO.md` is the priority source. The active order is:

1. unversioned development tracks;
2. versioned release milestones, in version order;
3. future/unversioned candidates and deferred work.

Do not assign a version number to an unversioned track until its scope is accepted into a
release. When a version is assigned, it must be the next semantic version that matches the
scope (major/minor/patch), not a placeholder.

## Local Blender skills (development aid)

The MIT `blender-skills` pack is installed locally at `.agents/skills/blender-skills/`
(94 skills plus a shared `references/` folder). It is **gitignored on purpose**: it is not
game content, not part of the build, tests, CI or release packages, and every contributor
may or may not have it. The agent runtime (Pi) gates project `.agents/skills` behind project
trust, so the trust prompt must be accepted before the skills load; `/skill:blender-director`
forces one.

Use them when a task touches `tools/blender_assets.py`, `tools/npc_pipeline.py`,
`tools/bake_ao.py`, `assets/models/blender/**`, or Blender-authored venue/prop geometry.

### Project-authored skills (tracked)

Two project skills are committed under `.agents/skills/` and are guidance for
any agent, not only Pi:

- `gig-line-blender-asset-contract` — the NPC/gear/prop contract, build order,
  headless Blender commands, failure playbook and verification gates.
- `gig-line-release-qa` — the test/smoke matrix, visual judges, clean-worktree
  build, checksum/tag/publish sequence and release records.

They are not runtime dependencies and do not move tool implementations into
`.agents/`. The third-party `blender-skills` pack stays local/gitignored.

### Routing

Start with `blender-director` for anything multi-discipline, then load only the
specialists the task needs:

| Work | Skills |
| --- | --- |
| Plan/route a Blender task, reference photo match | `blender-director` |
| Character mesh, face, hands, proportions | `character-artist`, `character-archetypes`, `retopology` |
| Skeleton, weights, pose/contract rigging | `rigging` |
| UV layout, texel density, UDIM | `uv-workflow` |
| Bakery, atlas, normal/AO/ORM maps | `texture-workflow` |
| PBR materials and shading | `materials` |
| Screenshot-driven material/light iteration | `lookdev` |
| Triangle/vertex budgets, naming, scene hygiene | `asset-optimization` |
| LOD tiers and impostors | `lod-pipeline` |
| Collision shapes and proxies | `collision-proxy` |
| GLB export for Godot | `godot-export`, `export-pipeline` |
| Gear, props, street furniture | `prop-artist`, `hard-surface` |
| Trees, hedges, foliage cards | `vegetation-artist` |
| Facades, venues, modular kits, dressing | `environment-artist`, `archviz`, `set-dressing`, `geometry-nodes` |
| Lighting, framing, final render/composite | `lighting`, `camera-cinematography`, `rendering`, `compositing` |
| Style direction (stylized / low-poly / realistic) | `stylized-style`, `lowpoly-style`, `realistic-style` |
| Ship/no-ship review | `qa-review` |

### Project rules that override a skill

1. **The project contract wins.** `npc_base` mesh node, the 13 required core bones at their rest
   positions, five tint slots, front on Blender −Y / Godot +Z, grounded feet, 24,000
   triangles / 24,000 glTF vertices per character, 1,500 per gear, 4,000 per prop. Optional
   extra bones (fingers, face, toes) are allowed if they do not move the core rest positions. A skill
   may recommend another topology, naming or budget scheme; do not adopt it unless the
   change is explicitly planned and the contract, tests and docs are updated together.
2. **Blender MCP is optional interactive tooling.** The headless flatpak scripts
   (`tools/blender_assets.py`, `tools/npc_pipeline.py`) remain authoritative. MCP may be used
   for local part exploration; setup and safety are in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](docs/asset-tooling.md#optional-interactive-blender-mcp).
   Never add an MCP dependency to the build, CI, tests or runtime, and always re-run the CLI
   audit/fit gates on anything MCP touched.
3. **CI stays offline and skill-free.** Skills are local guidance only; every gate must still
   work from a fresh checkout with committed `.glb`/`.png`/`.tres` files and Godot.
4. **No new asset source without the licence gate.** Skills may suggest reference packs or
   generated meshes; ADR-0015 (CC0, or CC-BY with attribution in `CREDITS.md`) and the
   provenance rules in `docs/npc-model-sourcing.md` still apply.
5. **Evidence, not vibes.** After a skill-informed change, run `blender_assets.py inspect`,
   `audit` and `fit` plus the relevant capture/smoke gates, and say in the handoff which
   skills informed the change and what the measurements were.

## 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 level-2 headings (`##`) for milestones or stable themes. A milestone should state its goal
  and an explicit exit criterion; a theme groups small related work that does not need a
  milestone.
- Order level-2 sections by current priority: unversioned development tracks first, then
  versioned release milestones in version order, then future/deferred work. Do not assign a
  version number to an unversioned track until it is scheduled for a release.
- Use level-3 headings (`###`) for workstreams inside a milestone. Keep the hierarchy to three
  levels: milestone → workstream → checkbox.
- Use checkbox items for each concrete task, normally under a level-3 workstream. Direct
  checkboxes under a level-2 section are acceptable for small, single-workstream sections.
- 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:

```md
# TODO

## Milestone X.Y.Z — goal and exit criterion

### Workstream A

- [x] Completed task.
- [-] Task in progress. (claimed; implementation/verification in progress)
- [ ] Open task.

### Workstream B

- [ ] Another task.

**Exit:** a verifiable statement of what "done" means for the milestone.

## Theme

- [ ] A small housekeeping task with no milestone.
```

Recommended `DONE.md` format: a `# DONE` heading, followed by each moved level-2 section
unchanged, with a completion date line under each section heading.

Order the actual file as described in "Priority and Versioning": unversioned development tracks
first, then versioned milestones in version order, then future/deferred work.

### 3. Move Completed Sections to `DONE.md`

`TODO.md` uses nested sections. Apply these completion rules:

1. **Level-3 workstream:** verify the work, mark every checkbox `[x]`, and add a short completion
   note. Leave the completed workstream under its parent milestone; do not move an isolated
   level-3 section to `DONE.md`.
2. **Level-2 milestone/theme:** it is complete only when its direct checkboxes and **all** of its
   level-3 workstreams are complete. Verify the whole milestone, record its capabilities in
   `docs/development-status.md` when it represents shipped functionality, and write the matching
   `CHANGELOG.md` entry.
3. Move the **entire level-2 section**, including all level-3 headings and checklists, to
   `DONE.md`. Remove it from `TODO.md` and add a completion date/note.
4. **Planning/overview sections** such as a gap analysis, roadmap overview, dependencies or
   deferred ideas are not completion milestones. Do not move them merely because their checkboxes
   are empty or complete; update or supersede them as the roadmap changes.
5. Do not move partially completed milestones. Leave them in `TODO.md` until every nested task is
   complete, or split the unfinished work into a new smaller level-2 milestone first.

When a completed milestone 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.

Record items such as:

- Important design and architecture decisions
- 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
- 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. 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. 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 only for changes that remove or break an existing player-facing feature, save format, or config contract, or that replace a system listed as a core pillar in PLAN.md; bump minor for new user-facing features; bump patch for fixes and small polish.
- A version increment is not complete until its `CHANGELOG.md` entry, `config/version` update and
  matching local release build have all been produced and verified.
- 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` as a staging entry; moving it into a numbered version is a version increment and is complete only when the `config/version` update and matching local release build have also been produced and verified (see "Commit, Build and Version Discipline").

When a full executable level-2 milestone/theme 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:

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 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. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry.
8. Commit each coherent, verified change as it is completed. Do not wait until a whole
   milestone is finished; keep commits small and descriptive and push them when the branch is
   shareable.
9. If the change is a release (a major, minor, or patch version increment), follow the Release
   Procedure in "Commit, Build and Version Discipline".
10. Push committed changes to the shared repository if applicable.
11. Note the new version, build artifacts or tag in the relevant documentation and handoff
    summary.

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

### 9. Commit, Build and Version Discipline

- **Commit often.** Make a commit after each coherent change or verified task, not only when a
  milestone or release is finished. Keep the working tree clean between tasks where possible.
- **Push regularly.** Push shareable commits to the shared repository; do not accumulate a long
  local-only history.
- **Build every version.** Every major, minor and patch increment follows the Release Procedure
  below; a changelog entry alone is not a release.
- **CI is a second gate, not a substitute.** Tag builds remain automated, but the local build is
  the required pre-tag check for every version.
- **Unversioned tracks stay unversioned.** A development track does not get a placeholder
  version; the version is assigned when the work is scoped into a release.

**Release Procedure** — follow these steps in order for every major, minor, or patch version
increment:

1. Update `config/version`.
2. Write the `CHANGELOG.md` entry for the version.
3. Run the local release build (`tools/build_releases.sh`).
4. Verify the build artifacts and checksums.
5. Commit the changes.
6. Tag the version.
7. Push the commit and tag.

## 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.
- Commit coherent increments as you go; do not wait until the end of a milestone.
- Follow the Release Procedure in "Commit, Build and Version Discipline" whenever a major, minor or patch version is incremented.
- 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.
- For 3D/Blender changes: `blender_assets.py inspect`, `audit` and `fit`, the relevant capture
  gate, and a note of which local skills informed the change.
- If the local Blender skills are not installed, state "no local skills used" in the handoff
  and list the skill-free checks that were run instead.
- 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.