CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

quick-question is the agent control plane for game-dev work. It is a Claude Code plugin and an engine-agnostic runtime: artifact-driven control (/qq:go), auto-compile hooks, test pipelines, deterministic policy checks, dual-mode cross-model / Claude-only code review with a verification loop, and 28 skills (/qq:*). It targets macOS and Windows (Windows requires Git for Windows for bash + core utilities). Engines at runtime parity: Unity 2021.3+, Godot 4.x, Unreal 5.x, S&box. Unity has the deepest integration: compile and test drive the open Editor through the official Unity CLI (unity command / unity job), with tykit only as a fallback in projects that still have it; the other three reach parity through Python bridges.

Although Claude Code gets the deepest integration (slash commands, hooks, review gates), the runtime core is agent-agnostic: scripts and bridges are plain shell + Python, and .qq/ state is plain JSON. Codex CLI, Cursor, Continue, and any MCP-compatible host can use the same runtime through qq_mcp.py (MCP) or by calling the scripts directly.

Repository Structure

• hooks/hooks.json — Hook definitions (PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd) loaded by the Claude Code plugin system
• scripts/ — Bash + Python runtime: compile / test / review dispatchers, hook helpers, MCP bridges, controller, runtime helpers
  • scripts/hooks/ — Hook implementations (auto-compile.sh, compile-gate-check.sh, review-gate.sh, pre-push-test.sh, skill-modified-track.sh, auto-sync.sh, session-cleanup.sh, auto-pipeline-*, execute-resume-hint.sh)
  • scripts/platform/ — OS detection helpers
  • scripts/qq_engine.py — multi-engine source-file matcher (matches-source)
  • scripts/qq-compile.sh — multi-engine compile dispatcher (delegates to unity-compile-smart.sh / godot-compile.sh / unreal-compile.sh / sbox-compile.sh)
  • scripts/qq-test.sh — multi-engine test dispatcher
  • scripts/qq-project-state.py — artifact-driven controller (preferred path for /qq:go)
  • scripts/qq-policy-check.sh — deterministic policy checks (run before deeper review workflows)
  • scripts/qq-decisions.py — cross-skill decision journal (session-decisions.json)
  • scripts/qq-frames-to-mp4.py, scripts/qq-contact-sheet.py, scripts/qq-review-page.py (shared helpers in scripts/qq_media.py) — /qq:record media pipeline: frames or video → captioned web-ready mp4, contact sheets for self-check, review page
• engines/ — Per-engine assets (unreal/, godot/, sbox/); referenced by the install flow
• shared/ — Shared prompt fragments (e.g. verification-prompt.md)
• bin/ — Wrapper executables. Skills call them as ${CLAUDE_PLUGIN_ROOT}/bin/<name>; Claude Code does not put them on PATH, so a bare name exits 127
• .qq/ — Runtime data written inside target projects (runs/, state/, telemetry/), not in this repo
• skills/ — 28 skill directories, each with a SKILL.md, invoked as /qq:<name>
• packages/com.tyk.tykit/ — UPM package providing tykit (in-process HTTP server inside Unity Editor). qq no longer installs it; it stays for standalone use and for projects that still depend on it
• .claude-plugin/ — Plugin manifest (plugin.json, marketplace.json)
• templates/ — CLAUDE.md.example, AGENTS.md.example, qq.yaml.example copied into target projects by install.sh
• install.sh — Installs scripts, templates, and engine bridges into a target project (auto-detects engine; supports --wizard, --preset, --profile, --modules, --without); the module list lives in scripts/qq_internal_install.py
• test.sh — Self-tests: shellcheck, JSON validation, executable bits, README consistency (skill count + per-skill /qq: reference), benchmark suites

Key Architecture

Hook System

Defined in hooks/hooks.json. Hooks are the plugin's runtime behavior:

