From 9d87372a159d00a0801e291ca6f474129797ccd6 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Tue, 7 Jul 2026 16:09:37 +0200 Subject: [PATCH] docs: capture agent workflow --- AGENTS.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5856181 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,142 @@ +# 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 +powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1 +``` + +For changed-file quick checks: + +```powershell +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: + +```powershell +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 `NodePath`s 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.