Skip to content

Registry

Jump to bottom
github-actions[bot] edited this page Jun 11, 2026 · 10 revisions

Registry

The Community Rule Registry lets you install, share, and manage reusable rule packs published to npm.

Concepts

A rule pack is an npm package that bundles vendor-neutral rules, agents, and/or skills in the standard llm/ directory layout. Packs are installed into a local cache (.bluetemberg/packs/) and automatically included during sync — lower priority than local sources and extends entries.

Pack layout

A rule pack is any npm package containing an llm/ directory (or rules/agents/skills at the package root):

my-rules-pack/
  package.json          # must include "bluetemberg-pack" keyword for discovery
  llm/
    rules/
      typescript-strict.md
      no-any.md
    agents/
      reviewer.md

Manifest and lockfile

Two files track installed packs:

File Purpose Commit?
llm/packages.json Manifest — package names and semver ranges Yes
llm/packages-lock.json Lockfile — exact versions, tarball URLs, integrity hashes Yes

Both should be committed so the team pins the same versions.

One manifest covers all pack kinds — rules, agents, skills, and guardrails. A pack declares what it ships through its llm/ directory layout, so a single package can mix kinds (e.g. a framework pack with both rules and a skill).

Migrating from kind-split manifests: projects scaffolded before the unification may still have rule-packages.json, agent-packages.json, or skill-packages.json. They keep working — sync merges them in memory with a warning — and the next bluetemberg install (or add/update/remove) consolidates them into packages.json and deletes the legacy files. Commit the result.

Manifest format

{
  "registry": "https://registry.npmjs.org",
  "packages": {
    "@company/rules-frontend": "^1.2.0",
    "community-ts-rules": "~2.0.0"
  }
}
Field Required Description
registry No Custom npm registry URL. Defaults to https://registry.npmjs.org.
packages Yes Map of package name to semver range.

Lockfile format

{
  "lockfileVersion": 1,
  "packages": {
    "@company/rules-frontend": {
      "version": "1.2.3",
      "resolved": "https://registry.npmjs.org/@company/rules-frontend/-/rules-frontend-1.2.3.tgz",
      "integrity": "sha512-abc123..."
    }
  }
}

Commands

bluetemberg add <package>

Install a rule pack from the npm registry.

bluetemberg add @company/rules-frontend
bluetemberg add @company/rules-frontend@^1.2.0
bluetemberg add community-ts-rules@latest
bluetemberg add community-ts-rules --version "~2.0.0"

What it does:

  1. Fetches package metadata from the npm registry.
  2. Resolves the best version matching the requested range.
  3. Downloads and extracts the tarball to .bluetemberg/packs/<name>/<version>/.
  4. Verifies the SHA-512 integrity hash.
  5. Updates llm/packages.json and llm/packages-lock.json.
  6. Adds .bluetemberg/ to .gitignore if not already present.

After adding, run bluetemberg sync to generate platform-specific files that include the new rules.

Options:

Option Description
--version <range> Semver range (overrides @version in the package spec)
--silent Suppress all output

bluetemberg remove <package>

Remove a rule pack from the project.

bluetemberg remove @company/rules-frontend

Removes the package from the manifest, lockfile, and local cache.

Options:

Option Description
--silent Suppress all output

bluetemberg list

List all installed rule packs with their resolved versions.

bluetemberg list

Options:

Option Description
--silent Suppress all output

bluetemberg install

Install all packs from the manifest. Similar to npm ci — reads the manifest, uses locked versions when available, and downloads missing packs.

bluetemberg install
bluetemberg install --force

Run this after cloning a repo or when the lockfile has new entries from a teammate.

Options:

Option Description
--force Force re-download even if cached
--silent Suppress all output

bluetemberg update [package]

Re-resolve and upgrade rule packs to the best version satisfying their current manifest range.

bluetemberg update                  # re-resolves all manifest packs
bluetemberg update @company/rules   # re-resolves a single pack
bluetemberg update --latest         # widens all ranges to "latest" in the manifest

What it does (for each pack):

  1. Fetches the latest metadata from the registry.
  2. Resolves the best version satisfying the current range (or "latest" if --latest).
  3. Downloads and installs the new version if it differs from the locked one.
  4. Removes the previously cached version when the version changed.
  5. Updates llm/packages-lock.json (and llm/packages.json when --latest).
  6. Logs what changed (e.g. @company/rules 1.0.0 → 1.2.3).

After updating, run bluetemberg sync to apply the changes.

Options:

Option Description
--latest Widen each pack's range to "latest" in the manifest, not just re-resolve the current range
--silent Suppress all output

bluetemberg search <query>

Search the npm registry for rule packs. By default only returns packages with the bluetemberg-pack keyword.

bluetemberg search typescript
bluetemberg search frontend rules --limit 10

