Add commit, build and version discipline to agent workflow

This commit is contained in:
zwitschi committed 2026-11-03 09:17:49 +01:00
1 parent ad14410337
commit 08e9044593
2 files changed
+58 -4

No files matched your search

+48 -4
View File
@@ -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/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/gameplay.md` — Gameplay systems, venues, and the escalation model.
- `docs/asset-tooling.md` — Asset pipelines, model tools, and screenshot gates. - `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/getting-started.md` — Setup, run/test commands, and the controls table.
- `docs/smoke-checklist.md` — The manual smoke-test checklist. - `docs/smoke-checklist.md` — The manual smoke-test checklist.
- `docs/adr/` — Architecture Decision Records. - `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 ## Required Workflow
### 1. Start by Inspecting the Repository ### 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 - 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 and an explicit exit criterion; a theme groups small related work that does not need a
milestone. 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 - 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. 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 - 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`. - [ ] 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` ### 3. Move Completed Sections to `DONE.md`
`TODO.md` uses nested sections. Apply these completion rules: `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. - 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. - 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. - 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. - 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. - 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`. 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. 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. 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. 8. Commit each coherent, verified change as it is completed. Do not wait until a whole
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. milestone is finished; keep commits small and descriptive and push them when the branch is
10. Push the committed changes to the shared repository if applicable. shareable.
11. Note the new version or tag created in the version control system in any relevant documentation or handoff summary. 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. 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 ## Collaboration Rules
- Prefer clear, reversible changes over broad rewrites. - 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. - Do not claim a task is complete without verification.
- Keep documentation synchronized with the implementation. - Keep documentation synchronized with the implementation.
- Mention files changed and checks run in handoff summaries. - 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. - 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`. - 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. - Avoid overwriting another contributor’s work; inspect recent changes before editing shared files.
+10
View File
@@ -4,6 +4,16 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
## Decisions ## 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 - **Gaussian splatting / photo-derived maps (unversioned local track):** expanded in
`TODO.md` "Gaussian splatting evaluation". Accepted photo channels are team captures, `TODO.md` "Gaussian splatting evaluation". Accepted photo channels are team captures,
permissioned user/volunteer photos and clearly licensed downloads; every set needs a permissioned user/volunteer photos and clearly licensed downloads; every set needs a