Installing and pinning

Installing and pinning

godot-devkit has Godot tooling; agentic-sdlc has agent guardrails; neither imports the other. A game needs godot-devkit and nothing from agentic-sdlc to run make check, make precommit and make verify. Agent guardrails (the git denylist hook, the model guide, the agents and the CI checks) come from the agentic-sdlc plugin: see cdowin/agentic-sdlc.

The verbs: scene, scene-diff, refs, orphans, autoloads, stats, tiles (read and surgical write), check <gate> and check all, and installers install-runners, install-gates and install-skills.

Makefile.tiers finds this kit in one of two shapes; keep one:

shape	the pin	what make runs
locked (recommended)	godot-devkit==X.Y.Z in pyproject.toml, hash-pinned in uv.lock — Consume it locked	uv run --frozen godot-devkit — uv syncs .venv to the lock first
legacy	GODOT_DEVKIT_VERSION := vX.Y.Z in the Makefile, ABOVE the include	uvx --from git+…@vX.Y.Z godot-devkit, built from the tag

"Locked" means uv.lock names godot-devkit; what .venv happens to hold decides nothing. With both, the legacy pin runs, as it did before the lock existed, and make warns you to delete the GODOT_DEVKIT_VERSION line (two pins of one tool ship two products). Neither is refused at parse time. GODOT_DEVKIT set to a command overrides both.

uv add --dev godot-devkit==X.Y.Z --index cdowin=https://cdowin.github.io/godot-devkit/simple/
# then add `explicit = true` to the [[tool.uv.index]] table `uv add` wrote
uv run godot-devkit install-gates     # Makefile.gates + tools/dev/gdk_gate.sh
uv run godot-devkit install-runners   # Makefile.tiers + the runners

Consume it locked

Every v* tag is built once into a wheel and an sdist, attached to its GitHub Release (a re-tag is refused), and listed on a static PEP 503 index on this repo's GitHub Pages, https://cdowin.github.io/godot-devkit/simple/ — public, no token. The PyPI name is someone else's, so the index is declared explicit and the kit never resolves from PyPI. install-runners prints this block at the version that ran it:

# pyproject.toml
[dependency-groups]
dev = ["godot-devkit==X.Y.Z"]

[[tool.uv.index]]
name = "cdowin"
url = "https://cdowin.github.io/godot-devkit/simple/"
explicit = true

[tool.uv.sources]
godot-devkit = { index = "cdowin" }

uv sync writes uv.lock, which records the version and the wheel's hash, so every machine and CI run gets the same bits and a moved tag cannot change them. Delete the GODOT_DEVKIT_VERSION line: once uv.lock names the kit, Makefile.tiers runs uv run --frozen godot-devkit, which syncs .venv to the lock before it runs, so a lock bump you pull takes effect on the next make with no uv sync to forget, and never rewrites the lock. In CI the installed godot-toolchain action runs the same command, --version, whenever uv.lock names the kit.

• Upgrade: uv add --dev godot-devkit==X.Y.Z, then install-gates --diff and install-runners --diff to see what the new installables change.
• Bots: the pin lives in pyproject.toml and uv.lock, where Renovate and Dependabot can see it and open the bump PR themselves.

Next: Quickstart. How the Makefile targets work: Gate framework. Moving from 2.x: Migrating from 2.x to 3.x.

Agent UI skill (3.9.0)

Run godot-devkit install-skills --runtime codex for a repository-local .agents/skills/godot-ui, or --runtime claude for .claude/skills/godot-ui. Use --dest ~/.agents/skills (Codex) or --dest ~/.claude/skills (Claude) for user scope. Verify installed content with the same destination and --check. Upgrades do not silently replace differing files: review --diff, then use --force when appropriate.

Route native UI design, implementation and review through godot-ui in the project's agent instructions. Confirm the runtime lists the installed skill as enabled; files on disk alone do not prove discovery. Codex also selects skills by their description. A restart may be needed if discovery has not refreshed. Optional general design skills remain independent packages; devkit neither installs nor imports them.