prpm-development

PRPM Development Knowledge Base

Complete knowledge base for developing PRPM - the universal package manager for AI prompts, agents, and rules.

Mission

Build the npm/cargo/pip equivalent for AI development artifacts. Enable developers to discover, install, share, and manage prompts across Cursor, Claude Code, Continue, Windsurf, and future AI editors.

Core Architecture

Universal Format Philosophy

1. Canonical Format: All packages stored in normalized JSON structure
2. Smart Conversion: Server-side format conversion with quality scoring
3. Zero Lock-In: Users convert between any format without data loss
4. Format-Specific Optimization: IDE-specific variants (e.g., Claude with MCP)

Package Manager Best Practices

• Semantic Versioning: Strict semver for all packages
• Dependency Resolution: Smart conflict resolution like npm/cargo
• Lock Files: Reproducible installs (prpm-lock.json)
• Registry-First: All operations through central registry API
• Caching: Redis caching for converted packages (1-hour TTL)

Developer Experience

• One Command Install: prpm install @collection/nextjs-pro gets everything
• Auto-Detection: Detect IDE from directory structure (.cursor/, .claude/)
• Format Override: --as claude to force specific format
• Telemetry Opt-Out: Privacy-first with easy opt-out
• Beautiful CLI: Clear progress indicators and colored output

Git Workflow - CRITICAL RULES

⚠️ NEVER PUSH DIRECTLY TO MAIN ⚠️

PRPM uses a branch-based workflow with CI/CD automation. Direct pushes to main bypass all safety checks and can break production.

ALWAYS follow this workflow:

1. Create a branch for your changes:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/bug-description
   

2. Make commits on your branch using conventional commit format:

   git add [files]
   git commit -m "feat: add OpenCode format support"
   

Commit Message Format

Use conventional commit prefixes for all commits:

Prefix	Use For	Example
feat:	New features	feat: add Kiro format support
fix:	Bug fixes	fix: resolve publish timeout issue
docs:	Documentation	docs: update API reference
chore:	Maintenance	chore(release): publish packages
refactor:	Code refactoring	refactor: simplify converter logic
test:	Test changes	test: add roundtrip tests for Gemini
perf:	Performance	perf: optimize search query

Why this matters:

• Automated changelog generation
• Clear commit history
• Easier code review
• Semantic versioning automation

Bad commits to avoid:

# ❌ Too vague
git commit -m "fixes"
git commit -m "updates"
git commit -m "changes"

# ✅ Clear and descriptive
git commit -m "fix: resolve schema validation for Claude agents"
git commit -m "feat: add support for Droid format subtypes"

3. Push your branch:

   git push origin feature/your-feature-name
   

4. Create a Pull Request on GitHub:

   • Automated CI tests run
   • Code review happens
   • Deployments are controlled

5. After PR approval, merge through GitHub UI:

   • Triggers automated deployment
   • Ensures CI passes first
   • Maintains deployment history

Why this matters:

• Main branch is protected and deploys to production
• Direct pushes skip CI tests, linting, type checks
• Can deploy broken code to 7500+ package registry
• Breaks audit trail and rollback capability
• GitHub Actions workflows expect PRs, not direct pushes

If you accidentally pushed to main:

1. DO NOT force push to revert - breaks CI/CD
2. Create a revert commit on a branch
3. Open PR to fix the issue properly
4. Let CI/CD handle the corrective deployment

Exception: Only repository admins can push to main for emergency hotfixes (with explicit approval).

Package Types

🎓 Skill

Purpose: Knowledge and guidelines for AI assistants Location: .claude/skills/, .cursor/rules/ Examples: @prpm/pulumi-troubleshooting, @typescript/best-practices

🤖 Agent

Purpose: Autonomous AI agents for multi-step tasks Location: .claude/agents/, .cursor/agents/ Examples: @prpm/code-reviewer, @cursor/debugging-agent

📋 Rule

Purpose: Specific instructions or constraints for AI behavior Location: .cursor/rules/, .cursorrules Examples: @cursor/react-conventions, @cursor/test-first

🔌 Plugin

Purpose: Extensions that add functionality Location: .cursor/plugins/, .claude/plugins/

💬 Prompt

Purpose: Reusable prompt templates Location: .prompts/, project-specific directories

⚡ Workflow

Purpose: Multi-step automation workflows Location: .workflows/, .github/workflows/

🔧 Tool

Purpose: Executable utilities and scripts Location: scripts/, tools/, .bin/

📄 Template

Purpose: Reusable file and project templates Location: templates/, project-specific directories

🔗 MCP Server

