Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- packages/webapp/src/app/blog/distributable-intelligence/page.tsx
- packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
- packages/webapp/src/app/blog/format-specifications-guide/page.tsx
- packages/converters/schemas/README.md
- packages/cli/src/commands/init.ts
- packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
- packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
- packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
- public-documentation/mint.json
- packages/converters/src/tests/from-agents-md.test.ts
The prpm (Prompt Package Manager) project is an ecosystem designed to address the fragmentation of prompt and configuration formats across various AI coding assistants. Its core architectural principle is to provide "distributable intelligence" by enabling developers to author, publish, and consume AI-guiding packages (rules, skills, agents) in a universal, tool-agnostic manner. The system is built around a central registry, a powerful CLI, a web interface with a testing playground, and a sophisticated format conversion engine.
The primary goal is to allow authors to publish a package once, and for users to install it in any supported AI IDE, with prpm handling the necessary format conversions automatically. This closes the gap between traditional documentation and codemods by shipping executable knowledge that AI assistants can use to perform context-aware refactoring, migrations, and code generation.
Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx, packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
Core Components
The prpm ecosystem is composed of several key components that work together to provide a seamless experience for both package authors and consumers.
| Component | Description |
|---|---|
CLI (prpm) | The primary interface for developers. Handles package installation, publishing, initialization, search, and local testing via the playground. |
| Web Application | A Next.js application that provides a web-based interface to the ecosystem, including a package registry, search, user accounts, a testing playground, and a blog. |
| Format Converters | A crucial backend system that handles the logic for converting between the various supported AI IDE formats. It uses JSON schemas for validation. |
| Package Registry | The central repository where all prpm packages are stored. It manages package metadata, versions, and analytics. |
| Documentation Site | A documentation portal built with Mintlify, providing guides, API references, and core concepts for users. |
Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx, public-documentation/mint.json
The following diagram illustrates the high-level interaction between these components.
Universal Package and Format Support
A fundamental architectural challenge prpm solves is the proliferation of proprietary formats for AI coding tools. Each tool (Cursor, Claude, GitHub Copilot, etc.) has its own way of defining rules and instructions. prpm abstracts this complexity by supporting multiple formats and converting between them.
Sources: packages/webapp/src/app/blog/format-specifications-guide/page.tsx
Supported Formats
The system is designed to be extensible, currently supporting a wide range of popular AI IDE formats.
| Format | File Location / Structure | Frontmatter | Key Feature |
|---|---|---|---|
| agents.md | AGENTS.md | None | Open standard, plain markdown, tool-agnostic. |
| Cursor | .cursor/rules/ | Required | Four rule types (Always Apply, Intelligent, etc.). |
| Claude Code | .claude/{agents,skills,commands}/ | Required | Granular control with allowed-tools and model selection. |
| GitHub Copilot | .github/copilot-instructions.md | Optional | Two-tier system (repo-wide and path-specific). |
| Windsurf | .windsurf/rules | None | Radically simple, single file with a 12k character limit. |
| Kiro | .kiro/steering/*.md | Optional | Domain-organized files with "inclusion modes". |
| Continue | .continue/rules/*.md | Required | Supports globs and content-matching regex. |
Sources: packages/webapp/src/app/blog/format-specifications-guide/page.tsx, packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/windsurf-deep-dive/page.tsx, packages/webapp/src/app/blog/kiro-deep-dive/page.tsx, packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
The agents.md Standard
prpm places special emphasis on agents.md as an open, tool-agnostic standard for providing project-specific guidance. It was created through a collaboration involving OpenAI and Google.
Key Characteristics:
- Simplicity: It is a single, plain markdown file with no required directory structure, special syntax, or frontmatter.
- Cross-Tool Compatibility: It is supported by major tools like OpenAI Codex, GitHub Copilot, and Google Gemini Code Assist, making it a neutral choice to avoid vendor lock-in.
- Hierarchical System (Codex Extension): OpenAI Codex extends the standard by allowing a hierarchy of files. It merges
AGENTS.mdfiles from the current directory up to the root, and anAGENTS.override.mdfile can be used to replace all parent instructions, which is useful in monorepos.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
Format Conversion System
The centerpiece of the prpm architecture is its format conversion engine. This system allows a package published in one format (e.g., Cursor) to be installed for use in another tool (e.g., Claude).
Schema-Driven Validation
The conversion process is underpinned by a set of JSON Schemas, one for each supported format. These schemas serve multiple purposes:
- Validation: They are used to validate packages at publish time and to verify that converted output is valid for the target format.
- Documentation: They act as the source of truth for auto-generating format specifications.
- IDE Support: They can provide autocomplete and validation within code editors.
Sources: packages/converters/schemas/README.md, packages/webapp/src/app/blog/format-specifications-guide/page.tsx
Canonical Format and Conversion Flow
To avoid a mesh of N-to-N converters, prpm uses a universal internal representation known as the Canonical Format. The conversion process is a two-step flow: the source package is first parsed into the canonical format, and then generated into the target format. This simplifies the architecture, as adding a new format only requires creating two converters (New Format -> Canonical and Canonical -> New Format).
The diagram below shows the conversion flow when a user installs a package.
CLI Architecture: The init Command
The prpm init command exemplifies the CLI's user-centric design. It supports two primary modes for initializing a prpm.json manifest file.
Classic Wizard vs. Smart Init
- Classic Wizard: An interactive prompt-based workflow that guides the user through creating a
prpm.jsonfile from scratch. It asks for package name, format, author, etc., and can scaffold example files. This is the fallback when no existing packages are detected. - Smart Init: A more advanced mode that scans the current directory for existing AI rule/prompt files. It automatically detects their format, subtype, and metadata. It can then reconcile these detected packages with an existing
prpm.jsonor generate a new one.
Sources: packages/cli/src/commands/init.ts:470-476, packages/cli/src/commands/init.ts:600-606
Package Reconciliation Logic
The "smart init" feature includes a reconciliation process that compares packages found on disk with those defined in prpm.json. It categorizes packages into three groups:
- In Sync: Packages present in both
prpm.jsonand on disk. - New: Packages found on disk but not in
prpm.json. - Missing: Packages in
prpm.jsonbut not found on disk.
The user is then prompted to review these changes and can choose to add new packages or remove stale entries from the manifest.
The following diagram illustrates the smart initialization and reconciliation flow.
Conclusion
The architecture of prpm is a direct response to the fragmented and rapidly evolving landscape of AI-assisted development tools. By establishing a centralized registry, a powerful conversion engine based on a canonical format, and user-friendly tooling like the CLI and web playground, prpm successfully creates a universal platform. Its support for open standards like agents.md and composable tools further reinforces its philosophy of interoperability over native integration. This enables the core vision of "distributable intelligence," where expert knowledge can be packaged and shared for any AI assistant to consume, ultimately making large-scale migrations and adherence to coding standards more automated and reliable.
Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx, packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx