docs(agents): add development guardrails and Claude Code automation

- CRITICAL pre-edit checklist (branch/worktree, dual build system, C++17, conventional commits)
- C++17-only standard with prohibited C++20/C++23 features list
- Build system integration rules (dual CMake + Xcode .pbxproj)
- PR review and code-first verification guardrails
- PostToolUse hook: auto-format C++/ObjC via clang-format
- PreToolUse hook: block edits to generated data files
- /engine-test and branch-guard skills
- Fix runtime version (11.0), blob reader name, bridge utility references

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: tianjianjiang

.claude/hooks/block-generated-data.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block direct edits to generated dictionary data files.
+# These files are produced by the dictionary compiler and must not be edited manually.
+# Exit code 2 blocks the tool from executing.
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Block generated data files in Source/Data/
+case "$FILE_PATH" in
+  */Source/Data/data.txt|*/Source/Data/data-plain-bpmf.txt|*/Source/Data/associated-phrases-v2.txt)
+    echo "Blocked: $FILE_PATH is a generated file. Edit the source and rebuild instead." >&2
+    exit 2
+    ;;
+esac

.claude/hooks/format-cpp.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# PostToolUse hook: auto-format C++/ObjC files with clang-format after edits.
+# Reads the tool input JSON from stdin to extract the edited file path.
+
+set -euo pipefail
+
+# Read stdin JSON and extract file_path
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Only format C++/ObjC source files
+case "$FILE_PATH" in
+  *.cpp|*.h|*.mm|*.m)
+    if [[ -f "$FILE_PATH" ]]; then
+      xcrun clang-format -i "$FILE_PATH"
+    fi
+    ;;
+esac

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/format-cpp.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/block-generated-data.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/branch-guard/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Verify branch and worktree before making edits
+user-invocable: false
+---
+
+# Branch Guard
+
+Before editing files, verify:
+
+1. **Current branch**: Run `git rev-parse --abbrev-ref HEAD` and confirm it matches the expected branch for the current task.
+
+2. **Worktree isolation**: Run `git rev-parse --show-toplevel` and confirm edits target the correct worktree directory.
+
+3. **Clean state**: Run `git status --porcelain` and warn if there are uncommitted changes that might conflict.
+
+If any check fails, stop and alert the user before proceeding.

.claude/skills/engine-test/SKILL.md

@@ -0,0 +1,32 @@
+---
+description: Build and run C++ engine tests
+user-invocable: true
+---
+
+# /engine-test
+
+Build and run the full C++ engine unit tests.
+
+## Steps
+
+1. Create the build directory if needed:
+   ```bash
+   mkdir -p Source/Engine/build
+   ```
+
+2. Configure with CMake:
+   ```bash
+   cd Source/Engine/build && cmake -DENABLE_TEST=ON ..
+   ```
+
+3. Build:
+   ```bash
+   cd Source/Engine/build && make -j$(sysctl -n hw.ncpu)
+   ```
+
+4. Run tests:
+   ```bash
+   cd Source/Engine/build && ctest --output-on-failure
+   ```
+
+Report test results. If any tests fail, show the failing test names and output.