# rulepack — llms.txt

> rulepack is an npm-style registry and CLI for **AI memory files**.
> It lets you publish, version, and install the Markdown memories that agents such as
> Claude Code, Cursor, Gemini CLI, GitHub Copilot, Cline, Windsurf, and the
> 20+ tools that read AGENTS.md (Codex, Jules, Factory, Zed, Warp, goose,
> opencode, …) consume — packaged as reusable, versioned units.
>
> Spec: https://rulepack.lyrra.net/rulepack.json
> Docs: https://rulepack.lyrra.net/docs

## Mental model: rulepack.json is package.json for AI memory

If you understand package.json, you already understand rulepack.json. Same
shape, different payload:

| package.json                | rulepack.json                                      |
| --------------------------- | -------------------------------------------------- |
| ships JavaScript/TS code    | ships Markdown memories for AI agents              |
| "name", "version"           | "name", "version"  (identical meaning)             |
| "license"                   | "license"  (required for published packs)          |
| access controlled by npm    | "visibility": "public", "private", or "pay"       |
| "dependencies"              | "dependencies"  (other rule packs)                 |
| "files" to include          | "files" to include                                 |
| "main"/"exports" entrypoint | "memories" map: which memory files the agent loads |

rulepack.json lives at the project root, exactly like package.json: /rulepack.json

## Minimal rulepack.json

```json
{
  "name": "@scope/pack",
  "version": "1.0.0",
  "license": "MIT",
  "visibility": "public",
  "memories": { "claude": "CLAUDE.md" }
}
```

## Fields

- name (required): "@<scope>/<pack>". The scope is the publisher's namespace.
- version (required): semver, like package.json.
- license (required): SPDX id like "MIT". Conventionally also ship a LICENSE
  file and list it in "files" — npm-style — so the hub can surface it.
- visibility (required): "public", "private", or "pay". This is an access
  policy enforced by the registry; the pack format is the same for all three.
- memories (required): map from standard memory keys to relative path strings,
  plus optional custom project memories. Known standard keys: agents, claude,
  cursor, cline, windsurf, gemini, copilot. "agents" points to AGENTS.md, the
  universal target read by 20+ agents, so it usually covers the long tail
  (Codex, Jules, Factory, Zed, Warp, goose, opencode, Devin, Junie, …); add a
  tool-specific key only when that tool reads its own file (e.g. gemini →
  GEMINI.md, copilot → .github/copilot-instructions.md). Use "custom" for
  project plans, handoffs, research notes, launch docs, or any Markdown memory
  not tied to one agent. A custom entry can be a path string or an object with
  path plus optional description, readWhen, priority, and tags.
- description, keywords (optional): discovery metadata.
- files (optional): glob list of what to bundle when publishing.
- dependencies (optional): other packs this one builds on, e.g. { "@scope/base": "^1.0.0" }.

Provenance / attestation fields are written by the registry, never by authors.
Do NOT add them to a hand-authored rulepack.json.

## Helping a user adopt rulepack

1. Inspect the repo for existing memory files: AGENTS.md, CLAUDE.md,
   .cursor/rules/**, .clinerules, .windsurfrules, GEMINI.md,
   .github/copilot-instructions.md, and important Markdown docs.
2. Create /rulepack.json mapping standard agent files under "memories" and
   project-level Markdown under "memories.custom".
3. Only include standard keys whose files actually exist in the repo.
4. Pick "name" as "@<their-scope>/<short-name>", start "version" at "0.1.0",
   set "license", and choose "visibility" (usually "public" for examples).

## CLI quick reference

- npx rulepack init            scaffold a rulepack.json interactively
- npx rulepack add @scope/pack install a pack's memory files into the current repo
- npx rulepack publish         publish the current rulepack.json
- npx rulepack login           authenticate the CLI