docs: capture agent workflow

2026-07-07 16:09:37 +02:00
parent b74573fe0e
commit 9d87372a15
1 changed files with 142 additions and 0 deletions
@@ -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.