From 08e90445935daa188ffaa5b6fd962ef02479b116 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Tue, 3 Nov 2026 09:17:49 +0100 Subject: [PATCH] Add commit, build and version discipline to agent workflow --- AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---- MEMORY.md | 10 ++++++++++ 2 files changed, 58 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7040558..b1a5bad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,10 +19,23 @@ The project should be developed in small, reviewable steps. Agents must keep pla - `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks). - `docs/gameplay.md` — Gameplay systems, venues, and the escalation model. - `docs/asset-tooling.md` — Asset pipelines, model tools, and screenshot gates. +- `docs/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan. - `docs/getting-started.md` — Setup, run/test commands, and the controls table. - `docs/smoke-checklist.md` — The manual smoke-test checklist. - `docs/adr/` — Architecture Decision Records. +## Priority and Versioning + +`TODO.md` is the priority source. The active order is: + +1. unversioned development tracks (currently character development and local map development); +2. versioned release milestones, in version order; +3. future/unversioned candidates and deferred work. + +Do not assign a version number to an unversioned track until its scope is accepted into a +release. When a version is assigned, it must be the next semantic version that matches the +scope (major/minor/patch), not a placeholder. + ## Required Workflow ### 1. Start by Inspecting the Repository @@ -47,6 +60,9 @@ All planned implementation work must be represented in `TODO.md`. - Use level-2 headings (`##`) for milestones or stable themes. A milestone should state its goal and an explicit exit criterion; a theme groups small related work that does not need a milestone. +- Order level-2 sections by current priority: unversioned development tracks first, then + versioned release milestones in version order, then future/deferred work. Do not assign a + version number to an unversioned track until it is scheduled for a release. - Use level-3 headings (`###`) for workstreams inside a milestone (for example, `0.8.1 First-shift tutorial`). Keep the hierarchy to three levels: milestone → workstream → checkbox. - Use checkbox items for each concrete task, normally under a level-3 workstream. Direct @@ -87,6 +103,10 @@ Recommended format: - [ ] Document the test procedure in `README.md`. ``` +Order the actual file as described in "Priority and Versioning": unversioned development tracks +first (for example character and local-map development), then versioned milestones in version +order, then future/deferred work. + ### 3. Move Completed Sections to `DONE.md` `TODO.md` uses nested sections. Apply these completion rules: @@ -175,6 +195,8 @@ The root-level `CHANGELOG.md` records the user-facing changes for every release. - Add an entry for every patch, minor, and major version change. - Follow Semantic Versioning (`major.minor.patch`): bump major for breaking or vision-level changes, minor for new features, and patch for fixes and small polish. +- A version increment is not complete until its `CHANGELOG.md` entry, `config/version` update and + matching local release build have all been produced and verified. - Group each entry under `Added`, `Changed`, `Fixed`, and `Removed` headings, and date every entry. - Describe changes in user-facing terms, not as raw commit messages. - Add the entry when its work ships. If the version number is not yet known, record it under `Unreleased` and move it into a numbered version when the version is tagged. @@ -198,13 +220,33 @@ For each task: 5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`. 6. Mark the task complete. 7. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry. -8. Commit the changes to the version control system with a descriptive message. -9. If a level-2 milestone from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` entry is in place, then create a new version or tag in the version control system to mark the milestone. -10. Push the committed changes to the shared repository if applicable. -11. Note the new version or tag created in the version control system in any relevant documentation or handoff summary. +8. Commit each coherent, verified change as it is completed. Do not wait until a whole + milestone is finished; keep commits small and descriptive and push them when the branch is + shareable. +9. On every major, minor or patch version increment: update `config/version`, add the + `CHANGELOG.md` entry, run the local release build (`tools/build_releases.sh`), verify the + artifacts and checksums, then commit, tag and push the version. +10. If a level-2 milestone from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` + entry and matching build are in place, then create the next semantic version or tag. +11. Push committed changes to the shared repository if applicable. +12. Note the new version, build artifacts or tag in the relevant documentation and handoff + summary. Avoid unrelated refactors unless they are required for the task or explicitly approved. +### 9. Commit, Build and Version Discipline + +- **Commit often.** Make a commit after each coherent change or verified task, not only when a + milestone or release is finished. Keep the working tree clean between tasks where possible. +- **Push regularly.** Push shareable commits to the shared repository; do not accumulate a long + local-only history. +- **Build every version.** Major, minor and patch increments each require a local release build + and artifact/checksum verification before tagging. A changelog entry alone is not a release. +- **CI is a second gate, not a substitute.** Tag builds remain automated, but the local build is + the required pre-tag check for every version. +- **Unversioned tracks stay unversioned.** Character, map and other development tracks do not get + a placeholder version; the version is assigned when the work is scoped into a release. + ## Collaboration Rules - Prefer clear, reversible changes over broad rewrites. @@ -213,6 +255,8 @@ Avoid unrelated refactors unless they are required for the task or explicitly ap - Do not claim a task is complete without verification. - Keep documentation synchronized with the implementation. - Mention files changed and checks run in handoff summaries. +- Commit coherent increments as you go; do not wait until the end of a milestone. +- Run a release build whenever a major, minor or patch version is incremented. - Leave follow-up work as checkbox items in `TODO.md` rather than hiding it in prose. - If blocked, document the blocker in `MEMORY.md` and add a corresponding task to `TODO.md`. - Avoid overwriting another contributor’s work; inspect recent changes before editing shared files. diff --git a/MEMORY.md b/MEMORY.md index 48d9a9e..ebf078e 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -4,6 +4,16 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o ## Decisions +- **Priority order (2026-11-03):** `TODO.md` now leads with the unversioned **Character + development** and **Local map development** tracks, then the versioned 0.10.0 release + candidate and later releases. Do not attach a placeholder version to an unversioned track; + assign one only when its scope enters a release. Character development is generator-first + (ADR-0015); local map development evaluates OSM/3D data, licensed reference imagery, + AI-assisted composition and development-only Gaussian splatting. +- **Commit/build discipline (2026-11-03):** commit each coherent verified change as it lands, not + only at milestone end, and push shareable commits. Every major, minor and patch version requires + a `CHANGELOG.md` entry, a local `tools/build_releases.sh` build and artifact/checksum + verification before tagging. CI tag builds are the second gate, not a substitute. - **Gaussian splatting / photo-derived maps (unversioned local track):** expanded in `TODO.md` "Gaussian splatting evaluation". Accepted photo channels are team captures, permissioned user/volunteer photos and clearly licensed downloads; every set needs a