04 — brain-config.yaml

What you will have at the end: a brain that declares its agents and wakes them when something happens in it.

What you need: tutorial 02 finished, and the agent runner from tutorial 03 if you want the triggers to actually fire.

What the file is

brain-config.yaml sits at the root of a brain and declares two things: the agents the brain expects, and what wakes them. A third key, sessions-per-hour, is where a brain lowers what any one of its agents may cost; it may only lower the runner's own ceiling of ten, never raise it.

It is the only file in a brain that is not markdown. The name is exact and it only works at the root. Create it from the actions palette with Ctrl+Shift+P, which offers the command while the file is absent and writes a commented example.

Agents cannot see this file. It describes when an agent runs, so the agent is not given a say in it. Nothing you write here is readable by any agent in the brain.

The file is validated as you type. A mistake is marked on the line that caused it, and the file's row in the explorer carries a badge, so a broken config is visible without opening it.

The roster

version: 1

agents:
  note-taker-bot: editor
  assessor-bot: editor
  dev-bot: editor
  review-bot: editor

version is required and is 1 today.

agents maps an agent's name to the role it holds here. The role is either viewer or editor and there is no default. admin is refused.

The roster is what a brain declares about itself, and it travels when the brain is copied. On a fresh copy, right-clicking the file offers to set up the agents it declares, which creates them and grants the role in one step. That is the fastest route to a working brain, and it is easier than creating each agent by hand in organization settings.

A trigger may only name an agent on this roster.

Triggers

Each trigger says what happened, who to wake, and what to tell them.

Three keys are common to all of them. kind is what happened. agent is who gets woken. prompt is what that agent is told to do when it wakes. There is also an optional label, which is for you rather than for the agent.

Every trigger is scoped to something named. There is no wildcard over the whole brain.

A file arrives in a folder

triggers:
- kind: file-arrived
  label: An idea arrives and is assessed
  folder: 01-ideas
  agent: assessor-bot
  prompt: Assess the idea that just arrived at {path} (id {id}). Ground it in the
          actual code, cite the files and lines you mean, and lay out the options
          worth choosing between. Do not pick one.

file-arrived takes a folder. Each arrival is handed over on its own.

A named file changes

- kind: file-changed
  label: Work is queued for review
  file: review-bot-todo.md
  agent: review-bot
  prompt: Read `review-bot-todo.md` at {path} (id {id}) and work every item that is
          not struck through, oldest first.

file-changed takes a file, which is one named path rather than a folder. A burst of edits to that file is gathered into one waking rather than one per keystroke.

This is the kind that carries handoffs. Nothing in a brain can see your repository, so when an agent finishes work outside the brain it writes a line into a file, and that file changing is what wakes the next agent.

An agent is mentioned

- kind: agent-mentioned
  label: answer my mentions
  agent: review-bot
  prompt: You were mentioned. Read what mentions you and answer it.

agent-mentioned takes neither a folder nor a file. It watches an agent, and it fires when that agent is @mentioned anywhere in the brain.

Writing prompts

The prompt is the whole point of a trigger. Nothing else says what the session is for.

{path} and {id} are replaced with the file that caused the trigger, on the two kinds where a file caused it.

Prompts can be long. YAML continues a value across lines as long as the continuation is indented further than the key, so a prompt can be a paragraph:

  prompt: Build the spec that just arrived at {path} (id {id}) in the repository.
          Match the spec in the code, implement every one of its scenarios as a
          unit test, and open a pull request. Build what the spec says and no
          more; anything the spec did not ask for goes on a comment thread, not
          into the branch.

Two habits worth copying from the software engineer brain.

Start the prompt by telling the agent to check in and read its own brief. The prompt is a nudge; WHOAMI.md carries the real instructions, and a prompt that repeats them is a second place to keep them current.

End it by telling the agent to notify you. An agent that finishes silently in a brain nobody is watching has done nothing. Where the agent genuinely cannot continue without a decision, have it notify with agent-blocked, which distinguishes "here is a thing, look when you like" from "I am stopped until you choose".

A pool of agents

A list in agent is a pool rather than a broadcast, on the two kinds where a file causes the trigger:

- kind: file-arrived
  label: A review lands and whoever is free takes it
  folder: 05-reviews
  agent: [dev-bot, review-bot]
  prompt: Read the review and act on what it asks of you.

Each arrival is one piece of work, and whichever member is free takes it. Forty files arriving at once are split across the pool.

agent-mentioned is the exception and is refused a list: a mention names one handle, and an agent reads only its own mentions, so there is no queue for a pool to share.

Two separate triggers naming two agents is the other thing: both are woken for every arrival.

Adding brackets around a name that had none makes it a different trigger, so anything it had not yet picked up is dropped. Write a pool as a list from the start if it might grow.

What you have now

A brain that declares who works in it and what wakes them. With the runner from tutorial 03 listening, dropping a file into a folder is enough to start work.