Skip to content

AI Workforce

SecondBrain workforces are declarative, local-first teams of background agents. They reuse existing runtime primitives instead of adding a separate agent stack:

  • roles launch as durable background sessions
  • skills are existing SKILL.md capabilities
  • toolsets and MCP remain governed capability bundles
  • project instructions and generated artifacts provide continuity
  • session automations provide recurring execution
  • Work Graph provides the portfolio dashboard context

Mental Model

The workforce layer turns the podcast-style "AI employees" framing into SecondBrain-native primitives:

Podcast concept SecondBrain primitive
employee workforce role backed by a durable background session
SOP SKILL.md skill reference in a role spec
workstation governed toolset/MCP capability bundle
manager WorkforceRunner
company handbook project/workspace instructions and repo instructions
conveyor belt existing session automations
dashboard Work Graph plus generated workforce artifacts

The important rule for v1 is review-first execution. A workforce can propose next actions, launch local background sessions, update generated continuity artifacts, and create lesson or review proposals. It does not silently send, publish, delete, or call external systems.

Roles can also carry a typed work package. Use depends_on for prerequisite roles, ownership_scope for the work boundary, shared_context for concise handoff facts, expected_outputs and acceptance_criteria for the review contract, and consumes_artifacts / produces_artifacts for artifact handoffs. Synchronous workforce runs execute dependency waves and pass normalized prerequisite handoffs into dependent role prompts. Detached runs with dependencies launch the first ready wave, persist later roles as pending, and can be resumed with sb workforce continue <run_id> after prerequisite sessions complete.

Built-In Workforce Catalog

SecondBrain ships these review-first workforces:

Workforce Purpose Schedule
portfolio_scouts Active project portfolio, stale work, risks, and lessons cron:0 9 * * 1-5
customer_success_scouts Customer commitments, follow-up risks, and customer-success lessons cron:30 9 * * 1-5
daily_operator_briefing Daily operator brief from approvals, sessions, priorities, and proposals cron:30 8 * * 1-5
context_gardeners Stale context, project knowledge sources, memory review pressure, and provenance gaps cron:0 10 * * 1
quality_guardians Quality failures, replay candidates, eval/autotune health, and regression risks cron:0 11 * * 1
integration_watchtower Local integration readiness, connector auth posture, and MCP drift cron:0 12 * * 1
developer_shiproom Manual release-readiness, docs drift, and test-plan review manual
solo_operator_agent_team Weekly research, content, operations, developer-support, and guardrail proposals cron:0 8 * * 1
x_agent_engineering_publisher Review-first X content drafts for governed AI-agent positioning cron:30 9 * * 1-5

Start with portfolio_scouts.

sb workforce show portfolio_scouts
sb workforce run portfolio_scouts --dry-run
sb workforce deploy portfolio_scouts

For the review-first X content workflow, start with a dry run:

sb workforce run x_agent_engineering_publisher --dry-run --json

Approved draft candidates can then be copied into the local social draft review queue without publishing anything externally:

sb social x drafts create --text-file ./draft.txt --pillar "Agent Engineering" --format agent_engineering_note
sb social x drafts list
sb social x drafts show <draft_id>
sb social x drafts review <draft_id> --decision approve --notes "Ready for governed publish queue."
sb social x drafts queue-publish <draft_id>
sb social x drafts history <draft_id>

portfolio_scouts uses the local provider by default and runs review-first. It does not send, publish, delete, or call external systems. It produces generated Markdown continuity artifacts under the local state directory:

<state_dir>/workforce/portfolio_scouts/
  portfolio-dashboard.md
  lessons-learned.md
  projects/<project_id>/evergreen.md
  projects/<project_id>/task-registry.md
  projects/<project_id>/flow.md

Generated project artifacts are registered as project knowledge sources so chat and project context can use them through the normal project workspace compiler. Manual edits to generated files are not imported in v1; add durable context through project instructions or project knowledge sources.

UI Workflow

Start the local daemon and open the web UI:

sb serve

In the UI, open Workforces. The route is:

/workforces?id=<workforce_id>&tab=<overview|runs|proposals|lessons|spec>

Normal operator loop:

  1. Select Portfolio Scouts.
  2. Review the dashboard counts, recent runs, review proposals, and pending lessons.
  3. Run with Dry run enabled to preview role session requests and generated artifacts.
  4. Enter one or more project ids when you want a scoped run.
  5. Use Deploy schedule to create or update the recurring session automation.
  6. Review or reject workforce proposals before acting on them.
  7. Promote lesson proposals only after reviewing their evidence.

Use New workforce to create a local overlay. The guided flow starts from a blank review team or a built-in template, then walks through identity, project selection, roles, schedule, and final YAML review. UI-created workforces are always forced to local review-first defaults: provider: local, permission_mode: ask, approval_mode: ask, write_capable: false, native chat roles, and no external connector side effects. Built-in specs are read-only in the UI; clone one into a new id to customize it.

Use Clone selected to copy any selected built-in or overlay into a new local overlay draft. Clone starts with scheduling disabled so you do not accidentally deploy duplicate recurring work. Use Edit overlay for an existing local overlay; the id stays fixed and the save path uses the authenticated PUT /workforces/{id} endpoint after validation.

