prpm-development

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.

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:

```bash

git checkout -b feature/your-feature-name

# or

git checkout -b fix/bug-description

```

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

```bash

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:

```bash

# ❌ 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"

```

1. Push your branch:

```bash

git push origin feature/your-feature-name

```

1. Create a Pull Request on GitHub:

- Automated CI tests run

- Code review happens

- Deployments are controlled

1. 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).

🎓 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/

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 are curated bundles of packages that solve specific use cases.

Collection Structure

```json

{

"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}

```bash

prpm install collections/nextjs-pro

prpm install collections/nextjs-pro@2.0.0

```

• 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}

```bash

prpm install khaliqgant/nextjs-pro

prpm install @khaliqgant/nextjs-pro

prpm install khaliqgant/nextjs-pro@2.0.0

```

• 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)

```bash

prpm install nextjs-pro

prpm install nextjs-pro@1.0.0

```

• 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

```typescript

// 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

```typescript

// 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:

```bash

# Latest version (default)

prpm install collections/nextjs-pro

# Specific version

prpm install collections/nextjs-pro@2.0.4

# With scope and version

prpm install khaliqgant/nextjs-pro@2.0.4

```

Registry Behavior:

• Without version: Returns latest (most recent created_at)
• With version: Exact match required

#### Discovery Prioritization

When searching across all scopes (collections/* format), the system prioritizes:

1. Official Collections (official = true)

- Curated by PRPM maintainers

- Highest trust level

1. Verified Authors (verified = true)

- Known community contributors

- GitHub verified

1. Download Count (downloads DESC)

- Most popular collections

- Community validation

1. Recency (created_at DESC)

- Latest versions

- Actively maintained

#### Error Handling

Collection Not Found:

```bash

prpm install collections/nonexistent

# ❌ Failed to install collection: Collection not found

```

Scope-Specific Not Found:

```bash

prpm install wrongscope/nextjs-pro

# ❌ Failed to install collection: Collection not found

# Suggestion: Try 'collections/nextjs-pro' to search all scopes

```

Collection Best Practices

1. Required vs Optional: Clearly mark essential vs nice-to-have packages
2. Reason Documentation: Every package explains why it's included
3. IDE-Specific Variants: Different packages per editor when needed
4. Installation Order: Consider dependencies
5. Scope Naming:

- Use your username/org as scope for personal collections

- Reserve "collection" scope for official PRPM collections

1. User-Friendly IDs: Use descriptive slugs (e.g., "nextjs-pro" not "np-setup")
2. Version Incrementing: Bump versions on meaningful changes (follow semver)

Multi-Factor Scoring (0-100)

Popularity (0-30 points):

• Total downloads (weighted by recency)
• Stars/favorites
• Trending velocity

Quality (0-30 points):

• User ratings (1-5 stars)
• Review sentiment
• Documentation completeness

Trust (0-20 points):

• Verified author badge
• Original creator vs fork
• Publisher reputation
• Security scan results

Recency (0-10 points):

• Last updated date (<30 days = 10 points)
• Release frequency
• Active maintenance

Completeness (0-10 points):

• Has README
• Has examples
• Has tags
• Complete metadata

CLI (TypeScript + Node.js)

• Commander.js: CLI framework
• Fastify Client: HTTP client for registry
• Tar: Package tarball creation/extraction
• Chalk: Terminal colors
• Ora: Spinners for async operations

Registry (TypeScript + Fastify + PostgreSQL)

• Fastify: High-performance web framework
• PostgreSQL: Primary database with GIN indexes
• Redis: Caching layer for converted packages
• GitHub OAuth: Authentication provider
• Docker: Containerized deployment

Testing

• Vitest: Unit and integration tests
• 100% Coverage Goal: Especially for format converters
• Round-Trip Tests: Ensure conversion quality
• Fixtures: Real-world package examples

Test Pyramid

• 70% Unit Tests: Format converters, parsers, utilities
• 20% Integration Tests: API routes, database operations, CLI commands
• 10% E2E Tests: Full workflows (install, publish, search)

Coverage Goals

• Format Converters: 100% coverage (critical path)
• CLI Commands: 90% coverage
• API Routes: 85% coverage
• Utilities: 90% coverage

Key Testing Patterns

```typescript

// Format converter test

describe('toCursor', () => {

it('preserves data in roundtrip', () => {

const result = toCursor(canonical);

const back = fromCursor(result.content);

expect(back).toEqual(canonical);

});

});

// CLI command test

describe('install', () => {

it('downloads and installs package', async () => {

await handleInstall('test-pkg', { as: 'cursor' });

expect(fs.existsSync('.cursor/rules/test-pkg.md')).toBe(true);

});

});

```

Package Manager: npm (NOT pnpm)

⚠️ CRITICAL: PRPM uses npm, not pnpm ⚠️

• Lock file: package-lock.json (npm)
• Install dependencies: npm install
• Run scripts: npm run