Purpose: Model Context Protocol servers Location: .mcp/servers/

Format Conversion System

Supported Formats

Cursor (.mdc)

• MDC frontmatter with ruleType, alwaysApply, description
• Markdown body
• Simple, focused on coding rules
• No structured tools/persona definitions

Claude (agent format)

• YAML frontmatter: name, description
• Optional: tools (comma-separated), model (sonnet/opus/haiku/inherit)
• Markdown body
• Supports persona, examples, instructions

Continue (JSON)

• JSON configuration
• Simple prompts, context rules
• Limited metadata support

Windsurf

• Similar to Cursor
• Markdown-based
• Basic structure

Conversion Quality Scoring (0-100)

Start at 100 points, deduct for lossy conversions:

• Missing tools: -10 points
• Missing persona: -5 points
• Missing examples: -5 points
• Unsupported sections: -10 points each
• Format-specific features lost: -5 points

Lossless vs Lossy Conversions

• Canonical ↔ Claude: Nearly lossless (95-100%)
• Canonical ↔ Cursor: Lossy on tools/persona (70-85%)
• Canonical ↔ Continue: Most lossy (60-75%)

Collections System

Collections are curated bundles of packages that solve specific use cases.

Collection Structure

{
  "id": "@collection/nextjs-pro",
  "name": "Next.js Professional Setup",
  "description": "Complete Next.js development setup",
  "category": "frontend",
  "packages": [
    {
      "packageId": "react-best-practices",
      "required": true,
      "reason": "Core React patterns"
    },
    {
      "packageId": "typescript-strict",
      "required": true,
      "reason": "Type safety"
    },
    {
      "packageId": "tailwind-helper",
      "required": false,
      "reason": "Styling utilities"
    }
  ]
}

Collection Installation Behavior

Collections can be installed using multiple identifier formats. The system intelligently resolves collections based on the format provided.

Installation Formats (Priority Order)

1. Recommended Format: collections/{slug}

prpm install collections/nextjs-pro
prpm install collections/[email protected]

• Behavior: Searches across ALL scopes for name_slug = "nextjs-pro"
• Resolution: Prioritizes by official → verified → downloads → created_at
• Use Case: User-friendly format for discovering popular collections
• Example: Finds khaliqgant/nextjs-pro even when searching collections/nextjs-pro

2. Explicit Scope: {scope}/{slug} or @{scope}/{slug}

prpm install khaliqgant/nextjs-pro
prpm install @khaliqgant/nextjs-pro
prpm install khaliqgant/[email protected]

• Behavior: Searches for specific scope and name_slug combination
• Resolution: Exact match only within that scope
• Use Case: Installing a specific author's version when multiple exist
• Example: Gets specifically the collection published by khaliqgant

3. Name-Only Format: {slug} (Legacy/Fallback)

prpm install nextjs-pro
prpm install [email protected]

• Behavior: Defaults to scope = "collection", then falls back to cross-scope search
• Resolution: First tries scope="collection", then searches all scopes
• Use Case: Quick installs when collection origin doesn't matter
• Recommendation: Prefer collections/{slug} for clarity

Registry Resolution Logic

Implementation Location: app/packages/registry/src/routes/collections.ts:485-519

// When scope is 'collection' (default from CLI for collections/* prefix):
if (scope === 'collection') {
  // Search across ALL scopes, prioritize by:
  // 1. Official collections (official = true)
  // 2. Verified authors (verified = true)
  // 3. Most downloads
  // 4. Most recent
  SELECT * FROM collections
  WHERE name_slug = $1
  ORDER BY official DESC, verified DESC, downloads DESC, created_at DESC
  LIMIT 1
} else {
  // Explicit scope: exact match only
  SELECT * FROM collections
  WHERE scope = $1 AND name_slug = $2
  ORDER BY created_at DESC
  LIMIT 1
}

CLI Resolution Logic

Implementation Location: app/packages/cli/src/commands/collections.ts:487-504

// Parse collection spec:
// - collections/nextjs-pro → scope='collection', name_slug='nextjs-pro'
// - khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'
// - @khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'
// - nextjs-pro → scope='collection', name_slug='nextjs-pro'

const matchWithScope = collectionSpec.match(/^@?([^/]+)\/([^/@]+)(?:@(.+))?$/);
if (matchWithScope) {
  [, scope, name_slug, version] = matchWithScope;
} else {
  // No scope: default to 'collection'
  [, name_slug, version] = collectionSpec.match(/^([^/@]+)(?:@(.+))?$/);
  scope = 'collection';
}

Version Resolution

Collections support semantic versioning:

# Latest version

---

*Content truncated.*