Skip to content

DISTRIBUTION.md

Latest commit

 

History

History
320 lines (205 loc) · 10.7 KB

DISTRIBUTION.md

File metadata and controls

320 lines (205 loc) · 10.7 KB
Raw

PPGP Distribution

PPGP is intentionally distributed through multiple channels. The protocol and canonical Agent Skill remain vendor-neutral; platform-native manifests are thin adapters for discovery and installation.

Canonical protocol skill:

skills/ppgp/SKILL.md
skills/ppgp/references/PPGP.md

For platforms that discover the cross-agent .agents/skills/ convention, the repository also contains a generated byte-identical mirror under .agents/skills/ppgp/. npm test fails if that mirror drifts from the canonical skill.

Regenerate the compatibility mirrors deterministically with:

node scripts/sync-skill-mirror.js

See COMPATIBILITY.md for the current platform-by-platform support matrix and verification state.

Universal Agent Skills route

Purpose: direct installation into Agent Skills-compatible environments without tying PPGP to a vendor.

npx skills add https://github.com/Fatboy-coder/ppgp/tree/main/skills/ppgp

This remains the preferred portable skill source.

Anthropic Claude and Claude Code

PPGP exposes a Claude plugin and a self-hosted marketplace from the canonical repository:

.claude-plugin/plugin.json
.claude-plugin/marketplace.json
plugins/ppgp/.claude-plugin/plugin.json
plugins/ppgp/skills/ppgp/

Install flow:

Claude
→ Plugins
→ Add marketplace
→ Fatboy-coder/ppgp
→ Sync
→ install ppgp

The exact invocation depends on the Claude client surface.

In the tested Claude client, the marketplace-installed skill is discovered and invoked with:

/ppgp

That same environment reports /reload-plugins as unavailable, so it is not a universal activation step.

Claude Code can namespace plugin skills as /plugin-name:skill-name. Where that namespace is exposed, the PPGP plugin and its single skill are both named ppgp, yielding:

/ppgp:ppgp

Use /reload-plugins only in a Claude surface that actually exposes that command and requires plugin activation after an update. Do not assume one slash-command form or reload command applies to every Claude client.

The dedicated plugins/ppgp/ package exists because Claude copies installed plugins into its cache. Its skill content is a deterministic mirror of the canonical skills/ppgp/ source and is drift-tested. Marketplace installation, updated-skill loading and invocation have been manually verified in a real Claude client. Public Anthropic directory listing is not claimed.

OpenAI Codex and ChatGPT

PPGP exposes a skill-only Codex/OpenAI plugin:

.codex-plugin/plugin.json
.agents/plugins/marketplace.json

The Codex plugin explicitly uses the canonical skills/ directory. The same canonical skill can be used as an OpenAI Agent Skill.

Repository packaging does not mean PPGP is publicly listed by OpenAI. These states remain distinct:

repository ready
!= submitted
!= approved
!= publicly listed

Public Plugin Directory publication is an external vendor-side step.

Google Gemini CLI

PPGP exposes a Gemini CLI extension manifest at repository root:

gemini-extension.json

The extension reuses the canonical skills/ppgp/ directory.

Intended install:

gemini extensions install https://github.com/Fatboy-coder/ppgp --auto-update

Repository structure is ready; a local Gemini CLI smoke test remains external.

Cursor

PPGP exposes the open Agent Plugins format at repository root:

plugin.json

The manifest remains schema-safe and co-located with canonical skills/ppgp/ content. A separate .cursor-plugin/plugin.json is intentionally not added in v0.1.2 because PPGP currently needs only skills and the portable Agent Plugin format covers the intended distribution surface.

Cursor Marketplace publication is an external submission step and is not claimed as complete.

GitHub Copilot

GitHub Copilot supports Agent Skills from .agents/skills/ in repository scope. PPGP therefore commits a generated compatibility mirror:

.agents/skills/ppgp/

This mirror is not authoritative. Tests enforce byte-for-byte parity with skills/ppgp/.

Windsurf

Windsurf recognizes .agents/skills/ as a cross-agent compatibility path. The generated PPGP mirror provides repository-native discovery without a Windsurf-specific semantic copy.

Devin

Devin supports the open Agent Skills convention and repository skills under .agents/skills/. The generated PPGP mirror provides repository-native discovery.

Kiro

Use the canonical public skill source:

https://github.com/Fatboy-coder/ppgp/tree/main/skills/ppgp

No Kiro-specific semantic copy is maintained.

Cline

Use the canonical PPGP skill and install/copy it into a supported Cline skills location, or use a generic Agent Skills installer where available.

No Cline-specific semantic adapter is maintained.

JetBrains Junie

PPGP remains consumable from the canonical skill through Junie's supported project/user skill import locations.

No Junie-specific semantic adapter is maintained.

Secondary-platform policy

For Roo Code, Amazon Q Developer and other agent platforms, PPGP only adds a native adapter after the platform exposes a stable, documented mechanism that can be tested without forking protocol semantics.

