Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / plugin-manifest-validation

Plugin manifest validation

Plugin manifest validation keeps the Claude, Codex, Factory, and Qoder host descriptions aligned as one release. It checks shared package metadata and the shared package-root relationship so each host can use the same plugin content. See Plugin distribution for the wider distribution model and Plugin release automation for version changes.

Validation model

Validation treats the native host manifests as different views of one package. It checks package identity first, then confirms that the package version and host paths support one consistent release.

Package identity

The package identity is diagram-design in the Claude, Codex, Factory, and Qoder manifests. The shared fields describe one product and one release across hosts. Codex adds host-specific skills and interface data, while Qoder adds host-specific command and skill paths; these extensions do not change the shared identity.

References: .claude-plugin/plugin.json• L2-24 .codex-plugin/plugin.json• L2-47 .factory-plugin/plugin.json• L2-24 .qoder-plugin/plugin.json• L2-27

Version alignment

All four manifests carry the same package version, 2.6.168. The version identifies one plugin release across hosts, so a change in one manifest must not create a host-specific release view.

References: .claude-plugin/plugin.json• L2-4 .codex-plugin/plugin.json• L2-4 .factory-plugin/plugin.json• L2-4 .qoder-plugin/plugin.json• L2-4

Shared package root

Marketplace entries point each host at the repository package root. This shared root lets the hosts consume the same skills and commands instead of separate copies.

The root relationship also defines a trust boundary: host paths must stay inside the repository and resolve to the expected package content. Claude and Factory expose marketplace entries at ./; Qoder declares its commands and skills from that same root. Codex exposes its skills from the shared root and its interface assets from paths below it.

This diagram shows how host metadata and package paths combine into one distribution result.

flowchart TD
    A[Host manifests] --> B[Shared identity and version]
    C[Marketplace sources] --> D[Shared repository root]
    D --> E[Host skills commands and assets]
    B --> F[One plugin release]
    E --> F

References: .claude-plugin/marketplace.json• L9-14 .factory-plugin/marketplace.json• L3-8 .codex-plugin/plugin.json• L25-48 .qoder-plugin/plugin.json• L25-26

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the package identity and release version aligned across all four host manifests.
  • Keep marketplace sources and host resource paths within the same package root.
  • If a host path changes, confirm that the referenced skill, command, or asset still exists at the new location.
  • Preserve the distinction between shared package metadata and host-specific interface fields.
  • Keep the Claude and Factory marketplace sources pointed at the package root.

Important failure modes

TriggerConsequenceGuard
One host manifest changes shared identity or release dataHosts describe different plugin packagesCompare shared fields and versions across all host manifests
Host paths point outside the package root or to different contentA host can receive incomplete or unrelated plugin contentKeep marketplace and resource paths rooted in the repository package
A host resource path no longer matches its packaged fileInstallation or host loading fails for that capabilityCheck each declared skill, command, and asset path when it changes
Host-specific interface data is copied into shared identity fieldsOne host change creates an unintended package-wide changeKeep host extensions separate from shared metadata

Key files

FileWhy to read it
.claude-plugin/plugin.jsonDefines the shared package metadata for the Claude host.
.codex-plugin/plugin.jsonShows shared metadata plus Codex skills, interface data, and assets.
.factory-plugin/plugin.jsonDefines the Factory host view of the package.
.qoder-plugin/plugin.jsonShows Qoder command and skill paths rooted in the package.
.claude-plugin/marketplace.jsonShows the Claude marketplace source for the shared package root.
.factory-plugin/marketplace.jsonShows the Factory marketplace source for the shared package root.