@tyroneross/build-loop 0.30.3

package/skills/plugin-builder/references/dual-host-claude-codex.md

@@ -0,0 +1,220 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Dual-Host Plugin Pattern: Claude Code + Codex
+
+Every plugin in the `rosslabs-ai-toolkit` marketplace ships to **both** Claude Code and Codex from a single repository. This reference covers the shared structure, per-host manifests, and what stays agent-neutral.
+
+## Why dual-host
+
+Codex (OpenAI's coding agent CLI) and Claude Code have converged on plugins as the packaging unit. The internals (skills, MCP servers, markdown commands) are largely agent-neutral. The per-host differences are thin: a manifest file per host, slightly different naming conventions, separate install surfaces.
+
+Shipping to both from one repo means:
+- One source of truth for skills, MCP tools, prompts
+- One CI/release pipeline
+- Users on either host get fixes at the same time
+
+## Repo layout
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json              # Claude Code manifest
+├── .codex-plugin/
+│   └── plugin.json              # Codex manifest (this file)
+├── .agents/                     # Codex workspace-install metadata (optional)
+│   └── plugins/
+│       └── marketplace.json
+├── skills/                      # Agent-neutral — both hosts load from here
+│   └── <skill-name>/
+│       └── SKILL.md
+├── commands/                    # Mostly agent-neutral markdown
+├── agents/                      # Claude-specific (Codex ignores)
+├── hooks/                       # Claude-specific (Codex has its own hook system)
+├── .mcp.json                    # Agent-neutral — both hosts load MCP from here
+└── package.json
+```
+
+**Agent-neutral surfaces** (one copy, both hosts consume):
+- `skills/*/SKILL.md` — markdown with YAML frontmatter
+- `.mcp.json` — MCP server configuration
+- `commands/*.md` — when they're pure prompts without Claude-only frontmatter
+
+**Claude-specific** (lives in standard Claude Code paths, Codex ignores):
+- `.claude-plugin/plugin.json`
+- `agents/*.md` with Claude frontmatter (`model: sonnet`, `isolation: worktree`, etc.)
+- `hooks/hooks.json` with Claude hook events (`PostToolUse`, `Stop`, etc.)
+
+**Codex-specific**:
+- `.codex-plugin/plugin.json`
+- `.agents/plugins/marketplace.json` (workspace-level install metadata)
+
+## `.codex-plugin/plugin.json` — required shape
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Brief description matching what you shipped to Claude",
+  "author": {
+    "name": "Your Name",
+    "url": "https://github.com/you"
+  },
+  "homepage": "https://github.com/you/my-plugin#readme",
+  "repository": "https://github.com/you/my-plugin",
+  "license": "MIT",
+  "keywords": ["tag1", "tag2"],
+  "skills": "./skills",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "My Plugin",
+    "shortDescription": "One-line description shown in Codex marketplace UI.",
+    "longDescription": "Full paragraph shown on the plugin detail page. Describe what it does and when a user should install it.",
+    "developerName": "Your Company",
+    "category": "Coding",
+    "capabilities": [
+      "Read",
+      "Write"
+    ]
+  }
+}
+```
+
+### Field rules
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | kebab-case. Match the Claude plugin name — users shouldn't see two different names for the same plugin. |
+| `version` | yes | semver. Keep in sync with `.claude-plugin/plugin.json` version — users think of it as one plugin. |
+| `description` | yes | One-sentence. Matches the Claude manifest's description for consistency. |
+| `skills` | yes if skills exist | Always `"./skills"` — same path Claude uses. |
+| `mcpServers` | yes if MCP exists | Always `"./.mcp.json"` — same file Claude uses. |
+| `commands` | optional | Only if you have agent-neutral markdown commands to expose. |
+| `interface.displayName` | yes | Title case; this is what users see in the Codex marketplace. |
+| `interface.shortDescription` | yes | Under ~150 chars. Marketplace card text. |
+| `interface.longDescription` | yes | Full plugin-detail page. Can reuse `description` if the plugin is simple. |
+| `interface.developerName` | yes | Company/team name. All Ross Labs plugins use `"Ross Labs"`. |
+| `interface.category` | yes | One of: `Coding`, `Productivity`, `Content`, `Research`, `Design`, etc. Pick from Codex's current list. |
+| `interface.capabilities` | yes | Array of coarse permissions Codex should surface at install: `Read`, `Write`. |
+
+## `.agents/plugins/marketplace.json` — workspace install metadata (optional)
+
+This file lets Codex install the plugin from the **local workspace** (`./`) without publishing to a registry. Use it for plugins under active local development.
+
+```json
+{
+  "name": "my-plugin-local-workspace",
+  "interface": { "displayName": "My Plugin Workspace" },
+  "plugins": [
+    {
+      "name": "my-plugin",
+      "source": { "source": "local", "path": "./" },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}
+```
+
+If you only distribute via the public GitHub marketplace (not local workspace), you can skip this file.
+
+## README pattern — announce the Codex surface
+
+When you add Codex support to an existing Claude plugin, append a short section to the README so existing users know the Codex install surface exists. Used verbatim across rosslabs-ai-toolkit plugins:
+
+```markdown
+## Codex
+
+This package ships an additive Codex plugin surface alongside the existing
+Claude Code package. The Claude package remains authoritative for Claude
+behavior; the Codex package adds a parallel `.codex-plugin/plugin.json`
+install surface without changing the Claude runtime.
+
+Package root for Codex installs:
+- the repository root (`.`)
+
+Primary Codex surface:
+- skills from `./skills` when present
+- MCP config from `./.mcp.json` when present
+
+Install the package from this package root using your current Codex plugin
+install flow. The Codex package is additive only: Claude-specific hooks,
+slash commands, and agent wiring remain unchanged for Claude Code.
+```
+
+## package.json scripts pattern
+
+When the plugin has install scripts (most do), pair them so users can pick their host. From NavGator:
+
+```json
+{
+  "scripts": {
+    "install:claude": "bash scripts/install-plugin.sh --global",
+    "install:codex": "bash scripts/install-codex-plugin.sh --user",
+    "install:codex-workspace": "bash scripts/install-codex-plugin.sh --workspace"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".agents/",
+    "scripts/install-plugin.sh",
+    "scripts/install-codex-plugin.sh"
+  ]
+}
+```
+
+The `files` array is what ships to npm — make sure both manifest directories and both install scripts are listed.
+Before publishing, run the package surface gate in
+`skills/plugin-builder/references/distribution.md`: review
+`npm pack --dry-run --json` output, confirm no build caches or local runtime
+artifacts are included, and validate npmjs and GitHub Packages as separate
+registry surfaces when both are used.
+
+## What stays the same
+
+Do not duplicate content:
+
+- **Skills**: one `skills/<name>/SKILL.md`, both hosts invoke it. YAML frontmatter that's Claude-specific (like `disable-model-invocation`) is silently ignored by Codex.
+- **MCP servers**: one `.mcp.json`, both hosts launch the same server with the same `${CLAUDE_PLUGIN_ROOT}` substitution (Codex uses the same env-var name).
+- **Commands as markdown**: if your `commands/*.md` is a pure prompt without Claude frontmatter, both hosts can read it.
+- **`package.json`**: one source of truth for scripts and `files[]`.
+
+## What to duplicate minimally
+
+- **Plugin manifest** (`.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`) — two files, same `name` / `version` / `description` / `keywords`. Codex adds an `interface` block; Claude doesn't need it.
+- **README** — one README, add the Codex section at the bottom.
+
+## What stays Claude-only
+
+- `agents/*.md` with Claude subagent frontmatter (Codex has no equivalent yet)
+- `hooks/hooks.json` with Claude hook events (Codex has a separate hook system — port if you want equivalent behavior, but don't expect parity)
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Divergent `name` or `version` between Claude and Codex manifests | Keep them identical — same plugin, same version |
+| Duplicating `skills/` under `.codex-plugin/skills/` | One `skills/` at repo root, both manifests point to it via `"skills": "./skills"` |
+| Forgetting `.codex-plugin/` in `package.json` `files[]` | Add it — otherwise `npm publish` ships a broken package for Codex users |
+| Treating GitHub Packages success as npmjs success | Verify each registry separately with `npm view` or an install smoke |
+| Treating `npm publish --dry-run` as proof npmjs trusted publishing is configured | Dry-run is a package check; verify the npm Trusted Publisher owner, repo, workflow filename, environment, and allowed action before real publish |
+| `interface.capabilities` claims more than the plugin uses | Codex surfaces this at install time; claiming unused permissions looks worse, not better |
+| Missing `interface` block entirely | Codex marketplace UI will show raw name/description with no formatting; always include the block |
+| README doesn't mention Codex | Existing users don't discover the new install surface |
+
+## Preflight checklist (supplements the plugin-builder checklist)
+
+- [ ] `.codex-plugin/plugin.json` exists and validates as JSON
+- [ ] `name` and `version` match `.claude-plugin/plugin.json`
+- [ ] `interface.displayName`, `shortDescription`, `longDescription`, `developerName`, `category`, `capabilities` all set
+- [ ] `skills` and `mcpServers` paths point to the repo-root directories (same ones Claude uses)
+- [ ] `package.json` `files[]` includes `.codex-plugin/` and `.agents/` if used
+- [ ] `npm pack --dry-run --json` inventory has no `.build/`, `node_modules/`, local runtime output, credentials, or unexpected large artifacts
+- [ ] npmjs and GitHub Packages publish/install checks are reported separately when both registries are in use
+- [ ] npmjs Trusted Publisher settings match the workflow owner, repo, workflow filename, environment, and `npm publish` allowed action
+- [ ] README has the Codex section so existing users know about the install surface
+- [ ] Install scripts exist for both hosts (`install:claude`, `install:codex`) when package.json has a `scripts` section

package/skills/plugin-builder/references/hooks-reference.md

@@ -0,0 +1,210 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Hooks Reference
+
+## Hook Configuration Format
+
+Hooks live in `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolPattern",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Available Events
+
+| Event | Trigger | Common Uses |
+|-------|---------|-------------|
+| `PreToolUse` | Before Claude uses any tool | Validate inputs, block dangerous commands |
+| `PostToolUse` | After successful tool use | Format code, lint, log changes |
+| `PostToolUseFailure` | After tool execution fails | Error recovery, retry logic |
+| `UserPromptSubmit` | When user submits a prompt | Track activity, preprocess |
+| `PermissionRequest` | When permission dialog shown | Auto-approve trusted patterns |
+| `Stop` | When Claude attempts to stop | Write summaries, save context |
+| `SubagentStart` | When subagent starts | Configure subagent behavior |
+| `SubagentStop` | When subagent attempts to stop | Aggregate results |
+| `SessionStart` | At session beginning | Restore context, initialize state |
+| `SessionEnd` | At session end | Cleanup, save state |
+| `PreCompact` | Before conversation compaction | Save important context |
+| `Notification` | When Claude sends notifications | Forward to external services |
+| `TaskCompleted` | When task marked complete | Verify completion, trigger follow-ups |
+| `TeammateIdle` | When team agent about to idle | Redistribute work |
+
+## Hook Types
+
+### Command Hooks
+Execute shell commands or scripts:
+
+```json
+{
+  "type": "command",
+  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
+}
+```
+
+The command receives hook input as JSON on stdin. Use `jq` to extract fields:
+```json
+{
+  "type": "command",
+  "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
+}
+```
+
+### Prompt Hooks
+Evaluate a prompt with an LLM:
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Review the changes made and verify they follow project conventions. $ARGUMENTS"
+}
+```
+
+### Agent Hooks
+Run an agentic verifier with tools:
+
+```json
+{
+  "type": "agent",
+  "prompt": "Verify the implementation is complete and correct."
+}
+```
+
+## Matchers
+
+Matchers filter which tools trigger a hook:
+
+```json
+{
+  "matcher": "Write|Edit",
+  "hooks": [...]
+}
+```
+
+- Use `|` for OR: `"Write|Edit"`
+- Omit matcher to trigger on all tools for that event
+- Tool names are case-sensitive
+
+## Environment Variables
+
+`${CLAUDE_PLUGIN_ROOT}` — Always use this for plugin paths. Resolves to the actual plugin directory regardless of installation location.
+
+## Script Requirements
+
+1. Must be executable: `chmod +x scripts/my-script.sh`
+2. Include shebang line: `#!/bin/bash` or `#!/usr/bin/env bash`
+3. Use `${CLAUDE_PLUGIN_ROOT}` for paths
+4. Test manually before integrating
+
+## Reliability: minimal PATH, fail-open, advisory-only
+
+Hooks fire in a **subprocess with a minimal, non-interactive PATH** — typically `/usr/bin:/bin`, *not* your login shell's PATH. Binaries you installed to `~/.local/bin`, a Node version-manager dir, Homebrew, etc. are **not on PATH** inside a hook. This is the #1 cause of `exit code 127` (command not found) hook failures.
+
+Three rules for any hook that calls an external binary (`node`, `jq`, a project CLI):
+
+1. **Resolve binaries absolutely or guard every call.** Don't trust inherited PATH. Either hardcode/derive an absolute path (`RALLY_BIN`, `"$(command -v node || echo /opt/homebrew/bin/node)"`), or `command -v <bin> >/dev/null 2>&1 || exit 0` before using it.
+
+2. **Fail open for real — and test it.** A hook whose tooling is missing/slow must `exit 0` with no output, never abort. Watch for `set -euo pipefail` + an **unguarded** binary in a command substitution: `meta="$(printf '%s' "$x" | node -e '…')"` aborts the *whole script* with 127 the instant `node` isn't found — even if a later line has `|| true`. Guarding one line doesn't make the script fail-open. Verify under the real hook environment:
+   ```bash
+   printf '{"tool_input":{"file_path":"/tmp/x"}}' | env -i PATH=/usr/bin:/bin bash hooks/my-hook.sh before-write; echo "exit=$?"
+   # MUST print exit=0
+   ```
+
+3. **Advisory hooks must not enforce.** A coordination/lint/reminder hook should emit `additionalContext` (SessionStart/UserPromptSubmit, added to context) or `systemMessage`, never `permissionDecision:"deny"` / `decision:"block"`. Reserve blocking (`exit 2`, deny/block) for explicit safety/security/integrity gates, and gate any hard-block behind an opt-in env flag so the default never surprises an agent. Note SessionStart/Notification/Setup **cannot** block regardless.
+
+4. **Resolve your own path at runtime if installed out-of-tree.** If a host wrapper references a versioned/cache path (`${CLAUDE_PLUGIN_ROOT}`, `~/.codex/…`), prefer a thin shim that `exec`s the version-controlled script, or `realpath "$0"` inside the script — so the hook can't desync from the code it's supposed to run (see plugin-hygiene-lessons.md §17).
+
+## Common Patterns
+
+### Auto-Format on Write
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
+        }]
+      }
+    ]
+  }
+}
+```
+
+### Save Context on Stop
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [{
+          "type": "prompt",
+          "prompt": "Write a brief summary of this session's task, progress, and decisions to .claude/bookmarks/context.md"
+        }]
+      }
+    ]
+  }
+}
+```
+
+### Restore Context on Session Start
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/restore-context.sh"
+        }]
+      }
+    ]
+  }
+}
+```
+
+### Block Dangerous Commands
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-safety.sh"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+| Issue | Check |
+|-------|-------|
+| Hook not firing | Event name correct? (PascalCase) |
+| Script not executing | Is it executable? (`chmod +x`) |
+| Script can't find files | Using `${CLAUDE_PLUGIN_ROOT}`? |
+| Matcher not matching | Tool name correct and case-sensitive? |
+| Prompt hook not working | Valid prompt with `$ARGUMENTS` if needed? |
+| `exit code 127` on every fire | A binary the script calls (`node`/`jq`/CLI) isn't on the hook's minimal PATH. Resolve it absolutely or `command -v`-guard it; test under `env -i PATH=/usr/bin:/bin`. |
+| Hook aborts instead of failing open | `set -e` + an unguarded command substitution. Guarding one line ≠ fail-open. |
+| Path-with-spaces → 127 | Known issue (anthropics/claude-code #5648); quote the path in the command string. |
+| Advisory hook blocking edits | It's emitting `deny`/`block`; switch to `additionalContext`/`systemMessage` and reserve blocking for safety gates. |

package/skills/plugin-builder/references/manifest-schema.md

@@ -0,0 +1,111 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Manifest Schema Reference
+
+The `.claude-plugin/plugin.json` file defines plugin metadata and configuration.
+
+The manifest is **optional**. If omitted, Claude Code auto-discovers components in default locations and derives the plugin name from the directory name.
+
+## Complete Schema
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.2.0",
+  "description": "Brief plugin description",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://github.com/author"
+  },
+  "homepage": "https://docs.example.com/plugin",
+  "repository": "https://github.com/author/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2"],
+  "commands": ["./custom/commands/special.md"],
+  "agents": "./custom/agents/",
+  "skills": "./custom/skills/",
+  "hooks": "./config/hooks.json",
+  "mcpServers": "./mcp-config.json",
+  "outputStyles": "./styles/",
+  "lspServers": "./.lsp.json"
+}
+```
+
+## Required Fields
+
+Only `name` is required if including a manifest.
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` |
+
+## Metadata Fields
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `version` | string | Semantic version | `"2.1.0"` |
+| `description` | string | Brief explanation | `"Deployment automation tools"` |
+| `author` | object | `{name, email?, url?}` | `{"name": "Dev Team"}` |
+| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
+| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
+| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
+| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
+
+## Component Path Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `commands` | string or array | Additional command files/directories |
+| `agents` | string or array | Additional agent files |
+| `skills` | string or array | Additional skill directories |
+| `hooks` | string, array, or object | Hook config paths or inline config |
+| `mcpServers` | string, array, or object | MCP config paths or inline config |
+| `outputStyles` | string or array | Output style files/directories |
+| `lspServers` | string, array, or object | LSP server configs |
+
+## Path Behavior Rules
+
+- Custom paths **supplement** default directories — they don't replace them
+- All paths must be relative to plugin root and start with `./`
+- Multiple paths can be specified as arrays:
+
+```json
+{
+  "commands": [
+    "./specialized/deploy.md",
+    "./utilities/batch-process.md"
+  ],
+  "agents": [
+    "./custom-agents/reviewer.md",
+    "./custom-agents/tester.md"
+  ]
+}
+```
+
+## Installation Scopes
+
+| Scope | Settings file | Use case |
+|-------|--------------|----------|
+| `user` | `~/.claude/settings.json` | Personal, all projects (default) |
+| `project` | `.claude/settings.json` | Team, shared via version control |
+| `local` | `.claude/settings.local.json` | Project-specific, gitignored |
+| `managed` | Managed settings | Org-wide (read-only, update only) |
+
+## Version Management
+
+Format: `MAJOR.MINOR.PATCH`
+- **MAJOR:** Breaking changes (incompatible API changes)
+- **MINOR:** New features (backward-compatible)
+- **PATCH:** Bug fixes (backward-compatible)
+
+Start at `1.0.0` for first stable release. Pre-release: `2.0.0-beta.1`.
+
+**Important:** Claude Code uses the version to determine updates. If code changes but version doesn't bump, existing users won't see changes due to caching.
+
+## Plugin Caching
+
+Marketplace plugins are copied to `~/.claude/plugins/cache` for security. This means:
+- Paths traversing outside plugin root (`../shared-utils`) won't work after install
+- Use symlinks for external dependencies (they're honored during copy)
+- `--plugin-dir` plugins are used in-place (no caching)