zwitschi/gig-line
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update task status markers in setup and TODO files

Browse Source
This commit is contained in:
zwitschi committed 2026-11-07 18:24:52 +01:00
1 parent accf3a5306
commit c3a92d008b
3 files changed
+66 -66
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+59 -59
View File
@@ -52,6 +52,65 @@ Semantic Versioning: `MAJOR.MINOR.PATCH`.
- 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](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](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.
## 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](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.
## Geographic & Art Pipeline
1. Save a versioned OSM extract; document date, bounds, and source.
@@ -105,62 +164,3 @@ Any change that affects the game's appearance — meshes, materials, lighting, l
5. Wait for the user's approval before treating a visual change as done; record approval by ticking the 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`.
## Roadmap and TODO
The two files have separate roles:
- **[TODO.md](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](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** (`- [ ]`), **in progress/active** (`- [-]` or `- [~]`), 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 `- [-]` or `- [~]`.
- 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.
## 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](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.