| name | run-maintenance |
| description | Repository maintenance preparation for XerahS. Use before release or changelog work to sync repositories, inspect submodule state, identify version/changelog needs, and hand off commit/push/version rules to git-workflow. |
Maintenance Prep Skill
This skill prepares the XerahS workspace for release, changelog, or routine repository maintenance. It is not the source of truth for commit, push, tag, or version-prefix rules.
Canonical references:
Scope
Use this skill to:
- Sync the main repository and submodules.
- Inspect sibling repositories when the maintenance task explicitly touches them.
- Identify whether a version bump or changelog update is needed.
- Run the relevant pre-commit build after changes are made.
- Leave final staging, commit, push, and tag decisions to
git-workflow or publish-release.
Do not use this skill to invent commit message formats, submodule version prefixes, release tags, or changelog grouping rules.
Workflow
1. Inspect Status Before Sync
Run from the XerahS repository root before any pull or submodule update:
git status --short
git submodule foreach --recursive "git status --short"
For optional sibling repositories involved in the task:
git -C ../xerahs.github.io status --short
git -C ../ShareX status --short
If the main repo, submodules, or in-scope sibling repositories have local changes, do not pull over them. Commit, stash, or explicitly pause for the owner to decide. Submodule changes belong to that submodule repository.
2. Sync Clean Repository State
Run from the XerahS repository root only after the relevant repositories are clean:
git pull --recurse-submodules
git submodule update --init --recursive
git submodule update can detach submodule HEADs because it checks out the exact commit recorded by the parent repository. Mandatory follow-up: reattach ShareX.ImageEditor to its tracked develop branch and fast-forward it before release or changelog work continues:
git -C ShareX.ImageEditor fetch origin --prune
git -C ShareX.ImageEditor checkout develop
git -C ShareX.ImageEditor pull --ff-only origin develop
git submodule status ShareX.ImageEditor
git -C ShareX.ImageEditor status --short --branch
Abort and resolve manually if ShareX.ImageEditor cannot fast-forward, has local changes, or remains detached. If the fast-forward changes the submodule commit recorded by XerahS, commit and push the submodule first, then commit the updated XerahS gitlink in the parent repository.
If the task also touches optional sibling repositories, sync only those clean repositories:
git -C ../xerahs.github.io pull origin main
git -C ../ShareX pull origin develop
Do not pull optional sibling repositories just because they exist.
If a submodule has its own changes, treat it as a separate repository. Shared-library submodule commits, such as ShareX.ImageEditor, must follow git-workflow and omit the XerahS app version prefix.
3. Check Version Needs
Read the current XerahS app version from the root Directory.Build.props:
$version = (Select-String -Path Directory.Build.props -Pattern '<Version>(.+?)</Version>').Matches[0].Groups[1].Value
git tag --sort=-v:refname | Select-Object -First 1
Only bump versions when the task is explicitly about versioning or release preparation. If a bump is needed, use git-workflow for version source-of-truth and prefix rules, or publish-release for the full release bump/tag sequence.
SkiaSharp remains centrally managed in Directory.Packages.props; do not reintroduce project-local legacy pins.
4. Update Changelog When Needed
For changelog work, use update-changelog. Prefer the helper script for draft generation:
powershell -NoProfile -ExecutionPolicy Bypass -File .ai/skills/update-changelog/scripts/update-changelog.ps1
Manually review generated changelog text for accurate grouping, contributor attribution, and wording before release.
5. Build Gate
For code/config changes, run the required build before pushing:
dotnet build src/desktop/XerahS.sln
Do not wait more than 5 minutes for a single build. If it stalls, stop it, clear stale build processes/locks, prefer -m:1, then retry.
Documentation-only skill edits do not require a full solution build unless they affect build or release scripts that need local execution.
6. Commit And Push Handoff
Use git-workflow for final staging, commit message, version prefix, and push behavior.
Summary:
- XerahS app commits use
[vX.Y.Z] [Type] description only after verifying the root version is ahead of the latest tag.
- Shared library or submodule-only commits omit
[vX.Y.Z] and use [Type] description.
- Submodule commits are pushed before the parent repository when the parent records an updated submodule pointer.
- Do not tag releases from this skill; use publish-release.
Checklist