• PreToolUse (Edit | Write): Compile Gate (compile-gate-check.sh) blocks edits to engine source files when this session's compile is red (except the files with errors and the file that triggered the compile; see scripts/qq_compile_gate.py) or the project has never been opened in its editor; Review Gate (review-gate.sh check) blocks code/doc edits while review verification is pending. A PreToolUse hook only blocks with exit 2 — exit 1 is a non-blocking error and the tool runs anyway.
• PostToolUse (Write | Edit): Auto-compile (auto-compile.sh) compiles via qq-compile.sh after edits to engine source files. The dispatcher handles .cs (Unity / S&box), .gd (Godot), and C++ (Unreal). Skill file changes are tracked by skill-modified-track.sh.
• PostToolUse (Bash): review-gate.sh set announces the review gate. The gate itself is opened by code-review.sh, claude-review.sh, plan-review.sh, and claude-plan-review.sh (qq_review_gate_open in scripts/platform/detect.sh) once a review has actually run; the hook never guesses from command text.
• PostToolUse (Agent): review-gate.sh count increments the verification subagent counter to release the review gate once all expected verifiers complete.
• Stop: check-skill-review.sh blocks session end if skills were modified without /qq:self-review; review-gate.sh stop blocks the stop once while verification is incomplete (bash builtins only, no python; it never deletes an unverified gate, so the gate outlives the turn); auto-pipeline-stop.sh keeps an --auto pipeline going. Claude Code runs a group's hooks in parallel, so nothing else in the Stop group may touch the gate file.
• SessionEnd: session-cleanup.sh removes this session's review gate (a killed session leaves it to the 2-hour expiry).
• SessionStart: auto-sync.sh syncs plugin scripts into the target project; on compact, execute-resume-hint.sh and auto-pipeline-resume-hint.sh surface in-flight work.

