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`	yes	Slug of the role that acts as the workflow coordinator (not a special runtime privilege — it is just the role whose system prompt is wired for coordination)
`roles`	yes	All roles the team may ever use (always-on and on-demand)
`size`	no	Expected always-on headcount including the lead (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 team-lead 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 team-lead'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` (inherits the lead's model)
`skills`	List of skill slugs preloaded into the teammate's system prompt
`permissionMode`	`"plan"` to start the teammate in plan-mode (must have its plan approved before executing); omit for normal mode
`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. Lead: 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. Lead: 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.