| name | cpv-canonical-pipeline |
| description | Standard files, CI/CD, hooks, and release pipeline for Emasoft Claude Code plugins. Use when creating or auditing plugin repos. Used dynamically via cpv-the-skills-menu — any CPV agent can invoke at runtime (TRDD-478d9687).
|
| user-invocable | false |
Canonical Plugin Pipeline Standard
Overview
Defines the standard files, workflows, hooks, and release pipeline that every Emasoft Claude Code plugin repository MUST have. Covers Python, JavaScript/TypeScript, Rust, Go, and Shell plugins. Pipeline supports all three CPV layouts (A: separate plugin and marketplace repos; B: nested monorepo; C: marketplace-in-plugin self-referential single repo).
Profile-aware
The pipeline comes in four PROFILES, auto-detected from repo shape (or set authoritatively via the manifest cpv.pipeline_profile; detection fails safe to standard) by scripts/cpv_pipeline_profile.py's resolve_pipeline_profile(). The profile is a SELECTOR (which canon a file is compared against), never a SUPPRESSOR — every drift finding still fires:
- standard — vendors the CPV validators and ships the standard
gen_* workflows.
- remote-validation — de-vendors the local validators; validation is ONLY the remote
cpv-remote-validate --strict gate (its absence is the point).
- submodule-build — build sources live in a git submodule, pre-built binaries are committed to
bin/, and publish.py is submodule-aware.
- binary-release — ships compiled binaries as RELEASE assets via a build matrix + stage script + CI smoke job +
SHA256SUMS.
Layout C specifics
Layout C (marketplace-in-plugin) needs a different release pipeline:
publish.py bumps THREE version slots atomically: plugin.json::version, marketplace.json::metadata.version, AND the self-entry's version in marketplace.json::plugins[].notify-marketplace.yml is NOT installed (no separate marketplace repo).- A single tag
vX.Y.Z covers both manifest changes.
validate_marketplace.py --strict runs alongside validate_plugin.py --strict in CI.
Prerequisites
git, uv, gh CLI on PATH- CPV plugin installed (
claude-plugins-validation)
- GitHub account with
repo scope PAT (for marketplace notification)
Instructions
- Create plugin repo: Run
generate_plugin_repo.py or use /cpv-main-menu → Create
- Verify standard files: Check all required files exist per Detailed Standard
- Install CI/CD workflows: Ensure
ci.yml (consolidated lint + validate + test), release.yml, notify-marketplace.yml in .github/workflows/. validate.yml was merged into ci.yml in v2.12.32.
- Install pre-push hook:
uv run python scripts/publish.py --install-hook
- Validate (from any directory — fetches CPV from GitHub, no local vendoring):
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml cpv-remote-validate plugin . --strict
- Fix ALL issues: CRITICAL, MAJOR, MINOR, NIT must be resolved — only WARNINGs may remain
- Commit and push: The pre-push hook enforces 4 gates (version bump, lint, validate, tests)
Copy this checklist and track your progress:
Output
A fully configured plugin repository with:
- Plugin manifest (
plugin.json) and project config
- CI/CD workflows for lint, validate, test, release, and marketplace notification
- Pre-push hook running
publish.py --gate (4-gate quality enforcement)
- 11-stage release pipeline via
publish.py (auto-bump via git-cliff; --patch/--minor/--major override the auto-detection)
Error Handling
| Error | Resolution |
|---|
| Missing required file | Run standardize_plugin.py --fix to generate missing files |
| Pre-push hook not blocking | Run publish.py --install-hook to reinstall |
CI failing on uv sync | Use uv sync --extra dev for ruff/pytest/mypy |
| Marketplace notification fails | Check MARKETPLACE_PAT secret and owner/repo placeholders |
Examples
Create and publish:
/cpv-main-menu
> Choose: 6 — Create → Create a new plugin → then Publish to GitHub
Standardize existing:
/cpv-main-menu
> Choose: 8 — Manage → Standardize plugin
Resources
- Detailed Standard — complete tables for files, workflows, hooks, pipeline stages, marketplace, and language-specific additions
Standard Plugin Files · Standard CI/CD Workflows · Git Hooks · Release Pipeline (scripts/publish.py) · Marketplace Standard · Language-Specific Additions
- Pipeline Rules — mandatory rules for all plugin operations
Pre-Push Hook: The Quality Gate · Fix-All Mandate · Running CPV Scripts · Processing Validation Output · GitHub Secrets · CI Workflow Dependencies · Marketplace Notification · All Scripts Are Python · Binary Plugins · README Requirements · Pre-Publish Local Dry-Run · Post-Push CI Verification · Generated-Pipeline Reliability Contract (v2.134.0 — CPV ref pinned, integrity-skip + timeout, Test aggregate gate, notify no-op without secret, "done" = green CI) · Mega-Linter Configuration · Common Fixes Reference
- Pipeline Standards (current) — the standards every newly-scaffolded plugin ships with
Overview · Whole-repo lint via cpv_lint_engine · Idempotent publish.py · validate_pipeline_script_refs rule · Cross-platform scripts — no bash, no jq/sed/awk · Input sanitization — every script parameter · Hooks MUST persist state in CLAUDE_PLUGIN_DATA, never CLAUDE_PLUGIN_ROOT · Hook commands MUST be cross-platform (Python-delegated) · PEP 723 scripts MUST be invoked via uv run · Migrating a legacy plugin
- v2.1.80+ Plugin Features
Monitor tool · userConfig (plugin.json) · channels (plugin.json) · CLAUDE_PLUGIN_OPTION_ env vars · Inline marketplace (settings.json) · managed-settings.d/ drop-in directory · Plugin skill name field (v2.1.98)
- Parallel scanning (v2.103.0+) — every CPV validator runs file scans in parallel by default; scaffolded plugins inherit ~11.6× speedup automatically via
uvx --from git+... remote-mode
Table of contents · Performance summary · Environment knobs (disable selectively for debugging) · Scaffolded plugins (created via cpv-create-plugin / cpv-setup-plugin-repo) · Batch commands (cpv-batch-*) · Remote validation (cpv remote-mode + scaffolded publish.py) · When to disable parallelism · See also
- Scan cache (v2.104.0+) — content-hash-keyed SQLite cache of skillaudit findings; ~50× speedup on repeat runs; 5-level storage path resolution; survives plugin updates via
$CLAUDE_PLUGIN_DATA
Table of contents · Overview · Storage path resolution chain · SQLite schema · Security invariants · Env-vars · GitHub Actions integration · Pruning (age + LRU) · Introspection helpers · When to invalidate manually · What the cache does NOT cache · Performance characteristics · See also
- Binary scanning (v2.104.0+) — binary-aware STRATEGY replacing the dangerous "skip binaries" anti-pattern; runs the full skillaudit catalog on ASCII / UTF-16 strings + recursive decode chain (base64 / hex / gzip / zlib); never skips a file
Table of contents · The security principle: NEVER skip a file · Detection · Scanning pipeline · Edge cases (ALL logged, NEVER silent) · Env-var · What this scanner does NOT do · Coverage gain vs current text-only behavior · Performance characteristics · Future work
- Migration exit gate: the repo-root
references/canonical-pipeline-migration-checklist.md (CPV ships it at the repo root, NOT inside this skill dir)