All gate / temp files are keyed by the Claude Code session id for session isolation (e.g. $QQ_TEMP_DIR/review-gate-<session_id>, $QQ_TEMP_DIR/compile-gate-<session_id>). Hooks read session_id from their stdin JSON, skill Bash snippets read CLAUDE_CODE_SESSION_ID (same value; subagents carry the parent session's id); both go through qq_session_id in scripts/platform/detect.sh. Never key on $PPID — under Windows Git Bash it is always 1, so every session would share one gate file. No session id → no gate (never fall back to a shared file).

Hook scripts read tool input from stdin via the shared qq_hook_input helper in scripts/qq-runtime.sh (jq-first, with a $QQ_PY python fallback so hooks work even when jq is missing).

Config Axes

Four independent knobs, resolved by scripts/qq_internal_config.py in the order .qq/local.yaml > qq.yaml > profile > default:

• work_mode = task stage (prototype / feature / fix / hardening)
• policy_profile = verification floor
• trust_level = automatic permission boundary
• workflow = how heavy the process is. heavy-review (Heavy Review, the default) runs every skill as written. prototype-loop (Prototype Loop) runs design / plan / execute / review as shared/prototype-loop.md describes: a user-approved acceptance checklist, a failing check first per slice, one review round verified by the main agent, and an independent closeout check. It drops the review_gate hook unless hooks.enable names it. Not the same as work_mode: prototype, which skips design and plan.

Skills read the workflow with ${CLAUDE_PLUGIN_ROOT}/bin/qq-config.py field workflow, or take --workflow <name> from their arguments, which wins over the config (a --auto pipeline resumes each step with the workflow it started with). The review scripts take --workflow too and open no review gate for prototype-loop.

Artifact-driven Controller

/qq:go should prefer scripts/qq-project-state.py when available. It is a controller, not an implementation engine:

1. Read project state from artifacts and recent run records
2. Recommend the next skill
3. Only fall back to prompt / context heuristics when state is ambiguous

The decision journal (scripts/qq-decisions.py) records cross-skill decisions in .qq/state/session-decisions.json so later skills can stay coherent with earlier ones.

Runtime Data + Policy

• scripts/qq-run-record.py and scripts/qq-runtime.sh write structured runtime data to .qq/
• scripts/qq-policy-check.sh runs deterministic engine checks (compile / test / asset hygiene) before deeper best-practice or review workflows
• .qq/state/*.json is the preferred source for the latest compile / test state; raw .qq/runs/*.json logs are for debugging or CI-style consumption
• .qq/state/session-decisions.json is the cross-skill decision journal

Smart Compile Dispatch

scripts/qq-compile.sh is the multi-engine entry point. It detects the active engine and delegates:

• Unity → unity-compile-smart.sh, which picks a channel to the open Editor with qq_unity_channel (unity-common.sh):
  1. Official Unity CLI — the project has a live Library/Pipeline/.unity-pipeline-port (Unity's Pipeline server, package com.unity.pipeline) and the unity CLI is found (QQ_UNITY_CLI overrides the lookup): unity command recompile, which works while Unity is unfocused or minimized and never brings its window forward
  2. tykit — only in projects that still have it (Temp/tykit.json)
  3. Refresh trigger — unity-check.sh --trigger writes Temp/refresh_trigger for an Editor-side watcher, and brings the Unity window forward (osascript / PowerShell) only when no Pipeline server is running
  • No Editor detected → hard failure, exit 2. Batch mode (Unity -quit -batchmode) runs only with an explicit --batch: a second Unity process would fight an open Editor for the project lock, and "not detected" does not prove the Editor is closed
  • unity-test.sh picks the same way: the official CLI (EditMode as a detached unity job, PlayMode asynchronously; green or red comes from the test summary, never from a success field) or tykit; no Editor → exit 2. shared/unity-live-state.md tells skills which channel a project uses
• Godot → godot-compile.sh (headless --check-only GDScript validation)
• Unreal → unreal-compile.sh (UnrealBuildTool + editor commandlet)
• S&box → sbox-compile.sh (dotnet build)

Shared utilities live in unity-common.sh / godot-common.sh / unreal-common.sh / sbox-common.sh (Editor detection, paths, port discovery).

tykit

UPM package at packages/com.tyk.tykit/. An HTTP server auto-starting in Unity Editor, exposing commands: status, compile, run-tests, play / stop, console, find / inspect. Port stored in Temp/tykit.json (hash of project path). Works standalone without qq. qq no longer installs it or its Python / MCP bridges (see the engine-unity module in scripts/qq_internal_install.py): Unity Editor control goes through the official Unity CLI (shared/unity-cli-reference.md), and the compile / test scripts use tykit only as a fallback channel. Unity MCP hosts get the generic qq_* tools from qq_mcp.py.

Code Review

Two symmetric review modes share the same verification loop:

• Claude review (/qq:claude-code-review): claude-review.sh → claude -p (process-isolated), then verification subagents check each finding
• Codex review (/qq:codex-code-review): code-review.sh → codex exec (cross-model), then verification subagents check each finding

Both modes: over-engineering check, fix confirmed issues, loop until clean (max 5 rounds). Under workflow: prototype-loop both run a single round verified by the main agent, with no gate (see Config Axes). The unified review gate (scripts/hooks/review-gate.sh) blocks code edits until ALL verification subagents complete (three-field gate format: <ts>:<completed>:<expected>). MCP exposes one-shot qq_code_review and qq_plan_review tools for non-Claude hosts.

There are also legacy review-gate-{check,set,count,stop}.sh scripts kept for backward compatibility with already-installed projects; new hook bindings should use review-gate.sh <subcommand>.

Development Commands

# Test the installer against a project
./install.sh /path/to/your-project

# Validate shell scripts
shellcheck scripts/*.sh scripts/hooks/*.sh

# Validate hook JSON
python3 -m json.tool hooks/hooks.json > /dev/null

# Run the full self-test suite (shellcheck, JSON, structural checks, README consistency, benchmark suites)
./test.sh

There is no build step or package manager for this repo itself. The scripts and skills are consumed as-is by the Claude Code plugin system.

Conventions

• Scripts use set -euo pipefail and source qq-runtime.sh / platform/detect.sh / engine-specific common files for shared functions
• Skills are each a directory under skills/<name>/ containing SKILL.md
• Hook scripts in scripts/hooks/ parse stdin JSON via qq_hook_input (jq-first, python3 fallback) — never call jq directly in new hook scripts
• Comments in shell scripts are in Chinese (author preference); code identifiers and user-facing output are in English
• install.sh output uses the current plugin skill names (/qq:test, /qq:commit-push, etc.)
• .gitattributes enforces LF line endings for .sh and .py so Windows checkouts don't corrupt hook scripts
• Comments and side-effects in hook scripts must remain idempotent; hooks may fire twice on the same input
• Chinese README has one canonical source — docs/zh-CN/README.md is the canonical file; the Chinese half embedded in the root README.md is auto-generated by scripts/qq-sync-readme-zh.py (it strips the title + lang nav and rewrites relative paths to be repo-rooted). Workflow: edit docs/zh-CN/README.md, then run python scripts/qq-sync-readme-zh.py --write to mirror, then commit both. test.sh section 4 enforces the contract via --check and fails CI with a DRIFT message if you skip the sync. Do not edit the root README's Chinese half directly — your changes will be clobbered the next time someone runs the sync.

Windows release gotchas

A recurring trap when releasing from a Windows host. It has bitten CI more than once — see commits eedebe2, 64bce1d.

• chmod +x on Windows does not write the git index mode bit. New .sh / .py scripts ship as 100644 even after a successful local chmod, and test.sh section 7 (Script permissions) catches it on CI (validate.yml, macos-latest) as NOT executable. When adding any new executable script, run git update-index --chmod=+x <path> and verify with git ls-files --stage <path> (look for 100755, not 100644) before committing. The Edit / Write tool path is the most common offender — Bash chmod is invisible to git index.

Releasing

scripts/qq-release.sh adds a Co-Authored-By trailer to the release commit only when the caller names one, with --co-author or the QQ_RELEASE_CO_AUTHOR environment variable; with neither, the commit has no such line. An agent running the release passes its own model line, e.g. scripts/qq-release.sh patch "<notes>" --co-author "Claude Opus 5.5 (1M context) <noreply@anthropic.com>".