Build Your Registry¶

PromptScript supports registries - collections of reusable configurations that can be inherited across projects. Each organization creates and manages their own registry, giving full control over AI instruction standards.

Quick Start¶

1. Create a Registry¶

prs registry init my-company-registry

This scaffolds a complete registry with starter configurations. See Creating a Registry for details.

2. Configure Your Project¶

Add to your promptscript.yaml:

registry:
  git:
    url: https://github.com/your-org/your-registry.git
    ref: main # Or pin to version: v1.0.0

2. Inherit Configurations¶

@meta {
  id: "my-project"
  syntax: "1.0.0"
}

@inherit @stacks/react
@use @fragments/testing

3. Compile¶

prs compile  # Automatically fetches registry and generates output

Note: When using a Git registry, the CLI automatically clones and caches the repository. You don't need to run prs pull separately - the compile and validate commands handle this automatically.

The registry is cached at ~/.promptscript/.cache/git/ with a default TTL of 1 hour. Use prs pull --refresh to force an update.

Using `prs init`¶

The prs init command can connect to your registry and suggest configurations:

prs init

It will:

Detect your tech stack (React, Node, Python, etc.)
Offer to connect to a Git or local registry
Suggest relevant configurations from your registry's catalog
Generate your promptscript.yaml and .promptscript/project.prs

You can also set a default registry via user-level config so prs init --yes automatically uses it.

Usage Patterns¶

Pattern 1: Inherit a Tech Stack¶

@meta { id: "react-app" syntax: "1.0.0" }

@inherit @stacks/react

Pattern 2: Mix in Fragments¶

@meta { id: "secure-app" syntax: "1.0.0" }

@inherit @stacks/node
@use @fragments/testing
@use @fragments/security/owasp-security-review

Pattern 3: Use Prompts Directly¶

@meta { id: "terminal" syntax: "1.0.0" }

@inherit @prompts/coding/linux-terminal

How Git Registry Resolution Works¶

When you configure a Git registry, the CLI handles everything automatically:

On first use: The registry is cloned to ~/.promptscript/.cache/git/<hash>/
On subsequent uses: The cached version is used if not stale (default: 1 hour TTL)
On cache expiry: The registry is updated with git fetch

prs init --yes
    ↓
Creates config with registry.git.url

prs compile
    ↓
resolveRegistryPath() → checks cache validity
    ↓
If stale/missing: GitRegistry.fetch() → clone/update
    ↓
Compiler uses cached registry path

Cache Configuration¶

Control caching behavior in promptscript.yaml:

registry:
  git:
    url: https://github.com/your-org/your-registry.git
    ref: main
  cache:
    enabled: true # Set to false to always fetch
    ttl: 3600000 # Cache TTL in ms (default: 1 hour)

Force Refresh¶

prs pull --refresh  # Force re-clone the registry

Version Pinning¶

Pin to a specific version for stability:

registry:
  git:
    ref: v1.0.0

Or in .prs files:

@inherit @stacks/react@1.0.0

Creating a Registry¶

Use the prs registry init command to scaffold a new registry:

prs registry init my-registry

This creates the full directory structure, manifest, and optional seed configurations.

Interactive Mode¶

prs registry init my-registry
# Prompts for: name, description, namespaces, seed configs

Non-Interactive Mode¶

prs registry init my-registry --yes --name "My Company Registry" --namespaces @core @stacks @fragments

Skip Seed Configs¶

prs registry init my-registry --no-seed

Registry Structure¶

my-registry/
├── registry-manifest.yaml    # Catalog of all configurations
├── @core/
│   └── base.prs
├── @roles/
│   └── developer/
│       └── fullstack.prs
├── @stacks/
│   └── react.prs
└── @fragments/
    └── testing.prs

Registry Manifest¶

The registry-manifest.yaml file catalogs all configurations and enables prs init suggestions:

version: '1'

meta:
  name: 'My Company Registry'
  description: 'Internal AI instruction configurations'
  lastUpdated: '2025-01-28'

namespaces:
  '@core':
    description: 'Universal foundations'
    priority: 100
  '@roles':
    description: 'AI personas'
    priority: 90
  '@stacks':
    description: 'Tech stack configurations'
    priority: 80
  '@fragments':
    description: 'Reusable mixins'
    priority: 70

catalog:
  - id: '@core/base'
    path: '@core/base.prs'
    name: 'Base Foundation'
    description: 'Universal AI assistant foundation'
    tags: [core, foundation]
    targets: [github, claude, cursor]
    dependencies: []
    detectionHints:
      always: true

  - id: '@stacks/react'
    path: '@stacks/react.prs'
    name: 'React Stack'
    description: 'React + TypeScript configuration'
    tags: [react, typescript, frontend]
    targets: [github, claude, cursor]
    dependencies: ['@core/base']
    detectionHints:
      dependencies: ['react', 'react-dom']
      frameworks: ['react', 'nextjs']

suggestionRules:
  - condition: { always: true }
    suggest: { inherit: '@core/base' }
  - condition: { frameworks: ['react'] }
    suggest: { inherit: '@stacks/react', use: ['@fragments/testing'] }

Manifest Fields¶

`catalog` Entry Fields¶

Field	Required	Description
`id`	Yes	Unique ID matching file path
`path`	Yes	Path to the `.prs` file
`name`	Yes	Human-readable name
`description`	Yes	Brief description
`tags`	Yes	Searchable tags
`targets`	No	Supported targets (github, claude, etc.)
`dependencies`	No	Required configurations
`detectionHints`	No	Auto-suggestion hints (see below)

`detectionHints` Fields¶

Field	Description
`always`	Always suggest this configuration
`files`	Suggest if these files exist
`dependencies`	Suggest if package.json has these dependencies
`languages`	Suggest for these languages
`frameworks`	Suggest for these frameworks

Using Your Registry¶

Git Registry¶

Host on GitHub, GitLab, or any Git provider:

registry:
  git:
    url: https://github.com/your-org/your-registry.git
    ref: main

Local Registry¶

For development or air-gapped environments:

registry:
  path: ./path/to/registry

Validating a Registry¶

Use prs registry validate to check your registry structure:

prs registry validate ./my-registry

Validation checks:

registry-manifest.yaml exists and parses correctly
Manifest schema is valid (version, meta, namespaces, catalog)
All catalog entry .prs files exist
Catalog IDs match declared namespaces
No circular dependencies
Warns about orphaned .prs files not in catalog

Use --strict to treat warnings as errors:

prs registry validate ./my-registry --strict

Use --format json for machine-readable output:

prs registry validate ./my-registry --format json

Publishing a Registry¶

Use prs registry publish to commit and push registry updates:

prs registry publish ./my-registry

This will:

Validate the registry (use --force to skip)
Update meta.lastUpdated in the manifest
Stage, commit, and push changes

Options:

prs registry publish ./my-registry --dry-run              # Preview without publishing
prs registry publish ./my-registry -m "Add React stack"    # Custom commit message
prs registry publish ./my-registry --tag v1.0.0            # Tag the release
prs registry publish ./my-registry --force                 # Skip validation

CI/CD Integration¶

Add registry validation to your CI pipeline:

# .github/workflows/registry.yml
name: Registry CI
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @promptscript/cli
      - run: prs registry validate --strict

Next Steps¶

Enterprise Setup — Scale PromptScript across your organization
CI/CD Integration — Automate validation and compilation in your pipeline