AGENTS.md@examples/platformer/panda-adventure git:20260716.394f863A

Immutable. This exact content is served forever at /api/v1/blob/5934703d8e6ceb36.

This directory is **Panda Adventure** — a 2D-platformer game demo, built with `gda`
(see the `/gda` Skill) by driving the Godot Engine. It is a subproject of the parent
`godot-agent` repo, but a **different domain**: its shared language is about the game
(pandas, gravity guns, enemy waves), not about `gda`'s CLI, daemon, or headless runners.

## Inherited from the repo root

Align with the repo-root `AGENTS.md` for everything **except domain docs**:

- `RULES.md` — communication & collaboration conventions.
- Issue tracker — game issues go to the same `aigengame/godot-agent` tracker, with titles
  prefixed **`[Panda Adventure]`** to distinguish them from `gda`-tool issues. (The prefix is for
  **game-self** issues only; `gda`-feedback issues are filed **unprefixed** — see *gda feedback*
  below.) See the repo-root `../../../docs/agents/issue-tracker.md` (these docs are inherited, not
  duplicated here).
- Triage labels. See the repo-root `../../../docs/agents/triage-labels.md`.

## Agent skills

### Domain docs (local override)

**This section is the game domain's local convention** — the repo root routes domain
contexts via `CONTEXT-MAP.md` and delegates each non-root domain's layout and override
rules to its own `AGENTS.md`, i.e. here. The game's domain context is confined to this
directory and must **not** pollute the parent's docs.

Local layout (analogue of the parent's):

| Parent (gda domain) | Here (game domain) | Holds |
|---|---|---|
| `CONTEXT.md` | `GAME-CONTEXT.md` | the game's shared language / glossary |
| `docs/adr/NNNN-*.md` | `docs/gadr/NNNN-*.md` | game decision records (gADR), same numbering |
| — | `docs/gdd/` | committed game design doc(s) |

**Skill remap.** The domain skills hardcode `CONTEXT.md` / `docs/adr/` as literals. When you
run one **inside this subproject**, restate and apply this remap before acting:

- any skill's `CONTEXT.md` → `GAME-CONTEXT.md`
- any skill's `docs/adr/` → `docs/gadr/`
- `CONTEXT-MAP.md` → not applicable (single local context — ignore)

Applies to `grill-with-docs`, `improve-codebase-architecture`, and `reconcile`. `to-prd` /
`to-issues` already defer abstractly to "the project's domain glossary" — point them here.

**Isolation boundary.** Never **write** game terms or decisions into the parent root `CONTEXT.md`
or `docs/adr/` — game-domain language and decisions live only under this directory. You **may
read** the parent `gda` docs when the work concerns the `gda` tool itself (its CLI, schema, daemon,
or `logger` protocol); just don't treat them as the game's domain authority.

See `./docs/agents/domain.md` for the authoritative detail.

## Development conventions

- **Architecture** — layered (Resource / Controller / CanvasItem) and data-driven, with JSON as
  the single authoritative config source converted to Godot `Resource`. See `docs/gadr/0000-architecture-design.md`.
- **Logger-based feedback development** — game code logs at module (and key function) entry/exit so
  the agent can observe runtime behavior in a closed loop — enough to trace behavior, not noisy
  per-call spam. Log output conforms to the `gda logger tail` protocol so the agent can parse it.
- **The gda daemon harness is COMMITTED** (`addons/gda_harness/` + the `GdaHarness` autoload in
  `project.godot`) — intentionally, not stray tool state. gda normally installs it on `gda daemon
  start` and treats it as transient, but that install mutates the *tracked* `project.godot`, and the
  autoload line can't be gitignored, so leaving it uncommitted means a manual revert every session
  (easy to forget → drift). Committing it makes `daemon start` an idempotent content-match **no-op**
  (zero working-tree churn), and it never reaches a build: `gda export run` snapshot-strips it and
  restores the project byte-for-byte (ADR-0028), and it stays dormant in a plain run. **Don't delete
  it or run `gda daemon uninstall`.** On a gda upgrade `daemon start` may re-materialize a newer
  harness — commit that diff to keep it in sync.
- **Keep the local export fresh** — `build/PandaAdventure.app` is a LOCAL, gitignored export
  artifact (`gda export run --preset macOS`), never committed — but human playtests run it, and a
  stale build once misled one (#401). **Re-export at wave close** (part of the closing slice's DoD)
  and smoke it: the app boots and logs `hud_ready` (release templates don't flush stdout per print —
  read it through a pty, or just launch it and look). See gADR-0007's consequences.
- **Opening scenes in the Godot GUI can uid-ify the tracked `.tscn`/`.tres`** — gda authors scenes and
  resources uid-free, referencing everything by `res://` path (deterministic, self-contained; parent
  `../../../docs/adr/0036-authored-scenes-reference-by-path-not-uid.md`). Opening the project in the
  desktop Godot editor to **view / run / inspect** is fine and expected — it writes only gitignored
  caches (`.godot/`, `*.uid`), so **no tracked drift**. But **saving** a scene in the GUI (Ctrl+S)
  re-serializes it into Godot's canonical form — adding `uid="uid://…"` to headers + `ext_resource`,
  reshuffling the `1_…` ids — which diverges from gda's byte-deterministic output. This is **not a
  breakage** (uid-ized files still load/run/export) and using the GUI is your call — it is **not
  forbidden and there is no guard hook** (a concurrent human editor is undefended, not prohibited:
  parent ADR-0018). Handling is **awareness + recovery**, not prevention: for view/run, just don't
  save; if you saved and don't want the churn, `git checkout` the affected `.tscn`/`.tres` (and any
  reimported `assets/**/*.import`) — the gda-authored form is the source of truth; a stray `uid=` in a
  tracked scene is the tell that someone saved in the GUI. To actually **change** content, prefer the
  in-game editor (`scenes/editor.tscn`, `S = save+derive`) or gda, both of which keep the source
  deterministic.

## gda feedback (dogfooding)

Building this demo is also a way to **validate and improve `gda`**: driving the tool surfaces real
gaps. Whenever you hit one while developing the game, **proactively file it as a separate issue** on
the `aigengame/godot-agent` tracker so the demo doubles as a `gda` quality signal. Categories:

- **Quality defect** — a `gda` capability that is claimed but unusable or behaves incorrectly.
- **Feature improvement** — a `gda` capability that works but is incomplete or awkward.
- **Performance** — a `gda` capability that works but is slow/janky.
- **New-feature need** — a capability `gda` lacks that would meaningfully speed up development.

These are **`gda`-tool issues, not game issues** — file them as regular `gda` issues **without** the
`[Panda Adventure]` prefix, so they land in the tool's own issue view rather than the game's.