The Proposals tab uses the proposal-list API, not only the selected dashboard snapshot. Filter by selected workforce, all workforces, explicit workforce id, status, and kind. The right rail also shows the most recent pending proposals across the workforce pack so review work is visible even when you are inspecting a different workforce.

The UI calls the same authenticated /workforces API used by scripts. It does not bypass the CLI, approval model, or local-only v1 constraints.

Commands

sb workforce list
sb workforce show <workforce_id>
sb workforce lint
sb workforce capabilities --json
sb workforce templates --json
sb workforce validate --file ./my_workforce.yaml --json
sb workforce create --file ./my_workforce.yaml --json
sb workforce enable <workforce_id> --json
sb workforce disable <workforce_id> --json
sb workforce run <workforce_id> --project <project_id> --dry-run
sb workforce run <workforce_id> --project <project_id> --no-detach --json
sb workforce continue <run_id> --json
sb workforce deploy <workforce_id>
sb workforce dashboard
sb workforce dashboard --workforce portfolio_scouts --json
sb workforce lessons list
sb workforce lessons review <lesson_id>
sb workforce lessons promote <lesson_id>
sb workforce proposals list --workforce <workforce_id> --status proposed
sb workforce proposals review <proposal_id>
sb workforce proposals reject <proposal_id>

Use --json on commands when integrating with the local serve UI or scripts. Inside sb chat, the equivalent operator surface is available through /workforce list, /workforce show <id>, /workforce dashboard, /workforce run <id>, and /workforce continue <run_id>.

Example Runs

Preview the committed Portfolio Scouts workflow:

sb workforce lint
sb workforce show portfolio_scouts --json
sb workforce run portfolio_scouts --dry-run --json

Scope the scouts to one project and run roles synchronously with the local provider:

sb projects list
sb workforce run portfolio_scouts --project <project_id> --no-detach --json

Deploy the weekday schedule:

sb workforce deploy portfolio_scouts --json
sb sessions automations list --json

Inspect outputs and promote a reviewed lesson:

sb workforce dashboard --workforce portfolio_scouts --json
sb workforce lessons list --workforce portfolio_scouts --status proposed --json
sb workforce proposals list --workforce portfolio_scouts --status proposed --json
sb workforce proposals review <proposal_id> --json
sb workforce lessons promote <lesson_id> --json

Serve API

With serve authentication enabled:

  • GET /workforces
  • GET /workforces/{id}
  • GET /workforces/capabilities
  • GET /workforces/templates
  • POST /workforces/validate
  • POST /workforces
  • PUT /workforces/{id}
  • POST /workforces/{id}/enable
  • POST /workforces/{id}/disable
  • POST /workforces/{id}/run
  • POST /workforces/runs/{run_id}/continue
  • POST /workforces/{id}/deploy
  • GET /workforces/dashboard
  • GET /workforces/lessons
  • GET /workforces/proposals
  • POST /workforces/lessons/{lesson_id}/promote
  • POST /workforces/proposals/{proposal_id}/review
  • POST /workforces/proposals/{proposal_id}/reject

Authoring Specs

Committed specs live in ops/workforces/. User overlays live in ~/.secondbrain/workforces/ and win by workforce id.

The safest authoring path is:

sb workforce templates --json
sb workforce validate --file ./my_workforce.yaml --json
sb workforce create --file ./my_workforce.yaml --json

create writes to ~/.secondbrain/workforces/<id>.yaml. It rejects collisions, unsafe paths, bridge engines, non-local providers, non-ask modes, unknown skills, unknown toolsets, and write_capable: true.

Minimum shape:

id: portfolio_scouts
version: 1.0.0
title: Portfolio Scouts
project_selector:
  active: true
  limit: 20
schedule: "cron:0 9 * * 1-5"
provider_policy:
  primary: local
roles:
  - id: portfolio_director
    goal: Summarize active projects and top next actions.
    engine: native
    runner_kind: chat
    provider: local
    permission_mode: ask
    depends_on: []
    ownership_scope: [portfolio/dashboard]
    expected_outputs:
      - Reviewable findings with sources and verification status.
    acceptance_criteria:
      - Proposed actions stay review-first and cite local evidence.

Run sb workforce lint after adding or changing specs.

For a complete authoring example, see examples/workforce/customer_success_scouts.yaml. For implementation details, see builders/workforce-specs.md.

Troubleshooting

  • sb workforce lint should be the first check when a workforce does not list.
  • Unknown provider names, missing skill references, unknown toolsets, and invalid schedules fail lint before runtime.
  • sb workforce run --dry-run --json shows the background session requests that would be launched for each role.
  • sb workforce continue <run_id> --json refreshes completed prerequisite sessions, launches the next ready dependency wave, and finalizes the run once all roles are complete.
  • Role toolsets are passed into native background chat sessions, and role skills are injected into the role prompt under Role SOPs.
  • Generated Markdown is not the source of truth. SQLite records under the work database are authoritative; artifacts are regenerated for agent continuity.
  • If a deployed workforce does not run on schedule, inspect the managed session automation with sb sessions automations list --json.