Options:

Option Description
--limit <n> Max results (default: 20)
--silent Suppress all output

Priority order

During sync, source directories are resolved in this priority (highest first):

  1. Local llm/ directory
  2. extends entries (in array order)
  3. Registry packs (in manifest order)

When the same rule filename appears in multiple sources, the higher-priority source wins. This means local rules always override pack rules, and you can selectively override individual rules from a pack.

Cache directory

Downloaded packs are extracted to .bluetemberg/packs/<name>/<version>/. This directory:

  • Should be added to .gitignore (done automatically on first add/install).
  • Can be deleted and restored via bluetemberg install.
  • Includes an integrity marker file (.bluetemberg-integrity) for cache validation.

Official packs

Bluetemberg's official packs live in prototypdigital/bluetemberg-packs and publish independently to npm. They cover rules, agents, and skills grouped by domain.

Rule packs

Package Domain
bluetemberg-rules-typescript TypeScript code quality
bluetemberg-rules-git Git workflow standards
bluetemberg-rules-security Security guardrails
bluetemberg-rules-docs Documentation & diagnostics
bluetemberg-rules-devops Infrastructure

Agent packs

Package Agent
bluetemberg-agents-frontend-specialist Frontend specialist
bluetemberg-agents-backend-specialist Backend specialist
bluetemberg-agents-test-specialist Test specialist
bluetemberg-agents-docs-maintainer Docs maintainer
bluetemberg-agents-code-reviewer Code reviewer
bluetemberg-agents-a11y-specialist Accessibility specialist
bluetemberg-agents-security-specialist Security specialist
bluetemberg-agents-infrastructure-specialist Infrastructure specialist
bluetemberg-agents-devops-specialist DevOps specialist
bluetemberg-agents-ansible-specialist Ansible specialist
bluetemberg-agents-kubernetes-specialist Kubernetes specialist
bluetemberg-agents-sre-specialist SRE specialist

Skill packs

Package Skill
bluetemberg-skills-patterns Patterns
bluetemberg-skills-docs-upkeep Docs upkeep
bluetemberg-skills-workspace-hygiene Workspace hygiene
bluetemberg-skills-react-patterns React patterns
bluetemberg-skills-code-review Code review
bluetemberg-skills-api-design API design
bluetemberg-skills-security-audit Security audit
bluetemberg-skills-ci-cd-best-practices CI/CD best practices
bluetemberg-skills-migration-safety Migration safety
bluetemberg-skills-stack-change-review Stack change review
bluetemberg-skills-infrastructure-drift-check Infrastructure drift check
bluetemberg-skills-rollback-plan Rollback plan

Guardrail packs

Package Guardrails
bluetemberg-guardrails-git Conventional branch names for AI-created worktrees

See Guardrails for the format and how they map to platform hooks.

For the full catalog, see the bluetemberg-packs wiki.

Using collections via init

When running bluetemberg init, select Rule collections (registry packages) as the rule source. The wizard will suggest collections based on your team profile and write a llm/packages.json manifest. Then run bluetemberg install to download the packages.

Using collections manually

bluetemberg add bluetemberg-rules-typescript
bluetemberg add bluetemberg-rules-git
bluetemberg install
bluetemberg sync

Local rules in llm/rules/ always take priority over collection rules, so you can override any rule by creating a file with the same name.

Publishing a rule pack

To publish your own rule pack:

  1. Create a standard npm package with an llm/ directory containing your rules, agents, and/or skills.
  2. Add "bluetemberg-pack" to the keywords array in package.json for discoverability.
  3. Publish to npm (or a private registry).
{
  "name": "@company/rules-frontend",
  "version": "1.0.0",
  "keywords": ["bluetemberg-pack", "rules", "frontend"],
  "files": ["llm/"]
}

Private registries

Set the registry field in llm/packages.json to use a private npm registry:

{
  "registry": "https://npm.pkg.github.com",
  "packages": {
    "@company/internal-rules": "^1.0.0"
  }
}

Programmatic API

All registry operations are available as named exports:

import {
  registryAdd,
  registryRemove,
  registryList,
  registryInstall,
  registryUpdate,
  registrySearch,
  resolvePackSourceDirs,
} from 'bluetemberg';

// Add a pack
await registryAdd('/path/to/project', 'my-rules@^1.0.0');

// Update all packs to the latest satisfying version
await registryUpdate('/path/to/project');

// Update a single pack
await registryUpdate('/path/to/project', '@company/rules');

// Widen all ranges to "latest"
await registryUpdate('/path/to/project', undefined, { latest: true });

// List installed packs
const packs = registryList('/path/to/project', { silent: true });

// Resolve pack source dirs for custom sync logic
const dirs = resolvePackSourceDirs('/path/to/project');

Clone this wiki locally