git:20260401.fa992a7 to git:20260401.0303049

4 added, 4 removed. Audit A to A.

# CLAUDE.md

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

## Project Overview

**quick-question** is a Claude Code plugin that provides a Unity developer-loop runtime: artifact-driven control (`/qq:go`), auto-compilation hooks, test pipelines, executable policy checks, cross-model and Claude-only code review, and 22 skills (`/qq:*`). It targets macOS + Windows (Windows requires Git for Windows) with Unity 2021.3+.

## Repository Structure

- `hooks/hooks.json` — Hook definitions (PreToolUse, PostToolUse, Stop) loaded by the Claude Code plugin system

- `scripts/` — Bash scripts for compilation, testing, and review (run inside the target Unity project)

- `.qq/` — Runtime data written in target Unity projects (`runs/`, `state/`, `telemetry/`)

- `skills/` — 22 skill definitions (each has a `SKILL.md`), invoked as `/qq:<name>`

- `packages/com.tyk.tykit/` — UPM package providing tykit (in-process HTTP server for Unity Editor control)

- `.claude-plugin/` — Plugin manifest (`plugin.json`, `marketplace.json`)

- `templates/` — `CLAUDE.md.example` and `AGENTS.md.example` copied into target projects by `install.sh`

- `install.sh` — Installs scripts, templates, and tykit into a Unity project

## Key Architecture

### Hook System

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

- **PreToolUse (Edit|Write):** Review Gate — blocks code edits while review verification is pending

- **PostToolUse (Write|Edit):** Auto-compiles `.cs` files via `unity-compile-smart.sh`; tracks skill file modifications for review enforcement

- **PostToolUse (Bash):** Activates review gate when `code-review.sh` or `plan-review.sh` runs

- **PostToolUse (Agent):** Increments verification subagent counter (to release review gate)

- **Stop:** Blocks session end if skills were modified without running `/qq:self-review`; cleans up gate files

All temp files are keyed by `$PPID` for session isolation (e.g., `$QQ_TEMP_DIR/review-gate-$PPID`).

### 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

### 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 Unity checks before deeper best-practice or review workflows

- `.qq/state/*.json` is the preferred source for latest compile/test state; raw `.qq/runs/*.json` logs are for debugging or CI-style consumption

### Smart Compilation Stack

`unity-compile-smart.sh` is the orchestrator, choosing the best path:

1. **tykit mode** — HTTP call to in-process Unity server (fastest, non-blocking)

2. **Editor trigger** — osascript (macOS) or PowerShell (Windows) to trigger compile in open Unity (fallback)

3. **Batch mode** — `Unity -quit -batchmode` (when Editor is closed)

Shared utilities live in `unity-common.sh` (Editor detection, Unity path lookup, tykit 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).

### Code Review

- Two review modes, same verification loop:

- - **Cross-model** (`/qq:codex-code-review`): Codex CLI reviews the diff, then verification subagents check each finding against actual source

- - **Single-model** (`/qq:claude-code-review`): A Claude subagent reviews the diff, then separate verification subagents check each finding

+ Two symmetric review modes, 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). The review gate (`scripts/hooks/review-gate-*.sh`) blocks code edits until at least one verification subagent completes.

+ Both modes: over-engineering check, fix confirmed issues, loop until clean (max 5 rounds). The 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.

## Development Commands

```bash

# Test the installer against a Unity project

./install.sh /path/to/unity-project

# Validate shell scripts

shellcheck scripts/*.sh

# Validate hook JSON

python3 -m json.tool hooks/hooks.json > /dev/null

```

There is no build step or package manager for this repo itself. Run `./test.sh` for self-tests (shellcheck, JSON validation, structural checks, README consistency). The scripts and skills are consumed as-is by the plugin system.

## Conventions

- Scripts use `set -euo pipefail` and source `unity-common.sh` for shared functions

- Skills are each a directory under `skills/<name>/` containing `SKILL.md`

- Hook scripts in `scripts/hooks/` follow the naming pattern `review-gate-{check,set,count,stop}.sh`

- Comments in shell scripts are in Chinese (author preference); code and user-facing output are in English

- The `install.sh` output now uses the current plugin skill names (`/qq:test`, `/qq:commit-push`, etc.)