AI Generation Rules

Rules are constraints that guide StudioBrain’s AI when generating or modifying content for a specific entity type. They ensure generated content stays consistent with the project’s world, tone, and structural requirements.

What Rules Do

When you ask the AI to generate a character backstory, describe a location, or write dialogue, StudioBrain includes the applicable rules in the generation prompt. Rules act as guardrails:

Enforce naming conventions (e.g. “all elven names must contain an apostrophe”)
Maintain world consistency (e.g. “magic does not exist in this setting”)
Set structural requirements (e.g. “every location must include a danger level”)
Define tone and style (e.g. “descriptions should be concise, no purple prose”)
Validate field values (e.g. “age must be between 1 and 500 for this species”)

Rule Formats

StudioBrain supports two rule formats: legacy Markdown and structured YAML.

Legacy Markdown Rules

The original format. A Markdown file named {ENTITY_TYPE}_RULES.md in the _Rules/ directory. The entire file content is passed to the AI as context during generation.

# Character Generation Rules
 
## Naming
- Character names must be culturally appropriate for their faction
- No modern Earth names in fantasy settings
- Titles (Sir, Lady, etc.) should match the character's social status
 
## Backstory
- Every character must have a clear motivation
- Backstories should reference at least one existing location
- Avoid orphan backstories unless the character's loss is plot-relevant
 
## Traits
- Maximum 5 personality traits per character
- At least one trait must be a flaw or weakness
- Traits should create internal tension when possible

Structured YAML Rules

The newer format, used in _Rules/Standard/. YAML rules have explicit fields for priority, severity, defaults, and validation — giving finer control over how rules are applied.

rule_id: character_generation
entity_type: character
version: "1.2"
description: Constraints for AI-generated character content
priority: 10
 
rules:
  - id: naming_convention
    description: Character names must fit the cultural context of their faction
    severity: error
    applies_to: [name, display_name]
 
  - id: backstory_motivation
    description: Every backstory must include a clear character motivation
    severity: warning
    applies_to: [backstory]
 
  - id: trait_limit
    description: Maximum 5 personality traits per character
    severity: error
    applies_to: [traits]
 
  - id: flaw_required
    description: At least one trait must be a flaw or weakness
    severity: warning
    applies_to: [traits]
 
defaults:
  age_range: [18, 200]
  max_traits: 5
  required_sections: [motivation, background, personality]
 
validation:
  name:
    min_length: 2
    max_length: 60
  backstory:
    min_length: 100

Format Comparison

Feature	Markdown (`*_RULES.md`)	YAML (`*.yaml`)
AI prompt injection	Entire file content	`rules[].description` values
Priority ordering	None (file order)	`priority` field (lower = higher priority)
Per-field targeting	Implicit (section headings)	Explicit `applies_to` lists
Severity levels	None	`error`, `warning`, `info`
Default values	None	`defaults` section
Field validation	None	`validation` section with constraints
Version tracking	None	`version` field

Both formats work side by side. Markdown rules are simpler to write; YAML rules give more control. For new projects, YAML is recommended.

YAML Rule Fields

Top-Level Fields

Field	Type	Required	Description
`rule_id`	string	Yes	Unique identifier for this rule set
`entity_type`	string	Yes	The entity type this rule applies to (e.g. `character`, `location`)
`version`	string	No	Rule version for update tracking (default: `"1.0"`)
`description`	string	No	Human-readable description of the rule set
`priority`	integer	No	Evaluation order. Lower numbers = higher priority (default: `10`)

Rules List

Each entry in the rules list has:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier within this rule set
`description`	string	Yes	The constraint text passed to the AI
`severity`	string	No	`error` (must follow), `warning` (should follow), or `info` (suggestion)
`applies_to`	list	No	Field names this rule targets. Empty = applies globally.

Defaults Section

Key-value pairs that provide default values or ranges for fields. These are passed to the AI as context and used by validation logic:

defaults:
  age_range: [18, 200]
  max_traits: 5
  default_alignment: neutral

Validation Section

Per-field validation constraints that are enforced at save time (not just during AI generation):

validation:
  name:
    min_length: 2
    max_length: 60
    pattern: "^[A-Za-z'\\- ]+"
  age:
    min: 1
    max: 500
  backstory:
    min_length: 100

Inheritance

Rules follow the same inheritance pattern as templates:

Catalog Standard (_Rules/Standard/)
  └── Custom (_Rules/Custom/)
        └── User (project-level _Rules/)

The Custom layer overrides Standard rules for the same rule_id. To override a catalog rule:

Copy the YAML file from _Rules/Standard/ to _Rules/Custom/ with the same filename.
Edit the rules, defaults, or validation as needed.
StudioBrain uses your Custom version instead.

CatalogSync discovers rules in both _Rules/*_RULES.md (legacy Markdown) and _Rules/Standard/*.yaml (structured YAML) from the catalog repo.

Creating a Custom Rule

For an Existing Entity Type

To add stricter rules for characters in your project:

# Create the Custom rules directory if it doesn't exist
mkdir -p _Rules/Custom
 
# Create your override
cat > _Rules/Custom/character_generation.yaml << 'EOF'
rule_id: character_generation
entity_type: character
version: "1.0"
description: Project-specific character constraints
priority: 5
 
rules:
  - id: no_magic
    description: This is a low-fantasy setting. Characters cannot have magical abilities.
    severity: error
    applies_to: [abilities, backstory]
 
  - id: faction_required
    description: Every character must belong to one of the four major factions.
    severity: error
    applies_to: [faction]
 
  - id: age_limit
    description: Characters in this setting are human-only and cannot exceed 100 years old.
    severity: warning
    applies_to: [age]
 
defaults:
  max_age: 100
  factions: [Iron Circle, Silver Dawn, Ember Court, Stone Pact]
 
validation:
  age:
    min: 1
    max: 100
EOF

For a New Entity Type

If you created a custom entity type (e.g. recipe), you can add rules for it:

rule_id: recipe_generation
entity_type: recipe
version: "1.0"
description: Constraints for AI-generated recipes
priority: 10
 
rules:
  - id: ingredient_availability
    description: Only use ingredients commonly available in grocery stores
    severity: warning
    applies_to: [ingredients]
 
  - id: step_clarity
    description: Each step must be a single clear action
    severity: error
    applies_to: [steps]
 
  - id: time_accuracy
    description: Prep and cook times must be realistic for the described technique
    severity: warning
    applies_to: [prep_time, cook_time]

How Rules Are Applied

During AI generation:

StudioBrain identifies the entity type being generated.
It collects all applicable rules (Markdown and YAML) for that entity type, respecting the inheritance chain.
For YAML rules, individual rule descriptions are sorted by priority and filtered by the target field(s).
The collected constraint text is injected into the AI system prompt alongside the template definition and any applicable skills.
The AI generates content within these constraints.
If validation rules are defined, the generated content is validated at save time. Errors prevent saving; warnings are shown as notifications.

Next Steps

Template System Overview — What templates are and how they work
Inheritance & Overrides — How resolution layers work
Agent Skills — AI capabilities that complement rules