Skip to content

Worker Builder Playbook

Primary doc: /home/justinwieb/forge/memory/handoffs/worker-builder-playbook-2026-04-23.md

The Worker Builder role (.claude/agents/ candidate for codification — not yet written as a standalone agent def) is the artisan of the fleet's most-used motion: shipping new workers. Agent: wb-meta (Opus47) remote-control session (persistent while alive).

When to consult this doc

Before spawning anything. Every time. The playbook answers: 1. What shape? — subagent vs dispatcher task vs remote-control vs agent def vs skill vs hook vs n8n trigger vs cron/SDK daemon 2. Which model? — Opus vs Sonnet vs Haiku, with the "why not cheaper?" justification 3. What goes in the briefing? — 7-part recipe (role, context load, current state, constraints, tools, deliverable, post-actions) 4. What's the name? — session/file/agent naming conventions 5. Does something already exist? — pointers to chief-director briefing + MEMORY.md + .claude/agents/ for dedup 6. Will this spawn regret itself? — the anti-patterns list

Key rules codified

  • Remote-control is sticky — use for emergent conversations only, not bounded one-shots (see Case B: PressYourLuck)
  • Opus requires a "why not Sonnet?" justification — always
  • If a Python library can do it, don't pay Claude to do it — pollers, health checks, CRUD → scripts (see Case C: wellness pollers)
  • State is a service, not a session — Context API pattern (see Case E)
  • Never hand-edit .claude/settings.json — use update-config skill
  • Credentials always via ~/.forge-secrets/ or n8n cred IDs — never inline in briefings
  • Every session needs a retirement criterion — otherwise they accumulate (see chief-director briefing: 9 stale sessions)
  • BootUpAutoRemote spec: CLAUDE.md:160
  • Dispatcher: scripts/dispatcher.sh + Task Queue Dispatcher
  • n8n task creator: infra/n8n/task-creator.sh + n8n Task Creator
  • Notifications: scripts/notify.sh + Notification System
  • Agent definitions: .claude/agents/ (README in same dir)
  • Skills: .claude/skills/ — /notify, /fleet-status, /create-task, /spawn-worker, /context
  • Fleet state source-of-truth: memory/handoffs/chief-director-briefing-YYYY-MM-DD.md

Update triggers

Update the primary doc when: - A new worker shape enters the fleet - A case study's lesson gets resolved or disproved - An anti-pattern becomes a pattern (or vice versa) - Cost routing shifts (model pricing, new tier lands)