Casting Reference

Total: 15 built-in universes — capacity range 6–25.

Descriptive Defaults

When the user does not request a themed universe, use descriptive role-based names instead of character names. Descriptive names are the default naming convention.

Rules for descriptive naming:

• Use short, functional names that describe the agent’s role.
• Agent folder names are the descriptive name in lowercase (e.g., .squad/agents/lead/).
• Set "universe": "descriptive" in registry.json.
• If the user later requests a themed universe via re-cast, replace all descriptive names with character names from the chosen universe.

Custom Universes

Users may request any universe — not just those in the built-in allowlist. When a user specifies a universe not in the table above, treat it as a custom universe.

Custom Universe Rules

1. Accept the request. Do not reject a universe because it is not in the allowlist.
2. Allocate character names from your knowledge of the source material. Pick characters whose traits or roles loosely resonate with the agent’s function.
3. Spoiler awareness still applies. Follow all spoiler rules (see below) — prefer names as introduced early, avoid fate-revealing epithets.
4. Capacity is flexible. There is no pre-set capacity for custom universes. If the source material has enough named characters for the team, proceed. If not, tell the user and suggest a different universe.
5. Record as custom. In registry.json, set "universe" to the user-specified universe name (e.g., "Doctor Who", "The Office"). In history.json, record the universe name as given by the user.
6. ONE UNIVERSE PER ASSIGNMENT still applies — do not mix custom and built-in characters.
7. Re-casting is allowed. The user can re-cast at any time by requesting a different universe (custom or built-in). All active agents are renamed; folder names and file references are updated.

Custom Universe in policy.json

When "allow_custom_universes": true is set in policy.json (this is the default), any user-specified universe is accepted. Built-in universes are preferred for auto-selection (no user preference), but the user can always override.

Selection Algorithm

Universe selection is deterministic and applies only when the user has not specified a universe. If the user requests a specific universe (built-in or custom), use it directly — skip scoring.

When auto-selecting, score each built-in universe and pick the highest:

Same inputs → same choice (unless LRU changes between assignments).

Spoiler Awareness

Character names are easter eggs shown in plain text across team.md, prompts, logs, and generated files. The user configuring the squad may be midway through the source material. A name that bakes in a future title, role, transformation, or fate can spoil later plot events even when the casting rationale stays hidden.

How to avoid it:

• Prefer the name a character has when first introduced.
• Avoid titles or epithets earned later.
• Avoid names that describe a transformation, fate, hidden identity, or reveal.
• When unsure, pick a safer character from the same universe.
• Keep existing name mappings stable — do not rename already-allocated agents or switch universes to dodge a spoiler. Only the next/new allocation should pick a different spoiler-safe character.

Motivating example. A user setting up a squad requested the Malazan Book of the Fallen universe (Steven Erikson) and was only four books into the series. The casting allocated two spoiler-bearing names:

• One name bundled a title/epithet the character only earns after a major mid-series development — encoding a role they do not yet hold at the reader’s current point in the story.
• The other referenced a state/transformation that has not yet occurred at the reader’s position — revealing what later becomes of that character.

Both leaked future plot. (Character names are deliberately omitted here so this document does not reproduce the spoiler.)

Casting State File Schemas

policy.json

Source template: .squad/templates/casting-policy.json Runtime location: .squad/casting/policy.json

registry.json

Source template: .squad/templates/casting-registry.json Runtime location: .squad/casting/registry.json

history.json

Source template: .squad/templates/casting-history.json Runtime location: .squad/casting/history.json