SwarmbuilderRead in French

Chief of Staff: orchestrating Claude Code subagents

Updated on

A Chief of Staff is an agent that runs the main Claude Code session: it plans the work, hands it to specialist subagents, then checks and merges their results. This guide explains the pattern, how to start it, and how Swarmbuilder generates its files. Back to the home page.

The Chief of Staff pattern

In this pattern, a team of Claude Code agents has two roles. The Chief of Staff does not do the specialized work: it receives the request, splits it, picks the right specialist for each part, and returns a checked answer. The specialists are subagents that each handle one precise part.

  • The Chief clarifies the goal of the request.
  • It splits the work into parts that each have an end criterion.
  • It hands each part to a specialist with a self-contained brief, then gathers the reports.

The pattern comes down to one rule: the main session coordinates, it does not write everything. A trivial task stays with the Chief; a complex task is split between agents with distinct roles.

Why subagents

A subagent starts with its own context: it does not see the main conversation, only the brief it receives. Heavy tasks (reading many files, running a test suite, reviewing a diff) fill that context. If everything happens in one session, coordination drowns in details. With subagents, the details stay in their context, and the main session keeps its own to decide.

Key point

A subagent does not share the history of the main session. Put everything it needs in the brief: goal, expected output, sources and limits.

There is a cost too: each agent adds latency and uses tokens. Start an agent only when the task justifies it, and do not multiply agents for a simple request.

Start the Chief in Claude Code

The Chief’s file is an agent like the others, placed in .claude/agents/. To make it lead the session, start Claude Code with the --agent option:

claude --agent chief-of-staff

To make it the default for the project, add the agent key to .claude/settings.json. The command-line option takes precedence over this setting. The file probably holds other settings: add only the key and keep the rest.

{
  "agent": "chief-of-staff"
}

This main session takes the tool restrictions and the model of the Chief. The details are in the official subagent documentation.

Specialists in .claude/agents/

Each specialist is a Markdown file in .claude/agents/. An agent placed in ~/.claude/agents/ applies to all your projects. When two agents have the same name, the project version wins. The locations are described in the official documentation.

---
name: tester
description: Writes and runs the vitest tests for a change. Use after the code is written.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
---

Write tests for the change, run them, and report the results in the format the brief asks for.
  • name and description are the only required fields. The description matters most: the main session reads it to choose a specialist.
  • tools lists the allowed tools. If you omit it, the agent inherits all the tools available.
  • model accepts sonnet, opus, haiku, a full model identifier, or inherit.
  • Other common fields are disallowedTools, maxTurns, effort and permissionMode.

A specialist does not need to start other agents. Remove Agent from its tool list, or add it to disallowedTools: the next section explains the rule.

Rules for a good Chief

These rules come from practice with this pattern. They are not guarantees from Claude Code: a prompt is an instruction, not a constraint. The model may not follow it, so read the reports.

  1. Write a self-contained brief for each delegation: goal, output format, sources and tools, limits of the task.
  2. Split each step into sub-steps, each with a checkable end criterion.
  3. Start a fresh agent for each sub-step instead of resuming an agent whose history has grown.
  4. Require a compact report: no log, no pasted command output.
  5. Group the checks: targeted tests while working, then the full suite, lint and build once per step.
  6. Never start the Chief as a subagent. It leads the session; it is not a specialist.
  7. Remove Agent from the specialists’ tools, so they do not start their own subagents.

By default, a subagent can start its own subagents, up to three levels below the main conversation. The simplest way to stop this is to leave Agent out of the tool list:

tools: Read, Glob, Grep, Edit, Write, Bash

Setting CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 also disables nesting. The Chief keeps the Agent tool, since it is the one that delegates.

What Swarmbuilder generates

Swarmbuilder writes the Chief into its own file, .claude/agents/chief-of-staff.md, with its team, its delegation rules and the reporting protocol. The shared context (goal and conventions) goes into .claude/rules/swarmbuilder.md. The ZIP never writes a CLAUDE.md file, so your existing one is never replaced.

- **`architect`** — À utiliser avant un changement qui touche plusieurs zones (front, serveur, MCP, export) : rend un plan par étapes, en lecture seule. _(when: avant un changement multi-zones)_
- **`ui-dev`** — À utiliser pour l’interface : écrans, canvas React Flow, panneaux, i18n, marketplace, page d’accueil, SEO et visite guidée. _(when: interface, i18n, marketplace)_
- **`export-engineer`** — À utiliser pour les fichiers générés (.claude/, SDK, swarm.json, ZIP), l’import d’une config existante, le plan d’écriture et le serveur MCP. _(when: export, import, MCP)_
- **`model-engineer`** — À utiliser pour le schéma zod du swarm, le store, la validation, le lint des prompts, le poids d’orchestration, les profils et les templates. _(when: schéma, lint, templates)_
- **`server-engineer`** — À utiliser pour le serveur Fastify hors MCP : routes, comptes, sessions, crédits, base SQLite et migrations, e-mails, invitations. _(when: serveur, comptes, crédits, base)_
- **`devops`** — À utiliser pour le Dockerfile, docker-compose, docker/deploy.sh et update.sh, les variables d’environnement, la sauvegarde et la mise en production. _(when: Docker, déploiement)_
- **`tester`** — À utiliser pour écrire et lancer les tests vitest (front et serveur) et les parcours e2e, et diagnostiquer les échecs. _(when: quand le code est prêt)_
- **`reviewer`** — À utiliser après une implémentation : relit le git diff pour la correction, les invariants et la sécurité du serveur, sans rien modifier. _(when: quand les tests passent)_
- **`doc-writer`** — À utiliser quand le comportement visible change : met à jour le README, TODO.md, le changelog des nouveautés et les textes d’aide. _(when: si le comportement visible change)_
Excerpt from the “Delegation rules” section, exported in English.

This excerpt is real export output, shown without changes. Each agent appears with its description and its delegation condition.

Do not edit this file by hand

It is rewritten on every export. Change the team in the editor, then export again: a manual edit here is overwritten.

Build your team

There are two ways. In the editor, you draw the team on the canvas, set each agent, then export a ZIP to unzip at the root of your project. From Claude Code, the Swarmbuilder MCP server proposes a team for the current project, and Claude Code writes the files itself. The MCP path goes like this:

  1. Connect the server once, with the command below.
  2. Ask Claude Code for a team for the current project.
  3. Read the preview and the proposed team before anything is written.
  4. Let Claude Code write the files, then start the Chief with claude --agent chief-of-staff.
claude mcp add --transport http --scope user swarmbuilder https://swarmbuilder.fr/mcp

The address is this service’s; if you read https://<domaine>, replace it with your service address. Its administrator must have opened MCP access. Sign-in uses OAuth, in the browser, with your account: there is no key to copy. In Claude Code, run /mcp, choose swarmbuilder, then “Authenticate”. Only generating the files uses credits; the preview and the validation use none.

Sources