diff --git a/AGENTS.md b/AGENTS.md index 6c4a8bf..16d2951 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,8 +42,9 @@ scope (major/minor/patch), not a placeholder. The MIT `blender-skills` pack is installed locally at `.agents/skills/blender-skills/` (94 skills plus a shared `references/` folder). It is **gitignored on purpose**: it is not game content, not part of the build, tests, CI or release packages, and every contributor -may or may not have it. Pi gates project `.agents/skills` behind project trust, so the -trust prompt has to be accepted before the skills load; `/skill:blender-director` forces one. +may or may not have it. The agent runtime (Pi) gates project `.agents/skills` behind project +trust, so the trust prompt must be accepted before the skills load; `/skill:blender-director` +forces one. Use them when a task touches `tools/blender_assets.py`, `tools/npc_pipeline.py`, `tools/bake_ao.py`, `assets/models/blender/**`, or Blender-authored venue/prop geometry. @@ -163,6 +164,9 @@ Recommended format: - [ ] Document the test procedure in `README.md`. ``` +Recommended `DONE.md` format: a `# DONE` heading, followed by each moved level-2 section +unchanged, with a completion date line under each section heading. + 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. @@ -254,12 +258,12 @@ Update `README.md` whenever setup instructions, commands, project structure, or The root-level `CHANGELOG.md` records the user-facing changes for every release. It exists so players and contributors can see what changed between versions without reading the commit log. - 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 only for changes that remove or break an existing player-facing feature, save format, or config contract, or that replace a system listed as a core pillar in PLAN.md; bump minor for new user-facing features; bump 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. +- Add the entry when its work ships. If the version number is not yet known, record it under `Unreleased` as a staging entry; moving it into a numbered version is a version increment and is complete only when the `config/version` update and matching local release build have also been produced and verified (see "Commit, Build and Version Discipline"). When a full executable level-2 milestone/theme in `TODO.md` is implemented, completed, and moved to `DONE.md`: @@ -283,13 +287,10 @@ For each task: 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 +9. If the change is a release (a major, minor, or patch version increment), follow the Release + Procedure in "Commit, Build and Version Discipline". +10. Push committed changes to the shared repository if applicable. +11. 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. @@ -300,13 +301,24 @@ Avoid unrelated refactors unless they are required for the task or explicitly ap 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. +- **Build every version.** Every major, minor and patch increment follows the Release Procedure + below; 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. +**Release Procedure** — follow these steps in order for every major, minor, or patch version +increment: + +1. Update `config/version`. +2. Write the `CHANGELOG.md` entry for the version. +3. Run the local release build (`tools/build_releases.sh`). +4. Verify the build artifacts and checksums. +5. Commit the changes. +6. Tag the version. +7. Push the commit and tag. + ## Collaboration Rules - Prefer clear, reversible changes over broad rewrites. @@ -316,7 +328,7 @@ Avoid unrelated refactors unless they are required for the task or explicitly ap - 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. +- Follow the Release Procedure in "Commit, Build and Version Discipline" 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. @@ -330,6 +342,8 @@ Before handing off work, an agent must run every check below that applies to the - Start the game or application and perform a basic smoke test. - For 3D/Blender changes: `blender_assets.py inspect`, `audit` and `fit`, the relevant capture gate, and a note of which local skills informed the change. +- If the local Blender skills are not installed, state "no local skills used" in the handoff + and list the skill-free checks that were run instead. - Check that documentation and task status reflect the actual state. - Review the final diff for accidental changes or unfinished markers.