pluginpack: Instructions file for Claude Code

pluginpack — agent guide

pluginpack compiles one source of portable agent plugins (skills, agents, commands, rules, hooks, MCP servers, assets, metadata) into the native plugin layouts each AI app expects. It is a build tool: it copies files, writes the manifests each target needs, and validates the result. It is not a package manager or publisher.

Commands

• npm run dev -- <args> — run the CLI from source (tsx src/cli.ts).
• npm test — vitest. A pretest hook builds first, because the conformance tests run the real built binary (dist/cli.js) via bintastic.
• npm run check — the full gate (test:all): format:check → lint → typecheck → test → build → docs. Run this before considering work done.
• npm run audit — npm audit --omit=dev, also run in CI. Scoped to production dependencies on purpose: devDependencies (eslint, test fixtures, etc.) never ship in the published package, so a vulnerability there isn't a risk to consumers — don't add fixes/overrides for dev-only findings.
• npm run build — bundle with tsup.
• After changing CLI commands/options, regenerate the README CLI reference with node dist/cli.js docs (the gate's docs --check fails if it is stale).

Node >= 22.12.0 (the engines floor in package.json, verified in CI against that exact version), ESM, moduleResolution: nodenext, strict: true. Local dev tooling (mise.toml) pins Node 24, but that's a dev-environment choice, not the supported floor.

Architecture

Data flows: config → discover source → collect/render files → emit per target → artifact (in-memory file map) → write / prune / validate / diff. The Artifact (a Map<path, contents> plus managedPaths) is the seam — dry-run, diff, prune, and validate all derive from it.

• src/cli.ts — commander CLI: init, build, validate, diff, prune, clean, install-info, docs.
• src/schema.ts — zod schemas are the source of truth for config types; authoring types use z.input, and parsed config uses z.infer. The build materializes these aliases as structural declarations without a Zod type dependency. Edit schemas here, not types.ts.
• src/types.ts — non-config types; re-exports the config types from schema.ts.
• src/components.ts — componentDirs + staticFiles (shared by render/config).
• src/config.ts — loadConfig (jiti loads pluginpack.config.ts) and legacy 0.10 source-plugin discovery during the migration window.
• src/source.ts — reads canonical direct shared/<plugin> sources, applies target overrides, packages mcp/, and retains the legacy filesystem source provider.
• src/render.ts — legacy collectPluginFiles/resolveMcpServers composition.
• src/partials.ts — loadPartials/resolvePartials: project-level {{> name}} text-reuse, wired into collectPluginFiles and withRootFiles. Substitution is real mustache rendering (view is always {} — no config/env data is ever exposed; this is not a general templating hook), but only ever sees partial tags: every other {{ is swapped for a sentinel first and restored after, so text that merely looks like a template survives byte-for-byte. An unresolvable tag is a build error, not an empty string. Also holds two checks mustache doesn't provide — circular partial reference detection at load time, and findUnsubstitutedPartialTags, the guard for tags in file types substitution skips (called from build() and, reading from disk, from validate).
• src/targets/registry.ts — targets: Record<TargetName, PluginTargetDefinition>, one file per target (src/targets/<name>.ts). Everything that varies by target — default components, manifest/marketplace builders, output paths, validation, install snippet — lives on that target's own PluginTargetDefinition (src/targets/types.ts).
• src/targets/engine.ts — emitFromDefinition/validateFromDefinition: the one emit/validate engine every target runs through, driven by its PluginTargetDefinition. Also withRootFiles (injects per-target repo-root files into the artifact).
• src/targets/validation-shared.ts — validators shared across targets whose shape actually matches (bare-string marketplace source, hooks.json shape, frontmatter conventions); a target with a genuinely different shape (e.g. Codex's structured source) writes its own instead of forcing a fit.
• src/adapters.ts — emitTarget/validateOutput/targetNames, thin wrappers around the registry + engine.
• src/build.ts — build(): emit all targets → assertNoCrossTargetCollisions → write/prune/manifest. Holds the delete guard.
• src/managed.ts — the managed-file manifest (.pluginpack/<target>.json), prune/clean, the delete guard, and path-safety checks.
• src/diff.ts — diffTarget: build to a temp dir and compare against an existing target repo (the CI staleness gate).