gig-line/AGENTS.md

AGENTS.md

Working rules for autonomous agents, AI coding assistants, and contributors. Planned work is tracked in TODO.md; development direction is in ROADMAP.md.

Project Goal

Develop and test on Linux; ship Windows and Linux builds, with Linux as the primary development and CI platform. The game supports walking and driving through a real city. The initial release is 0.1.0: a walkable exterior demo around 6840 Hollywood Blvd / El Capitan Entertainment Centre, including buildings on the south side of Hollywood Blvd between Highland Avenue and Orange Drive, plus buildings whose footprint lies within 50 m of the north-side frontage.

• Verify the address, building footprints, and demo boundaries before modeling.
• If the address, footprint, or boundary cannot be verified from permitted sources, do not model that structure. Record the unresolved item in Geo/ with the sources checked and continue with verified structures only.
• Treat similarly named venues as distinct structures where source data indicates; do not merge footprints by assumption.
• use available research and reference data in local project /run/media/system/DATA/Documents/06-games/security-game/.

Toolchain

Tool	Role
Unreal Engine	Rendering, gameplay, World Partition, Chaos Vehicles
Blender	Modeling, UVs, baking, collision meshes, character prep
MPFB	Human base meshes; baked materials, deform skeletons
QGIS	Geographic cleanup, coordinate conversion, elevation prep
Blosm	OSM building/street blockouts in Blender
Git + Git LFS	Source control, large assets, tagged releases

• Pin compatible versions in Docs/toolchain.md.
• Validate Blender→Unreal mesh, skeleton, material, and scale transfers before producing assets.

Repository Layout

• Game/ — Unreal project, configuration, source, game-ready content.
• Art/ — editable Blender files and original textures.
• Geo/ — source manifests, permitted geographic data, processing scripts.
• Tools/ — repeatable import/export helpers.
• Docs/ — setup, licenses, architecture, release checks.

Git/LFS rules:

• Track .uasset, .umap, .blend, and large source binaries with LFS.
• Ignore Binaries/, Intermediate/, Saved/, and Derived Data Cache.
• Never commit Unreal Engine source, credentials, or non-redistributable assets.
• Active remote repository (origin): https://git.allucanget.biz/zwitschi/gig-line.git. Verify connectivity before use.

Release Policy

Semantic Versioning: MAJOR.MINOR.PATCH.

• Each major milestone → minor release (e.g. 0.2.0, possibly as 0.2.0-alpha.1 first).
• Each release containing only bug fixes, performance changes, documentation, or tuning of existing features → patch release (e.g. 0.2.1). Any new feature, map area, or asset category → minor release.
• Patches contain fixes, optimization, docs, or refinements only — never new scope.
• Tag as vX.Y.Z; maintain CHANGELOG.md.
• During 0.x, document breaking changes and asset migrations.
• 1.0.0 marks the stable, agreed game scope — not completion of a whole city.

Roadmap and TODO

The two files have separate roles:

• TODO.md is the single, central task list for all agents: checkbox items, progress marks, and active-section ownership. Put all planned actionable work and follow-ups there. Do not create parallel task lists elsewhere.
• ROADMAP.md holds the development plan: milestone goals, scope, decisions, and release gates for each version. It is a planning document and contains no checkbox items. Read it for future direction; record scope changes there as prose, and record the resulting tasks in TODO.md.

Rules for TODO.md:

