Sculptured docs

Designing teams of agents

Choose roles, define handoffs and give each agent a clear job, a budget and a way to check its work.

Start with one agent and a clear task. Add agents when separate roles, independent work or a second review will help. For each agent, define what it owns, what it passes on and how you will check the result. More agents also mean more coordination and token use.

When to split work

These four reasons can help you decide whether to split the work:

ReasonExample
SpecializationA researcher, a writer and a reviewer with different instructions or models.
IsolationA reviewer with separate instructions and restricted permissions. See the permission limits below.
ParallelismIndependent chapters or components built at the same time.
ContextEach agent keeps a small context instead of one agent carrying everything.

If none applies, refine the single agent's Job before expanding the team.

Pick a pattern

PatternShape on the boardUse forWatch
Pipeline with a review loopBuilder → Reviewer ↺Work that needs implementation and reviewBound the revision rounds
Supervisor and workersLead → Workers → LeadSeparable parts that one agent integratesKeep the lead's context manageable
Independent reviewersDraft → Reviewer A + B → EditorQuality over costReviewers must not see each other's verdicts
Dynamic dispatchCoordinator → spawned specialists → AssemblyThe number of pieces is known only at run timeSet spawn, depth and token limits first

The built-in templates cover several of these: Builder → Reviewer, Planner → 2 Builders, Independent reviewers, Design and revise and Adaptive support team. The CS2680 pattern catalog has a ready-made block for each slide.

flowchart LR
  B["Builder"] -- "done" --> R["Reviewer"]
  R -- "changes" --> B
  R -- "approved" --> D(("item complete"))

Plain arrows can loop, for example a reviewer handing work back to a builder, as long as an agent outside the loop hands work into it. Each piece of work goes round such a loop at most 3 times before it stops and says so. A review loop with named outcomes and a round limit you set, like the one above, is a workflow.

Set up each agent

Select an agent on the board to open its details. These settings decide what it costs and what it can touch.

Runs on: Claude or Codex

ChoiceWhat runsModel selection
ClaudeClaude Code, with your own sign-inChoose from the model menu or use Claude's default.
CodexCodex, with your own sign-inUse the default, select a listed model or enter a model ID.

You can also set models for the whole team (Team models) or for a group (Group models). An agent's own choice wins, then its group's, then the team's. All agents run on switches every agent at once, and Ctrl+Z undoes it.

Permissions

Under Advanced in the agent's details:

SettingClaude CodeCodex
unrestricted (the default)Runs without permission promptsApprovals off, no sandbox
restrictedPermission prompts come to you as approvalsAsks before untrusted actions

Sculptured's own tools, including questions, reports and workflow calls, do not raise permission prompts. Restricted adds the CLI's approval controls; it does not make an agent read-only. Claude tool approvals are allowed automatically if their timeout expires. Read Questions and approvals before relying on those controls.

Token limit

Token limit caps the tokens an agent uses in one run. Choose which tokens count (all tokens, all except cache reads, or output only) and whether the limit should include agents it spawns. When the agent reaches the limit, Sculptured asks it to wrap up with a summary, then stops it.

Check

Check is a command Sculptured runs in the agent's folder after each turn the agent finishes, for example npm test. Exit code 0 shows "check passed"; anything else shows "check failed", with its output. A check result is verified by Sculptured; the agent's own "done" is only agent-reported. The command runs as you, with your permissions.

Briefing

With its first message every agent gets a briefing: by default (full) the team, its neighbours' jobs, the workflow and the working rules. The agent keeps it for the whole conversation and reads it again at every step, so it costs tokens on every call. Choose minimal for agents that only need their own assignments, such as workflow workers: they get only their role, their own Job and contract, their own skills, and one line on how to finish. Helpers a minimal agent starts are briefed minimally too.

Skills

Instructions the agent loads only when it needs them, such as your house style or how to run a release. Until then only their names and descriptions are in its context. See Skills and tools.

Contract and tools on its computer

Under Advanced, an agent's Contract says what it reads, writes and decides, and the values it shares with others; see Contracts. Kindex memory and Signet-Eval policy checks give it tools installed on its computer; see Skills and tools.

When it restarts

Under Advanced, When it restarts sets what happens when the agent's session has to start again: resume if possible, start fresh, or wait for me to choose.

Write each Job like a task spec

An agent's Job defines its assignment. An agent that starts immediately receives the Job as its first message. An agent waiting for upstream work receives it with its first handoff; you can still edit the Job while it waits. Use this template:

Objective: <what to achieve, in one or two sentences>
Output: <the exact file, format or message you hand on>
Done when: <a check anyone can run, e.g. "npm test passes" or "REPORT.md has these sections">
Boundaries: <what you must not touch or decide>
Budget: <rounds or time; the token limit itself is set on the agent>
Hand on: <who receives your result, and what they need from it>

The next agent receives the final reply from the completed work turn. Ask for a concise handoff that includes the result, relevant file paths, checks run and unresolved issues. Keep longer outputs in files.

When completion can be tested by a command, put that command in the agent's Check field. Set the actual Token limit in the agent's settings; a budget written in the Job is an instruction, not an enforced limit.

An agent with no Job waits: your first message to it becomes its work, and when it finishes, its result is handed on.

Let an agent draft the team

On a new project, Describe it sends your description to your own Claude Code or Codex, which drafts the team. It can ask you questions first. You choose the team size, the agent kinds and a shape, then keep or drop agents and arrows before anything is created. The team panel shows "Generated by Claude Code from a description" (or Codex) and "not run yet" until it runs. Review every Job: a drafted team is a starting point, not a checked design.

What goes wrong

FailureWhat it looks likePrevention
OverlapTwo agents edit the same fileGive each agent its own files in its Job
GapsNobody owns integration or testsName one owner for the final check
Hidden dependencies"Parallel" pieces wait on each otherMake it an arrow, or a dependent workflow item
Unmergeable outputsResults arrive in different formatsSpecify the Output format exactly
Lost context at aggregationThe lead summarises away detailsWrite results to files and pass paths
LoopsAgents message each other without endUse workflow routes with Most rounds per item

Finish with an agent Check or a workflow check stage where appropriate. Read the result alongside the agent's report to see what was tested and what still needs review.

Next steps