Until then, the canonical Agent Skill and CLI remain available, and COMPATIBILITY.md records the exact current support state rather than inventing proprietary files.

GitHub Release

Purpose: zero-friction download of the installable Agent Skill archive.

Current canonical asset:

ppgp-v0.1.2.zip

Each release also publishes a SHA-256 checksum next to the archive. Older release assets remain historical artifacts and are not the canonical download for the current release.

npm

Purpose: public CLI discovery and zero-install execution.

Canonical public package name:

@fatboy-coder/ppgp

Current package release:

@fatboy-coder/ppgp@0.1.2

The original unscoped name ppgp is intentionally not used because npm's similarity protection rejects it as too close to existing high-traffic package names.

CLI binary:

ppgp

Zero-install examples:

npx @fatboy-coder/ppgp init
npx @fatboy-coder/ppgp doctor
npx @fatboy-coder/ppgp goal "Ship the next verified milestone"
npx @fatboy-coder/ppgp status
npx @fatboy-coder/ppgp handoff

When diagnosing npx executable inference or npm cache behavior, the explicit npm-exec form removes ambiguity about which binary must run:

npm exec --yes --package=@fatboy-coder/ppgp@0.1.2 -- ppgp --version

On Windows PowerShell, some npm versions can route npm through the npm.ps1 wrapper and mis-handle forwarded arguments. If the command above prints the npm version instead of the PPGP version, bypass the wrapper explicitly:

npm.cmd exec --yes --package=@fatboy-coder/ppgp@0.1.2 -- ppgp --version

Expected output:

0.1.2

This is a shell-wrapper issue, not evidence that the PPGP package lacks its CLI binary. PPGP CI packs and installs the package on Windows and verifies the generated ppgp.cmd shim by executing ppgp --version.

A plain ppgp command is expected only after the package has been installed globally or linked for local development:

npm install -g @fatboy-coder/ppgp@0.1.2
ppgp --version

Inside the PPGP source repository itself, the source CLI can always be tested directly without any installation:

node ./bin/ppgp.js --version

The npm package bundles the canonical Agent Skill, benchmark protocol, deterministic benchmark reporter and Pilot 01 preparation tooling. Platform adapter manifests remain excluded from the npm payload because they are repository distribution surfaces rather than CLI package contents.

npm Trusted Publisher

The package is published through GitHub Actions using npm Trusted Publishing/OIDC. The workflow is .github/workflows/publish-npm.yml.

Long-lived npm automation tokens are not required when trusted publishing is correctly configured.

GitHub Packages

Purpose: package presence inside GitHub associated with the repository.

Published package name:

@fatboy-coder/ppgp

The GitHub package is produced from the same source package contents and published to GitHub's npm registry.

GitHub Packages is a secondary distribution surface. GitHub Release and npmjs.com remain the lower-friction universal entry points.

Release automation

A release decision begins with one guarded manual workflow:

Publish PPGP release
        ↓ workflow_run
Publish PPGP to npm
        ↓ workflow_run
Publish PPGP to GitHub Packages

The release workflow validates that the requested version exactly matches the committed package.json version before creating the immutable tag and GitHub Release. Downstream package workflows re-check the canonical GitHub Release and package version before publishing.

Manual recovery dispatches exist for downstream publication if an already-created release needs to be republished to a package registry after an infrastructure failure.

Validation

npm test validates the CLI, package contents and distribution invariants, including:

  • canonical skill and compact reference exist;
  • Claude, Codex, Agent Plugin and Gemini manifests parse correctly;
  • every versioned adapter matches the committed package.json version;
  • marketplace identities point to ppgp;
  • the Codex manifest points to the canonical ./skills/ directory;
  • the root Agent Plugin manifest remains schema-safe;
  • .agents/skills/ppgp/ and plugins/ppgp/skills/ppgp/ remain byte-identical to the canonical skill and reference;
  • platform adapter directories do not silently enter the npm package contents;
  • public current-version documentation, citation metadata and CLI protocol headers remain aligned with the committed package version.

GitHub Actions runs the test suite on Linux and Windows and includes an installed-package CLI smoke test that verifies the platform-specific ppgp binary shim after packing and installing the package.

Version mapping

PPGP v0.1.2 uses one canonical current release version across the protocol specification and versioned distribution artifacts:

PPGP specification 0.1.2
npm package @fatboy-coder/ppgp@0.1.2
GitHub package @fatboy-coder/ppgp@0.1.2
Codex/Gemini/Agent Plugin adapters 0.1.2
Agent Skill metadata 0.1.2
GitHub release v0.1.2

Claude's repository-backed plugin manifest intentionally does not pin a static version because client refresh follows repository revisions. This is an adapter caching policy, not a second PPGP version.

Historical release numbers remain in CHANGELOG.md and publication history only. Benchmark result-schema versions are independently labeled as schema versions and are not PPGP release versions.