gamedev-the-steward/AGENTS.md

Agent working guide for The Steward

This repository is a Godot 4.7 simulation prototype. Treat it as a living systems project, not a content dump. The expected working style is:

Default development loop

1. Read the relevant roadmap/docs before changing code.
   • Start with docs/README.md.
   • Use docs/LEARNING_ROADMAP.md for the current next item.
   • Use focused plans such as docs/RESOURCE_NODE_MIGRATION.md only within their stated scope.
2. Inspect the current code and tests before assuming roadmap status is still accurate. The user often changes things in parallel.
3. Implement the smallest useful vertical slice.
   • Prefer functional systems progress over broad polish.
   • Avoid deep rabbit holes unless the current slice needs them.
   • Keep Jajce visual/design work bounded; prioritize simulation behavior, validation, WorldEnvironment ambience, and readable presentation.
4. Validate with the local quality gate.
5. Update the smallest relevant docs after completing a phase or decision.
6. Commit with a conventional commit message.

Validation

Only Godot 4.7 matters for this project.

Use the project quality gate from PowerShell:

powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1

For changed-file quick checks:

powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed

The quality scripts isolate Godot's user profile under logs/quality/godot_profile so headless Godot 4.7 can run without crashing on blocked Windows app-data paths. Do not remove that behavior.

Useful extra checks:

git diff --check

If touching main.tscn or runtime wiring, also do a direct Godot 4.7 headless boot when practical.

Architecture direction

Preserve the simulation/presentation boundary.

• Simulation state owns authority: resources, storage, NPC inventory, events, task state, target IDs, positions, RNG streams, and save records.
• World nodes are presentation and interaction geometry. They may register or bind state, but they should not become the only owner of persistent facts.
• NPCs store stable IDs, not NodePaths or node references.
• Target discovery should go through ActiveWorldAdapter and ActionTargetResolver.
• Visual movement belongs to WorldViewManager/NpcVisual; decision and task execution belong to the simulation systems.

When adding a system, first prove the contract with one real gameplay use case. Do not extract generic frameworks before multiple real consumers justify them.

Resource and target rules

Do not reintroduce abstract food/wood task-zone fallbacks.

Current resource gathering should use finite ResourceNode instances:

• food: berries, animal camps, village stock, future farms/crops;
• wood: trees, wood piles, future forestry contexts.

Resource additions should preserve:

• stable unique IDs;
• food/wood coverage;
• meaningful placement context;
• reachable interaction points;
• safety_risk, comfort_distance, and discovery_priority metadata;
• clear player interaction ranges so nearby storage/activity/resource targets do not overlap accidentally.

Storage uses StorageNode. Rest, study, and patrol use ActivitySite. Do not turn these back into generic marker zones.

Testing expectations

Add or update headless scenarios when a change affects:

• resource conservation;
• target selection or reservations;
• save/load or schema behavior;
• navigation/reachability assumptions;
• player/NPC parity;
• deterministic continuation;
• UI/debug state that represents real simulation facts.

Keep tests deterministic. Prefer fixed seeds and stable IDs.

Documentation expectations

Update docs when the implemented behavior changes the roadmap, architecture, or current contract. Keep updates local:

• docs/LEARNING_ROADMAP.md for next-item sequencing and milestone status;
• docs/RESOURCE_NODE_MIGRATION.md for resource-target migration status;
• docs/SIMULATION_STATE_SCHEMA.md for serialized state changes;
• docs/SIMULATION_DEFINITIONS.md for action/profession/ID contracts;
• docs/BUILD_IN_PUBLIC_PLAN.md for Jajce/demo/readability slices;
• docs/decisions/ only for durable architectural decisions.

Do not duplicate full status tables across many docs. If docs and code differ, trust code/tests first, then update docs.

Git expectations

Preserve user changes. Check git status --short before editing and before committing. Do not use destructive cleanup commands unless explicitly asked.

Use conventional commits, for example:

• feat: validate expanded resource discovery
• fix: stabilize godot 4.7 headless validation
• docs: capture agent workflow

Commit only after validation relevant to the change has passed.

Product taste

The project is aiming for a readable, magical simulation garden that can grow into a larger systemic game. Prefer honest visible cause-and-effect:

• NPCs should walk to real resources, storage, and activity sites.
• UI/debug overlays should explain actual simulation state.
• Beauty work should represent real state rather than fake activity.
• Each slice should leave the project easier to reason about than before.