Gamewright

Docs Decisions

Contents

ADR-0008: One tool registry; MCP first; the Director never grades itself

  • Status: Proposed
  • Date: 2026-09-30

Context

Reelwright's showrunner has one tool registry behind MCP, an in-app agent and a CLI, and every mutating tool returns a proposed change set. The survey of AI and Godot tooling (research/ai-godot-tooling.md) adds:

  • Godot MCP servers work on nodes and scripts, below the spec and the approval step. The best are paid and closed, or need a running editor.
  • Unity replaced its in-editor MCP server with a CLI: "faster and use fewer tokens".
  • Tools that go beyond editing converge on run, read errors, inject input, playtest. The best playtest designs pause the game while the model thinks and give it structured state.
  • Users of Rosebud and GDevelop complain about false success claims and "fix one, break another".
  • Godogen deleted its planner and decomposer skills as models improved: prompt scaffolding goes stale, checks don't.
  • There's no Anthropic API key on the dev box today. Claude Code is available.

Decision

  1. One tool registry in the core, exposed three ways: gamewright mcp (stdio, for Claude Code and any MCP client), the in-app Director (Anthropic SDK), and the gamewright CLI. The web API calls the same functions.
  2. MCP first. The owner directs games from Claude Code before any in-app agent exists. The client is the LLM, so this needs no key and no Director loop.
  3. Design-level tools only. Read, propose, run and decide tools over documents (ARCHITECTURE §7). No node-level Godot editing. Every call carries a session id.
  4. Proposals, not writes. Propose tools return change sets with a diff, previews and the verification report. Decide tools (approve, reject, lock, unlock, undo, redo) belong to the human: buttons in the web studio, destructiveHint and explicit-request wording over MCP, a changes subcommand in the CLI.
  5. The Director never grades itself. Pass or fail comes from validators, the engine and the ladder. A report is data the Director reads, not text it writes.
  6. Thin harness, thick checks. Engineering goes into validators, the playtest bridge and the vocabulary, not elaborate prompt pipelines. The staged pipeline is enforced by which tools each stage exposes and by gates, not by prose.
  7. The in-app Director uses the official Anthropic SDK with adaptive thinking; the model and effort are set per stage; there's no forced tool_choice; small inputs use strict tools; tests replay recorded fixtures; budgets stop spending.

Alternatives considered

  • Adopt a Godot MCP server (godot-ai, Coding-Solo). It's useful as contributor tooling in the engine repo, but as the Director's interface it bypasses the spec, the validators and approval.
  • Computer use for playtesting. Too slow and too blind for real-time play (VideoGameBench best 0.48%); macOS-only in the Claude Code CLI.
  • An in-app agent first. It needs a key and a UI before anything is playable.

Consequences

  • Games can be directed from Claude Code as soon as the registry and a few tools exist (M2).
  • The web studio later reuses the registry unchanged; only the agent loop and UI are new.
  • Tool descriptions come from schema descriptions and kit registrations, so they stay in step with the engine.

From docs/adr/0008-director-surfaces.md in the Gamewright repository.