bb-plugin-chief-nav

Chief's chat, with the org it runs down the left side.

The operating model this plugin enforces: the Captain (the user) talks only to Chief. There is exactly one Chief thread, global — not tied to a project. Chief does no substantive work: it stands up a project chief per project, which creates BB tasks and hands each to a task architect with a complete brief. Nobody below Chief addresses the Captain directly — they ask through the Inbox, or point at a thread for review.

Command Center

Chief talks to the command-center plugin only over bb.sdk.plugins.callRpc, never by importing it:

• The needs-input rail reads Command Center's list rpc for open questions.
• chief_handoff reads Command Center's dispatchPreference rpc for the harness/model the Captain chose in its composer, applied when a handoff does not name one explicitly.

Command Center reads this plugin's state rpc the same way, to find the live Chief thread when dispatching a request. Each plugin degrades gracefully — reporting an error rather than breaking — if the other is not installed.

(These two plugins briefly lived merged into one, sharing a database and a single CLI command. They were split back apart, restoring this contract.)

CLI and agent surface

bb chief status|start|adopt|project-chief|adopt-project-chief|handoff|retire|tidy is Chief's whole CLI surface. The agent tools — chief_project_chief, chief_handoff, chief_roster — and the three bundled skills (chief, project-chief, chief-architect) are how Chief and its subordinates actually do the work; the CLI is mostly for the Captain and for tidy's sidebar cleanup.

Data

Chief's own tables — chief (the one global thread), project_chiefs, architects — live in this plugin's own SQLite at <dataDir>/plugins/chief-nav/data.db, independent of Command Center's.

UI components

components/ui/ is vendored source you own (the shadcn model): edit the files freely — they never update out from under you. Add more from the BB component registry (the full shadcn set, version-matched to your BB install via the pinned ref in components.json):

npx shadcn add @bb/dialog @bb/select

Run npm install once before bb plugin build — the vendored components' npm deps bundle into your dist. React, and BB-shimmed packages like the radix portal primitives and sonner (import { toast } from "sonner" reaches BB's own toaster), are provided by the BB app at runtime and never bundled. Ship dist/ (npm tarball or committed for git installs) so people installing your plugin never need npm.

Manifest

package.json is the plugin manifest. Notable fields:

• bb.server — backend entry (required); optional bb.app for a frontend.
• bb.name and bb.description — required human-facing identity.
• bb.branding — required; declare icon as a BB icon name or a plugin-relative compact SVG, or declare logo.light (with optional logo.dark). Logo assets must be relative .svg, .png, or .webp files.
• engines.bb — supported bb app version range.
• engines.bbPluginSdk — the lowest plugin SDK you need (scaffold: >=0.4.6). BB reads this as a floor, not a ceiling: a later SDK in the same major still loads your plugin.
• dependencies — every package your source imports that BB does not provide. bb plugin build inlines them into dist/, and git installs resolve this list alone, so a build-required package here rather than in devDependencies is what keeps your plugin installable. devDependencies is for types and tooling only (BB shims React, the portal primitives, and @get-bb/plugin-sdk at runtime — never bundle them).

Run bb plugin build before publishing git/npm installs. It writes dist/server.js + server.meta.json (and, with bb.app, app.js / app.css / app.meta.json). Each *.meta.json stamps SDK major/version, artifactFormatVersion, pluginId, pluginVersion, and builtWith so managed installs can verify the artifacts.

Install

From this directory (bb plugin new already ran the install; a fresh clone needs it):

npm install
bb plugin install .

After editing sources, reload:

bb plugin reload chief-nav

Configure

bb plugin config chief-nav
bb plugin config chief-nav set greeting hi

Types & API reference

The plugin API ships as the npm package @get-bb/plugin-sdk, pinned to an exact version in devDependencies (0.4.6 — the SDK of the BB that scaffolded this plugin). After npm install, the full surface is on disk at:

node_modules/@get-bb/plugin-sdk/bundled-types/bb-plugin-sdk.d.ts      # backend
node_modules/@get-bb/plugin-sdk/bundled-types/bb-plugin-sdk-app.d.ts  # frontend

Your editor and tsc resolve @get-bb/plugin-sdk there through ordinary node resolution — no path mapping. These are readable declarations: open them for an exact signature.

The SDK surface grows with every BB release, so the pin has to track the BB you actually run:

bb plugin types          # sync this plugin's SDK surface to the running BB
bb plugin types --check  # CI: fail when it does not match

Ask BB to write plugins for you: the bb-plugin-authoring skill documents the whole surface with examples.

Confused by the API, or need something the types don't explain? Clone the BB repo and read the source: https://github.com/get-bb/bb.