v4.1.1

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Your game needs git (git init if it has none) and no uncommitted changes. You also need Godot 4.5 or newer, and bash (on Windows it comes with Git for Windows).

Option 1: the skill. In your game's folder, run:

npx skills add Freakling/Godot-Director

That installs the skill for the assistant you choose in the prompt. In Claude Code it becomes a /godot-director command. The skill fetches the latest Godot Director release outside your game and runs onboarding.

Option 2: the Claude Code plugin. In Claude Code:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Then open a new Claude Code session in your game's folder (or run /reload-plugins), and run /godot-director:godot-director.

Option 3: manual install. Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Either run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip from the Releases page and rename the extracted folder. Then ask your assistant:

Read Godot-Director/ONBOARDING.md and follow it to install Godot Director into this project.

Afterwards, restart Claude Code so the new commands load. Each new clone of the game later needs one command: bash tools/setup-clone.sh.

With another AI assistant: tell onboarding, and it installs the tool-neutral core only (--tools none). Your assistant then reads AGENTS.md, which points it to .godot-director/rules.md and the procedures.

How to upgrade

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

Only Godot Director's own files are replaced, and your edits to them are kept. When a new version also changes a file you edited, the new version is written next to it as <file>.gdir-new for you to merge. Review the result with git diff.

What's changed

• An install from a development snapshot says so. An install from a source whose CHANGELOG.md has entries under ## Unreleased records # godot-director <version> + unreleased (<commit>) as the manifest's first line, and its closing lines say it is a development snapshot, not a release, with where the latest release is listed. VERSION stays at the last release until a release is cut, so the manifest tells the truth. The commit comes from the source's git checkout (a release zip has none) and goes on a # source <commit> line, which release installs get too. An install from a release records the plain version. Upgrades read the old version without the suffix, so an upgrade from a snapshot works.
  • Upgrade steps: none: the next upgrade rewrites the manifest.

v4.1.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Your game needs git (git init if it has none) and no uncommitted changes. You also need Godot 4.5 or newer, and bash (on Windows it comes with Git for Windows).

Option 1: the skill. In your game's folder, run:

npx skills add Freakling/Godot-Director

That installs the skill for the assistant you choose in the prompt. In Claude Code it becomes a /godot-director command. The skill fetches the latest Godot Director release outside your game and runs onboarding.

Option 2: the Claude Code plugin. In Claude Code:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Then open a new Claude Code session in your game's folder (or run /reload-plugins), and run /godot-director:godot-director.

Option 3: manual install. Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Either run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip from the Releases page and rename the extracted folder. Then ask your assistant:

Read Godot-Director/ONBOARDING.md and follow it to install Godot Director into this project.

Afterwards, restart Claude Code so the new commands load. Each new clone of the game later needs one command: bash tools/setup-clone.sh.

With another AI assistant: tell onboarding, and it installs the tool-neutral core only (--tools none). Your assistant then reads AGENTS.md, which points it to .godot-director/rules.md and the procedures.

How to upgrade

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

Only Godot Director's own files are replaced, and your edits to them are kept. When a new version also changes a file you edited, the new version is written next to it as <file>.gdir-new for you to merge. Review the result with git diff.

What's changed

