The prpm.json Manifest File

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/commands/init.ts
• CONTRIBUTING.md
• packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
• packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx
• packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx
• public-documentation/mint.json
• packages/converters/schemas/README.md

The prpm.json manifest is the central configuration file for a PRPM package. Analogous to package.json in the Node.js ecosystem, it defines the metadata, format, files, and other essential information required for publishing, installing, and managing AI prompts, rules, and agents. This file is the source of truth that powers PRPM's discovery, versioning, and cross-format conversion capabilities.

The manifest can define a single package, a multi-package collection within a single repository, or a collection of related packages. The structure of the manifest adapts based on the project's needs, but its primary role is to make AI-executable knowledge distributable and machine-readable.

Sources: CONTRIBUTING.md:12-14, packages/cli/src/commands/init.ts:31-33, packages/webapp/src/app/blog/distributable-intelligence/page.tsx:39-42, public-documentation/mint.json:63-67

Manifest Structures

PRPM supports three primary manifest structures: Single-Package, Multi-Package, and Collections. The prpm init command can automatically detect which structure to use.

Sources: packages/cli/src/commands/init.ts:511-514, CONTRIBUTING.md:43-45

Single-Package Manifest

This is the most common structure, used for publishing a single, self-contained package. It contains metadata for one set of prompt files.

{
  "name": "my-awesome-rule",
  "version": "1.0.0",
  "description": "A helpful Cursor rule for...",
  "format": "cursor",
  "subtype": "rule",
  "tags": ["typescript", "testing", "best-practices"],
  "author": "your-username",
  "license": "MIT",
  "files": ["./rule.md"]
}

Sources: CONTRIBUTING.md:16-28, packages/cli/src/commands/init.ts:742-763

The diagram below shows the relationship between a single-package manifest and its content file.

Multi-Package Manifest

For monorepos containing several distinct packages, a multi-package manifest can be used. It contains a top-level packages array, where each element is a single-package manifest object. The prpm init --scan command can automatically generate this structure.

{
  "name": "multi-package",
  "version": "1.0.0",
  "packages": [
    {
      "name": "typescript-best-practices",
      "version": "1.0.0",
      "description": "TypeScript coding standards",
      "format": "copilot",
      "subtype": "repository",
      "files": [".github/copilot-instructions.md"],
      "tags": ["typescript", "copilot"]
    },
    {
      "name": "react-component-patterns",
      "version": "1.0.0",
      "description": "Patterns for React components",
      "format": "cursor",
      "subtype": "rule",
      "files": [".cursor/rules/react-components.md"],
      "tags": ["react", "cursor"]
    }
  ]
}

Sources: packages/cli/src/commands/init.ts:912-921, 946-953

Collection Manifest

A collection bundles multiple, independent PRPM packages into a single installable unit. This is useful for creating complete workflow setups, such as a "Next.js Professional Setup". The manifest uses a packages array to list the package IDs and versions to include.

{
  "scope": "@collection",
  "id": "nextjs-pro",
  "name": "Next.js Professional Setup",
  "version": "1.0.0",
  "description": "Complete Next.js development environment",
  "category": "frontend",
  "packages": [
    {
      "id": "react-best-practices",
      "version": "^1.0.0",
      "required": true
    },
    {
      "id": "typescript-strict",
      "version": "^1.0.0",
      "required": true
    }
  ]
}

Sources: CONTRIBUTING.md:47-69, packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx:100-104

Manifest Fields

The following table details the core fields for a single-package manifest.

Field	Type	Required	Description
name	string	Yes	The unique name of the package.
version	string	Yes	The semantic version of the package (e.g., "1.0.0").
description	string	Yes	A brief, human-readable summary of the package's purpose.
format	string	Yes	The AI tool format (e.g., cursor, claude, copilot).
subtype	string	Yes	The specific type within the format (e.g., rule, skill, agent).
files	string[]	Yes	An array of file paths to the package's content, relative to prpm.json.
author	string	Yes	The name and optional email of the package author.
license	string	Yes	The license under which the package is distributed (e.g., "MIT").
tags	string[]	No	An array of keywords to aid in package discovery.
repository	string	No	The URL of the source code repository.

Sources: packages/cli/src/commands/init.ts:34-44, 742-763, CONTRIBUTING.md:16-28, packages/converters/schemas/README.md:29-39

Manifest Creation and Management

The prpm init command is the primary tool for creating and managing prpm.json files. It operates in two main modes: a classic interactive wizard and a "smart" scan-and-reconcile mode.

Sources: packages/cli/src/commands/init.ts:476-479, 995-1002

prpm init Workflow

The command first attempts a "smart init" by scanning for existing prompt files. If none are found, it falls back to the classic wizard.

Classic Wizard (classicInit)

When no existing packages are detected, prpm init launches an interactive wizard that prompts the user for all required metadata, such as package name, format, and files. It can pre-fill defaults by inspecting the git configuration for the author's name and email. It also generates example files and a README.md based on the chosen format.

Sources: packages/cli/src/commands/init.ts:696-702, 720-730, 810-819

Smart Init and Reconciliation (smartInit)

If prpm.json does not exist but prompt files are found on disk, "smart init" scans the project, detects packages, and proposes a new manifest. If prpm.json does exist, it performs a reconciliation process.

The reconciliation logic is as follows:

1. Scan: The scanForPackages function searches the filesystem for known prompt file structures (e.g., .cursor/rules, agents.md).
2. Read Manifest: The existing prpm.json is parsed.
3. Reconcile: The detected packages are compared against the packages listed in the manifest.
4. Categorize: Packages are categorized as:
   • inSync: Present in both the manifest and on disk.
   • newPackages: Present on disk but not in the manifest.
   • missingPackages: Present in the manifest but not found on disk.
5. User Review: The user is prompted to review the changes, with options to bulk-accept or review each new and missing package individually.
6. Update Manifest: A new prpm.json is written with the approved changes.

Sources: packages/cli/src/commands/init.ts:476-486, 500-503, 521-530

This sequence diagram illustrates the reconciliation flow.

Role in Publishing and Conversion

The prpm.json manifest is crucial for both publishing packages and enabling format conversions.

• Publishing: When prpm publish is run, the CLI reads prpm.json to get the package's metadata and file list. It validates the package against the corresponding JSON schema for the declared format and subtype before uploading it to the registry.
  Sources: packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:135-149, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:215-225

• Format Conversion: The format and subtype fields in the manifest tell PRPM how to parse the source files and how to convert them to a different target format when a user runs prpm install --as <format>. This allows authors to write a package once and have it work in any supported AI editor.
  Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx:44-53, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:64-79

Summary

The prpm.json file is the cornerstone of the PRPM ecosystem. It provides a structured, machine-readable definition of an AI package, containing all the metadata necessary for validation, publishing, discovery, and installation. Through its flexible support for single-package, multi-package, and collection structures, and its tight integration with the prpm init command, the manifest simplifies the process of creating and maintaining distributable AI knowledge. It is the key that unlocks PRPM's "write once, distribute everywhere" promise.

Sources: CONTRIBUTING.md:12-14, packages/cli/src/commands/init.ts, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:50-54