Skip to main content

ᛗ The Nine Realms

The Yggdrasil framework organizes all projects and concerns into Nine Realms, each modeled after a world in Norse mythology. This is not cosmetic — each realm has specific conventions, CI/CD pipelines, and role-based access.

Asgard — Core Technology ᛊ​

The realm of gods. Where the foundational architecture lives.

Purpose: Foundation libraries, core frameworks, shared configurations, and project scaffolding.

Key Projects:

  • yggdrasil-core — The runtime engine connecting all realms
  • brier-config — Shared configuration schemas and validators
  • norns-pipeline — CI/CD orchestration layer

Conventions:

  • Strict semver enforcement
  • 100% test coverage required
  • All changes require 2+ reviewer approvals
  • API stability guarantees (no breaking changes without major version bump)

When to use Asgard: When building something that other realms depend on. If it's a library, a shared utility, or a configuration schema — it belongs here.

Vanaheim — AI Agents ᛉ​

The realm of Freyja. Where intelligence dwells.

Purpose: AI agent development — Discord bots, Telegram agents, personality profiles, and conversational AI systems.

Key Projects:

  • lilith-discord — Lilith v2.0 Discord bot
  • lilith-telegram — Telegram agent interface
  • personality-engine — The core personality definition and switching system

Conventions:

  • All agents must define a personality.yml manifest
  • Rate limiting is mandatory for all external API calls
  • Conversation logs are ephemeral — no persistent storage of user messages
  • Agent responses must pass through the personality filter pipeline

When to use Vanaheim: If your project involves conversational AI, chatbot development, or personality-driven interaction — this is the realm.

Alfheim — UI Prototypes ᛉ​

The realm of light. Where interfaces are born.

Purpose: Visual design systems, frontend prototypes, UI component libraries, and design experimentation.

Key Projects:

  • neon-ui — BrierStudios design system (react components with neon aesthetic)
  • docs-theme — This very documentation theme
  • lilith-avatar-gen — Avatar generation UI for Lilith expressions

Conventions:

  • All components must support dark mode exclusively
  • Follow the BrierStudios color palette: cyan #38bdf8, magenta #d946ef, gold #fbbf24
  • Accessibility: WCAG 2.1 AA minimum contrast ratios (verified in dark mode)
  • Storybook documentation required for all exported components

When to use Alfheim: Frontend work, design systems, prototype interfaces, and anything visual.

Svartalfheim — Knowledge & Docs ᚨ​

The realm of dwarves. Where knowledge is forged.

Purpose: Documentation, wikis, knowledge bases, and reference materials.

Key Projects:

  • docs-brierstudios — This documentation site (Docusaurus)
  • api-reference — Auto-generated API docs from OpenAPI schemas
  • knowledge-base — Internal wiki and decision records

Conventions:

  • All docs use MDX with proper frontmatter
  • Write in English with Spanish-neutral headers where culturally appropriate
  • Every page must have title and description in frontmatter
  • Link checks are enforced in CI

When to use Svartalfheim: Documentation of any kind. If you're writing it down, it goes here.

Muspelheim — Active Dev ᛏ​

The realm of fire. Where creation happens in real-time.

Purpose: Work-in-progress features, experimental branches, and active development sprints.

Key Projects:

  • Feature branches and WIP PRs
  • Experimental prototypes
  • Hackathon projects

Conventions:

  • No stability guarantees — things break here
  • Branch names follow: muspel/<feature-description>
  • Auto-deploy to staging on merge
  • Projects promoted out of Muspelheim graduate to their appropriate realm

When to use Muspelheim: When you're prototyping, experimenting, or building something that isn't ready for a permanent home.

Niflheim — Resources & Assets ᛁ​

The realm of ice. Where assets are preserved.

Purpose: Static resources, model weights, datasets, images, LoRA files, and generated assets.

Key Projects:

  • lora-models — Trained LoRA model files and configs
  • asset-pipeline — CDN and asset processing workflow
  • dataset-collections — Curated training datasets

Conventions:

  • All assets must include metadata manifests (origin, license, dimensions)
  • LFS (Large File Storage) for binary files >10MB
  • Assets are immutable once published — use versioned paths
  • Organize by realm: /asgard/, /vanaheim/, etc.

When to use Niflheim: When storing models, images, datasets, or any static binary resource.

Helheim — Archive ᚻ​

The realm of the dead. Where old code rests.

Purpose: Deprecated code, archived projects, and the graveyard of failed experiments.

Key Projects:

  • Archived repositories (read-only)
  • Deprecated API versions
  • Abandoned prototypes

Conventions:

  • Read-only — No new commits accepted
  • All projects moved here are marked with a DEPRECATED header in their README
  • Deletion from Helheim requires admin approval and a 90-day waiting period
  • Projects can be resurrected from Helheim by opening a "Revival" issue

When to use Helheim: When a project is end-of-life. Don't delete it — archive it here so history is preserved.

Jotunheim — Massive Projects ᛃ​

The realm of giants. Where scale matters.

Purpose: Large-scale, long-term projects that require dedicated infrastructure and extended timelines.

Key Projects:

  • yggdrasil-platform — The full stack platform deployment
  • multi-agent-orchestrator — Distributed agent management at scale

Conventions:

  • Monthly milestone reviews required
  • Dedicated infrastructure budgets
  • Long-term support (LTS) release cycle
  • Architecture Decision Records (ADRs) mandatory for all major changes

When to use Jotunheim: When a project outgrows a single realm and needs its own infrastructure investment.

Midgard — Personal Apps ᛗ​

The realm of humans. Where applications serve real people.

Purpose: End-user applications, personal utilities, and directly-shipped products.

Key Projects:

  • brierstudios-site — The main brierstudios.com website
  • personal-tools — CLI utilities and automation scripts
  • discord-community-bot — Community-facing Discord features

Conventions:

  • User-facing documentation is required (even for personal tools)
  • Semantic versioning with public changelogs
  • Deployment to production requires manual approval
  • Accessibility testing before any public release

When to use Midgard: When building something that actual humans will use directly.

Realm Transition Rules​

Projects can move between realms as they evolve. The standard lifecycle:

Muspelheim → (relevant realm) → Jotunheim (if it scales)
                                          ↓
                                       Helheim (when retired)

Use yg realms migrate to transition a project:

yg realms migrate --project my-experiment --from muspelheim --to vanaheim
tip

Always create an Architecture Decision Record (ADR) when transitioning a project between realms. This maintains context for future contributors.