• Autoplay's no-focus check looks under the nodes the adapter names. A shell that keeps each view's flat UI outside the view node (a HUD layer, a ui_root it hands each view) or draws a view's page in a SubViewport with a stand-in control holding the window's focus no longer fails no-focus on every step. The adapter base has a new hook, focus_roots() -> Array[Node]: the nodes under which the current view's focusable controls and its focus owner live. It returns the view node by default, so a game whose adapter doesn't override it behaves as before.
  • The invariant. The focus owner satisfies the check when it is a root or under any root (a control in another window is still exempt); the check looks at a focusable control (an enabled button) under any root; a root that is a SubViewport (a page on a sheet) counts its own focus owner as well as the window's, so the page's focused control satisfies the check while the window's focus sits on a stand-in in another root. An empty list means no rule for that step: a game may return [] for a screen that is mouse-only by design, and the invariant then doesn't apply there. The freed-view check still uses view_node().
  • The finding names its roots, so a wrong hook is easy to spot: the view hub has no focused control under ViewUI, HUD (so a keyboard or controller player can't act). A view with the default hook reads the view shop has no focused control under ShopScreen (so ...): the text and the signature of an existing no-focus finding change with it.
  • A weight of 0 means never. A scenario's weights entry of 0 used to pick the first action when every candidate was at 0; now the step picks nothing. Smoke carries on to the progress action (and ends the turn it was playing), and a random or end_turn strategy that has nothing else to pick ends.
  • Seeds, example, docs. tools/autoplay_adapter.gd (the seed) has focus_roots() stubbed with its comment, and tools/autoplay_scenarios.gd's header says a weight of 0 means never; the example adapter's header points at the hook. procedures/autoplay.md says how to read a no-focus finding and fix it with focus_roots(), rules.md has a rule for it, and the README names it. The selftest covers a HUD outside the view node (the hook and the default), the finding naming every root, a SubViewport page with a stand-in outside it, an empty list, and every candidate at weight 0.
  • Upgrade steps: none for a game whose views keep their UI under the view node: the hook is the base's and arrives on upgrade. A game that keeps a view's UI elsewhere adds focus_roots() to tools/autoplay_adapter.gd, returning the view node plus the nodes that hold its focus (such as [view, ui_root], plus any SubViewport page), and, once its smoke run is clean, sets enforce=["smoke"] under [autoplay] in tools/check.cfg. A screen that is mouse-only by design returns []. An adapter that overrides view_node() keeps working, since the default roots are the node it returns.

v4.0.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Your game needs git (git init if it has none) and no uncommitted changes. You also need Godot 4.5 or newer, and bash (on Windows it comes with Git for Windows).

Option 1: the skill. In your game's folder, run:

npx skills add Freakling/Godot-Director

That installs the skill for the assistant you choose in the prompt. In Claude Code it becomes a /godot-director command. The skill fetches the latest Godot Director release outside your game and runs onboarding.

Option 2: the Claude Code plugin. In Claude Code:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Then open a new Claude Code session in your game's folder (or run /reload-plugins), and run /godot-director:godot-director.

Option 3: manual install. Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Either run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip from the Releases page and rename the extracted folder. Then ask your assistant:

Read Godot-Director/ONBOARDING.md and follow it to install Godot Director into this project.

Afterwards, restart Claude Code so the new commands load. Each new clone of the game later needs one command: bash tools/setup-clone.sh.

With another AI assistant: tell onboarding, and it installs the tool-neutral core only (--tools none). Your assistant then reads AGENTS.md, which points it to .godot-director/rules.md and the procedures.

How to upgrade

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

Only Godot Director's own files are replaced, and your edits to them are kept. When a new version also changes a file you edited, the new version is written next to it as <file>.gdir-new for you to merge. Review the result with git diff.

Why 4.0

The minimum Godot is now 4.5, because the engine Logger that captures errors inside the game needs it. Every game gets a play log, which runs on that Logger, so a game on Godot 4.3 or 4.4 upgrades the engine first.

What's changed

• New: the play log. Every game gets a log of what happened in each run, one plain-text line for you and one JSON line for tools, so an assistant can read what a playtest did. The framework owns tools/play_log_base.gd; the game's PlayLog autoload, tools/play_log.gd (a new seed, like tools/ui_screens.gd), extends it and fills its hooks. It works in debug and release builds.
  • Two files per run, one call. PlayLog.log_event(category, event, text, data) writes HH:MM:SS T<turn> [category] text to user://logs/play/run-<datetime>.log, and {"t": ms, "turn": n, "cat": "...", "event": "<stable_id>", "text": "...", "data": {...}} to the .jsonl beside it. Tools read the stable event id; the text is free to change. Each line is flushed as it's written, so a crash keeps everything up to it. Only the newest keep_files runs are kept (20 by default).
  • A run's files. Until the game decides the run, lines are held and stamped T-. begin_run() starts the files with the held lines and returns the run id to keep in the run save; continue_run(id) appends to that run's files and drops the held lines (engine errors and warnings are kept), so a throwaway boot never reads as turn 0. continue_run() accepts only a run id (YYYYMMDD-HHMMSS, with a -NN suffix when two start in one second): the id comes from a save the player can edit, so anything else gets new files. A launch that ends before any run began keeps its lines in boot-<datetime>.log and .jsonl, the newest keep_boot_files (5) of them, so open-and-quit launches never push real runs out. Each session opens with a header: build version, Godot version, OS, debug or release, the command line, the game's _session_extras() (its settings, with secret ones left out) and a resource count per folder of data/.
  • A run's first view. A run that starts without the shell announcing a view gets the current one as its first view.changed line, a few frames after begin_run() or continue_run() (first_view_frames, 3), named from the screen catalog (else the scene's node name in snake_case), or by the game's _current_view() hook for a shell that swaps views inside one scene. The log and its review then always carry the first view ("initial": true in the line's data). The shell's own view_changed inside those frames is the line instead, so a view isn't logged twice, and a second run in the same session gets its own first view.
  • Built in, for any genre: engine errors and warnings through a Logger (OS.add_logger; queued under a mutex from any thread and logged on the main thread, with the top frame of the script backtrace, which release builds have only with debug/settings/gdscript/always_track_call_stacks; the same error is logged at most max_engine_repeats times, 20 by default, so a hook that fails every frame can't flood the files), InputMap actions pressed (by name, never typed text, and nothing while a text field has focus; polled once per frame, so a held stick logs once and an action a node handles is still logged), window and focus changes, frame hitches over hitch_threshold_ms, orphan-node counts at each snapshot in debug builds, view changes from the shell's view_changed(name) signal (watch_views()), and the main progress button (watch_progress_button()): its blocked state each time it changes, and every press with what blocked it.
  • The game's hooks: _session_extras(), _build_snapshot() (logged by log_snapshot() wherever the player may act), progress_block_reason() and _install_id(). The seed has all four stubbed and marked ## PLACEHOLDER.
  • Scrubbed in the base: the OS user name, the home folder (in every slash style), the install id and the text values of secret settings never reach the files. A setting is secret when its name contains secret, token, password, passwd, _key, apikey, auth, credential, _id, uuid, guid, account or email (secret_names). The user name is replaced only as a whole word, and only when it has 3 characters or more, so a short name doesn't blank ordinary words; the home folder covers it in paths. A hard crash can lose the engine errors queued in its last frame, since they're written on the main thread; Godot's own godot.log keeps them.
  • Tests and tools. start_capture() records lines into memory, also under the check, so a test asserts on them; tail() keeps the recent lines. Nothing is written under the check or a capture, or when a tool script runs the project (--script); the godot_director_autoplay meta turns writing back on, for autoplay.
  • Rules. rules.md gets five rules: everything is logged (every player action, turn step, view change and blocked progress logs a line with a stable event id, and a test asserts on it), every action is drivable (it appears in the autoplay adapter's list_actions() with a ui route), agent-visible state (hidden values go in the dev menu's inspector and the snapshot; this replaces the advice to use the editor's Remote scene tree, which the agent can't see), seeded randomness (one seeded generator the run owns, its seed logged and its state saved) and privacy (nothing leaves the machine without the player's consent; logs hold no user name, home path, install id or typed text). Debug-only tools now says the play log ships in every build.
  • The example (examples/market-day) registers its PlayLog, logs each trade, day and the end of the market from RunState, names the shop view and its Next Day button, and tests its lines through start_capture().
• New: autoplay, the game plays itself. bash tools/autoplay.sh <scenario>|--all [--seed N] [--steps N] [--no-images] [--size WxH] launches the real game through its main scene, with the godot_director_autoplay meta set and user:// pointed at a temporary folder, and plays a scenario through the game's adapter, so an assistant can playtest a change before you do. Exit codes as in capture: 0 clean, 1 findings, 3 couldn't run (no Godot, no display; --no-images plays headless). The framework owns tools/autoplay.sh, tools/autoplay.gd (the driver), tools/autoplay_adapter_base.gd and tools/autoplay_catalog.gd; the game owns three new seeds: tools/autoplay_adapter.gd, tools/autoplay_scenarios.gd and tools/autoplay_invariants.gd.
  • The adapter is the only way the driver reaches the game: start_run(seed) (the run's seeded generator takes the seed), load_save(path), save_run(path), list_actions(), perform(action), state(), progress_block_reason() (the play log's by default), is_run_over(), current_view() and view_node(). An action has an id, a label, a kind (ui or api) and, for ui, a unique node name (%EndTurn) or an InputMap action; it may say it's the progress action, that it opens a catalog view or goes back, that it unblocks progress, and its weight. The seed's stubs are marked ## PLACEHOLDER.
  • Real input. A ui action is a mouse click at the cen...

v3.13.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Your game needs git (git init if it has none) and no uncommitted changes. You also need Godot 4.3 or newer, and bash (on Windows it comes with Git for Windows).

Option 1: the skill. In your game's folder, run:

npx skills add Freakling/Godot-Director

That installs the skill for the assistant you choose in the prompt. In Claude Code it becomes a /godot-director command. The skill fetches the latest Godot Director release outside your game and runs onboarding.

Option 2: the Claude Code plugin. In Claude Code:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Then open a new Claude Code session in your game's folder (or run /reload-plugins), and run /godot-director:godot-director.

Option 3: manual install. Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Either run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip from the Releases page and rename the extracted folder. Then ask your assistant:

Read Godot-Director/ONBOARDING.md and follow it to install Godot Director into this project.

Afterwards, restart Claude Code so the new commands load. Each new clone of the game later needs one command: bash tools/setup-clone.sh.

With another AI assistant: tell onboarding, and it installs the tool-neutral core only (--tools none). Your assistant then reads AGENTS.md, which points it to .godot-director/rules.md and the procedures.

How to upgrade

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

Only Godot Director's own files are replaced, and your edits to them are kept. When a new version also changes a file you edited, the new version is written next to it as <file>.gdir-new for you to merge. Review the result with git diff.

What's changed

• New: a Game Design Document template for you to fill in, in your own words (design/director-gdd.md). Every game gets it, for a new game or one already underway. Its sections are overview and concept, gameplay mechanics and controls, art and visual style, audio, levels and world, UI and UX, and the milestone roadmap. Onboarding offers it before the design interview, as an alternative to the interview or an addition to it, and says why it helps: a written document gives the agent your intent and its context, and sets the stage for the design sessions and builds that follow. Fill it before onboarding, during it or later.
  • It stays yours. design/gdd.md remains the design record the agent maintains. Your document is input: the agent reads it, never edits it, and writes the current design into the GDD's own sections, so each fact lives in one place.
  • Onboarding reads a filled one first. For a new game it takes the interview's answers from it and asks only what it leaves open. For an existing game it builds the initial assessment (Architecture, GDD sections, first items) from it, together with the code and the existing documents. It marks what it took (from your document) and what it worked out itself (inferred, please confirm), records decisions with why: from your document, and turns what is undecided into open questions. Tell the agent when the document changes and it brings the GDD in line.
• Align checks the GDD against reality. align.md's item 6 is "Brief against reality". It reads the whole GDD and checks every statement of state (a section marked later or planned, a count, a list of what exists, a line saying work waits on something, "once X exists") against the built game, the done items and the latest releases. It also checks every decision line since the last docs: align commit one by one, not a sample. Mechanical drift gets fixed; design calls are reported with the stale statement named.

Upgrade steps

• Design document: the installer adds design/director-gdd.md when the game doesn't have it (project seeds are copied once and never overwritten). After the upgrade, the agent tells you it exists, where it is, and why writing it helps. If you fill it in, the agent reads it as ONBOARDING.md describes and brings design/gdd.md in line, marking what it inferred. Nothing else in the game changes.
• Align: none. The procedure is framework-owned and arrives on upgrade.

v3.12.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Install from the release, which installs the latest version. Pick one of three ways:

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches the latest Godot Director release and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip and rename the extracted folder. Then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

What's changed

• The repository ignores OS metadata files. A root .gitignore keeps .DS_Store, Thumbs.db, desktop.ini and __MACOSX/ out of the repository, as the Claude plugin directory's scanner requires.
• Fix: the protected-space guard blocks absolute paths. The guard for director/ matched file paths only as written, so a write to director/ given as an absolute path got through. It now resolves the path against the project root before matching, in Windows, Git Bash and POSIX forms, with .. segments and case-insensitive matching on Windows. Paths outside the project root, and folders named director elsewhere in it, are still allowed. If you rely on director/ being read-only for the agent, this release is the one that closes the absolute-path gap.
• /ui-design tells you how to open and save the starter drawing. The capture step gives one plain message: nothing to install, excalidraw.com in the browser with no account, how to open the starter (the menu's Open, or drag it in), how to save it as director/ui/<screen>.excalidraw, and that the drawing stays on the machine unless Live collaboration or a shareable link is used. In Chrome and Edge, Save to... lets you pick the folder; other browsers save to Downloads, so move and rename the file. The drawing guide (design/ui/README.md) gets a "Using Excalidraw" section with the same facts, plus the address-bar install.

Upgrade steps

None for games' own files. The .gitignore belongs to the Godot Director repository, and the hook is framework-owned and arrives on upgrade. An existing design/ui/README.md is the project's own and isn't rewritten; the capture step's message gives the same instructions the next time the agent hands over a starter drawing.

v3.11.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Install from the release, which installs the latest version. Pick one of three ways:

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches the latest Godot Director release and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip and rename the extracted folder. Then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

What's changed

/ui-design lets you design your game's screens by drawing them, and checks the built screens against your drawings. The agent sees each screen the way a player does, so layout bugs that tests can't see are caught automatically. You draw over a screenshot in Excalidraw, which is free, open source, runs in a browser and needs no account. The agent reads exactly what you drew, asks about anything it can't tell, and then builds the screen to match.

The pieces:

• Capture: every screen, at every size. bash tools/ui_capture.sh renders each screen offscreen at each size, with the project's stretch settings. For each screen and state it writes a screenshot, an element map (every visible control that is focusable, has text or has a unique name, with its position, focus order and overflow), the screenshot with each element outlined and numbered, and a layout lint. The screens are listed in a catalog (tools/ui_screens.gd), each with the scene it opens and how to put it in a representative state, built through the game's public APIs and debug hooks. Captures repeat exactly and touch no player data. Headless Godot renders nothing, so captures need a display; on Linux without one, the script uses xvfb-run.
• Drawings: you draw the layout. Each screen gets a starter drawing with its screenshot locked inside a frame. You draw one rectangle per thing, colour says what changes (green new, blue kept but moved or resized, red removed, orange not sure), and design/ui/README.md explains the rest. /ui-design process <screen> reads the drawing, confirms its reading with you, settles open points with options and a recommendation, and records a screen spec, the decisions, and one item per screen.
• Verify: the built screen is checked against its spec. bash tools/ui_capture.sh <screen> --verify prints one row per element in the spec: whether it is on screen, where it sits within a tolerance (4 percent of the screen by default), whether it can be reached by keyboard or controller, and whether it is lint-clean. It also lists unexpected elements and writes compare images that put your drawing beside the new capture.
• A layout lint with seven rules: squeezed text, stretched controls, off-screen elements, overlaps, unreachable elements, no default focus, and hard-coded positions. Findings are advisory. You can turn the lint on in the project check for the screens you choose.
• Overlays. A catalog entry can name the HUD or toast layer a player sees over a screen, so captures show what players see.
• The workflow uses the spec. Build, review, the function check and align all work from the screen spec and drawing, and onboarding asks once whether you want to design screens by drawing.
• Selftest covers the wiring, the reader, the lint, the verify table and an upgrade from v3.10.0, and captures the example game's screens when a display is available.

Not tested in this release: macOS, Linux with xvfb, and a machine without a display.

Upgrade steps

1. The installer creates tools/ui_screens.gd and tools/ui_capture.cfg when the game doesn't have them, and adds the .gitignore and .gitattributes lines; check that they're there, and commit the two files with their .uid files.
2. Replace the seed's main-scene entry in tools/ui_screens.gd with one entry per screen the game has (see .godot-director/procedures/ui-design.md › The catalog), or leave it for the next item that touches a screen.
3. .claude/settings.json is framework-owned; if you edited it, merge .claude/settings.json.gdir-new and keep "Bash(bash tools/ui_capture.sh *)" in permissions.allow. Restart Claude Code so the new skill loads.
4. The installer creates design/ui/README.md when the game doesn't have it. To design screens by drawing, create director/ui/ and an empty director/.gdignore (so Godot doesn't import the PNGs you export there); director/ is yours, and the agent never writes in it.
5. The installer writes tools/ui_capture.cfg with the layout lint in the check off (check_in_check=false, enforce=[]) when your game doesn't have it yet, and adds tools/ui_verify.gd to the framework files. A game that already has the file keeps it: add check_in_check=false and enforce=[] under [lint] and tolerance_pct=4.0 under [verify] (a missing key reads as off and as 4.0). To turn the lint on, set check_in_check=true and list the screens whose capture is lint-clean in enforce; commit tools/ui_capture.cfg with it, since the check's fingerprint covers it.
6. Run bash tools/ui_capture.sh --missing (onboarding does this on an upgrade and reports; it never fails) and add a catalog entry for each screen scene it lists, or add the scene to [capture] skip if it isn't a screen. Give an entry the overlays a player sees over it (a HUD an autoload draws, for example "overlays": ["/root/Hud"]).
7. Add design/ui/ to the Layout table in your AGENTS.md (the template's row reads: screen specs, and captures/ (gitignored); the director's drawings are in director/ui/). If you want to design screens by drawing, set the UI / screen layout row in Ownership to director designs (director/ui/), agent builds, keeping its placeholder.
8. .claude/skills/ui-design/SKILL.md and the procedures build.md, review.md, function-check.md and align.md are framework-owned: if you edited one, merge its .gdir-new file. Restart Claude Code so the changed skill loads.

v3.10.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Install from the release, which installs the latest version. Pick one of three ways:

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches the latest Godot Director release and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip and rename the extracted folder. Then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

What's changed

• New: /release and a release step in onboarding (.godot-director/procedures/release.md). CI exports on every change; CD uploads builds to a platform's UAT branch or channel and, when you ask, promotes them to production.
  • You supply the upload commands; Godot Director knows no store. release.cfg in the project root has one section per export preset with a uat command, an optional production command, and secrets, the names of the environment variables the commands read. It is committed; only names are in it, never values.
  • /release uploads to UAT and promotes only when asked. It checks the working tree is clean and bash tools/check.sh passes, exports the presets (/export), shows a dry run, then runs tools/release.sh uat. Production needs your request, a passing UAT upload of the same commit and your yes. It never prints a secret.
  • tools/release.sh uat|production [preset] [--dry-run] runs the commands from release.cfg for the presets whose builds are in builds/, and stops before running anything when a build is missing or a named secret is unset. Any CI can run it after its own export.
  • A GitHub Actions workflow template (.godot-director/templates/release-workflow.yml, copied to .github/workflows/release.yml): it exports every preset on every push and pull request, uploads to UAT on main, and has a production job run by hand that waits for approval from a protected GitHub Environment named production. It is a starting point, not a finished workflow: the lines marked FILL IN (the Godot image, the upload tool to install, and the secret lines) are yours to fill in for your project.
  • Credentials are CI secrets only. Onboarding lists the secret names to set. They never go in the repo, export_presets.cfg, release.cfg or the chat.
  • Onboarding offers the step after exports, and you can skip it: a skip adds an open question to GDD › Open Questions and a "Set up release" item that depends on it, as for exports.
  • Selftest checks the wiring and the install, and runs tools/release.sh against a fake release.cfg with echo commands, so it needs no network, export templates or credentials.

Upgrade steps

1. Ask the human whether the game should release builds, and run ONBOARDING.md › 6 › Release: the upload commands, the secret names, and (for GitHub Actions) the workflow file. If the human skips it, add the open question and the "Set up release" item that .godot-director/procedures/release.md › "When the human skips it" gives, with the game's next Q and T numbers.

v3.9.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Install from the release, which installs the latest version. Pick one of three ways:

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches the latest Godot Director release and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip and rename the extracted folder. Then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

What's changed

• New: /export and an export step in onboarding (.godot-director/procedures/export.md). Exporting is Godot's own word for producing a game's binaries, so the skill is /export.
  • /export exports the game. It reads the presets in export_presets.cfg, finds Godot through tools/godot_bin.local, checks that the export templates for the project's engine version are installed (and says how to install them when they aren't), runs --export-release (or --export-debug on request) headless for each preset, and reports the files it produced. Builds go to builds/<preset>/, which is gitignored. It commits nothing and changes no source file.
  • Onboarding asks for the export settings Godot doesn't have yet. The target platforms, and where exports run: on your machine, in a build container (local or in the cloud), or on a hosted service such as GitHub Actions, with guidance to set it up. The answers become presets in export_presets.cfg, the platforms in the GDD, decision lines, and one line in AGENTS.md › Project rules. You can skip the step.
  • A skipped step stays visible. It adds an open question to GDD › Open Questions (which platforms, and where exports run) and a "Set up exports" item that depends on it. /design Q<n> runs the step later, and /next-task builds the setup once the question is answered. Changing exports later is a design session too.
  • Depends on can name an open question. An item that lists Q<n> there is ready once the question is no longer in Open Questions; /next-task and the item format say so.
  • The installer adds /builds/ to the game's .gitignore.
  • Selftest checks that the procedure and skill exist and are wired into the rules, README, ONBOARDING and the skip path, that the installer ships them and the gitignore line, and needs no export templates. The example ignores /builds/, and the scenarios gain one for /export.

Upgrade steps

1. The installer adds /builds/ to the game's .gitignore; check that the line is there.
2. Ask the human whether the game should have exports, and run ONBOARDING.md › 6 › Exports: the platforms and where exports run. If the game already has export_presets.cfg, read it first and ask only for what is missing. If the human skips it, add the open question and the "Set up exports" item that .godot-director/procedures/export.md › "When the human skips it" gives, with the game's next Q and T numbers (bump Next and Next IDs).

v3.8.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Install from the release, which installs the latest version. Pick one of three ways:

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches the latest Godot Director release and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

The plugin installs the latest release. Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put the latest release in your game's root folder, next to project.godot, as a folder named Godot-Director. The release's tag is v followed by its version number, and the Releases page shows the latest one. Run git clone --branch <tag> --depth 1 https://github.com/Freakling/Godot-Director.git Godot-Director there, replacing <tag> with it, or download that release's source zip and rename the extracted folder. Then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: run npx skills add Freakling/Godot-Director again to get the skill of the latest release, then ask for it (/godot-director in Claude Code).
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

What's changed

• The manual install clones the latest release. The README's manual option cloned main, the integration branch, so a manual install got unreleased changes. It now clones the release tag (git clone --branch <tag> --depth 1), and says the tag is v followed by the version and where the latest one is listed; a release's source zip is the other way in. The manual upgrade wording still holds: put the new folder in and ask for ONBOARDING.md again.
• Every install path gets the latest release. The installer skill and the Claude Code plugin now install the release tagged v<version>; main is where changes are integrated, not what people install. The skill clones --branch v<version> into a fresh temporary folder, the way SaaSAllTheThings does, and deletes it after onboarding, instead of cloning main into a fixed folder and pulling it on reuse. The marketplace names the plugin as a github source with ref v<version>, because Claude Code's relative-path source (./) can't pin a ref. The skill's metadata.version said 3.3.0; it now follows VERSION. CLAUDE.md › After any change lists every file that carries the version and says each release is tagged v<version> once its pull request is merged. The selftest checks that the skill's version and the release it clones, and the marketplace's ref, agree with VERSION. The README says the skill and the plugin install the latest release, and that upgrading the skill means running npx skills add again.

Upgrade steps

None for the game's own files.

v3.7.0

How to install

Option 1: the skill (any assistant):

npx skills add Freakling/Godot-Director

In Claude Code this becomes a /godot-director command. The skill fetches Godot Director and runs onboarding.

Option 2: the Claude Code plugin:

/plugin marketplace add Freakling/Godot-Director
/plugin install godot-director@godot-director

Open a new session in your game, then run /godot-director:godot-director.

Option 3: manual:
Put this repository next to project.godot as a folder named Godot-Director, then ask your assistant to read Godot-Director/ONBOARDING.md and follow it.

Upgrade:

• Skill: ask for the skill again (/godot-director in Claude Code); it fetches the latest Godot Director each time.
• Plugin: run /plugin marketplace update godot-director and then /plugin update godot-director@godot-director. Start a new session in the game, and run /godot-director:godot-director again.
• Manual: put the new Godot Director folder in the game, and ask for ONBOARDING.md again.

---

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

---

What's changed

• New: /research, the research assistant (.godot-director/procedures/research.md). When a design question depends on facts nobody has checked, or you ask for research, a read-only researcher subagent looks into it in a fresh context and reports a note. It informs; you decide: its recommendation is one option shown with its reason, and it never records a decision, edits the GDD or design/decisions.md, answers an open question, or asks you anything. It states its assumptions in the note instead.
  • Research is a task type. Research items get their own IDs, R<n>, drawn from the Next IDs line like bugs. Instead of Done when they have Question: and, when they feed an open question, Informs: Q<n>. They are sized like any item, and the size picks the model. An item is done when its note exists.
  • Two ways to start. On the fly: a design session delegates a complex question, or you run /research <question>, and the item is created and run at once. For later: queue the item, and list it under Depends on of the tasks that need its findings. A task that needs the decision stays gated by the open question itself.
  • /next-task hands research items to the researcher. No check runs and no review: research changes no code. This session writes the note to design/research/YYYY-MM-DD-<slug>.md and commits it with the records. A finished item that informs Q<n> makes that question ready for a design call, and a run goes on to the next item.
  • Design sessions list design/research/ first, show notes on the topic in the context brief, delegate a question that needs facts, and end the decision's why with the note's path so later sessions reuse the evidence.
  • The note is one dated file per topic: the conclusion first, the options and trade-offs, the recommendation, every claim with its source, source tier and confidence, the date the claims were verified, and what stays unknown.
  • A Godot domain file (.godot-director/research-domain.md) is read when the question touches the engine and its docs for the project's version, plugins and assets and their licences, export and store requirements, or how comparable games solve the problem (design references, checked against the Design Pillars).
  • Confidentiality. Project text and unpublished design never go into a public search query or fetch.
  • The researcher has Read, Grep, Glob, WebSearch and WebFetch: no edit, write or shell tool. .claude/settings.json allows web search and fetch; everything with side effects keeps asking.
• Align checks that Next IDs has an R counter, that research items have a Question: instead of Done when, and that each done research item has its note.
• Selftest checks that the research files exist and are wired into the procedures, the item format, the seeds and the docs, that the researcher has no edit, write or shell tool, that the installer ships everything (including with --tools none), and that a research note commits without running the check.
• The example (examples/market-day) shows the R counter and the note folder, and the scenarios gain two for research.
• Web search and fetch are allowed in every session in a game, not only for the researcher, because Claude Code can't limit a permission to one subagent: .claude/settings.json allows WebSearch and WebFetch, so any session can search and fetch the web without asking.

Upgrade steps

1. TASKS.md: add an R counter to the Next IDs line, so **Next IDs:** T12 · B3 becomes **Next IDs:** T12 · B3 · R1.
2. design/research/: the installer creates the folder with a short README.md (a project file, yours from then on) when the game doesn't have it. Notes are added there as research runs; commit them like the other records.
3. .claude/settings.json is framework-owned, so it is replaced on upgrade. If you edited it, the new version arrives as .claude/settings.json.gdir-new; merge it, and make sure "WebSearch" and "WebFetch" are in permissions.allow, which lets the researcher read the web without asking each time. Restart Claude Code afterwards so the new skill, subagent and permissions load.

No other game-owned file changes are required.