@tyroneross/build-loop 0.30.3

package/skills/plan-verify/test-fixtures/unrelated-good-plan-findings.json

@@ -0,0 +1,15 @@
+{
+  "fixture": "unrelated-good-plan.md",
+  "expected_exit_code": 0,
+  "description": "False-positive control. Clean plan from a different project. Should produce zero BLOCKERs.",
+  "expectations_by_rule_id": {
+    "delete-with-callers": { "max_blocker_count": 0 },
+    "numeric-drift": { "max_blocker_count": 0 },
+    "route-change-evidence": { "max_blocker_count": 0 },
+    "package-state": { "max_blocker_count": 0 },
+    "missing-evidence": {
+      "max_warn_count": 5,
+      "rationale": "Clean plan, but warn budget allows for a few unmarked stylistic claims."
+    }
+  }
+}

package/skills/plan-verify/test-fixtures/unrelated-good-plan.md

@@ -0,0 +1,55 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+override: reads-from-dependency — pre-dates the reads-from section requirement; fixture demonstrates other rules only
+
+# Travel Planner — Summer Camp Listings
+
+> Clean plan from another project. False-positive control fixture for `plan_verify.py`.
+
+## Goal
+
+Add summer-camp listings to the existing trips dashboard. Reuse the `Trip` schema; do not introduce a new entity type. ✅ verified by reading `src/db/schema.ts` lines 14-32.
+
+## Approach
+
+Add a `category` enum field to `Trip` with values `vacation | camp | conference`. Default is `vacation` to preserve existing rows. ✅ verified by checking current Drizzle migration history shows no `category` column exists.
+
+Render camps in the same TripCard component. The card already accepts an optional badge prop; we wire `category === 'camp'` to a "Camp" badge.
+
+## Failure Modes
+
+- **Primary invariant:** existing vacation trips continue rendering exactly as before while camp trips get the new category badge.
+- **Likely failure modes:** migration default omitted, enum value misspelled, existing TripCard badge prop bypassed.
+- **Observability signal:** failing migration, snapshot diff missing the badge, or existing trip snapshot changing unexpectedly.
+- **Proof check:** run the migration in CI and update the TripCard snapshot test with both `vacation` and `camp` categories.
+- **Rollback/containment:** revert the UI badge wiring and leave the additive defaulted column in place until a follow-up migration removes it.
+
+## Phase 1 — Schema
+
+Add migration `0014_trip_category.sql`:
+
+```sql
+ALTER TABLE trips ADD COLUMN category text NOT NULL DEFAULT 'vacation';
+```
+
+Backfill is the default value, so the migration is idempotent.
+
+## Phase 2 — UI
+
+Update `TripCard.tsx` to render the badge. ✅ verified TripCard already supports a `badge` slot via prop drilling.
+
+## Phase 3 — Tests
+
+Add a snapshot test for the camp badge. Test data uses real category values; no mocks.
+
+## Verification
+
+- Migration runs cleanly on staging — ✅ verified by running `pnpm db:migrate` in CI.
+- TripCard snapshot updated — ⚠️ untested, will run after merge.
+- No regressions in existing trip flows — ❓ uncertain; needs a manual spot-check.
+
+## Out of scope
+
+- No new database table.
+- No changes to auth.
+- No new package dependencies.

