@tyroneross/build-loop 0.30.3

package/skills/plugin-builder/references/plugin-hygiene-lessons.md

@@ -0,0 +1,307 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Hygiene — Lessons Learned
+
+Real-world incidents from building and maintaining the `rosslabs-ai-toolkit` marketplace. Each lesson names the specific failure mode and the rule that prevents recurrence.
+
+## 1. Duplicate hook declarations produce `/doctor` errors
+
+**What happened.** Four plugins (research, spectra, showcase, replit-migrate) declared `"hooks": "./hooks/hooks.json"` in `plugin.json`. Claude Code auto-loads `hooks/hooks.json` by convention, so the explicit declaration registered the file twice, producing:
+
+> Hook load failed: Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file …
+
+**Rule.** Only declare `hooks` in the manifest when the file is at a non-standard path. Same for `mcpServers` (`.mcp.json` auto-loads) and `lsp` (`.lsp.json` auto-loads). Explicit declarations *supplement* auto-discovery, they do not replace it — declaring a default-path file guarantees duplication.
+
+## 2. `type: "prompt"` on `PostToolUse:Bash` is always wrong
+
+**What happened.** `showcase` plugin shipped a PostToolUse:Bash hook with `type: "prompt"` intended to suggest `/showcase:capture` after successful builds. In practice, Claude Code evaluated the prompt after every bash command — `ls`, `grep`, `cat` — producing a stream of "PostToolUse:Bash hook stopped continuation" messages tied to the negative condition ("this isn't a build so don't mention capture"). The user perceived it as aggressive blocking.
+
+**Rule.** `PostToolUse:Bash` fires on every shell command. A `type: "prompt"` hook there turns every command into an LLM evaluation step — expensive in tokens, disruptive in UX. Use `type: "command"` with silent `exit 0` for conditional reminders, or move the reminder to `SessionStart` where it fires once per session. Reserve `type: "prompt"` for truly low-frequency events.
+
+Applies equally to: `UserPromptSubmit`, `PreToolUse:Bash`, any matcher that fires per-turn.
+
+## 3. Marketplace renames leave install records behind forever
+
+**What happened.** The marketplace `RossLabs-claude-plugins` was renamed to `rosslabs-ai-toolkit` (kebab-case is required by Claude Code's marketplace schema, 2026-04-20). Plugins previously installed from the old name kept their install records in `~/.claude/plugins/installed_plugins.json` pointing at cache paths under `RossLabs-claude-plugins/` that no longer received updates. The resulting state:
+- Same plugin, two install keys (old + new)
+- Stop hooks from the old install pointing at paths like `/Users/.../claude-code-debugger/claude-code-debugger/1.8.0` that didn't exist
+- `/plugin` UI showed both as "installed"
+
+**Rule.** Renaming a marketplace is a full migration, not a metadata change. Checklist:
+1. `/plugin` → uninstall every plugin from the old marketplace name
+2. Remove the old marketplace from `extraKnownMarketplaces` in `settings.json`
+3. Re-add the new marketplace
+4. Reinstall each plugin from the new name
+5. Audit `installed_plugins.json` for any remaining old-name keys — remove them only if the uninstall didn't
+
+Document the rename in a feedback memory so future sessions handle it correctly.
+
+## 4. `@local` and `@marketplace` for the same plugin is a footgun
+
+**What happened.** Local development on `bookmark`, `showcase`, `mockup-gallery`, and `NavGator` registered each as `@local` directory installs. The same plugins also existed in the `rosslabs-ai-toolkit` marketplace. Both installs stayed "enabled" simultaneously — both MCP servers started, duplicate slash commands registered, hooks fired twice. The Installed view showed "bookmark MCP · failed" twice, one per copy.
+
+**Rule.** Pick one at a time. When iterating on source, disable the marketplace install. When consuming normally, disable the `@local`. The `enabledPlugins` map in `settings.json` is the source of truth — set the non-active source to `false`.
+
+Better: use `EnterWorktree` or a separate test project directory for plugin development, so the live user environment is not polluted with dev installs.
+
+## 5. Cache directories are downstream; commit source before expecting changes to persist
+
+**What happened.** Editing hook files under `~/.claude/plugins/cache/rosslabs-ai-toolkit/showcase/0.1.1/hooks/hooks.json` took effect immediately, but the next marketplace sync (pulling the GitHub repo) overwrote the edit with the repo's original file. Hours of debugging lost to the illusion of a persistent fix.
+
+**Rule.** Cache is regenerated from the marketplace's upstream repo. Always edit the source (`~/Desktop/git-folder/RossLabs-AI-Toolkit/plugins/<plugin>/…`), commit, push. If you need an immediate fix in the current session, edit both the source and the cache — the cache copy keeps the session alive until you push, then the next sync reconciles.
+
+The marketplace repo is the source of truth. Nothing under `~/.claude/plugins/cache/` is authored — it's all generated.
+
+## 5a. The reverse trap: source-only edits don't take effect at runtime
+
+**What happened (2026-04-22, build-loop).** Edited `~/Desktop/git-folder/build-loop/scripts/write_run_entry.py` in the source repo and updated the orchestrator prose to invoke `${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry.py`. Tests passed. Claimed success. The orchestrator never saw the new script because `${CLAUDE_PLUGIN_ROOT}` resolves to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` — a frozen snapshot that only updates on marketplace sync. Source-only edit = runtime silently runs the old version (or in this case, returns "file not found" and the orchestrator falls back to hand-writing JSON, if it remembers to).
+
+**Rule.** The full sync cycle is **source → commit → push → marketplace sync → cache**. Any link that breaks leaves the cache stale.
+
+For the current session you need BOTH: edit source (for persistence) AND copy to cache (for immediate effect). Scripts for doing this safely:
+
+```bash
+# Sync single plugin's source → cache (run from source repo root)
+PLUGIN=build-loop
+MARKET=rosslabs-ai-toolkit
+VERSION=$(jq -r .version .claude-plugin/plugin.json)
+CACHE=~/.claude/plugins/cache/$MARKET/$PLUGIN/$VERSION
+rsync -av --delete --exclude=.git --exclude=node_modules --exclude='__pycache__' ./ "$CACHE/"
+```
+
+This rule applies to EVERY path referenced via `${CLAUDE_PLUGIN_ROOT}/...`: hooks, manifests, SKILL.md, agent definitions, scripts, references, MCP servers, command .md files. Not just the originally-documented hooks + dist/.
+
+**Detection script.** Build-loop ships `scripts/check_cache_sync.py` that greps the source repo for `${CLAUDE_PLUGIN_ROOT}/` references, resolves each, diffs against the cache, and fails with a list of out-of-sync paths. Review-D (Fact-Check) runs it automatically when Phase 1 detects "plugin work" on the target repo.
+
+**Why this class of bug is easy to miss.** Local tests pass (they use the source path directly). Orchestrator-driven use fails silently (cache path returns stale or missing file). The mismatch only surfaces when the orchestrator and the developer use different resolved paths for the same logical file.
+
+## 6. Aggregator marketplaces hide their own update failures
+
+**What happened.** When a plugin inside `rosslabs-ai-toolkit` ships a fix, the user has to run `/plugin` update on the aggregator, not on the individual plugin. Updates to individual plugins in the aggregator are not auto-pulled when only the plugin's version bumps — the aggregator's own marketplace.json must reflect the new version. Forgetting to update `marketplace.json` means users install stale plugin versions even though the GitHub repo has the fix.
+
+**Rule.** When shipping a plugin in an aggregator marketplace, always update three things: (a) the plugin's own `version` in `plugin.json`, (b) the marketplace entry for that plugin in `.claude-plugin/marketplace.json`, (c) the README.md list showing installed plugins. If any of the three are missing, users get inconsistent views. See `feedback_rosslabs_toolkit_sync.md` for the full skill.
+
+## 7. `.mcp.json` MUST wrap servers in `"mcpServers"`
+
+**What happened.** `navgator` and `showcase` shipped a flat `.mcp.json`:
+```json
+{ "navgator": { "command": "node", "args": [...] } }
+```
+instead of the required wrapped form:
+```json
+{ "mcpServers": { "navgator": { "command": "node", "args": [...] } } }
+```
+The flat form silently loaded without errors in `/doctor`, but the MCP server never started. `/mcp` showed "plugin:gator:navgator · failed" with no helpful error. Node would try to launch and immediately fail because Claude Code couldn't locate the server definition.
+
+**Rule.** `.mcp.json` top-level must be `{"mcpServers": {...}}`. Inline manifest declarations (`"mcpServers": {...}` in `plugin.json`) use the same structure minus the outer object. Only `/mcp` shows this failure, not `/doctor` — always open both when verifying plugin health.
+
+## 8. Marketplace sync omits `dist/` and `node_modules/`
+
+**What happened.** Plugins that require a TypeScript build (`tsc` producing `dist/mcp/server.js`) were synced into `~/.claude/plugins/cache/` without their `dist/` directories. The cached `plugin.json` pointed at `${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js` which didn't exist. MCP failed silently at startup. Same for `node_modules/` needed by the compiled output.
+
+**Rule.** Either:
+- Ship pre-bundled output (e.g. `tsup` producing a single file that bundles all deps) so the plugin doesn't need `node_modules`
+- OR ensure the marketplace publish process includes `dist/` in the plugin's repo (not gitignored) and runs `npm install --production` as a postinstall step in the plugin's cache directory
+- OR use a postinstall hook that rebuilds on install (acceptable but slow)
+
+ibr uses `tsup` and ships a 525KB bundled `dist/mcp/server.js` that runs standalone — this is the cleanest pattern. showcase, navgator, spectra use `tsc` which requires `node_modules/` at runtime — fragile.
+
+## 9. `/doctor` catches manifest issues; `/plugin` and `/mcp` catch install/runtime issues
+
+Use both. `/doctor` surfaces load-time failures (bad hooks, broken manifests, missing commands). `/plugin` (Installed tab) surfaces runtime issues (MCP servers that won't start, duplicate installs). They report different layers and will not overlap.
+
+## 8. Never commit `settings.json` changes to a plugin
+
+**Relevant to plugin authors.** A plugin's `settings.json` sets *default* settings — values Claude Code merges into the user's config. Writing absolute paths, your local API keys, or your personal `enabledPlugins` map into a plugin's `settings.json` ships your machine's state to every user. Plugin-level `settings.json` should only contain defaults the user is expected to override (usually empty or near-empty).
+
+## 9. Removing a marketplace from `known_marketplaces.json` is not enough
+
+**What happened (2026-04-21).** After a marketplace consolidation, editing `~/.claude/plugins/known_marketplaces.json` and running `/reload-plugins` made the removed marketplaces come right back. Five "zombie" marketplaces kept auto-re-registering on every reload: `bookmark`, `interface-built-right`, `mockup-gallery`, `navgator`, `build-loop`.
+
+**Rule.** Claude Code re-seeds `known_marketplaces.json` from multiple persistent sources on every reload. To fully remove a marketplace, clean all of:
+
+| Location | What it does | How to clean |
+|---|---|---|
+| `~/.claude/settings.json` → `extraKnownMarketplaces` | User-level persistent marketplace definitions. Re-registers on every reload. | Delete the entry. Highest-priority cleanup target. |
+| `~/.claude/settings.json` → `enabledPlugins` | Keys like `"plugin@marketplace": true` also re-register the marketplace implicitly. | Delete dead entries. |
+| `~/.claude/settings.json` → top-level `plugins` array (deprecated) | Legacy paths like `".../bookmark/.claude-plugin"` re-add plugins and their marketplace. | Remove or replace with empty array. |
+| `~/.claude/plugins/.install-manifests/<plugin>@<marketplace>.json` | Per-install manifests with hashes. Each file implicitly keeps its marketplace registered. | Archive or delete the manifest files. |
+| `~/.claude/plugins/marketplaces/<name>/` | Physical clone of a git-sourced marketplace. Presence can trigger auto-registration. | Archive the directory. |
+| Project-scope `.claude/settings.json` → `extraKnownMarketplaces` | Team-level injection that re-registers when you trust the folder. | Audit `git-folder/*/.claude/settings.json`. |
+| `~/.claude/plugins/known_marketplaces.json` | The runtime registry. Rewritten each reload from the sources above. | Clean this LAST so there's nothing to rewrite it from. |
+
+Cleanup ordering matters: purge the re-seeding sources first, only then rewrite `known_marketplaces.json`. Otherwise the next reload resurrects everything.
+
+## 10. Partial cache dirs from interrupted updates confuse plugin resolution
+
+**What happened.** Plugins had two cache directories for the same plugin, e.g. `claude-code-debugger/1.8.0/` (complete) and `claude-code-debugger/1.8.1/` (partial — missing `dist/` and `node_modules/`). Claude Code saw 1.8.1 as the "installed version" per `installed_plugins.json` but the `installPath` still pointed at 1.8.0. Additionally, the newer directory was incomplete so even if Claude tried to use it, the MCP server failed to start.
+
+**Rule.**
+- **Verify `installed_plugins.json` version matches installPath** — if `version: "1.8.1"` but installPath ends in `/1.8.0/`, something is stale. Align them.
+- **Audit for incomplete cache dirs:** for each `<plugin>/<version>/`, check `dist/` and `node_modules/` presence if the plugin needs them. Missing = delete the incomplete dir.
+- **Do not manually `cp` files between version dirs.** Either let `/plugin update` regenerate cleanly, or remove the bad version and let Claude Code re-fetch.
+
+Quick audit:
+```bash
+for p in ~/.claude/plugins/cache/*/*/; do
+  name=$(basename $(dirname $p))
+  ver=$(basename $p)
+  nm=$([ -d "$p/node_modules" ] && echo y || echo n)
+  dist=$([ -d "$p/dist" ] && echo y || echo n)
+  echo "$name/$ver: node_modules=$nm dist=$dist"
+done
+```
+
+## 11. `${CLAUDE_PLUGIN_DATA}` is the right home for build artifacts
+
+**Context.** TypeScript plugins that bundle with `tsc` need `node_modules/` at runtime. The marketplace sync doesn't include `node_modules/`, so cached plugins arrive without dependencies and MCP servers fail at startup.
+
+**Rule.** Three correct patterns, in order of preference:
+
+1. **Bundle with `tsup`** — single-file `dist/mcp/server.js` that embeds all deps. No `node_modules/` needed at runtime. IBR follows this pattern. Ship `dist/` in git (don't gitignore it).
+2. **SessionStart hook with `${CLAUDE_PLUGIN_DATA}`** — install deps once into the persistent data dir, not the cache. Survives plugin updates.
+   ```json
+   {
+     "hooks": {
+       "SessionStart": [{
+         "hooks": [{
+           "type": "command",
+           "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install)"
+         }]
+       }]
+     }
+   }
+   ```
+   Then point MCP at the bundled script with `NODE_PATH=${CLAUDE_PLUGIN_DATA}/node_modules`.
+3. **Commit `dist/` + use pure-stdlib server** — smallest deliverable but only viable for servers with zero runtime deps.
+
+`${CLAUDE_PLUGIN_ROOT}` changes on every plugin update; data there doesn't survive. `${CLAUDE_PLUGIN_DATA}` persists at `~/.claude/plugins/data/<id>/`.
+
+## 12. Reserved marketplace names
+
+**Context.** Claude Code rejects these names at publish/sync time:
+- `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`
+- `anthropic-marketplace`, `anthropic-plugins`
+- `agent-skills`, `knowledge-work-plugins`, `life-sciences`
+- Any name that impersonates the above (`official-claude-plugins`, `anthropic-tools-v2`, etc.)
+
+**Rule.** Use a clearly-original kebab-case name that identifies you or your team. Validate before publishing: the `claude.ai` marketplace sync rejects non-kebab-case names silently even when the local `/plugin` flow accepts them.
+
+## 13. Testing an MCP server without Claude Code
+
+**Rule.** You can verify a Claude Code plugin's MCP server is healthy without any plugin machinery by sending the `initialize` RPC directly:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+  CLAUDE_PLUGIN_ROOT=/path/to/plugin \
+  node /path/to/plugin/dist/mcp/server.js
+```
+
+A healthy server responds with a single-line JSON-RPC `result` containing `protocolVersion`, `serverInfo.name`, `serverInfo.version`, and `capabilities`. If you see nothing, a stack trace, or `EACCES`/`MODULE_NOT_FOUND`, the server has a real failure.
+
+This distinguishes "server works but Claude Code's UI shows stale failure" from "server actually broken." Extremely useful for debugging the `/plugin` "Needs attention" pane — which sometimes caches failure status across reloads.
+
+## 14. Kebab-case and reserved-name checks happen at different stages
+
+**Rule.** Anthropic's `claude.ai` marketplace sync is stricter than the local `/plugin` install flow:
+- Local flow: accepts `UpperCase`, `under_scores`, even short paths. Shows warnings but loads.
+- claude.ai sync: rejects non-kebab-case plugin or marketplace names with no override.
+
+Check kebab-case for both `marketplace.json.name` and every `plugins[].name` before publishing. The fastest way to catch this: run `claude plugin validate .` in the marketplace root.
+
+## 15. Never delete a cache version dir while Claude Code is running
+
+**What happened (2026-04-21).** During mid-session cleanup, I archived `~/.claude/plugins/cache/rosslabs-ai-toolkit/ibr/1.0.1/` (a partial dir left from an interrupted update). The live Claude Code session had loaded ibr's hooks at startup with `${CLAUDE_PLUGIN_ROOT}` resolved to `.../ibr/1.0.1/`. Hook paths are cached in memory at session start — `/reload-plugins` does not rebuild them. On next `Stop` event:
+
+> Stop hook error: Failed to run: Plugin directory does not exist: /Users/.../ibr/1.0.1 (ibr@rosslabs-ai-toolkit — run /plugin to reinstall)
+
+`installed_plugins.json` correctly pointed at `1.0.0`, but the in-memory hook registry still held `1.0.1`.
+
+**Rule.** Cache-directory cleanup must follow session state:
+
+| Action | When safe |
+|---|---|
+| Edit `installed_plugins.json` version/installPath | Anytime |
+| Archive/delete an *unused* version dir | Only when no live session holds a hook from it |
+| Archive/delete the *active* `installPath` dir | Never while Claude Code is running — will break hooks, MCP, and commands immediately |
+
+**Recovery without restart.** Symlink the missing dir back to the active version:
+```bash
+ln -s ~/.claude/plugins/cache/<mkt>/<plugin>/<active-version> \
+      ~/.claude/plugins/cache/<mkt>/<plugin>/<missing-version>
+```
+The symlink satisfies the stale path until the session restarts and re-resolves `${CLAUDE_PLUGIN_ROOT}`.
+
+**Safe sequence for mid-session cache cleanup.**
+1. Align `installed_plugins.json` `version` + `installPath` for the plugin.
+2. Leave all cache version dirs in place.
+3. Have the user `/exit` and relaunch Claude Code.
+4. On the fresh session, archive or delete the orphaned version dirs.
+
+**For plugin authors.** If your plugin registers hooks that reference `${CLAUDE_PLUGIN_ROOT}`, document that plugin updates require a Claude Code restart (not just `/reload-plugins`) for the hook paths to refresh. Consider writing hook scripts that resolve their own path at runtime (e.g. `realpath "$0"` inside the script) rather than relying on the registered command's frozen `${CLAUDE_PLUGIN_ROOT}`.
+
+## 16. `/plugin` "Needs attention" badges persist beyond the failure
+
+**What happened (2026-04-21).** After fixing the `.mcp.json` schema for bookmark, debugger, and ibr — verified healthy via direct JSON-RPC `initialize` handshake — the `/plugin` UI kept showing the red "✗ failed" badge after `/reload-plugins`. `/reload-plugins` correctly reported "7 plugin MCP servers" loaded, matching the expected count, so all servers were in fact running. Only the UI status was stale.
+
+**Rule.** Claude Code's `/plugin` panel caches per-session MCP connection status. When an MCP fails at startup, the panel latches the red badge for the life of the session. `/reload-plugins` re-runs plugin discovery but does **not** re-probe existing MCP health. Same staleness pattern as § 15 (hook `${CLAUDE_PLUGIN_ROOT}` paths).
+
+**Ways to clear stale badges, in order of disruption:**
+
+| Method | Disruption | Reliability |
+|---|---|---|
+| `/exit` and relaunch Claude Code | High — full restart | 100% — fresh process |
+| Toggle each plugin off then on in `/plugin` UI | Medium | ~95% — forces MCP reconnect |
+| Toggle `enabledPlugins` in `settings.json` + `/reload-plugins` | Low | ~70% |
+| Wait — do nothing | None | 0% during session, 100% next launch |
+
+**Diagnostic rule: do not trust UI badges over direct evidence.** When a badge says failed but the server tests healthy, the badge is the lie. Checks that trump the UI:
+
+1. **Direct handshake test** — if the server responds to `initialize` RPC with a valid result, it's healthy:
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | \
+     CLAUDE_PLUGIN_ROOT=<path> node <path>/dist/mcp/server.js
+   ```
+2. **Reload loaded count** — if `/reload-plugins` reports N plugin MCP servers loaded and N matches the enabled count, the servers are running regardless of UI.
+3. **Invoke a tool** — call a slash command or tool that depends on the MCP (e.g. `/bookmark:snapshot`). Success = server live.
+
+**For plugin authors.** Don't treat user bug reports of "MCP failed in /plugin" as gospel. Ask them to (a) run the standalone handshake, (b) try an actual tool invocation. Stale UI badges generate false bug reports.
+
+## 17. Out-of-tree hook wrappers desync silently; hooks must fail-open under a minimal PATH
+
+**What happened (2026-06-06, agent-rally-point).** Codex sessions spammed `PreToolUse hook (failed) error: hook exited with code 127` and `Stop hook (failed) error: hook exited with code 127` on every tool call. Two compounding defects:
+
+1. **Out-of-tree wrapper desync.** `~/.codex/rally-hook.sh` (installed once, *not* version-controlled) called `rally start` / `rally hook before-write` — subcommands the Rust rewrite had **removed**. The in-repo fix (a version-controlled canonical hook + an installer that repoints the wrapper to a thin `exec` shim) had shipped, but this machine's pre-rewrite global wrapper was never migrated. The repo *said* "fixed, advisory-only"; ground truth on disk was a months-old enforcing wrapper. A loose installed file cannot be caught by the repo's tests or CI — it drifts the moment the code it calls changes.
+
+2. **`set -e` + bare binary on the hook's minimal PATH → exit 127.** Hook subprocesses inherit `/usr/bin:/bin`, **not** the login PATH. The wrapper's line 6 ran `node` in a command substitution *before any guard*, under `set -euo pipefail`. `node` (in a version-manager dir) and `rally` (in `~/.local/bin`) were both absent → the substitution returned 127 → `set -e` aborted the whole script with 127, before it ever reached the removed subcommand. The lone `2>/dev/null || true` guarded a *different* line. Verified: `env -i PATH=/usr/bin:/bin bash stale-wrapper.sh before-write` → exit 127; the hardened in-repo hook under the same env → exit 0.
+
+A third latent hazard: the stale wrapper mapped `severity=="stop"` → `permissionDecision:"deny"` / `decision:"block"`. Had someone "fixed" only the PATH, the wrapper would have started **blocking tool calls** — violating the facilitator/never-block charter.
+
+**Rules.**
+
+- **Version-control the hook in-repo; make any host-side wrapper a thin shim.** The wrapper at `~/.codex/…` or `~/.claude/settings.json` should `exec "<repo>/hooks/<hook>.sh" "$@"`, never contain logic. Logic in-tree = tested, CI-guarded, can't silently desync from the CLI it drives. Ship an idempotent installer with `--uninstall` that backs up the prior wrapper to `.bak`.
+- **Hooks run with a minimal PATH. Resolve binaries absolutely or `command -v`-guard every call**, and **fail-open (`exit 0`) on any missing binary / timeout / parse error.** Guarding one line is not fail-open when `set -e` is on — an unguarded later command still aborts. Add a test that runs the hook under `env -i PATH=/usr/bin:/bin` and asserts `exit 0` + no `deny`/`block`. This catches the whole 127 class in CI.
+- **Advisory/coordination hooks never enforce by default.** Emit `additionalContext`/`systemMessage`; reserve `deny`/`block`/`exit 2` for explicit safety/security/integrity gates, gated behind an opt-in env flag.
+- **When a hook's backend changes, repoint or remove the installed wrapper** — don't leave an orphan. Treat "the repo shipped the fix" and "this machine runs the fix" as separate facts; verify the second on disk (`trust ground truth over artifacts`).
+- **Coordination caveat:** repointing/disabling a hook changes behavior for *live* peer agents. Hooks are read per-invocation (not cached like plugin `${CLAUDE_PLUGIN_ROOT}` paths in §15), so no restart is needed — but in a multi-agent room, prefer the least-disruptive relief (a clean fail-open shim) over one that introduces new behavior (e.g. auto-claim) mid-session.
+
+## Preflight checklist before shipping a plugin change
+
+- [ ] `plugin.json` declares only non-default paths for `hooks`, `mcpServers`, `lsp`
+- [ ] `plugin.json` lives at `.claude-plugin/plugin.json` (not plugin root)
+- [ ] Version bumped in `plugin.json`
+- [ ] No `type: "prompt"` hooks on per-turn events (PostToolUse:Bash, UserPromptSubmit, PreToolUse:Bash)
+- [ ] No absolute paths — use `${CLAUDE_PLUGIN_ROOT}`
+- [ ] No personal values in `settings.json`
+- [ ] `.mcp.json` uses `{"mcpServers": {...}}` wrapper (not flat form)
+- [ ] MCP server responds to `initialize` RPC when launched directly
+- [ ] `dist/` is in git (not gitignored) OR bundled via `tsup` OR rebuilt via SessionStart hook with `${CLAUDE_PLUGIN_DATA}`
+- [ ] Plugin name and marketplace name are kebab-case
+- [ ] If in an aggregator: marketplace.json version matches plugin.json, README.md updated
+- [ ] Test with `claude --plugin-dir ./my-plugin` in a scratch directory before committing
+- [ ] `claude plugin validate .` passes in the marketplace root
+- [ ] `jq` the `installed_plugins.json` audit command on your own machine — no duplicates for this plugin
+- [ ] Hook scripts live in-repo; any host wrapper (`~/.codex/…`, settings.json) is a thin `exec` shim, not logic (§17)
+- [ ] Every external binary in a hook is absolute-path-resolved or `command -v`-guarded; hook fails open (`exit 0`) on missing binary (§17)
+- [ ] Hook tested under `env -i PATH=/usr/bin:/bin` → exits 0, no `deny`/`block` unless an explicit safety gate (§17)
+- [ ] `python3 scripts/hook_hygiene_lint.py --hooks hooks/hooks.json --json` returns exit 0 (no `HH001` bare-binary / `HH002` strict-mode-subst / `HH003` no-fail-open / `HH004` advisory-deny findings). Operationalizes §17. WARN-level — surfaces in the run report, never blocks. Build-loop's own `hooks/hooks.json` is the passing reference fixture.

package/skills/plugin-tests/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: plugin-tests
+description: Static-analysis test harness for Claude Code plugins. Triggers on "test plugin", "validate plugin", "check skill resolution", "run plugin tests", "lint plugin", "verify manifest", "namesake collision", "MCP registration check". Runs Python stdlib pytest scripts that catch namesake collisions, manifest drift, MCP misregistration, trigger-phrase coverage gaps, bridge pre-flight gaps, agent-surface drift, and cache-prune regressions. Routed as build-loop's 4th orchestrator mode (Build / Optimize / Research / Test).
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Tests — Static-Analysis Harness
+
+A pytest-stdlib test suite that validates a Claude Code plugin's structure, manifest, MCP wiring, skill descriptions, and bridge preflights. Designed to catch the bug classes that have actually shipped through build-loop's history (namesake collisions, manifest version drift, missing frontmatter on commands, bare MCP server names).
+
+This is the **static** tier — pure text/JSON validation, zero runtime dependencies, runs in under a second. Runtime tests (live MCP round-trip, real bridge delegation) are out of scope here and live in the orchestrator's Phase 4 Review-B Validate.
+
+## When this skill fires
+
+- **User direct** — `/build-loop:test [test-name]` or any of: "test plugin", "validate plugin", "lint plugin", "verify manifest", "check skill resolution", "run plugin tests"
+- **Orchestrator intent routing** — TEST mode (4th mode alongside Build / Optimize / Research) — `agents/build-orchestrator.md` §Intent Routing
+- **Orchestrator auto-dispatch in Phase 4 Review-B Validate** (always on, since v0.7.3; advisory-not-blocking since v0.7.4) — when Phase 3 Execute's diff touches any plugin metadata path: `*.claude-plugin/*.json`, `commands/*.md`, `skills/*/SKILL.md`, `agents/*.md`, `.mcp.json`, `hooks/hooks.json`, or any path referenced by `mcpServers`. Findings are written to `.build-loop/state.json.pluginTests` and surfaced in the Review-F Report — they do NOT block the build or auto-route to Iterate. Static-analysis is heuristic (regex over markdown frontmatter); the user decides whether each finding is a real defect or a false positive.
+- **Pre-publish gate** when bumping a plugin version (the human-driven equivalent of the auto-dispatch — run `/build-loop:test --strict` before pushing)
+
+## What's tested
+
+| Script | What it catches | Reference defects |
+|---|---|---|
+| `scripts/test_skill_resolution.py` | Namesake collisions (commands/X.md + skills/X/SKILL.md), frontmatter `name:` drift from dir name | `build-loop:build-loop` collision (shipped through 6 versions undetected before 0.4.1) |
+| `scripts/test_plugin_manifest.py` | Required manifest fields, version sync between plugin.json and marketplace.json, MCP path resolution, every command has frontmatter, skill name uniqueness | 0.4.0/0.3.2 marketplace drift; missing frontmatter on `commands/debugger-detail.md` |
+| `scripts/test_mcp_registration.py` | `.mcp.json` shape, referenced binaries exist, server-name hygiene (warns on bare names that collide across plugins) | Historical `debugger` bare-name collision risk; Build Loop now skips this test because it does not ship an MCP server |
+| `scripts/test_trigger_phrases.py` | Curated (skill, phrase) coverage in skill `description:` fields | Trigger-phrase gaps after the multi-provider auth audit |
+| `scripts/test_bridge_preflight.py` | Every `*-bridge/SKILL.md` has an availability/absence check + `user-invocable: false` | api-registry-bridge missing `user-invocable: false`; bridges that hard-fail when their target plugin isn't installed |
+| `scripts/test_agent_surface_policy.py` | Codex public wrappers, Claude `user-invocable` flags, and host-neutral Cursor/AGENTS policy stay aligned | Helper skills crowding Codex/ChatGPT `#` picker while Claude internals still need the full tree |
+| `scripts/test_prune_plugin_cache.py` | Host-aware stale cache pruning for Claude Code and Codex | Old Build Loop versions staying visible after a new version is installed |
+| `scripts/test_prune_codex_plugin_cache.py` | Backward-compatible Codex-only cache pruning wrapper | Existing `codex:prune-cache` workflow breaking after host-aware pruning was added |
+
+## How to run
+
+From the plugin repo root:
+
+```bash
+# Run all 8
+for t in scripts/test_skill_resolution.py scripts/test_plugin_manifest.py \
+         scripts/test_mcp_registration.py scripts/test_trigger_phrases.py \
+         scripts/test_bridge_preflight.py scripts/test_agent_surface_policy.py \
+         scripts/test_prune_plugin_cache.py scripts/test_prune_codex_plugin_cache.py; do
+  echo "=== $t ==="
+  python3 "$t"
+done
+
+# Or via the slash command
+/build-loop:test
+```
+
+Each script is independent — running one without the others is fine. Each follows the build-loop pytest-stdlib convention from `scripts/test_plan_verify.py` (subprocess-against-sibling-script + tempfile fixtures + `unittest.TestCase`).
+
+## Exit codes
+
+- `0` — all tests pass
+- `1` — at least one test failed (advisory in Review-B; hard CI gate when invoked via `/build-loop:test --strict` or run directly in CI)
+- `2` — runner error (test script itself crashed)
+
+The orchestrator records findings under `.build-loop/state.json.pluginTests` and surfaces a one-line summary in the Review-F Report. **It does not gate the build on plugin-tests results.** Why: static-analysis findings are heuristic (regex/pattern matches over markdown frontmatter) and false positives are common — 3 hit on initial rollout (legitimate user-invocable bridge, filesystem-based pre-flight, PRD-absence prose). A blocking gate that flaps gets disabled, which destroys the value. Surfacing as advisory keeps the signal alive while letting the user judge edge cases.
+
+For pre-publish checks, run with `--strict` to make the CLI exit non-zero on any finding (without involving the orchestrator).
+
+## Adding new tests
+
+When a new bug class ships through, add a test that would have caught it. Pattern:
+
+1. Write `scripts/test_<bug_class>.py` matching the existing pattern (stdlib only, `unittest.TestCase`, subprocess against any helper script)
+2. Add a row to the table in §"What's tested" above
+3. Add the script to the runner in §"How to run"
+4. Add a `(skill, phrase)` to `EXPECTED_TRIGGERS` in `test_trigger_phrases.py` if the new test covers a class that should be discoverable by user phrasing
+
+Don't migrate to pytest, vitest, or Playwright. The stdlib pattern keeps the harness portable, zero-install, and CI-friendly. (See the testing survey at the head of `KNOWN-ISSUES.md` 2026-05-02 entry — IBR's vitest, example-app's Jest+Playwright, prompt-test-lab's Playwright stratification all have their place; for plugin metadata validation specifically, stdlib Python wins.)
+
+## What this skill does NOT do
+
+- Runtime testing (live MCP calls, actual `Skill()` invocation) — that's Review-B Validate's job, executed by the orchestrator with the live runtime
+- UI testing — for plugins that build UIs, use the orchestrator's build-loop-owned UI validation route (`ui-validator`, project-native tests, screenshots/static scanner). Dispatch IBR only when the user explicitly asks for IBR / Interface Built Right / `.ibr-test.json`.
+- Performance / Lighthouse — separate concern, not a plugin metadata issue
+- Cross-plugin integration — that's the bridge skills' job at runtime
+
+## Cross-references
+
+- `agents/build-orchestrator.md` §Intent Routing — TEST mode classification
+- `commands/test.md` — slash-command surface (`/build-loop:test`)
+- `scripts/collision_scan.py` — the static detector that `test_skill_resolution.py` wraps
+- `KNOWN-ISSUES.md` 2026-05-02 entry — testing survey across 13 projects that informed this design
+- `agents/ui-validator.md` and `skills/build-loop/phases/ui-validation.md` — default UI validation route. IBR's `.ibr-test.json` remains an explicit-only auxiliary format.
+
+## History
+
+- 2026-05-02 — initial release with 5 static-analysis scripts. Caught 2 real defects on first run (debugger-detail frontmatter, api-registry-bridge user-invocable). Pattern borrowed from build-loop's existing `scripts/test_plan_verify.py` + survey of test setups across 13 user projects.

package/skills/prd-bridge/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: build-loop:prd-bridge
+description: Use when Phase 1 Assess runs, the user mentions a PRD, or asks to "ground the build in product strategy". Surfaces always-true principles and Navigation Map from the project PRD so subsequent phases reason from strategic frame; recommends prd-builder if none exists.
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# PRD Bridge
+
+Lets build-loop ground every phase decision in a project's strategic frame (its PRD) when one exists, and surfaces a recommendation when one doesn't. The PRD is the source of strategic truth; this bridge consumes it without coupling to its content.
+
+**Use:**
+- **Phase 1 Assess** — load PRD frontmatter and Navigation Map; mirror always-true principles into `.build-loop/state.json.prd`. Phase 2 Plan and Phase 5 Review consult this for scoping, criterion design, and "is this on-vision" gates.
+- **Phase 5 Review-D Fact-Check** — verify the build doesn't violate any PRD `core_principles` (e.g., a change that exposes admin-only complexity to regular users when the PRD's complexity stance forbids that).
+- **Phase 6 Learn (optional)** — flag if the build's lessons contradict a PRD principle. The user decides: was the principle wrong (update PRD), or was the build off-vision (don't promote learning)?
+
+## Cherry-pick principle
+
+**The PRD remains owned by the project, not by build-loop.** This bridge does not author, modify, or shadow PRDs — it only consumes the relevant fields:
+
+- Reads `docs/prd-*.md` frontmatter (`core_principles`, `load_when`, `evolves_when`, `revision`, `status`) — file-only
+- Reads the body's "LLM Navigation Map" and "Section Index" tables to enable targeted offset/limit reads in later phases
+- Writes to `.build-loop/state.json.prd.*` — bridge's own namespace
+- Surfaces a one-line recommendation when no PRD exists; does not auto-create one
+
+What this bridge does NOT do:
+- Write or edit the PRD
+- Cache PRD content (always reads live from disk)
+- Resolve ambiguous principles by interpretation (if a principle is unclear, surface it as a question for Phase 2 Plan)
+- Block the build when a PRD is missing — only recommends one
+
+## Pre-flight
+
+Before phase logic runs, check:
+
+```bash
+ls docs/prd-*.md 2>/dev/null | head -1 && echo "HAVE_PRD" || echo "NO_PRD"
+```
+
+If `HAVE_PRD`, run the steps below.
+
+If `NO_PRD`, surface this one-line note in `state.json.prd.recommendation`:
+
+> No PRD found. Tactical decisions during this build will lack strategic grounding. Consider running the **`prd-builder`** skill from RossLabs-AI-Toolkit (or `/build-loop:start-prd`) to draft a living PRD before iterating further. This is a recommendation, not a blocker.
+
+The note appears in Phase 5 Report's "Open recommendations" section so the user can act between builds.
+
+## Phase 1 Assess — Load PRD into state
+
+When a PRD is present:
+
+1. **Read frontmatter** with a YAML parser (or grep for the documented fields). Extract:
+   - `name`
+   - `status`
+   - `revision`
+   - `last_updated`
+   - `load_when` (array)
+   - `evolves_when` (array)
+   - `core_principles` (array of 1-line statements)
+
+2. **Read the Navigation Map table** if present. Parse rows into `{decision_type: section_name}` mapping. This is what Phase 2 Plan and Phase 5 Review consult to load only the relevant section.
+
+3. **Read the Section Index table** if present. Parse rows into `{section_name: line_range}`. This enables targeted `Read --offset --limit` calls.
+
+4. **Write to `.build-loop/state.json.prd`:**
+   ```json
+   {
+     "path": "docs/prd-example-app.md",
+     "status": "living",
+     "revision": "0.1",
+     "last_updated": "2026-05-01",
+     "core_principles": ["..."],
+     "load_when": ["..."],
+     "navigation_map": {
+       "should_i_add_this_feature": "Persona + Outcome + Methodology",
+       "...": "..."
+     },
+     "section_index": {
+       "intent": [95, 98],
+       "...": [0, 0]
+     }
+   }
+   ```
+
+5. **Surface staleness signals**:
+   - If `last_updated` is more than 90 days old AND `status: living` → flag `prd_stale: true` so Phase 5 Report includes a "PRD review due" note.
+   - If `status: pivoting` → flag `prd_pivoting: true` so Phase 2 Plan asks the user before locking scope.
+   - If any `evolves_when` trigger condition is true (best-effort detection) → surface as a "PRD review recommended" note.
+
+## Phase 2 Plan — Consult navigation map
+
+When Phase 2 is about to lock scope:
+
+1. Identify the **decision type** the build represents (new feature, UX change, architectural choice, rubric/scoring change, etc.).
+2. Look up the matching row in `state.json.prd.navigation_map`.
+3. Read the indicated section(s) using `Read --offset --limit` per `section_index`.
+4. Cite the section in the plan's rationale (e.g., *"per Persona, Director+ users won't tolerate hidden-required complexity, so this UI surfaces the toggle by default"*).
+
+If no row matches the decision type, default to **Persona + Outcome** (the universal fallback per most PRDs).
+
+## Phase 5 Review-D Fact-Check — Principle violation check
+
+After implementation, scan the diff for changes that contradict any `core_principles`:
+
+1. For each `core_principle`, attempt a lightweight grep against the diff for keywords that suggest a violation. Examples:
+   - Principle: *"Hide complexity from regular users"* → grep diff for new public Settings UI with admin-tier features
+   - Principle: *"On-device first; cloud fallback only when..."* → grep diff for new always-cloud calls
+   - Principle: *"Don't add new drills next; polish, fold, kill"* → grep diff for new drill ViewModel/View pairs
+2. **Heuristic only** — surface findings as `principle_check_findings` for human review, not auto-block.
+3. If any finding suggests a principle violation, route to Phase 5 Report with the principle citation + the diff hunk that triggered it.
+
+If the heuristics produce no findings, write `principle_check: clean`. The clean-result is honest: "no obvious contradictions; not a guarantee."
+
+## Standalone fallback
+
+If `${CLAUDE_PLUGIN_ROOT}/skills/build-loop/fallbacks.md` `#prd` exists, follow its degraded recipe. Otherwise:
+
+- **If no PRD frontmatter parser is available** → grep `^- ` lines under `core_principles:` (works for simple list format), surface as raw text.
+- **If no Navigation Map exists in PRD** → fall back to reading the entire body once and asking Phase 2 Plan to derive the relevant section by reading section headers.
+- **If no Section Index exists** → fall back to reading the section by `grep -n '^## '` to find line ranges.
+
+The fallback degrades gracefully — partial signal is better than no signal.
+
+## Files referenced
+
+- `docs/prd-*.md` (project-level PRD; pattern allows multi-app monorepos)
+- `.build-loop/state.json.prd` (bridge output)
+- `.build-loop/issues/principle-violations.md` (Phase 5 fact-check findings, when populated)
+
+## Related
+
+- `prd-builder` skill (RossLabs-AI-Toolkit) — drafts a new PRD from 3-5 strategic questions when none exists.
+- `/build-loop:start-prd` command — explicit invocation path; loads `prd-builder` from the toolkit if installed.

package/skills/research/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: research
+description: Use when the user asks to "research", "investigate", "evaluate options", or "find out about" a topic. Generate a repo-grounded research packet before deciding whether/how to build — pre-decision analysis with risks, best path, confidence, next action.
+user-invocable: true
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Research — Pre-Decision Analysis
+
+Produces a repo-grounded research packet without committing to implementation. Use when evaluating approaches, comparing options, or preparing a handoff.
+
+## When to Use
+
+- "Should I use X or Y?"
+- "What's the best way to add Z?"
+- "Evaluate this approach before I commit"
+- "Research this before we build"
+- The orchestrator routes here when intent is exploratory, not implementational
+
+## Process
+
+1. **Scan the repo**: Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/research_packet.py --scan --workdir "$PWD" --focus "<topic>"` to get repo context (manifests, entrypoints, focus hits, validation commands)
+
+2. **Classify the task**: product, feature, algorithm, prompt, bugfix, or refactor
+
+3. **Build the packet**: Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/research_packet.py --packet --workdir "$PWD" --task "<full request>" --mode balanced` to generate the structured research packet
+
+4. **Review and present**: Read the generated packet, verify claims against the actual repo, adjust confidence if needed
+
+5. **Archive**: Save to `.build-loop/research/YYYY-MM-DD-<topic>.md`
+
+## Output Format
+
+```
+# Research Packet
+
+## Bottom line
+[One sentence: what this is and the recommended path]
+
+## What I found
+- project kind, manifests, entrypoints, validation commands
+- focus hits (files relevant to the topic)
+- integration surfaces (APIs, auth, payments, deployment)
+
+## Best path
+[Recommended approach with reasoning]
+
+## Why this path
+[Evidence from repo analysis and domain knowledge]
+
+## Risks / unknowns
+[What could go wrong, what's uncertain]
+
+## Confidence
+- Context coverage: high/medium/low
+- Verification coverage: high/medium/low
+- Evidence quality: high/medium/low
+- Overall: high/medium/low
+
+## Next action
+[Concrete first step — could be "run /build-loop" or "investigate X further"]
+```
+
+## Modes
+
+- `quick` — repo scan only, no external research, fast
+- `balanced` — repo scan + selective external research when current facts matter
+- `max_accuracy` — deep scan + external research + self-debug pass
+
+## Integration
+
+- Standalone: `/build-loop:research [topic]`
+- From build-loop: orchestrator routes RESEARCH-intent requests here instead of the full loop
+- During normal build-loop runs: `scripts/research_trigger.py` decides whether this skill should run, which depth to use, where to persist the packet, and whether current/external claims are blocked until cited. See `references/research-trigger-policy.md`.
+- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize` to optimize, or shelve
+
+## State
+
+Packets archived to `.build-loop/research/YYYY-MM-DD-<topic>.md` with JSON frontmatter (confidence scores, mode, task type, timestamp).