godot-stagehand: Instructions file for Codex

Agent Instructions

This project uses br (beads_rust) for issue tracking. Run br robot-docs guide to get started.

Quality Standards — MANDATORY

Every agent session MUST follow strict TDD. No exceptions.

TDD Protocol

1. Write a failing test FIRST — before any implementation code
   • Go: unit test in *_test.go or E2E test in e2e_test.go
   • GDScript: GdUnit4 test in testdata/test_project/test/
2. Run the test — verify it fails for the right reason
3. Write the minimum code to make the test pass
4. Run the full test suite — go test ./... — no regressions
5. Refactor if needed, re-run tests
6. Run code-simplifier:code-simplifier agent before committing

Quality Gates (run before every commit)

go vet ./...          # Lint
go test ./...         # All Go tests pass
# If GDScript changed — run the GdUnit4 unit suite (headless):
GODOT_BIN=/path/to/Godot_v4.x-stable_linux.x86_64 ./scripts/run-gdscript-tests.sh
# Or through Go, which parses the JUnit report and fails on any failure/skip:
GODOT_BIN=/path/to/Godot_v4.x-stable_linux.x86_64 go test -tags=gdscript -run TestGdUnitSuite .
# Needs Godot 4.6+: GdUnit4 v6.1.3's CLI runner hangs on 4.4 headless. The addon
# itself still targets 4.3+, which the gdscript-parse CI matrix covers.
# If GDScript changed — strict-mode validation:
timeout 5 ${GODOT_BIN:-godot} --path testdata/test_project --headless --stagehand 2>&1 | grep -E "SCRIPT ERROR|Server listening"
# Must show "Server listening on port 26700" with ZERO "SCRIPT ERROR" lines.
# testdata/test_project has all GDScript warnings elevated to errors — this catches:
#   - Implicitly inferred static types (:= without annotation)
#   - float()/int()/bool()/String() constructors with Variant args
#   - Discarded return values
#   - Variable shadowing
#   - Untyped function parameters
#   - Unsafe property/method access on Variant
# Set GODOT_BIN to your Godot binary (e.g. export GODOT_BIN=/path/to/Godot_v4.x-stable_linux.x86_64)