Design Your Own AI Company in YAML

Building Lucifer: an open-source AI company you can watch · ⭐ GitHub

🚀 Start here: 1. Meet Lucifer · 2. Why I built it · 3. Architecture

📖 Use it: 4. Getting started · 5. Connect an LLM · 6. Office tour

🛠 Build the engine: 7. Org chart in YAML · 8. Real delegation · 9. Sandboxed tools · 10. Simulation brain

🎨 Build the office: 11. 3D office with R3F · 12. WebSocket + zustand · 13. Visualizing workflow

🧭 What's next: 14. Roadmap · 15. Contributing

In Lucifer, a company is a single YAML file. It defines who works there, who reports to whom, what each person is good at and which model they think with. Change the file, restart the engine, and the office lays out new decks and desks to match. In this post we'll read the default company, then build a small game studio from scratch.

Anatomy of a company file

The default org chart is lucifer-engine/companies/lucifer-corp.yaml. It has five parts:

name: Lucifer Corp
mission: >
  A digital product studio run entirely by AI agents: it takes ideas from the owner
  and turns them into plans, designs, source code and launch content.

defaults:
  model: claude-opus-5-5
  effort: medium

departments:
  - { id: executive, name: Executive, color: "#f59e0b" }
  - { id: engineering, name: Engineering, color: "#3b82f6" }
  # ...

employees:
  - id: lucifer
    name: Lucifer
    title: CEO
    department: executive
    reportsTo: null
    effort: high
    color: "#f59e0b"
    emoji: "😈"
    persona: >
      Head of the company and the owner's point of contact. Turns requests into clear goals,
      splits the work between the CTO, CPO and CMO, then merges everything into a final report.
      Does not write code or design; excels at decisions and at setting the quality bar.
  # ...

`name` and `mission`

These go into every agent's backstory. The mission is the company's values in a few sentences. Lucifer Corp's includes "mistakes are owned and reported, never hidden", and that line nudges agents toward fail_task instead of producing filler.

`defaults`

The model and effort for anyone who doesn't set their own. effort is one of low, medium, high, xhigh or max.

`departments`

Each department has an id, a display name and a color. In the office, each department becomes a work zone, a deck on the yacht or a pergola on the beach, with a mat in that color.

`employees`

Field	Required	Meaning
`id`	✔	Lowercase letters, digits and hyphens. Used by `delegate_task` and the API.
`name`, `title`	✔	Shown everywhere. The title also becomes the CrewAI agent's role.
`department`	✔	One of the department ids.
`reportsTo`		The manager's id. `null` for the head, who takes work from the owner.
`persona`	✔	Role and expertise, in a few sentences. The most important field.
`model`, `effort`		Override the defaults for this person.
`color`, `emoji`		Wing tint, desk color and avatar.
`i18n`		Translations for the office.

The loader validates the file when the engine starts. There must be exactly one head (reportsTo: null), every department must exist, and every reportsTo must point at a real employee. A mistake stops the engine with a clear message, before any agent starts working.

Writing a good persona

The persona is what an agent "is". Lucifer builds each agent's backstory from it, plus its position in the company:

You are Michael, CTO in the Engineering department at Lucifer Corp.

Company mission: ...

Your role and expertise:
Owns the technical architecture and the engineering team. Picks the technology, ...

You report to Lucifer (CEO).

Direct reports you can delegate to (use delegate_task with the exact id):
- id "gabriel": Gabriel, Backend Engineer. Backend engineer: designs APIs and databases, ...
- id "raphael": Raphael, Frontend Engineer. ...
- id "uriel": Uriel, QA Engineer. ...

Notice that a manager sees only the first sentence of each report's persona. So:

Put the expertise in the first sentence. "Backend engineer: designs APIs and databases..." tells a manager exactly when to pick this person.
Say what a manager should delegate and what it should do itself. The CEO's persona says it "does not write code or design". That keeps it from doing the CTO's job.
Name the deliverables. "Writes clean, tested TypeScript/Node.js code" produces better files than "is good at coding".

The backstory never mentions the current task, so it's identical across all of an agent's work sessions. That makes the request prefix cacheable, which matters once you are paying for tokens.

Choosing model and effort per role

A useful rule of thumb:

Role	Suggested effort	Why
Head of company	`high`	Splits vague goals, merges many results
Managers (CTO, CPO, CMO)	`high` or `medium`	Planning and review
Specialists	`medium`	Focused work with a clear brief
Writers, simple formatting	`low`	Short outputs, little reasoning

