docs: move task list to TODO.md and keep ROADMAP.md as plan
Split the former ROADMAP.md checklists into TODO.md, which now holds all actionable work and progress marks. ROADMAP.md keeps milestone goals, scope, and release gates as prose with no checkboxes. Update AGENTS.md, Docs/, Geo/README.md, MEMORY.md, and README.md to point to the new file roles.
This commit is contained in:
1 parent
91fd123ab4
commit
5ab8b556f3
8 files changed
+560
-385
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md
|
||||
|
||||
Instructions and living roadmap for autonomous agents, AI coding assistants, and contributors working on this repository.
|
||||
Working rules for autonomous agents, AI coding assistants, and contributors. Planned work is tracked in **[TODO.md](TODO.md)**; development direction is in **[ROADMAP.md](ROADMAP.md)**.
|
||||
|
||||
## Project Goal
|
||||
|
||||
@@ -69,7 +69,7 @@ Always use a consistent scale test, named export presets, and repeatable import
|
||||
|
||||
`.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 `ROADMAP.md` lists its suggested skills; the general mapping is:
|
||||
**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`.
|
||||
@@ -105,19 +105,22 @@ Any change that affects the game's appearance — meshes, materials, lighting, l
|
||||
|
||||
New content that needs a different camera angle gets a new entry in the shot list in `Tools/ue_build_review_map.py`.
|
||||
|
||||
## Roadmap
|
||||
## Roadmap and TODO
|
||||
|
||||
The living roadmap with per-version task checklists is in **[ROADMAP.md](ROADMAP.md)**.
|
||||
The two files have separate roles:
|
||||
|
||||
- `ROADMAP.md` is the single, central TODO and progress list for all agents. Put planned work and actionable follow-ups there rather than creating parallel task lists.
|
||||
- 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 checklist items currently being worked on `- [-]` or `- [~]`; update the marks as their status changes.
|
||||
- Planned work is listed as checkbox items in `ROADMAP.md`, marked **open** (`- [ ]`), **in progress/active** (`- [-]` or `- [~]`), or **done** (`- [x]`). Keep the marks accurate.
|
||||
- **[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 (`[-]` in progress, `[x]` done).
|
||||
- When **all** steps in a version section are done: write a short descriptive entry to `CHANGELOG.md`, then remove the version section from `ROADMAP.md` to keep it concise.
|
||||
- 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.
|
||||
- Define the release checks in `Docs/release-checks.md`. If a check fails, do not tag the release; open a patch task in `ROADMAP.md` and report the failing check in `CHANGELOG.md`.
|
||||
|
||||
## Git workflow
|
||||
|
||||
@@ -125,9 +128,9 @@ Every agent works on a dedicated git branch. **Never commit work directly to `ma
|
||||
|
||||
Before starting any task:
|
||||
|
||||
1. **Scan `ROADMAP.md`** and pick a task — a level-three (`###`) section — to work on. 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.
|
||||
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 `ROADMAP.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.
|
||||
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.
|
||||
@@ -135,18 +138,18 @@ Before starting any task:
|
||||
**Branch hygiene:**
|
||||
|
||||
- Branch from the current `main` revision, not from a stale local checkout.
|
||||
- Keep `ROADMAP.md` checkbox updates on your branch — they are part of the work.
|
||||
- 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 `ROADMAP.md` and leave the branch for the coordinator to clean up.
|
||||
- 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 roadmap, 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 roadmap section and items 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; the roadmap is not an atomic lock.
|
||||
- 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 roadmap and memory changes, and update ownership and status. Follow the visual review and user-approval requirements before marking visual work done.
|
||||
- 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
|
||||
|
||||
@@ -155,8 +158,8 @@ Before starting any task:
|
||||
- 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 `ROADMAP.md` checkbox, such as a workaround, an assumption, or a rejected approach and why.
|
||||
- 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 roadmap: planned work stays in `ROADMAP.md`.
|
||||
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.
|
||||
Reference in new issue
Block a user