Upgrading¶
To upgrade a project to a new release of uncoded:
- Find the release that the project uses. For version 6 or later, run
uv run uncoded --version. For an earlier version, read the version from the pre-commit hook'sentry, or runuvx uncoded --versionif there is no hook. - Read the changelog for every release after that release.
- If the new release is major, follow the section below for each major release that the upgrade crosses, oldest first.
- Run
uv lock --upgrade-package uncoded. - Run
uv run uncoded sync, and commituv.lockand every installed skill file that the command writes, rewrites or removes.
From version 5 to version 6¶
Version 6 supports projects that use uv and require Python 3.12 or later. It
runs uncoded from the project's uv environment and reads its settings only from
pyproject.toml.
- If the project has no
pyproject.toml, create a uv project first. If the project supports Python below 3.12, raise that requirement before upgrading, or keep using version 5. - Add uncoded as a development dependency with
uv add --dev uncoded. - Move the settings from
.uncoded.tomlinto a[tool.uncoded]table inpyproject.toml, then delete.uncoded.toml. - Change the uncoded pre-commit hook's
entrytouv run uncoded sync. - Run
uv run uncoded sync, then commit the regenerated installed skill files withpyproject.toml,uv.lockand the pre-commit configuration.
From version 4 to version 5¶
Version 5 no longer reads the required-version setting. Delete it from the
configuration file. The version in the entry of the pre-commit hook now pins
uncoded. If the project has no hook, add one as
Refresh on commit says.
From version 3 to version 4¶
Version 4 adds uncoded init and a required version, runs body and refs
only inside a project, and lays stubs out in the standard stub style.
- Run version 4, which rewrites every stub in the new layout:
uvx uncoded@4.0.0 sync
Commit every installed skill file that it writes or rewrites.
- Pin the project to version 4, so that every machine runs the same uncoded. Add this setting to the configuration file:
required-version = "4.0.0"
If a pre-commit hook runs uncoded, name the same version in its entry, as
uvx uncoded@4.0.0 sync, since uncoded refuses any other version.
- Delete any skill that an earlier version of uncoded wrote under a name it no longer uses, since version 4 no longer removes them:
rm -rf .agents/skills/coherence-review .claude/skills/coherence-review
rm -rf .agents/skills/uncoded-coherence-review .claude/skills/uncoded-coherence-review
rm -rf .agents/skills/uncoded-review .claude/skills/uncoded-review
Check first that none of them is a skill of the project's own.
-
Run
uncoded bodyanduncoded refsfrom inside the project. They now stop outside a project, and when the--infile is outside the project directory. A script that ran them from elsewhere changes directory first. -
On Windows, expect
/between directories in the paths thatuncoded refsprints. A script that read them with\changes to match.
From version 2 to version 3¶
Version 3 keeps generated indexes local, renames the semantic consistency review, and makes navigation skills load once per session.
- Stop tracking
.uncoded/, then rebuild the index locally:
git rm -r --cached .uncoded
uvx uncoded sync
Commit the updated files under .agents/skills/ and .claude/skills/. The
generated .uncoded/.gitignore keeps the rebuilt index out of Git.
-
Add
always_run: trueto the localuncodedpre-commit hook. The ignored index must also be refreshed when a commit only deletes files. -
Change every skill pointer from
uncoded-coherence-reviewtouncoded-consistency-review. Delete the old generated skill:
rm -rf .agents/skills/uncoded-coherence-review .claude/skills/uncoded-coherence-review
- Replace any always-on navigation instructions in
AGENTS.mdorCLAUDE.mdwith the skill-loading instructions from Getting started.
From version 1 to version 2¶
Version 2 replaces instruction injection with generated skills.
- Run the final version 2 release to create the skill files:
uvx uncoded@2.1.1 sync
It also removes the version 1 skills, coherence-review and
uncoded-review. Later releases leave them in place.
- Remove the old marker blocks from
AGENTS.mdorCLAUDE.md:
<!-- uncoded:start ... -->
...
<!-- uncoded:end -->
<!-- uncoded:docs:start ... -->
...
<!-- uncoded:docs:end -->
-
Change every skill pointer from
coherence-reviewtouncoded-coherence-review. -
Remove
instruction-filesfrompyproject.tomlor.uncoded.tomlbecause version 2 no longer reads it. -
To keep navigation always on, add the skill-loading instructions from Getting started to
AGENTS.mdorCLAUDE.md.