# pi-chef ubiquitous language

Use these words in code, docs, tool text, and commit messages. One word means one thing.

| Term | Meaning | Owner in code |
|---|---|---|
| chef | The main Pi session in chef mode. The human talks only to the chef. The chef splits work into tasks, dispatches them, answers or escalates cook questions, reviews results, and closes tasks. | `extension/chef.ts` |
| chef mode | The state of a Pi session that has the chef tools active and owns or watches the kitchen. Turned on with `pi --chef` or `/chef`. A normal Pi session is not in chef mode and sees no chef tools. | `extension/chef.ts` |
| kitchen | The directory on disk that holds all chef state: projects, tasks, runs, inboxes, worktrees, config, and the lease. Default `<pi agent dir>/chef`, override with `CHEF_HOME`. | `extension/store.ts` |
| lease | The file `pass.lock` that names the one chef session that owns the kitchen. A dead holder makes the lease stale, and the next chef takes it. | `extension/kitchen.ts` |
| owner | The chef session that holds the lease. Only the owner launches cooks, writes task logs, and receives wakes. | `extension/kitchen.ts` |
| read-only session | A chef-mode session that does not hold the lease. It can show the board and results. It cannot change the kitchen. | `extension/kitchen.ts` |
| project | A git repository that the human registered with the chef. Tasks fork from its base branch. Its branch prefix (default `issue/`) starts the branch name of each new task. | `extension/store.ts` |
| task | One unit of work for one project, with a title and a brief. A task has its own worktree, its own branch `<branch prefix><task id>` (fixed at dispatch), and its own Pi session. Task ids look like `api-7`. | `extension/domain.ts` |
| brief | The instructions for a task, written by the chef. It says the intent, what done means, and how to deliver. | `extension/domain.ts` |
| cook | A child Pi process that works on one task. A cook runs detached, so it can outlive the chef session. | `extension/cooks.ts` |
| run | One cook process lifetime for a task. A task has one or more runs. Run `n` writes `runs/<n>.jsonl`. A later run continues the same Pi session. | `extension/store.ts` |
| model rule | An entry in `config.json` `models.rules`: a `name`, a plain-words `when` (the kind of task it fits), the models to `use`, and an optional `why`. The chef model reads the rules in its system prompt and names one per dispatch. | `extension/derive.ts` |
| candidate | One model, with an optional thinking level, in the ordered list a task may run on: the chosen rule's models or an explicit model, then the default models, without models that Pi cannot run. The list is fixed in `task.json` at dispatch. | `extension/derive.ts` |
| fallback | A run of a task on its next candidate, started by the tick with no chef wake, because the run before it failed with a provider error. Each provider failure uses up one candidate. The candidate of a run is derived from the earlier runs, never stored. | `extension/derive.ts` |
| report | The cook's structured status, given with the `chef_report` tool at the end of a run: `done`, `needs_decision`, `blocked`, or `failed`, with a summary. | `extension/cook.ts` |
| outcome | How a finished run ended, derived from the run file: done, needs decision, blocked, failed, or stopped. | `extension/derive.ts` |
| task state | `queued`, `cooking`, `idle` (with an outcome), or `closed`. Always derived from files and live processes. Never stored. | `extension/derive.ts` |
| inbox | The directory of messages from the chef to one task. A cooking cook takes them mid-run. An idle task gets them as the prompt of its next run. | `extension/store.ts` |
| wake | One `chef-wake` message that tells the chef about one or more new outcomes and starts a chef turn. | `extension/chef.ts` |
| board | The view of all open tasks: state, current activity, and age. Shown as a widget, by `/chef`, and by `chef_board`. | `extension/derive.ts` |
| tick | One pass of the reconcile loop: read files and processes, derive task states, plan actions, run them. Startup reconciliation is the first tick. | `extension/kitchen.ts` |
| recipe | A named group of working rules that the user chooses for the chef and the cooks. Each recipe is an optional add-on with a name, for example `pstack`. At each turn it asks the role query and appends a block headed `# Recipe: <recipe name>` to the system prompt of the chef, the cooks, or both, unless the answer selects another recipe or `none`. Core has no recipe, so without an add-on no prompt gets a recipe block. The recipes are `pstack` and `superpowers`. | `addons/recipe-pstack/`, `addons/recipe-superpowers/` |
| recipe selection | The `recipe` field of `config.json`, which the human writes: a default recipe for the chef and the cooks, and a recipe per project for the cooks of that project. A value is a recipe name or `none`. Without a selection, every installed recipe adds its block. Chef resolves it again at each role query, so an edit applies at the next turn. | `extension/derive.ts` |
| principle | One working rule of the pstack recipe: a vendored file `addons/recipe-pstack/principles/<name>/SKILL.md`. The pstack block has the always-on rules of the role and an index of every principle with the path of its file. The superpowers recipe keeps the word of its source: its working rules are skills, each a vendored file `addons/recipe-superpowers/principles/<skill>/SKILL.md`, and the index of a role lists only the skills of that role. | `addons/recipe-pstack/principles.ts`, `addons/recipe-superpowers/superpowers.ts` |
| landed | A task's commits are reachable from the project base branch or from a remote-tracking ref as of the last fetch. `chef_close` removes a worktree only when its work is landed or the caller discards it, and deletes the task branch only when the base branch contains it. | `extension/git.ts` |
| cooks snapshot | The event `pi-chef:cooks:v1` on `pi.events`: the chef session id, its role (`owner`, `read-only`, or `off`), and every open task with its state, outcome, paths, and viewer command. Chef emits it after a tick that changed it, on request, and with role `off` when chef mode closes. Add-on packages read it. It is a full snapshot, never a delta. | `extension/events.ts` |
| role query | The event `pi-chef:role:v1` on `pi.events`. An add-on emits a request with no role, and chef fills it before `emit` returns: `chef` while chef mode is on, `cook` in a cook process, else no role. With a role, it also fills the selected recipe, if any. An add-on asks again each time it needs the answer. | `extension/events.ts` |
| cook tab | A herdr tab named `cook <task id>` that the optional herdr add-on opens when an owner snapshot first shows a run of the task cooking, if the chef runs inside herdr. It runs the viewer, `watch.mjs`, which prints the run files of the task and exits when the task is closed. It is for watching only. | `addons/herdr/herdr.ts` |