CLAUDE.md · diff
git:20261110.472164c to git:20261110.5084b95
2 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# agent-skills-vrc-udon Development Guide
This repository is an **npm package** that distributes AI agent skills for VRChat UdonSharp development.
It is NOT a VRChat/Unity project. The codebase consists of markdown knowledge files, templates, and CI workflows.
## Repository Structure
```
skills/ # Skill content (distributed to users)
unity-vrc-udon-sharp/ # UdonSharp constraints, networking, templates
unity-vrc-world-sdk-3/ # World SDK components, optimization
.claude/
rules/
doc-sync.md # Documentation sync rule (repo maintenance)
hooks/
doc-sync-reminder.sh # PostToolUse hook: reminds about doc updates
skills/
unity-vrc-skills-renovator/ # Meta-skill for maintaining skills (dev only, not distributed)
audit/ # SDK coverage-audit tooling + ledger (maintainer-only, not distributed)
README.md # How to run the SDK-bump diff audit
sdk-coverage-ledger.md # Decision ledger (candidates, verdicts, skips)
scripts/ # census / diff / refine pipeline
templates/ # AI tool config templates (distributed to users)
CLAUDE.md # Claude Code project instructions
AGENTS.md # Codex CLI / generic agent instructions
GEMINI.md # Gemini CLI instructions
hooks/
hooks.json # Claude Code plugin hook registration (runs validate-udonsharp.sh)
.github/
workflows/ # CI (lint, pack test, publish)
ISSUE_TEMPLATE/ # Bug report, knowledge request
tests/
run.sh # Local entry point: runs every suite CI runs
docs/ # Documentation contract tests and fixtures
hooks/ # Validator hook tests and fixtures
package.json # npm package config
```
## Development Workflow
```
feature/* ──PR──> dev ──release PR──> main ──tag──> npm publish
```
- Default branch: **`dev`** (integration)
- Release branch: **`main`** (triggers npm publish via GitHub Release)
- **All PRs must target `dev`** (never `main` directly)
- `main` is updated only via release PRs from `dev`
### Branch Protection
Both `dev` and `main` are protected:
- No direct push (`enforce_admins: true`, applies to admin too)
- All seven CI checks are required: Symlink Integrity, Hook Scripts, Documentation Smoke Tests,
Markdown Links, npm Pack Test, EditorConfig, and Version Sync
- Required checks use `strict: false` on `dev` and `strict: true` on `main`
- PR required for all changes
### Branch Naming
`feature/*`, `fix/*`, `docs/*`, `refactor/*`, `security/*`, `chore/*`
## Key Files
| File | Purpose |
|------|---------|
| `package.json` | npm metadata, `files` array controls what gets published |
| `skills/*/SKILL.md` | Skill definitions with YAML frontmatter |
| `skills/*/rules/*.md` | Constraint rules for AI code generation |
| `templates/*.md` | AI tool config files distributed to end users |
## Testing
```bash
# Run every suite CI runs. Needs bash, python3 and jq; on Windows run it inside WSL.
npm test # same as: bash tests/run.sh
bash tests/run.sh layers # only suites whose path contains "layers"
# Verify npm pack includes correct files
npm pack --dry-run
```
The BusyBox and PowerShell hook suites are skipped locally when `busybox` or `pwsh` is missing; CI always runs them.
## CI Checks
| Check | What it verifies |
|-------|-----------------|
| Symlink Integrity | No symlinks in repo (breaks npm pack) |
| Hook Scripts | validate-udonsharp.sh is executable and valid bash |
| Documentation Smoke Tests | Required documentation reference coverage is present |
| Markdown Links | No broken links in documentation |
| npm Pack Test | Package includes all required files |
| EditorConfig | File formatting matches .editorconfig rules (indent_size check disabled; see below) |
| Version Sync | All five package version fields agree |
### EditorConfig Notes
- **IndentSize check is intentionally disabled** in `.editorconfig-checker.json` (`Disable.IndentSize: true`).
C# uses 4-space indentation while JS/MJS uses 2-space; continuation lines and alignment patterns
in C# templates cause false positives. The `indent_style` check (tabs vs spaces) remains active.
- **Editor setup**: Install an [EditorConfig plugin](https://editorconfig.org/#pre-installed) for your IDE
to automatically apply formatting rules from `.editorconfig`.
- **Per-line exceptions**: Use `// editorconfig-checker-disable-line` for intentional deviations.
## Release Guide
### Overview
```
main ──sync PR──> dev (when the ancestry check fails)
dev ──version-bump PR──> dev ──release PR──> main ──Release Drafter draft──> publish ──> npm
```
GitHub Release notes are drafted by Release Drafter, and GitHub Releases are the canonical release history. `CHANGELOG.md` is a historical archive through v1.2.0; later releases are not backfilled. **Version numbers must be bumped manually on `dev` before opening the release PR** (see Step 2 below). `publish.yml` does run `npm version "$VERSION" --no-git-tag-version` in the CI runner as a safety net, but those edits are not committed back, so the git tree's source-of-truth must be kept current by hand.
### Step-by-step
1. **Synchronize `main` into `dev` when needed**
- Fetch both remote branches and verify that `dev` contains the current `main` history:
```bash
set -e
git fetch origin
if ! git merge-base --is-ancestor origin/main origin/dev; then
SYNC_BRANCH="chore/sync-main-into-dev-$(date +%Y%m%d%H%M%S)"
git switch --create "$SYNC_BRANCH" origin/dev
git merge --no-ff origin/main -m "chore: sync main into dev before release"
git push -u origin "$SYNC_BRANCH"
SYNC_PR=$(gh pr create --base dev --head "$SYNC_BRANCH" \
--title "chore: sync main into dev before release" \
--body "Merge the current main history into dev before the next release.")
REQUIRED_CHECKS=(
"Symlink Integrity"
"Hook Scripts"
"Documentation Smoke Tests"
"Markdown Links"
"npm Pack Test"
"EditorConfig"
"Version Sync"
)
for ((attempt = 1; attempt <= 30; attempt++)); do
REGISTERED_CHECKS=""
if REGISTERED_CHECKS=$(gh pr view "$SYNC_PR" --json statusCheckRollup \
--jq '.statusCheckRollup[] | (.name // .context)' 2>/dev/null); then
:
fi
MISSING_CHECKS=()
for REQUIRED_CHECK in "${REQUIRED_CHECKS[@]}"; do
if ! grep -Fqx -- "$REQUIRED_CHECK" <<<"$REGISTERED_CHECKS"; then
MISSING_CHECKS+=("$REQUIRED_CHECK")
fi
done
if (( ${#MISSING_CHECKS[@]} == 0 )); then
break
fi
if (( attempt == 30 )); then
printf 'ERROR: timed out waiting for required checks to register. Missing checks:\n' >&2
printf ' - %s\n' "${MISSING_CHECKS[@]}" >&2
exit 1
fi
sleep 10
done
gh pr checks "$SYNC_PR" --required --watch
gh pr merge "$SYNC_PR" --merge --delete-branch
git fetch origin
git merge-base --is-ancestor origin/main origin/dev
fi
```
- The sync PR must pass all seven required checks: Symlink Integrity, Hook Scripts,
Documentation Smoke Tests, Markdown Links, npm Pack Test, EditorConfig, and Version Sync.
Do not continue until the final ancestry check succeeds.
2. **Bump version fields on `dev`**
- Decide the target version vX.Y.Z (consult labels on merged PRs since the last release — see "Version resolution" below).
- Branch off `dev`, run the bump, open a PR back to `dev`:
```bash
set -e
git checkout dev && git pull
git checkout -b chore/release-vX.Y.Z
# OLD: read from local package.json. If your local is stale, prefer:
# OLD=$(npm view agent-skills-vrc-udon version)
OLD=$(node -p "require('./package.json').version")
NEW=X.Y.Z
# 5 fields must move together — Version Sync CI verifies parity.
# The SKILL.md sed is anchored to the 4-space-indented frontmatter line
# so body-text occurrences (e.g. SDK version mentions) are not rewritten.
sed -i "s/\"version\": \"$OLD\"/\"version\": \"$NEW\"/" package.json .claude-plugin/marketplace.json
sed -i "s/^ version: \"$OLD\"$/ version: \"$NEW\"/" \
skills/unity-vrc-udon-sharp/SKILL.md \
skills/unity-vrc-world-sdk-3/SKILL.md \
.claude/skills/unity-vrc-skills-renovator/SKILL.md
# Sanity check before commit — only the 5 expected fields should diff.
git diff --stat
git commit -am "chore(version): bump to vX.Y.Z"
git push -u origin chore/release-vX.Y.Z
gh pr create --base dev --label "release: maintenance" \
--title "chore(version): bump to vX.Y.Z" \
--body "Pre-release version bump for Step 3 of the release flow."
```
- Wait for all seven required CI checks to pass. Version Sync verifies all 5 fields agree on `vX.Y.Z`. Merge the bump PR into `dev` (squash is fine here — single-purpose commit). CodeRabbit review is optional on this PR — it's mechanical and Version Sync is the substantive check.
3. **Create a release PR from `dev` to `main`**
```bash
gh pr create --base main --head dev \
--title "Release vX.Y.Z" \
--body "Merge dev into main for release"
```
- Title must include the version that matches `package.json#version` on `dev` after Step 2.
- Wait for CI to pass. CodeRabbit approval is **not required for release PRs** (per repo convention — release PRs are mechanical merges of already-reviewed commits).
4. **Merge the release PR**
- Merge (do NOT squash — preserve commit history so Release Drafter sees each underlying PR commit).
- This triggers Release Drafter to update the draft release on `main`.
5. **Publish the GitHub Release draft**
```bash
# List draft releases
gh release list --exclude-drafts=false
# Always rewrite the auto-generated notes before publishing:
# - Remove the "Release vX.Y.Z (#N)" self-reference line
# - Replace bare PR titles with user-facing prose
# - Use a bilingual structure: English release notes first, then a Japanese
# version of the same user-facing content below it.
# - Add a contributor acknowledgement section when any bundled PR closed an
# externally-reported Issue. Name the Issue number and reporter explicitly.
# Keep the acknowledgement respectful and mirror the reporter's language
# when possible.
gh release edit vX.Y.Z --notes "$(cat <<'NOTES'
## What's New in vX.Y.Z
...
## vX.Y.Z の変更点
...
NOTES
)"
# Publish (this triggers publish.yml → npm publish)
gh release edit vX.Y.Z --draft=false
```
- The `published` event triggers `publish.yml`.
- `publish.yml` reads the tag, runs `npm version "$VERSION" --allow-same-version` (no-op if Step 2 was done correctly), syncs to SKILL.md / marketplace.json again as a safety net, and runs `npm publish --provenance`.
- Uses the `npm-publish` environment (requires `NPM_TOKEN` secret).
- All published releases and their tags are kept permanently. Never delete releases or tags — published versions may be referenced by tag (e.g. `git clone --branch vX.Y.Z`), and deleting tags breaks reproducibility for users pinning a version (see Issue #290).
### Version resolution (label-driven)
When deciding the target version in Step 2, count the labels on PRs merged into `dev` since the last release:
| Label | Bump |
|-------|------|
| `release: breaking` | major |
| `release: feature` | minor |
| `release: fix` | patch |
| `release: docs` | patch |
| `release: maintenance` | patch |
The highest bump wins. If no label matches, default to **patch**. Release Drafter independently resolves the same labels for the draft body, so as long as the manual bump in Step 2 matches Release Drafter's resolution, the draft and `package.json` will agree.
### What NOT to do
- Do NOT skip Step 2 (the manual version bump). `publish.yml`'s runner-side mutation does **not** commit back, so a missed bump leaves the git tree frozen. The Version Sync CI check trivially passes when all 5 fields agree on the wrong value — this drifted for 5 release cycles before being caught (PR #169).
- Do NOT create tags manually (Release Drafter creates them when the release is published).
- Do NOT push directly to `dev` or `main` (branch protection blocks it; use the PR flows above).
- Do NOT merge feature branches directly to `main` (always go through `dev`).
## SDK Verification
Public VRChat creator docs and the `vrchat-community/UdonSharp` API page sometimes lag behind the actual SDK binary. When triaging a knowledge-request Issue that hinges on whether a specific API exists, the authoritative source is the SDK DLL itself.
This repo uses a gitignored local workspace pattern at `unity-project-for-sdk-search/` for that verification. The directory is intentionally not packed into the npm tarball — only its `README.md` is tracked so the convention is discoverable on clone. See [`unity-project-for-sdk-search/README.md`](unity-project-for-sdk-search/README.md) for one-time setup steps, the canonical `strings | grep` command, and the Udon wrapper symbol legend.
Use this verification path before documenting any API that you cannot confirm against the official public docs.
### Coverage audit (SDK bumps)
Beyond point verification of a single API, the same workspace backs a repeatable **coverage audit** that diffs the full Udon-callable surface against current skill coverage to surface undocumented-but-shipped gaps — the structural problem behind #190 (`VRCObjectPool.Shuffle()`) and #213/#214 (missing events). Run it on each SDK bump and triage only what changed. The procedure and tooling are in [`.claude/audit/README.md`](.claude/audit/README.md); the inclusion policy it feeds — binary presence is a discovery signal only, never grounds for inclusion — is in [`CONTRIBUTING.md`](CONTRIBUTING.md) ("Content Scope").
## Editing Skills
When modifying skill content in `skills/`:
- Always verify against [official VRChat documentation](https://creators.vrchat.com/)
- Update SDK version tables if adding new API coverage
- Run the validate-udonsharp hook against any `.cs` code examples
- Keep `templates/` in sync if skills table or rules paths change
+ - After adding, renaming, or removing a `##` section in a reference, run `python3 tests/docs/reference-toc.py --write` to refresh its table of contents
+ - The active SDK target is declared once per skill, in the `## SDK Versions` section of each `SKILL.md`. Other files under `skills/` link to it instead of repeating the number
### Documentation Sync
A PostToolUse hook (`.claude/hooks/doc-sync-reminder.sh`) automatically reminds you to update documentation when editing files under `skills/` or `templates/`. See `.claude/rules/doc-sync.md` for the full sync checklist and trigger conditions.