/validate-ai-local

name: validate-ai-local
argument-hint: "[base-ref] (defaults to the repository default branch)"
allowed-tools: Read, Edit(~/.claude/plugins/data/claude-config-validator*/ai-validation/*), Grep, Glob, Task, Skill, WebFetch(domain:code.claude.com), Bash(git diff:*), Bash(git fetch origin:*), Bash(git rev-parse:*), Bash(git symbolic-ref:*), Bash(git ls-files:*), Bash(date:*), Bash(ls:*)
description: Validate the Claude Code material you changed locally and write a timestamped report to the plugin's data directory

Validate the Claude Code material changed in this checkout, the same way the `bitwarden/gh-actions` [validate-ai](https://github.com/bitwarden/gh-actions/tree/main/validate-ai) action validates a pull request — but against your working tree, and writing the report to a local file instead of a pull request comment.

Read `${CLAUDE_PLUGIN_ROOT}/skills/reviewing-claude-config/reference/validate-ai-scope.md` first. It defines which paths count as Claude material, how to bucket them, which validations each bucket gates, and the report contract. Follow it exactly.

Requirements and troubleshooting are in `${CLAUDE_PLUGIN_ROOT}/docs/local-validation.md`.

**Never post anything to GitHub from this skill.** Output is local files only.

**This skill produces a report. It does not fix anything.** The report is the deliverable and you decide what to act on — nothing here holds a grant to edit the files under review. If you are re-running after fixes, keep the base ref pinned where the first run had it and re-check the previous findings; do not discover new ones against the fixes, or each round manufactures the next round's work.

1. Determine the base ref

• If `$ARGUMENTS` is provided, use it as the base ref.
• Otherwise resolve the default branch:

`git symbolic-ref --quiet refs/remotes/origin/HEAD` → strip `refs/remotes/`; fall back to `origin/main` if that fails, and to `main` if there is no `origin` remote.

• Best-effort `git fetch origin <branch>` so the comparison is against current base.

Only `origin` is pre-approved, so a base ref on another remote is not fetched; the comparison then runs against whatever that ref already points at locally. If the fetch fails (offline, no remote), continue with what is local and note it in the report.

• If the resolved base ref does not exist (`git rev-parse --verify`), stop and tell the

user which ref you tried.

2. Collect changed files

Local review covers committed **and** uncommitted work — this is the point of running it before you push. Take the union of:

git diff --name-only <base-ref>...HEAD    # committed on this branch
git diff --name-only HEAD                 # staged and unstaged, tracked files
git ls-files --others --exclude-standard  # untracked files

Deduplicate, then classify with the scope reference. Report the file counts you found so the user can see what was in scope.

If nothing matches, write the report saying no Claude-related files changed, tell the user, and stop.

3. Run the bundled script checks

These live in `bitwarden/gh-actions` at [`validate-ai/scripts/`](https://github.com/bitwarden/gh-actions/tree/main/validate-ai/scripts) — that directory is their sole source of truth, so never vendor or reimplement them.

Skip this whole section when the repository has no `.claude-plugin/marketplace.json`.

Locate the scripts, in order:

1. `$BW_GH_ACTIONS_PATH/validate-ai/scripts` 2. A sibling checkout: `<repo-root>/../gh-actions/validate-ai/scripts` 3. Neither found — tell the user you need a `gh-actions` checkout, and offer to shallow clone it: `git clone --depth 1 https://github.com/bitwarden/gh-actions <tmpdir>`. Ask before cloning. If the user declines, skip the script checks and name them on the report's `**Not covered:**` line.

Cloning and running these scripts is deliberately not pre-approved in this skill's `allowed-tools`, so both will be asked for. They execute shell code that lives outside this repository; that is worth a prompt, and a user who runs this often can allowlist the exact commands themselves.

Run each applicable check from the scope reference's gating table, with `REPO_ROOT` set to this repository (without it the scripts inspect the `gh-actions` checkout and fail on a path that isn't there):

REPO_ROOT=<repo-root> bash <scripts>/validate-plugin-structure.sh <changed plugins>
REPO_ROOT=<repo-root> bash <scripts>/validate-marketplace.sh <changed plugins>
REPO_ROOT=<repo-root> bash <scripts>/validate-version-bump.sh <base-ref> <component plugins>

Capture each script's exit status and output; a non-zero exit is a failing check, not a reason to stop. Run every remaining check, then report them all together.

**Local caveat to state in the report when the version-bump check runs:** it reads the current version from the working tree, so an uncommitted bump counts, but it detects the changelog entry with `git diff <base-ref>...HEAD`, so an uncommitted `CHANGELOG.md` edit is not seen and will be reported as missing until you commit it.

4. Plugin validation (plugin-validator agent from plugin-dev)

Sections 4 and 5 are subagent work, and every call in them is independent: one validation per changed plugin, one review per changed skill. Work out the full set across both sections and dispatch it in a single message with several tool calls, so they run concurrently. Keep them synchronous (`run_in_background: false`, where that parameter exists), and never describe a subagent's findings before it has returned them. Section 6 is yours to carry out once their results come back. The numbering is not an execution order.

Every subagent prompt must state that findings are limited to **what this changeset introduced or worsened — never a pre-existing finding on a line the diff did not touch.** Subagents do not inherit this skill's context, and an unfenced one re-audits whole files because they appear in the diff.

Usually the changes here are your own, so