• Mark items open (- [ ]), active/in progress (- [A], deferred - [D]), or done (- [x]). Keep the marks accurate.
• When working on a level-three (###) section, append - active - <sessionId> to its heading, using your current session ID. Remove the suffix when you stop working on that section. Mark the items you are working on - [A] or - [D].
• Existing in-progress marks can describe unfinished work, not necessarily a live session; use the active heading and assignment details to identify current ownership.
• Each version is a ## heading; task groups are ### headings with - [ ] steps.
• When all steps in a version section are done: write a short descriptive entry to CHANGELOG.md, remove the version section from TODO.md, and leave its goal in ROADMAP.md.
• Release checks for each version are listed at the end of its TODO.md section; Docs/release-checks.md defines the checks themselves. If a check fails, do not tag the release; open a patch task in TODO.md and report the failing check in CHANGELOG.md.
• Finish each milestone's release checks before expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience.
• Realism leads, performance is a floor. When a realism improvement costs frame time, realism wins and the cost is paid — but 60 FPS at 1440p without frame generation must still be met at every release. If realism cannot fit the budget, reduce the realism scope deliberately and record it in CHANGELOG.md; never ship below the floor without the owner's approval. Walkability outranks realism in one direction only: a block the player falls through is not a demo.

Git workflow

Every agent works on a dedicated git branch. Never commit work directly to main (except the coordinator's integration merges).

Before starting any task:

1. Scan TODO.md and pick a task — a level-three (###) section — to work on. Use ROADMAP.md for the goal and scope of the version you are working in. Prefer sections that are already active (they may be yours) or open items in sections that are not owned by another agent. Check the active heading and assignment details to identify ownership.
2. Create a branch for that task from the current main: git checkout -b <topic>-<version> (e.g. git checkout -b facade-hero-0.1.4). One branch per task; do not stack unrelated tasks on one branch.
3. Record the active branch in the heading of the section you are working on in TODO.md: append - active - <sessionId> (and, if useful, the branch name) to the level-three heading. This is the only way other agents can see that work is in progress on this section.
4. Commit changes often on that branch — small, focused commits with clear messages. Do not accumulate large uncommitted changes.
5. Push to remote when a checklist item is done — each completed - [x] item in that section should be committed and pushed. This keeps the remote state visible and makes progress recoverable.
6. When the section is complete, report the branch, changes, checks, and unresolved issues to the coordinator for integration (see Parallel agent workflow below). Do not merge into main yourself unless authorized.

Branch hygiene:

• Branch from the current main revision, not from a stale local checkout.
• Keep TODO.md checkbox updates on your branch — they are part of the work.
• If a task needs a different camera angle, or affects visual review, follow the Visual review section before pushing.
• If a task is abandoned, remove the - active - <sessionId> suffix from the heading in TODO.md and leave the branch for the coordinator to clean up.

Parallel agent workflow

• Designate one coordinator to serialize assignments, updates to the shared TODO.md, and integration into main. Agree on task and file or asset ownership before work starts; avoid assigning the same section or binary asset to multiple agents at once.
• The coordinator records the session ID, branch name, and owned files or assets alongside the active TODO.md section on the shared main coordination copy. Publish and synchronize this state through the remote when agents use different machines. Branch-local changes are not visible to other worktrees until integrated; TODO.md is not an atomic lock.
• For parallel implementation, use a separate branch and Git worktree per agent, based on the agreed main revision. Do not switch branches in a directory another agent is using. Create branches, commits, pushes, and merges only when authorized; never overwrite another agent's uncommitted work.
• Keep ignored local references, generated files, build outputs, and Unreal editor processes in mind: worktrees do not automatically share ignored files, and shared output paths or concurrent editors can collide. Arrange required inputs and isolated outputs before running tools.
• Blender and Unreal binary assets cannot be meaningfully merged like text. Give each asset one owner; use Git LFS locks when supported by the remote, but do not assume locking is available.
• When work is ready, report the branch, changes, checks, unresolved issues, and relevant memory findings to the coordinator. Review and integrate branches into main one at a time, reconcile TODO.md and memory changes, and update ownership and status. Follow the visual review and user-approval requirements before marking visual work done.

Memory

MEMORY.md is shared session memory for agents and collaborators. Write to it whenever you:

• discover a fact about the environment, a tool, or a data source that cost time to establish;
• hit a gotcha, trap, or surprising failure mode, and what actually caused it;
• find or fix a bug, and how it was found so it can be found again;
• make a decision that does not fit a TODO.md item, such as a workaround, an assumption, or a rejected approach and why. Record scope or direction decisions in ROADMAP.md as prose.

Keep entries short and dated, with the evidence: the command, the log line, or the file path. Anything that belongs in a formal document (setup steps, tool versions, licensing) goes in Docs/ as well — memory is for coordination, not a replacement for the record. Do not let MEMORY.md become a second task list: planned work stays in TODO.md, and development direction stays in ROADMAP.md.

Memory edits on an agent's branch are not shared live. Communicate important findings to the coordinator during work and reconcile them into the shared main copy when integrating.

Python and shell tooling

Every committed asset and every measured claim in this repository is produced by a script. Tools live in Tools/ (Unreal, network, repository), Geo/tools/ (projection, OSM/DEM parsing, metadata) and Art/blender/*/ (Blender-side builders, next to their output).

Fix the tool, not the artefact. If an asset is corrected by hand, script the correction (or regenerate it) in the same change. A second manual fix of the same kind means the tool is missing a step.

Improve over fork. Extend the existing tool rather than adding a near-duplicate. When two or three scripts start sharing logic, factor the shared part into Tools/_common.py, Geo/tools/osm_common.py or Art/blender/common.py; keep the single metres→centimetres conversion where it already lives.

Rules that keep tools reusable and reviewable:

• One script, one job. Every input is an argument; no interactive prompts; deterministic output paths.
• Fail loudly. A tool that cannot do its job exits non-zero with a message. Never leave a partially written asset and a success code.
• Result files for Unreal. Unreal commandlets swallow print(); write the outcome to /tmp/gigline/<tool>.txt and read that instead of trusting the exit code alone.
• Absolute paths into sandboxes. Blender Flatpak (LD_LIBRARY_PATH="$B/blender/lib") and Unreal do not share the repo's working directory; pass absolute paths.
• Clean worktree for generators. Tools that rewrite committed assets (site/street/hero builders, importers, map builders) run from a clean worktree; inspect the LFS diff before committing. Note that .blend and .umap check out read-only — chmod u+w first or the save silently fails.
• Network and paid-API tools are human-triggered. Tools/commons_fetch.py, Tools/page_image_fetch.py, Tools/judge_screenshot.py (OpenRouter) and anything similar never sit in a gate or CI. Handle HTTP 429 with back-off rather than retrying immediately.
• Measure, don't assert. Verification tools print the sampled numbers — counts, holes, Z ranges, worst step and its location, frame-time percentiles — so a claim in TODO.md, CHANGELOG.md or Docs/ can be re-checked by re-running the command.

Document every tool. A new or changed tool gets a row in the inventory table of the README beside it: Tools/README.md, Geo/README.md, or Art/blender/README.md. What it does, its arguments, and a typical command. A tool without a README row is unfinished.

Test the pure parts. Tools/tests/ holds stdlib unittest tests (no Blender or Unreal process; they must not start a game or editor). Extract the testable core — argument parsing, geometry maths, licence gating, report formatting — into functions that a test can call directly.

python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py'

Keep the tools standard-library-only where practical; if a third-party import is genuinely needed, add it to requirements-tools.txt with a version floor and mention it in the tool's README row.

Architecture documentation

Docs/Architecture/ is the arc42 documentation: twelve numbered section files, about-arc42.md, and the combined architecture.md. Markdown is canonical — the .adoc sources were removed on 2026-11-08.

Keep it current in the same change as the implementation, not in a later documentation pass. When work alters any of the following, edit the matching section:

Change	Section
A new or restructured module, tool, data source or external interface	05_building_block_view.md
A runtime flow, tick/order dependency, or lifecycle (possession, map load, QA self-test)	06_runtime_view.md
Packaging, engine pin, checkout/build/launch procedure	07_deployment_view.md
A pattern, convention or cross-cutting rule (units, collision policy, provenance)	08_concepts.md
A decision that constrains future work	new ADR in 09_architecture_decisions.md
A quality goal or a measured budget (frame time, traversal coverage)	10_quality_requirements.md
A known risk or a risk that retired	11_technical_risks.md
A new term, tool or abbreviation	12_glossary.md

Rules:

• Describe what exists. No aspirational architecture: anything planned belongs in ROADMAP.md and TODO.md. Every structural claim names the file, script or flag that implements it.
• ADRs are append-only. Never rewrite an accepted decision; supersede it with a new ADR that says what it replaces and why.
• Keep the combined document in sync. architecture.md mirrors the section files; when a section changes, update the combined document too.
• Images live in Docs/Architecture/images/ and are referenced, not duplicated.
• Verify: all Markdown must pass prettier --check (config in .prettierrc), and a command you quote must still run.

Geographic & Art Pipeline

1. Save a versioned OSM extract; document date, bounds, and source.
2. Acquire separately licensed elevation data for the demo bounds unless the source DEM shows less than 1 m height variation across the demo area; record the decision in Geo/ metadata.
3. In QGIS, use a suitable local projected CRS (e.g. EPSG:26911) and record a local origin.
4. Import OSM blockouts through Blosm; clean and detail them in Blender.
5. Preserve geographic coordinates in metadata; convert to local Unreal coordinates with explicit meter→centimeter conversion.
6. Export modular buildings, sidewalks, roads, collision, and materials.
7. Use reference photography for manual façade work, ignore licensing for internal development use and do not commit reference images to the repository.
8. Treat OSM as layout data only — not authoritative façade, height, or pavement detail.

Always use a consistent scale test, named export presets, and repeatable import settings.

Blender skills

.agents/skills/blender-skills/ holds 94 Blender skill packs (MIT, blender-skills 1.3.0). They are agent instructions, not add-ons, and nothing in the pipeline depends on them.

All agents must consult the relevant skill packs before starting a task in that discipline. Each patch section in TODO.md lists its suggested skills; the general mapping is:

• Modeling / procedural assets — blender-modeler, procedural-modeling, geometry-nodes, hard-surface.
• Façades and architecture — archviz, historical-worlds (1920s Hollywood Blvd direction), realistic-style.
• Materials and textures — materials, texture-workflow, lookdev.
• UVs and export — uv-workflow, export-pipeline, unreal-export (verify against the ue_metric_v1 / ue_character_v1 presets in Tools/).
• Collision — collision-proxy (UCX/UHX naming, hulls, simple colliders).
• Scene assembly / optimization — scene-assembly, asset-optimization, lod-pipeline.
• Review and QA — qa-review, references (reference-image-match and visual-match checklists), camera-cinematography (matching reference camera angles).

Caveat: the skill packs assume MCP-driven interactive Blender. This project runs Blender headless via scripts in Tools/ — use the skills as method guides (checklists, naming conventions, proportions, validation steps), not for their MCP tooling. The headless scripts remain the execution path.

Licensing & Distribution

• Publish project-owned code under a chosen open-source license.
• Unreal remains proprietary/source-available; this is not a fully open-source stack.
• Keep code, art, engine, and geographic-data licensing separate.
• Record asset provenance and redistribution permissions in THIRD_PARTY_NOTICES.md.
• Verify licenses for every MPFB asset, texture, animation, vehicle, and audio file.
• An asset whose license cannot be verified must not be committed. Record it as unresolved in THIRD_PARTY_NOTICES.md and replace it with a redistributable asset before the release.
• Keep restricted assets out of the public repository; prefer redistributable replacements.
• Review Epic distribution requirements before publishing builds.

Visual review (screenshots)

Any change that affects the game's appearance — meshes, materials, lighting, levels, character, camera, post-processing — must be rendered for human review:

1. Run Tools/render_screenshots.sh (rebuilds Game/GigLine/Content/Test/ReviewMap.umap from current content, runs the game on it, captures the fixed camera list, copies the PNGs into Screenshots/).
2. Optional pre-check with a vision model: Tools/judge_screenshot.py --image <shot.png> --expect "<what it should show>" (or --shots to run every shot in the README) flags likely-missing content before a human looks. It reads OPENROUTER_API_KEY from .env (ignored). Small helper only — it never replaces the human verdict.
3. Update Screenshots/README.md: the image is embedded inline (![alt](demo/<shot>.png)) with its view, expected content, verification and approval state, plus one row in the status table at the top. The point is that the review happens in the file; a path alone is not a review. Describe any new shots or scene changes in the same change.
4. The PNGs are committed so reviewers see exactly what the build rendered (.gitignore does not exclude them). Keep them in sync with this README: drop retired shots in the same change.
5. Wait for the user's approval before treating a visual change as done; record approval by ticking both the shot's section and its row in the status table in Screenshots/README.md.

New content that needs a different camera angle gets a new entry in the shot list in Tools/ue_build_review_map.py.