@tyroneross/build-loop 0.30.3

package/skills/plugin-builder/references/components-guide.md

@@ -0,0 +1,221 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Components Guide
+
+## Overview
+
+| Component | Location | File format | Auto-discovered |
+|-----------|----------|-------------|-----------------|
+| Skills | `skills/` | Subdirs with `SKILL.md` | Yes |
+| Commands | `commands/` | `*.md` files | Yes |
+| Agents | `agents/` | `*.md` files | Yes |
+| Hooks | `hooks/hooks.json` | JSON | Referenced in manifest |
+| MCP Servers | `.mcp.json` | JSON | Referenced in manifest |
+| LSP Servers | `.lsp.json` | JSON | Referenced in manifest |
+| Settings | `settings.json` | JSON | Auto-loaded |
+
+---
+
+## Skills
+
+Skills are the recommended way to add capabilities. Each skill is a directory containing a `SKILL.md`.
+
+### Structure
+```
+skills/
+├── code-review/
+│   ├── SKILL.md
+│   ├── references/
+│   │   └── patterns.md
+│   └── scripts/
+│       └── validate.sh
+└── deploy/
+    └── SKILL.md
+```
+
+### SKILL.md Format
+```yaml
+---
+name: code-review
+description: Reviews code for best practices and potential issues.
+  Use when reviewing code, checking PRs, or analyzing code quality.
+---
+
+When reviewing code, check for:
+1. Code organization and structure
+2. Error handling
+3. Security concerns
+4. Test coverage
+```
+
+### Key Points
+- Folder name becomes skill name, prefixed with plugin namespace
+- Auto-discovered from `skills/` directory
+- Can include supporting files (references/, scripts/, assets/)
+- Use the `skill-builder` skill for detailed SKILL.md guidance
+
+---
+
+## Commands
+
+Simple markdown files that create slash commands. Legacy approach — prefer skills for new development.
+
+### Structure
+```
+commands/
+├── status.md
+└── logs.md
+```
+
+### Format
+```markdown
+---
+description: Show project status
+disable-model-invocation: true
+---
+
+Check the current project status:
+1. Run git status
+2. Check for pending changes
+3. Report any issues
+```
+
+### Key Points
+- File name becomes command name (e.g., `status.md` → `/plugin-name:status`)
+- Same frontmatter fields as skills
+- No supporting files — everything in one markdown file
+- Skills take precedence if both share the same name
+
+---
+
+## Agents
+
+Specialized subagents Claude can invoke for specific tasks.
+
+### Structure
+```
+agents/
+├── security-reviewer.md
+├── performance-tester.md
+└── compliance-checker.md
+```
+
+### Format
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities and OWASP top 10 issues.
+  Invoke when the user asks to review security, check for vulnerabilities,
+  or audit code safety.
+---
+
+# Security Reviewer Agent
+
+Analyze code for security issues including:
+- SQL injection
+- XSS vulnerabilities
+- Authentication flaws
+- Authorization bypasses
+- Sensitive data exposure
+
+For each issue found, provide:
+1. Severity (Critical/High/Medium/Low)
+2. Location (file:line)
+3. Description of the vulnerability
+4. Recommended fix with code example
+```
+
+### Key Points
+- Appear in `/agents` interface
+- Claude invokes automatically based on task context
+- Can also be invoked manually by users
+- The markdown body becomes the agent's system prompt
+
+---
+
+## MCP Servers
+
+Connect Claude to external tools and services.
+
+### Configuration (`.mcp.json`)
+```json
+{
+  "mcpServers": {
+    "my-database": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
+      "env": {
+        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
+      }
+    },
+    "external-api": {
+      "command": "npx",
+      "args": ["@company/mcp-server", "--plugin-mode"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}"
+    }
+  }
+}
+```
+
+### Key Points
+- Start automatically when plugin is enabled
+- Tools appear as standard MCP tools in Claude's toolkit
+- Always use `${CLAUDE_PLUGIN_ROOT}` for paths
+- Can be configured independently of user MCP servers
+
+---
+
+## LSP Servers
+
+Give Claude real-time code intelligence (diagnostics, go to definition, find references).
+
+### Configuration (`.lsp.json`)
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+### Required Fields
+| Field | Description |
+|-------|-------------|
+| `command` | LSP binary to execute (must be in PATH) |
+| `extensionToLanguage` | Maps file extensions to language identifiers |
+
+### Optional Fields
+| Field | Description |
+|-------|-------------|
+| `args` | Command-line arguments |
+| `transport` | `stdio` (default) or `socket` |
+| `env` | Environment variables |
+| `initializationOptions` | Server initialization options |
+| `settings` | Workspace settings |
+| `restartOnCrash` | Auto-restart on crash |
+| `maxRestarts` | Maximum restart attempts |
+
+### Key Points
+- Users must install the language server binary separately
+- For common languages, install pre-built LSP plugins from official marketplace
+- Create custom LSP plugins only for languages not covered
+
+---
+
+## Default Settings (`settings.json`)
+
+Apply default configuration when the plugin is enabled.
+
+```json
+{
+  "agent": "security-reviewer"
+}
+```
+
+Currently only the `agent` key is supported. Setting `agent` activates one of the plugin's custom agents as the main thread, applying its system prompt, tool restrictions, and model.
+
+`settings.json` takes priority over `settings` declared in `plugin.json`. Unknown keys are silently ignored.

package/skills/plugin-builder/references/distribution.md

@@ -0,0 +1,317 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Plugin Distribution Guide
+
+## Distribution Methods
+
+### 1. Local Testing (--plugin-dir)
+For development and testing:
+```bash
+claude --plugin-dir ./my-plugin
+```
+Plugins are used in-place, no caching. Changes picked up on restart.
+
+### 2. GitHub Repository
+Host your plugin as a public (or private) repo:
+- Include a README.md at repo root (NOT inside skill folders)
+- Add installation instructions
+- Include example usage and screenshots
+- Use semantic versioning with tags
+
+### 3. Plugin Marketplace
+Create a marketplace for organized distribution:
+
+**Marketplace structure:**
+```
+my-marketplace/
+├── marketplace.json           # Registry of available plugins
+├── plugins/
+│   ├── formatter/             # Plugin directories
+│   │   ├── .claude-plugin/
+│   │   │   └── plugin.json
+│   │   └── ...
+│   └── linter/
+│       └── ...
+└── README.md
+```
+
+**marketplace.json:**
+```json
+{
+  "name": "My Team Marketplace",
+  "version": "1.0.0",
+  "plugins": [
+    {
+      "name": "formatter",
+      "description": "Code formatting tools",
+      "version": "1.2.0",
+      "source": "./plugins/formatter"
+    }
+  ]
+}
+```
+
+### 4. Official Anthropic Marketplace
+Submit via in-app forms:
+- Claude.ai: claude.ai/settings/plugins/submit
+- Console: platform.claude.com/plugins/submit
+
+## Installation Commands
+
+```bash
+# Install to user scope (default)
+claude plugin install formatter@my-marketplace
+
+# Install to project scope (shared with team)
+claude plugin install formatter@my-marketplace --scope project
+
+# Install to local scope (gitignored)
+claude plugin install formatter@my-marketplace --scope local
+
+# Uninstall
+claude plugin uninstall formatter@my-marketplace
+
+# Enable/disable without uninstalling
+claude plugin enable formatter@my-marketplace
+claude plugin disable formatter@my-marketplace
+
+# Update to latest version
+claude plugin update formatter@my-marketplace
+```
+
+## Version Management
+
+**Format:** `MAJOR.MINOR.PATCH`
+
+**Rules:**
+- Start at `1.0.0` for first stable release
+- Bump version in `plugin.json` before distributing changes
+- Document changes in `CHANGELOG.md`
+- Pre-release: `2.0.0-beta.1`
+
+**Critical:** Claude Code uses the version to determine whether to update. If you change code but don't bump the version, existing users won't see changes due to caching.
+
+Version can be set in either `plugin.json` or `marketplace.json`. If both are set, `plugin.json` takes priority.
+
+## Team Marketplace Setup
+
+For team-internal distribution:
+
+1. Create a Git repository with `marketplace.json`
+2. Add plugins as subdirectories
+3. Configure in project `.claude/settings.json`:
+```json
+{
+  "pluginMarketplaces": [
+    "https://github.com/your-org/claude-plugins"
+  ]
+}
+```
+4. Team members can install via `/plugin` interface
+
+## Plugin Caching Behavior
+
+**Marketplace plugins** are copied to `~/.claude/plugins/cache`:
+- External files (`../shared/`) won't be accessible
+- Symlinks are followed during copy
+- Changes require version bump to propagate
+
+**--plugin-dir plugins** are used in-place:
+- Changes take effect on restart
+- No caching involved
+- Good for development
+
+## npm Package Publishing
+
+Use this checklist when a plugin also ships as an npm package. Keep npmjs and
+GitHub Packages as separate release surfaces; a pass on one registry does not
+prove the other one shipped. For the build-loop-wide package standard, also
+load `../../../references/npm-package-publishing.md`.
+
+### npmjs Release Standard
+
+Every npmjs package publish uses provenance. Preferred path: trusted publishing
+with OIDC, using explicit `npm publish --provenance` without a stored npm token.
+Fallback path: a scoped npm access token plus `npm publish --provenance`. Do not add or edit an
+npmjs publish workflow that omits provenance unless the user explicitly accepts
+that exception.
+If an npm token is pasted into chat, logs, docs, or shell history, treat it as
+compromised. Do not use it for publishing; revoke it and return to the Trusted
+Publisher path.
+
+Use npm CLI v11 command docs as the command reference for release work. The
+standard command set is:
+
+```bash
+npm whoami --registry=https://registry.npmjs.org
+npm view @scope/package version dist-tags --registry=https://registry.npmjs.org --json
+npx -y npm@11 pack --dry-run --json --registry=https://registry.npmjs.org
+npm publish --dry-run --provenance --access public --registry=https://registry.npmjs.org
+npm publish --provenance --access public --registry=https://registry.npmjs.org
+npm token list
+npm audit signatures
+```
+
+### Registry Rules
+
+- Public npmjs publishes must target `https://registry.npmjs.org`. If
+  `package.json` has `publishConfig.registry` set to GitHub Packages, pass
+  `--registry=https://registry.npmjs.org` in the npmjs workflow and validation
+  commands.
+- GitHub Packages publishes target `https://npm.pkg.github.com` and need their
+  own install smoke. Do not report "published" without naming which registry
+  passed.
+- Validate the final registry state after publish:
+
+```bash
+npm view @scope/package version dist-tags --registry=https://registry.npmjs.org --json
+npm view @scope/package version --registry=https://npm.pkg.github.com
+```
+
+### Package Surface Gate
+
+Run the pack inventory before any tag or publish:
+
+```bash
+npx -y npm@11 pack --dry-run --json --registry=https://registry.npmjs.org
+```
+
+Review the JSON, not just the exit code:
+
+- Required files are present: `dist/` or runtime entrypoints, `bin` targets,
+  `.claude-plugin/`, `.codex-plugin/`, `skills/`, install scripts, README, and
+  license.
+- Generated caches are absent: `.build/`, `node_modules/`, simulator or local
+  runtime build output, local config, credentials, and large derived artifacts.
+- The tarball size is plausible for the package. A sudden large tarball is a
+  release blocker until the included file list is explained.
+- `package-lock.json`, if present, has the same package version as
+  `package.json`.
+
+### npmjs Trusted Publisher Gate
+
+For npmjs tokenless publishing from GitHub Actions, verify the npm package's
+Trusted Publisher settings before the real publish:
+
+- Provider: GitHub Actions.
+- Owner/user or organization and repository exactly match the GitHub repo.
+- Workflow filename exactly matches the publish workflow, for example
+  `publish-npm.yml`.
+- Environment is blank unless the workflow uses a GitHub environment.
+- Allowed actions include `npm publish`.
+
+The workflow should use a GitHub-hosted runner, `permissions: id-token: write`,
+`actions/checkout`, and `actions/setup-node` with `registry-url` set to the
+target registry. Do not set `NODE_AUTH_TOKEN` for trusted-publisher npmjs
+publishes. Remove obsolete `always-auth` inputs when using modern
+`setup-node`; use an explicit package-manager cache setting if the default
+cache detection is noisy.
+
+Run `npm publish --dry-run --provenance --access public --registry=https://registry.npmjs.org`
+as a packaging check, but do not treat it as proof that the Trusted Publisher
+mapping is valid. A real publish can still fail after a successful dry-run when
+the npm package settings do not match the GitHub workflow. After publishing,
+verify the registry metadata includes
+`dist.attestations.provenance.predicateType = https://slsa.dev/provenance/v1`.
+
+### Access Token Fallback Gate
+
+Trusted publishing is preferred because it removes long-lived npm secrets from
+CI and automatically generates provenance attestations. Use an npm access token
+only when the user explicitly chooses a fallback after the trusted-publisher
+path is blocked. Token fallback is still a provenance publish; it is not a
+non-provenance shortcut.
+
+If token fallback is approved:
+
+- Use a granular access token, not a legacy token.
+- Grant read/write only to the package or scope being published; do not grant
+  organization access and assume it allows package publishing.
+- Set an expiration date and record the rotation/removal follow-up.
+- Leave 2FA bypass off unless CI publishing cannot work without it and the user
+  accepts that exception. npm documents that Bypass 2FA takes precedence over
+  account-level and package-level 2FA, so record and rotate/revoke the exception.
+- Store the value as a GitHub secret such as `NPM_TOKEN`; never commit it to
+  `.npmrc`, workflow files, docs, or shell history examples.
+- If a token value is pasted into chat, logs, docs, or shell history, treat it as
+  compromised: do not use it; revoke it and create a fresh token.
+- Run `npm token list` to audit tokens and revoke the fallback token after the
+  release if it is no longer needed.
+
+Token fallback workflow steps should set:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+```
+
+and publish with:
+
+```bash
+npm publish --provenance --access public --registry=https://registry.npmjs.org
+```
+
+using `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
+
+### Provenance Gate
+
+For all npmjs packages, publish with provenance unless there is an explicit
+reason not to and that exception is recorded in the release notes. Provenance
+requires:
+
+- A supported cloud CI/CD provider and a cloud-hosted runner.
+- npm CLI `11.5.1+` for Trusted Publisher flows; prefer current npm.
+- `package.json.repository` set to the public source repository and matching the
+  repository used by the workflow.
+- `permissions.id-token: write` in the workflow.
+
+Trusted Publisher and token fallback publishes both use explicit `--provenance`
+on every real npmjs `npm publish` command. After install, downstream consumers
+can verify registry signatures and attestations with:
+
+```bash
+npm audit signatures
+```
+
+### Failure Triage
+
+- If GitHub Packages publishes and installs but npmjs fails, report split
+  registry status instead of changing package code by default.
+- If npmjs fails with `E404` or "not found or you do not have permission" on the
+  final `PUT`, first inspect the npm Trusted Publisher owner/repo/workflow and
+  package access. After fixing npm settings, rerun the failed workflow:
+
+```bash
+gh run rerun <run-id> --failed
+```
+
+- Use local npm login or token publishing only as an explicit fallback decision,
+  because it bypasses the trusted-publisher/provenance path.
+
+### Official References
+
+- npm CLI v11 command index:
+  `https://docs.npmjs.com/cli/v11/commands/npm`
+- npm CLI publish command:
+  `https://docs.npmjs.com/cli/v11/commands/npm-publish`
+- npm Trusted Publishers:
+  `https://docs.npmjs.com/trusted-publishers#supported-cicd-providers`
+- npm access tokens:
+  `https://docs.npmjs.com/about-access-tokens`
+- npm provenance:
+  `https://docs.npmjs.com/generating-provenance-statements`
+- GitHub Actions setup-node trusted-publisher OIDC:
+  `https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#publishing-to-npm-with-trusted-publisher-oidc`
+
+## README Guidelines
+
+For GitHub distribution, include:
+1. What the plugin does (outcomes, not implementation)
+2. Installation instructions
+3. Component list (skills, agents, hooks)
+4. Example usage with screenshots
+5. Configuration options
+6. Changelog
+
+**Note:** README.md goes at the repo root, never inside skill folders.