Team Recipes¶

A team recipe is a Markdown file with YAML frontmatter that declares who is on the team, what safety floor it runs under, and when to use it. Recipes live in your mission repo under orchestrator/teams/<slug>/team.md and are loaded automatically when bnerd discovers the mission repo.

Recipe format¶

---
name: pr-review
description: Run a multi-role review of a pull request.
lead: product-orchestrator
roles: [product-orchestrator, code-reviewer, security-reviewer]
size: 3
mode: in-process
plan_approval: false
workspace: cloud/app
repos: [cloud/app/hq]
when_to_use: >
  Reviewing a pull request that touches the API, the CLI, or both.
  Use instead of a single-AI review when you want distinct code and security lenses.
---

# PR Review Team

…markdown body describing the team's working contract…

Frontmatter fields¶

Field	Required	Description
`name`	yes	Human-readable display name
`description`	yes	One-line summary shown in `bnerd team list`
`lead`	no	Slug of the role whose persona (system prompt, model) the coordinator driver should adopt — an optional hint, not a runtime privilege or a separate session. Omit it and the driver falls back to a built-in, deliberately read-only auto-coordinator. `bnerd team describe` prints this field as `coordinator hint:` (`(built-in)` when empty).
`roles`	yes	All roles the team may ever use (always-on and on-demand)
`size`	no	Expected always-on headcount, including the role the coordinator hint names if any (informational)
`mode`	no	Currently always `in-process`
`plan_approval`	no	When `true`, every teammate that has `permissionMode: plan` in its role file enters plan-mode on spawn and must have its plan approved by the coordinator driver before executing
`workspace`	no	Relative path to the working directory (resolved against the mission repo root)
`repos`	no	List of repo paths the team operates on (informational; used by the TUI to set context)
`when_to_use`	no	Guidance shown in `bnerd team describe` to help you pick the right recipe

The Markdown body after the frontmatter is the team's working contract: norms, safety guardrails, role summaries, and any fixed workflow steps. The Coordinator injects it into the coordinator driver's system prompt at spawn.

Role files¶

Each role slug referenced in a recipe must have a matching file at orchestrator/roles/<slug>.md. The role file's frontmatter drives the teammate's spawn configuration:

---
name: code-reviewer
description: Correctness pass on diffs.
tools: [Read, Grep, Glob, Bash, Skill, SendMessage, TaskCreate, TaskList, TaskUpdate, TaskGet]
model: sonnet
---

Role frontmatter fields¶

Field	Description
`name`	Display name (shown in the roster and event stream)
`description`	One-line summary
`tools`	Claude Code tool names the role may use (translated to bnerd tool names at spawn; unknown names are dropped with a warning)
`disallowedTools`	Tool names explicitly blocked (applied after the `tools` allowlist)
`model`	`opus`, `sonnet`, `haiku`, or `inherit` (defers to the operator's configured default model)
`skills`	List of skill names force-loaded into the teammate's system prompt at spawn, regardless of the skill's own `applies_to` restriction. Static for the teammate's lifetime — a teammate has no self-serve `skill` tool to load anything beyond this list. An unresolved name is dropped with a spawn warning, not a fatal error. See Rules & Skills.
`permissionMode`	`"plan"` to start the teammate in plan-mode (must have its plan approved before executing); omit for normal mode
`reviewer`	`true` opts the role into satisfying task gates via `team_task_satisfy_gate` (grants gate-checker capability once spawned as a teammate)
`subagents`	`true` grants the role's `sub_agent`/`explore_agent` tools for read-only fan-out investigation (both still run on a hardcoded read-only, local-only registry regardless of the role's own mode, and inherit the launching operator's permission denies). Applies when the role runs as a teammate; a standalone agent profile ignores it
`permission`	Optional block of `allow`/`ask`/`deny` entries, same shape as an `--ai-permissions` profile file, applied on top of the mode preset when the role spawns — see Agent Profiles → The `permission:` block for the full syntax and composition order
`color`	Display colour in the roster

Fields mcpServers and hooks are read but ignored in phase 1 (logged as warnings).

Built-in team recipes¶

The mission repo ships these recipes out of the box:

`cli`¶

Deep-dive CLI work: Cobra commands, the Bubbletea TUI, AI chat and MCP surfaces, and Go internals. Coordinator hint: product-orchestrator. Roles: go-cli-dev, ux-designer, app-qa, security-reviewer, code-reviewer (on-demand), docs-engineer (on-demand).

Use when: a CLI-internal effort that does not pivot on the cross-surface API contract.

`cloud-app`¶

Full cross-surface product team: API, dashboard, CLI, Terraform provider, and docs. Coordinator hint: product-orchestrator. One developer per surface, plus QA, security review, code review, and observability as on-demand specialists.

Use when: a feature or change that spans hq / dashboard / CLI / provider.

`pr-review`¶

Focused PR review with a code-reviewer and a security-reviewer working concurrently against the same commit. Both roles satisfy their respective gates (code-review, security-review) at the same commit SHA; tip-alignment is checked before the task is marked complete.

`incident-response`¶

Read-only triage. An ops-investigator gathers logs, metrics, k8s events, and OpenProject context; a security-reviewer checks for security implications. Safe to run with --auto-approve=safe.

Schema loading and precedence¶

bnerd loads recipes and roles from three locations in this order (first match wins; conflicts log a warning naming both sources):

Mission repo (<missionRepo>/orchestrator/{roles,teams}/) — canonical source
Global fallback (~/.bnerd/{agents,teams}/) — your personal defaults
Project-local additive (<workDir>/.bnerd/{agents,teams}/) — repo-specific additions only; cannot override mission or global definitions

The additive model means a project can add a new role without touching the mission repo. It cannot silently shadow an existing one — bnerd warns and the mission-repo definition wins.