gitmost/agent-roles-catalog/README.md

Agent roles catalog

This directory is data, not application code. It holds the content of an "agent roles catalog": reusable agent role definitions (system prompts plus a little metadata), grouped into bundles and translated into one or more languages. A separate server reads these files and serves them; nothing here is executable application logic except the validation script.

File layout

agent-roles-catalog/
  index.json                  # the catalog manifest: bundles, languages, role versions
  bundles/
    <bundle-id>/
      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
  scripts/
    check.mjs                 # validates the catalog (no dependencies)
  package.json                # defines the `check` script
  README.md

Currently shipped bundles:

• editorial — the editorial suite (structural-editor, line-editor, copy-editor, fact-checker, proofreader, narrator), languages ru, en.
• research — a single researcher role, languages ru, en.

How it's served

The server does not bundle this data; it reads it at request time from a single configured location, the AI_AGENT_ROLES_CATALOG_URL env var (EnvironmentService.getAiAgentRolesCatalogSource()). The value selects one of three sources:

• http(s)://… — a REMOTE base URL. The server fetches <base>/index.json for the manifest and <base>/bundles/<bundle-id>/<lang>.json for each opened bundle file (e.g. the raw GitHub base of the catalog repo in production).
• any other non-empty value — a LOCAL filesystem directory; the same index.json / bundles/<id>/<lang>.json paths are read from disk.
• empty / unset (the default) — the in-repo agent-roles-catalog/ folder (this directory), i.e. local dev reads these files directly.

In every case the layout below is what the server expects, and the fetched JSON is re-validated server-side (the catalog is treated as untrusted input). See .env.example for the variable and the CHANGELOG for the rollout.

index.json schema

{
  "schemaVersion": 1,
  "bundles": [
    {
      "id": "editorial",                       // unique bundle id; matches bundles/<id>/
      "name": { "ru": "...", "en": "..." },    // localized display name
      "description": { "ru": "...", "en": "..." },
      "languages": ["ru", "en"],               // which <lang>.json files must exist
      "roles": [
        { "slug": "structural-editor", "version": 1 }
        // ...
      ]
    }
  ]
}

version lives here, in index.json, per role. Bump it whenever a role's content (instructions, name, description, etc.) changes, so consumers can detect updates.

Bundle (<lang>.json) schema

{
  "schemaVersion": 1,
  "language": "ru",
  "roles": [
    {
      "slug": "structural-editor",   // REQUIRED, unique across the whole catalog
      "emoji": "🧱",
      "name": "...",                 // REQUIRED, localized
      "description": "...",          // localized
      "instructions": "...",         // REQUIRED, the system prompt, localized
      "autoStart": true,             // whether the role starts working immediately
      "launchMessage": "..."         // first message sent on launch (or null)
    }
  ]
}

Notes:

• modelConfig is intentionally absent; the server treats an absent modelConfig as null.
• A role's slug, emoji, and autoStart are identical across all language files of the same bundle. Only name, description, instructions, and launchMessage are translated.

Slug uniqueness

Every slug must be UNIQUE ACROSS THE WHOLE CATALOG, not just within a bundle. A slug appears once per language file of its bundle (same slug in ru.json and en.json), but no two different bundles may share a slug. scripts/check.mjs enforces this.

How to add things

Add a role to an existing bundle

1. Add an entry to that bundle's roles[] in index.json with a new unique slug and version: 1.
2. Add a role object with the same slug to every <lang>.json of the bundle, translating name, description, instructions, and launchMessage.
3. Run the check (see below).

Add a bundle

1. Add a bundle object to index.json (id, name, description, languages, roles).
2. Create bundles/<id>/<lang>.json for each declared language, with one role object per roles[] entry.
3. Run the check.

Add a language to a bundle

1. Add the language code to that bundle's languages[] in index.json.
2. Create bundles/<id>/<lang>.json containing every role of the bundle, translated.
3. Run the check.

Change a role's content

Edit the role in the relevant <lang>.json file(s) and bump that role's version in index.json.

Validating

From this directory:

node scripts/check.mjs   # or: npm run check

It fails (exit code 1) if any slug is duplicated across the catalog, if a bundle's index roles[] don't match the slugs present in each language file, if a declared language file is missing, or if any role is missing a required field (slug, name, instructions). It prints OK on success.