package/skills/plugin-builder/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: plugin-builder
+description: Use when the user asks to create, build, scaffold, convert, or migrate a Claude Code plugin, or needs guidance on plugin.json, directory layout, hooks, MCP servers, agents, LSP, or distribution.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Builder
+
+Build Claude Code plugins following official documentation and best practices.
+
+## When to Use Plugins vs Standalone
+
+| Approach | Skill names | Best for |
+|----------|-------------|----------|
+| **Standalone** (`.claude/`) | `/hello` | Personal workflows, single-project, quick experiments |
+| **Plugin** (`.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with team, distributing, versioned, reusable across projects |
+
+**Use standalone when:** Single project, personal, experimenting, want short names.
+**Use plugins when:** Sharing with team/community, need same skills across projects, want version control.
+
+## Plugin Creation Workflow
+
+### Step 1: Create the Directory Structure
+
+```bash
+mkdir -p my-plugin/.claude-plugin
+mkdir -p my-plugin/{commands,agents,skills,hooks,scripts}
+```
+
+**Standard layout:**
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # ONLY manifest here
+├── commands/                 # Slash commands (*.md files)
+├── agents/                   # Subagent definitions (*.md files)
+├── skills/                   # Skills (subdirs with SKILL.md)
+│   └── my-skill/
+│       ├── SKILL.md
+│       └── references/
+├── hooks/
+│   └── hooks.json            # Event handlers
+├── scripts/                  # Utility scripts
+├── .mcp.json                 # MCP server configs
+├── .lsp.json                 # LSP server configs
+├── settings.json             # Default settings
+└── CHANGELOG.md
+```
+
+**CRITICAL:** Components go at plugin root, NOT inside `.claude-plugin/`. Only `plugin.json` goes in `.claude-plugin/`.
+
+### Step 2: Create the Manifest
+
+Create `.claude-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "description": "Brief description of what the plugin does",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  }
+}
+```
+
+**`name` is the only required field.** It becomes the namespace prefix for all components (`/my-plugin:skill-name`).
+
+**Naming rules:**
+- kebab-case, no spaces
+- Used as namespace for all skills/commands
+- Cannot use "claude" or "anthropic"
+
+For the complete manifest schema with all optional fields, see `references/manifest-schema.md`.
+
+### Step 3: Add Components
+
+#### Skills (Recommended)
+Create a subdirectory under `skills/` with a `SKILL.md`:
+
+```
+skills/code-review/
+└── SKILL.md
+```
+
+Skills are auto-discovered — no manifest entry needed. See the `skill-builder` skill for detailed SKILL.md guidance.
+
+#### Commands
+Simple markdown files in `commands/`:
+
+```markdown
+---
+description: Greet the user
+---
+
+Greet the user warmly and ask how you can help.
+```
+
+#### Agents
+Markdown files in `agents/` defining subagent behavior:
+
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities
+---
+
+Detailed system prompt for the agent...
+```
+
+#### Hooks
+Create `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Hook types:** `command` (shell), `prompt` (LLM evaluation), `agent` (agentic verification)
+
+**Available events:** PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact, Notification, TaskCompleted, TeammateIdle, PermissionRequest, SubagentStart
+
+For detailed hooks configuration, see `references/hooks-reference.md`.
+
+**Lint hooks before shipping.** Run `python3 scripts/hook_hygiene_lint.py --hooks hooks/hooks.json --json` against any hooks.json change. It operationalizes §17 of `references/plugin-hygiene-lessons.md`: HH001 (bare-binary on minimal PATH), HH002 (`set -e` + unguarded substitution), HH003 (no fail-open tail), HH004 (advisory-deny without safety marker). WARN-level — surfaces in the run report, never blocks; consistent with build-loop's "judges route, never stop" rule. Build-loop's own `hooks/hooks.json` is the passing reference fixture (`scripts/test_hook_hygiene_lint.py`).
+
+#### MCP Servers
+Create `.mcp.json` at plugin root:
+
+```json
+{
+  "mcpServers": {
+    "my-service": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  }
+}
+```
+
+Always use `${CLAUDE_PLUGIN_ROOT}` for paths — plugins are cached to a different location after install.
+
+#### LSP Servers
+Create `.lsp.json` at plugin root:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": { ".go": "go" }
+  }
+}
+```
+
+Users must install the language server binary separately.
+
+#### Default Settings
+Create `settings.json` to activate a default agent:
+
+```json
+{
+  "agent": "security-reviewer"
+}
+```
+
+### Step 4: Test Locally
+
+```bash
+claude --plugin-dir ./my-plugin
+```
+
+**Test each component:**
+- Skills: `/my-plugin:skill-name`
+- Commands: `/my-plugin:command-name`
+- Agents: Check `/agents`
+- Hooks: Trigger the relevant events
+- MCP: Verify tools appear
+
+Load multiple plugins: `claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two`
+
+**Debug issues:** `claude --debug` shows plugin loading details, errors, registration.
+
+### Step 5: Distribute
+
+**Version management:** Semantic versioning (MAJOR.MINOR.PATCH). Bump version before distributing — users won't see changes without a version bump due to caching.
+
+**Distribution options:**
+1. Host on GitHub with README and installation guide
+2. Create a marketplace (see `references/distribution.md`)
+3. Submit to official Anthropic marketplace
+
+## Key Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to plugin directory. Use in hooks, MCP, scripts. |
+
+## Auto-Discovery Rules
+
+Claude Code automatically discovers components in default locations:
+- `commands/` → `*.md` files become slash commands
+- `agents/` → `*.md` files become subagents
+- `skills/` → subdirectories with `SKILL.md` become skills
+- `hooks/hooks.json` → hook configurations
+- `.mcp.json` → MCP server definitions
+- `.lsp.json` → LSP server configurations
+
+Custom paths in `plugin.json` **supplement** defaults, they don't replace them.
+
+## Converting Standalone to Plugin
+
+1. Create plugin structure with `.claude-plugin/plugin.json`
+2. Copy `.claude/commands/` → `my-plugin/commands/`
+3. Copy `.claude/agents/` → `my-plugin/agents/`
+4. Copy `.claude/skills/` → `my-plugin/skills/`
+5. Move hooks from `settings.json` to `hooks/hooks.json`
+6. Test with `claude --plugin-dir ./my-plugin`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Components inside `.claude-plugin/` | Move to plugin root |
+| Absolute paths in hooks/MCP | Use `${CLAUDE_PLUGIN_ROOT}` |
+| Script not executable | `chmod +x scripts/*.sh` |
+| Hook event name wrong case | Use PascalCase: `PostToolUse` not `postToolUse` |
+| Version not bumped | Users won't see updates without version change |
+| Path traversal (`../shared/`) | Won't work after install — use symlinks if needed |
+| Redeclaring `"hooks": "./hooks/hooks.json"` in manifest | Remove it. `hooks/hooks.json` is auto-loaded; redeclaring produces `Duplicate hooks file detected` in `/doctor`. Same for `.mcp.json` at default path. Only declare when using a non-standard path. |
+| `type: "prompt"` hooks on high-frequency events | Never use `type: "prompt"` on `PostToolUse:Bash` or `UserPromptSubmit`. They fire on every tool call — LLM must evaluate the prompt each time, which spams "hook stopped continuation" messages and costs tokens. Use `type: "command"` with silent exit (exit 0) for conditional nudges; `type: "prompt"` is only OK on low-frequency events like `SessionStart`. |
+| Identical hook in source repo and marketplace aggregator | Edit the source repo manifest — cache under `~/.claude/plugins/cache/` is regenerated from the marketplace repo on every sync, overwriting local edits. Commit + push before expecting changes to persist. |
+| Flat `.mcp.json` without `mcpServers` wrapper | Always wrap: `{"mcpServers": {"<name>": {...}}}`. Flat form `{"<name>": {...}}` silently passes `/doctor` but fails at MCP startup — only visible in `/mcp`. |
+| Claude-only plugin (no `.codex-plugin/plugin.json`) | Add a Codex manifest per `references/dual-host-claude-codex.md` so users on either host get the same plugin. Name/version must match the Claude manifest; skills and MCP config paths are shared. |
+| Divergent `name` or `version` across Claude/Codex manifests | Keep identical. Users think of it as one plugin; split versions cause support confusion. |
+| Plugin ships without pre-built `dist/` | Either bundle with `tsup` (single-file output, no runtime deps) OR commit `dist/` to the repo OR add a postinstall rebuild. `tsc`-only output that depends on `node_modules/` will fail when the marketplace sync excludes those dirs. |
+| Removing a marketplace doesn't stick after `/reload-plugins` | Multiple sources re-seed `known_marketplaces.json`: `extraKnownMarketplaces` in `settings.json`, `~/.claude/plugins/.install-manifests/*.json`, and `~/.claude/plugins/marketplaces/<name>/`. Clean all three sources, then rewrite `known_marketplaces.json` last. See `references/plugin-hygiene-lessons.md` § 9. |
+| Partial cache dirs from interrupted `/plugin update` | Two version dirs for the same plugin (one complete, one missing `dist/`/`node_modules/`). Align `installed_plugins.json`'s `version`+`installPath` and delete the incomplete one. See § 10. |
+| `plugin.json` at plugin root instead of `.claude-plugin/plugin.json` | Move it. Only `plugin.json` lives in `.claude-plugin/`; everything else (commands/, skills/, agents/, hooks/) stays at plugin root. |
+| Reserved marketplace name | Avoid `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-*`, `agent-skills`, `knowledge-work-plugins`, `life-sciences`, plus impersonating variants. Rejected at claude.ai sync. |
+| Non-kebab-case plugin or marketplace name | Local flow tolerates it with a warning; claude.ai sync rejects outright. Use `[a-z0-9][a-z0-9-]*`. Validate with `claude plugin validate .`. |
+
+## Plugin Hygiene (Preventing Install Chaos)
+
+Accumulating installs cause MCP server conflicts, phantom Stop-hook errors, and /doctor warnings. Rules:
+
+**One canonical marketplace per plugin.** If a plugin is shipped via an aggregator (e.g. `rosslabs-ai-toolkit`), do not also register a per-plugin marketplace pointing at the same repo. `extraKnownMarketplaces` in `settings.json` bloats when every source gets added.
+
+**Never `@local` + `@marketplace` for the same plugin concurrently.** When iterating in the source directory, disable the marketplace install first. Dual installs both start MCP servers, both compete for the same `.mcp.json` tools, and one always fails.
+
+**Renaming a marketplace is a full migration.** When a marketplace is renamed (e.g. `RossLabs-claude-plugins` → `rosslabs-ai-toolkit`, kebab-case is required by the schema), every plugin installed from the old name stays in `installed_plugins.json` with a stale install path forever. Uninstall every plugin from the old marketplace, then reinstall from the new one. Edit `installed_plugins.json` by hand only as a last resort — corruption bricks the plugin system.
+
+**Audit periodically:**
+```bash
+jq 'keys | group_by(split("@")[0]) | map(select(length > 1))' \
+  ~/.claude/plugins/installed_plugins.json
+```
+Returns plugins with multiple install sources. Anything in that list is a duplicate.
+
+**`extraKnownMarketplaces` hygiene.** Each entry is a registered marketplace that `/plugin` can pull from. If you added a directory source for local dev and later moved to the aggregator, remove the dev entry.
+
+## Building an MCP Server
+
+When the plugin exposes MCP tools (not just hooks/skills/agents), see the dedicated **`mcp-builder` skill** for server implementation, bundling strategies (`tsup` vs `tsc` + SessionStart install hook), stdio transport, tool design rules, and a standalone smoke-test. Plugin-builder covers the `.mcp.json` config; mcp-builder covers the server itself.
+
+## Debugging MCP Failures
+
+When `/plugin` shows "MCP · ✗ failed":
+
+1. **Standalone handshake test.** Launch the server directly with an `initialize` RPC — if it returns valid JSON-RPC, the server is fine and the UI is stale:
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+     CLAUDE_PLUGIN_ROOT=<plugin-path> node <plugin-path>/dist/mcp/server.js
+   ```
+2. **Schema check.** Verify `.mcp.json` has the top-level `"mcpServers"` wrapper (most common root cause).
+3. **Cache completeness.** Confirm `dist/` and (if needed) `node_modules/` exist at the `installPath` listed in `installed_plugins.json`.
+4. **Version alignment.** `version` field and `installPath` dir must agree — mismatches produce phantom failures.
+
+Full playbook in `references/plugin-hygiene-lessons.md` § 13.
+
+## Dual-Host: Shipping to Claude Code AND Codex
+
+Plugins ship to both Claude Code and Codex from one repo with thin per-host manifests. For the full pattern — `.codex-plugin/plugin.json` schema, agent-neutral surfaces (skills, MCP), Claude-only surfaces (hooks, agents), README/install-script conventions — see **`references/dual-host-claude-codex.md`**.
+
+Quick summary:
+
+| Surface | Location | Host |
+|---|---|---|
+| Claude manifest | `.claude-plugin/plugin.json` | Claude Code |
+| Codex manifest | `.codex-plugin/plugin.json` | Codex |
+| Workspace install metadata (optional) | `.agents/plugins/marketplace.json` | Codex (local dev) |
+| Skills (agent-neutral) | `./skills/<name>/SKILL.md` | Both |
+| MCP servers (agent-neutral) | `./.mcp.json` | Both |
+| Agent definitions | `./agents/*.md` | Claude only |
+| Hooks | `./hooks/hooks.json` | Claude only (Codex has its own system) |
+
+Keep `name` and `version` identical across the two-or-three manifests — users think of it as one plugin. **Include `.claude-plugin/marketplace.json` if the plugin ships its own marketplace listing** (both `metadata.version` AND the `plugins[name=<plugin>].version` entry must match). The version-sync test enforces all enforced manifests; treat the test (`scripts/test_plugin_manifest.py` for build-loop; equivalent elsewhere) as the **source of truth** — read its failure output to enumerate every enforced manifest before drafting a version-bump brief. Prose can undercount silently; the test cannot. See `references/coordination-rules.md` §"Verification of release surface" for the cross-cutting release-surface rule that includes this lockstep check (memory: `feedback_three_file_lockstep_plugin_manifest`).
+
+## Additional Resources
+
+Core references (load as needed — don't pre-load all):
+
+- **`references/authoritative-sources.md`** — Anthropic + MCP doc URLs, validation tooling, sanity-test commands, canonical behavior rules. Start here when you need to verify a claim.
+- **`references/manifest-schema.md`** — Complete `plugin.json` schema with all fields
+- **`references/hooks-reference.md`** — All hook events, types, matchers, and patterns
+- **`references/components-guide.md`** — Detailed guide for each component type
+- **`references/distribution.md`** — Marketplace creation, versioning, and sharing
+- **`references/dual-host-claude-codex.md`** — Codex plugin surface, dual-host shape, schema for `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`, README/install-script patterns
+- **`references/plugin-hygiene-lessons.md`** — 16 real-world incidents from shipping plugins (duplicate installs, `.mcp.json` schema, marketplace zombies, partial cache dirs, `${CLAUDE_PLUGIN_DATA}` patterns, UI failure-badge persistence)
+- **`references/build-loop-phase-guidance.md`** — How build-loop phases should handle plugin edits (Assess → Plan → Execute → Review → Iterate)
+
+Related skills:
+- **`mcp-builder`** — MCP server implementation companion
+- **`skill-builder`** — SKILL.md authoring (for skills shipped inside a plugin)

package/skills/plugin-builder/references/authoritative-sources.md

@@ -0,0 +1,104 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Authoritative Sources for Claude Code Plugin Development
+
+When the plugin-builder skill or any build-loop phase needs to verify a claim about plugin behavior, cite from this list. T1 sources override training data — if the docs changed, the docs win.
+
+## Tier 1 — Anthropic official (ground truth)
+
+| Topic | URL |
+|---|---|
+| Plugins reference (full schema, all components) | https://code.claude.com/docs/en/plugins-reference |
+| Plugin marketplaces (how to create/host/publish) | https://code.claude.com/docs/en/plugin-marketplaces |
+| Plugins tutorial | https://code.claude.com/docs/en/plugins |
+| Discover and install plugins | https://code.claude.com/docs/en/discover-plugins |
+| Plugin dependencies | https://code.claude.com/docs/en/plugin-dependencies |
+| Settings (enabledPlugins, extraKnownMarketplaces, strictKnownMarketplaces) | https://code.claude.com/docs/en/settings |
+| Hooks reference | https://code.claude.com/docs/en/hooks |
+| Skills | https://code.claude.com/docs/en/skills |
+| Subagents | https://code.claude.com/docs/en/sub-agents |
+| Tools reference (Monitor, etc.) | https://code.claude.com/docs/en/tools-reference |
+
+Anthropic also ships a documentation index at https://code.claude.com/docs/llms.txt — fetch it first if you don't know the exact page.
+
+## Tier 1 — MCP protocol
+
+| Topic | URL |
+|---|---|
+| Model Context Protocol spec | https://modelcontextprotocol.io/ |
+| MCP specification (versioned) | https://spec.modelcontextprotocol.io/ |
+| TypeScript SDK | https://github.com/modelcontextprotocol/typescript-sdk |
+| Python SDK | https://github.com/modelcontextprotocol/python-sdk |
+
+## Tier 2 — Working plugin examples (reference implementations)
+
+Use these when you want to see a specific pattern in production code. Prefer bundled-with-`tsup` plugins as the cleanest MCP packaging pattern.
+
+| Pattern | Repo |
+|---|---|
+| `tsup`-bundled MCP server (single-file `dist/`, no runtime deps) | https://github.com/tyroneross/interface-built-right |
+| Aggregator marketplace with 16 symlinked plugins | https://github.com/tyroneross/RossLabs-AI-Toolkit |
+| Session-continuity plugin (hooks + MCP + CLI) | https://github.com/tyroneross/bookmark |
+| Architecture-scan plugin (CLI-heavy, TypeScript + tsc) | https://github.com/tyroneross/NavGator |
+| Build-loop orchestrator plugin (multiple subagents + skills) | https://github.com/tyroneross/build-loop |
+| Anthropic's official plugins | https://github.com/anthropics/claude-plugins-official |
+
+## Validation tooling
+
+| Tool | What it checks |
+|---|---|
+| `claude plugin validate <path>` | `plugin.json`, skill/agent/command frontmatter, `hooks/hooks.json` schema |
+| `claude --debug` at startup | Plugin load errors, MCP init errors |
+| `/plugin` → "Needs attention" tab | Runtime MCP failures |
+| `/mcp` | Live MCP server status (more detail than `/plugin`) |
+| `/doctor` | Manifest drift, duplicate hook declarations |
+
+## Sanity tests
+
+**MCP server standalone**:
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+  CLAUDE_PLUGIN_ROOT=<plugin-path> node <plugin-path>/dist/mcp/server.js
+```
+
+**Duplicate-install audit**:
+```bash
+jq 'keys | group_by(split("@")[0]) | map(select(length > 1))' \
+  ~/.claude/plugins/installed_plugins.json
+```
+
+**Cache completeness 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
+```
+
+**Zombie-marketplace audit** (after a cleanup, verify nothing re-seeds):
+```bash
+ls ~/.claude/plugins/.install-manifests/
+ls ~/.claude/plugins/marketplaces/
+jq '.extraKnownMarketplaces | keys' ~/.claude/settings.json
+jq 'keys' ~/.claude/plugins/known_marketplaces.json
+```
+
+## Behavior rules worth remembering
+
+These are extracted from the docs above; cite the URL when quoting.
+
+1. **Plugin manifest is optional.** If omitted, Claude Code auto-discovers components and derives the name from the directory. Use a manifest only when you need metadata or custom component paths. ([plugins-reference](https://code.claude.com/docs/en/plugins-reference#plugin-manifest-schema))
+2. **`name` is the only required manifest field.** Kebab-case, no spaces.
+3. **`${CLAUDE_PLUGIN_ROOT}`** — path to plugin install dir. Changes on every plugin update.
+4. **`${CLAUDE_PLUGIN_DATA}`** — persistent state dir at `~/.claude/plugins/data/<id>/`. Survives updates. Right place for `node_modules/`, virtualenvs, generated code.
+5. **Plugin cache lives at `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`.** Each version is a separate dir. Orphaned versions are removed 7 days after an update or uninstall.
+6. **Path traversal (`../shared-utils`) fails after install** — cached plugins can't see files outside their dir. Use symlinks if needed; they're preserved in the cache.
+7. **Relative paths** in the manifest must start with `./` and be relative to the plugin root.
+8. **Marketplace schema** requires `name` (kebab-case), `owner.name`, and `plugins[]`. Reserved names: see lesson #12 in `plugin-hygiene-lessons.md`.
+9. **`strict: true`** (default) means `plugin.json` is authoritative. Marketplace entry can supplement. `strict: false` = marketplace entry is the full definition.
+10. **Version precedence** — `plugin.json.version` wins over `marketplace.json` plugin entry silently. Set in one place only; for relative-path plugins, set in the marketplace; for everything else, in `plugin.json`.
+
+Always verify before acting: open the relevant page above, quote the section, then apply.

package/skills/plugin-builder/references/build-loop-phase-guidance.md

@@ -0,0 +1,94 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Hygiene — Build-Loop Lessons
+
+When build-loop phases produce, modify, or ship Claude Code plugins, apply these rules. Each is traceable to a real failure in the `rosslabs-ai-toolkit` marketplace.
+
+## Assess phase
+
+Before modifying a plugin, check for duplicate installs:
+
+```bash
+jq 'keys | group_by(split("@")[0]) | map(select(length > 1))' \
+  ~/.claude/plugins/installed_plugins.json
+```
+
+Any duplicate entry means the user has the same plugin installed from multiple sources (e.g. `@local` + `@marketplace`). Edits to one source don't reach the other. **Flag this in the Assess report and offer to consolidate before proceeding.**
+
+## Plan phase
+
+When the plan touches `plugin.json`, require an explicit field inventory. Do not write these fields if the referenced file is at its default path:
+
+| Field | Auto-loaded path | When to declare |
+|-------|------------------|-----------------|
+| `hooks` | `hooks/hooks.json` | Only for non-standard path |
+| `mcpServers` | `.mcp.json` | Only for non-standard path or inline definitions |
+| `lsp` | `.lsp.json` | Only for non-standard path |
+
+Declaring a default-path file produces `Duplicate hooks file detected` errors in `/doctor`. Fact-check this in Review-D.
+
+## Execute phase
+
+**Never emit `type: "prompt"` hooks on per-turn events.** PostToolUse:Bash, UserPromptSubmit, and PreToolUse:Bash fire on every tool call. A prompt hook there runs the LLM on every event — expensive in tokens, disruptive in UX (streams "hook stopped continuation" messages). If a plugin needs conditional nudges, use `type: "command"` with silent exit 0.
+
+Allowed locations for `type: "prompt"` hooks:
+- SessionStart (fires once per session)
+- Stop (fires once per turn-end)
+- PreCompact (fires once per compaction)
+
+## Review phase (sub-step D: Fact-Check)
+
+Add to the manifest-drift check:
+1. Grep plugin.json files in the diff for `"hooks":`, `"mcpServers":`, `"lsp":`
+2. For each match, verify the referenced file is NOT at the auto-loaded default path
+3. Grep hook files for `"type": "prompt"` inside `PostToolUse`, `PreToolUse`, `UserPromptSubmit`
+4. If the plugin ships in an aggregator marketplace, verify marketplace.json version matches plugin.json version
+5. **`.mcp.json` schema**: verify top-level key is `"mcpServers"`. Flat form `{"<name>": {...}}` silently passes `/doctor` but fails at MCP startup — only `/mcp` surfaces the failure. Correct form is `{"mcpServers": {"<name>": {...}}}`.
+6. **Build artifacts**: if plugin.json's `mcpServers.*.args` references `${CLAUDE_PLUGIN_ROOT}/dist/...`, verify `dist/` is not gitignored and is checked into the repo. Alternative: plugin uses `tsup` to bundle into a single self-contained file (preferred — ibr's pattern).
+
+## Iterate phase
+
+If `/doctor` still reports errors after Review, common root causes in order of likelihood:
+
+1. Duplicate hooks/mcpServers declaration → remove field from manifest
+2. `type: "prompt"` on high-frequency event → change to command or move to SessionStart
+3. Stale install record → user needs to `/plugin` uninstall old-marketplace copy
+4. Cache regenerated from marketplace, overwriting local fix → commit+push source repo, re-sync
+
+## Marketplace rename checklist
+
+If build-loop is executing a marketplace rename (e.g. detected in the Assess phase via `extraKnownMarketplaces` showing old + new names simultaneously), generate this task list:
+
+- [ ] `/plugin` → uninstall every plugin from the old marketplace name
+- [ ] Remove old marketplace entry from `settings.json` → `extraKnownMarketplaces`
+- [ ] Re-add new marketplace (kebab-case name — Anthropic schema requires it)
+- [ ] Reinstall each plugin from the new name
+- [ ] Audit `installed_plugins.json` for residual old-name keys
+- [ ] Update any CLAUDE.md memory referencing the old name
+- [ ] Update README.md in the marketplace repo
+- [ ] Bump marketplace.json version
+
+The rename is a full migration, not a metadata change. Partial renames produce permanent stale install paths.
+
+## Source-of-truth flow
+
+```
+~/Desktop/git-folder/<plugin-repo>/            ← author-owned, edit here, commit
+       │
+       ▼ (git push)
+GitHub: tyroneross/<marketplace>/              ← marketplace pulls from here
+       │
+       ▼ (plugin sync)
+~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/   ← generated, never edit long-term
+       │
+       ▼ (runtime)
+Claude Code session
+```
+
+Build-loop must edit the source repo, not the cache. Cache edits survive until the next sync, then vanish. If an edit MUST land this session, edit both source and cache, then commit source before Review ends.
+
+## References
+
+- `~/.claude/skills/plugin-builder/references/plugin-hygiene-lessons.md` — full incident log
+- `~/.claude/projects/-Users-tyroneross/memory/feedback_hook_design.md` — hook design rules
+- `~/.claude/projects/-Users-tyroneross/memory/feedback_rosslabs_toolkit_sync.md` — marketplace rename sync