143 lines
5.1 KiB
Markdown
143 lines
5.1 KiB
Markdown
# 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.
|