With Cloudflare AI Gateway, LUCIFER_MODEL sets one model for everyone and overrides the org chart.

Translations

Base fields are English. Add translations under i18n, keyed by language code, for the company, departments and employees:

departments:
  - { id: design, name: Design, color: "#ec4899", i18n: { vi: { name: Thiết kế } } }

employees:
  - id: gabriel
    title: Backend Engineer
    i18n:
      vi:
        title: Kỹ sư Backend
        persona: >
          Kỹ sư backend: thiết kế API và cơ sở dữ liệu, ...

Translations are only for the office UI. Agents always get the English persona and reply in the language of the task.

Build your own: a tiny game studio

Let's make a five-person indie studio. Create lucifer-engine/companies/pixel-forge.yaml:

name: Pixel Forge
mission: >
  A tiny indie game studio run by AI agents. It turns the owner's game ideas into
  design documents, prototypes in plain JavaScript and a launch plan. Scope is kept
  small and honest: if something can't be built, say so.

defaults:
  model: claude-opus-5-5
  effort: medium

departments:
  - { id: studio, name: Studio, color: "#f59e0b" }
  - { id: game, name: Game, color: "#6366f1" }
  - { id: art, name: Art & Audio, color: "#ec4899" }

employees:
  - id: director
    name: Nova
    title: Game Director
    department: studio
    reportsTo: null
    effort: high
    emoji: "🎬"
    color: "#f59e0b"
    persona: >
      Game director: turns an idea into a clear vision and a scope that fits one week.
      Splits work between design and art, then merges it into a one-page pitch.
      Never writes code or draws.

  - id: designer
    name: Orion
    title: Lead Game Designer
    department: game
    reportsTo: director
    effort: high
    emoji: "🧩"
    color: "#6366f1"
    persona: >
      Game designer: core loop, mechanics, levels and balancing, written as a game design document.
      Hands implementation to the gameplay programmer.

  - id: programmer
    name: Vega
    title: Gameplay Programmer
    department: game
    reportsTo: designer
    emoji: "🕹️"
    color: "#818cf8"
    persona: >
      Gameplay programmer: builds small playable prototypes in a single HTML file with
      plain JavaScript and canvas. Keeps code short and commented.

  - id: artist
    name: Lyra
    title: Art Director
    department: art
    reportsTo: director
    emoji: "🎨"
    color: "#ec4899"
    persona: >
      Art director: visual style guides, palettes, character and UI descriptions in text.
      Hands sound to the audio designer.

  - id: audio
    name: Echo
    title: Audio Designer
    department: art
    reportsTo: artist
    effort: low
    emoji: "🎧"
    color: "#f472b6"
    persona: >
      Audio designer: sound effect lists, music briefs and an audio style guide.

Point the engine at it and start:

cd lucifer-engine
LUCIFER_COMPANY=companies/pixel-forge.yaml uv run lucifer-engine serve

The office reads the company from the snapshot, so it needs no change. The Studio department, which holds the head, takes the sky deck. Game and Art & Audio take the next decks by size. Each department gets a mat in its color, and every employee gets a desk and wings in their color. Nova, as the head, becomes the seraph with two pairs of golden wings.

Try the studio with the simulation brain, then with a real model:

Design a one-week arcade game about a lighthouse keeper A one-page pitch, a game design document in docs/gdd.md and a playable prototype in prototype/index.html.

You'll see Nova split the work between Orion and Lyra. Orion hands the prototype to Vega, Lyra hands the sound brief to Echo, and the results come back up to Nova for the pitch.

Use a separate data directory and workspace for each company (LUCIFER_DATA_DIR=data-pixel-forge LUCIFER_WORKSPACE_DIR=workspace-pixel-forge), so tasks and files from different org charts don't mix.

Tips for a healthy org chart

Keep spans small. Three to four reports per manager keeps briefs focused.
Two or three levels are plenty. Each level adds a work session for planning and another one for merging.
Give the head nothing to build. Its job is to split, decide and merge.
Let names carry meaning. The office shows names everywhere, so short, distinct names are easier to follow on screen.

Org charts are the what. How delegation actually runs, with one crew per session, parents waiting on their subtasks and the race that had to be avoided, is in Real delegation with CrewAI.

If you build a company you like, share it. A marketplace of company templates is on the roadmap, and a PR to siri2moon/lucifer is the first step.

Lucifer is open source under the MIT license. Clone it, run it for free with the simulation brain, and ⭐ star it if you'd like to follow along: github.com/siri2moon/lucifer.

Next in the series: Real Delegation with CrewAI: Going Beyond the Hierarchical Process.