Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Make the Lead's instructions match the system and record the Swarm role names (#1558)

0xken15a9c1dd25e1c5
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index 152334d72..2237463b4 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -127,8 +127,8 @@ describe('Super Tab native delivery handoff', () => {
'In reply to message question-2. Read it before interpreting the answer:'
), 'team:service:superTabs:delivery')
expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain('Message message from Collaborator:\nYes, keep them.')
- expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain('On Claude Code or Codex, Leads use swarm-lead, workers swarm-dev and Reviewers swarm-review.')
- expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain('Leads coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and small fixes yourself; your subagents only read/look up.')
+ expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain('On Claude Code or Codex, Leads use swarm-lead, Builders swarm-dev and Reviewers swarm-review.')
+ expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain('Leads coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and work under 15 minutes yourself; your subagents only read/look up.')
})
it('keeps a slow configuration observation out of the native delivery and lease path', async () => {
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index 1ef9eb0d6..d9ce46d6e 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -105,7 +105,7 @@ const SUPER_TAB_REPLY_STYLE = 'Write to the people in this tab like a helpful co
+ 'Do not describe your own tools or permission prompts unless that blocks what they asked. '
+ 'Answer each message once: post with --reply-to MESSAGE_ID. If you have already answered a message, do not post again. '
+ 'When you hand over finished work, give the result with the revision and links they need. '
- + 'Lead: when a worker finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon.'
+ + 'Lead: when a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon.'
/** Owns only the handoff between a durable backend claim and the core's native input.
* A process restart never interprets a lost acknowledgement as permission to type twice. */
@@ -627,7 +627,7 @@ export class SuperTabHost {
return `You are participating in a shared Super Tab conversation (${group}). Other humans and agents see messages posted there.\n`
+ `Read its state: ${command} status\nRead this conversation: ${command} messages ${shellQuote(group)}\n`
+ `Reply there: ${command} post ${shellQuote(group)} 'your message' UNIQUE_OPERATION_ID --reply-to ${shellQuote(String(message.id))}\n`
- + `Manage agreed work and delegation: ${command} help. Leads: route before starting or assigning: ${command} route GROUP JSON. Each task needs goal, changes, constraints, owned code and acceptance checks. On Claude Code or Codex, Leads use swarm-lead, workers swarm-dev and Reviewers swarm-review. Leads coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and small fixes yourself; your subagents only read/look up.\n`
+ + `Manage agreed work and delegation: ${command} help. Leads: route only when starting an agent or assigning work to another agent (not work you do yourself): ${command} route GROUP JSON. Each task needs goal, changes, constraints, owned code and acceptance checks. On Claude Code or Codex, Leads use swarm-lead, Builders swarm-dev and Reviewers swarm-review. Leads coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and work under 15 minutes yourself; your subagents only read/look up.\n`
+ `Ask questions and post results in this conversation. ${SUPER_TAB_REPLY_STYLE} Replies to these delivered instructions must be posted here explicitly.\n\n`
+ native + reply + `Message ${String(message.id)} from ${String(object(message.author).name ?? 'a collaborator')}:\n${message.text}`
+ (files ? `${message.text ? '\n\n' : ''}${files}` : '')
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 3ead7f60f..2ac620d3d 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -544,7 +544,7 @@ it('documents finished worker decisions and explains an older backend without re
? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid request' } } } as never
: { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })
const reply = await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'release', command: { type: 'agent.release', agentId: 'worker', decision: 'stop' } }, owner)
- expect(reply).toMatchObject({ detail: 'This backend does not support releasing workers yet. Update the backend and try again.' })
+ expect(reply).toMatchObject({ detail: 'This backend does not support releasing Builders yet. Update the backend and try again.' })
})
describe('the Swarm cards the devices ask for', () => {
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 24bebe294..33a76b3ba 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -18,9 +18,9 @@ const HELP = {
message: 'message GROUP MESSAGE_ID: read one exact message, including an earlier question or result referenced by a reply.',
post: 'post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: reply in that conversation. Use a unique ID per message and reuse it after an interrupted request. Answer a message once, with --reply-to its ID. --attach sends a file (a screenshot, a log; up to 10 files of 10 MB each), and TEXT may then be empty.',
start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work. With worktree true, the agent starts from the repository\'s default branch, fetched first, unless you set branchRef (refs/heads/BRANCH, or refs/remotes/origin/BRANCH to fetch it first) to start from another branch, such as the one this work builds on. Set role "reviewer" to start a Reviewer; leave role out for a Builder. The role is kept for the session. A Reviewer runs on claude or codex and is assigned only review groups (conversation.create with reviewOf naming the group it reviews); a review group is assigned only to a Reviewer. Add the Reviewer to the reviewed group with conversation.agent so it is told when that work is ready for review and can pass its independent check. Start one with a routeDecisionId like any agent.',
- release: 'When a worker finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',
+ release: 'When a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',
resume: 'resume START_ID: finish a pending start without creating another agent.',
- route: 'route GROUP JSON: before starting or assigning work, choose who does it. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',
+ route: 'route GROUP JSON: before you start an agent or assign work to another agent, choose who does it. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',
capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',
startRequest: { conversationId: 'GROUP', machineId: 'MACHINE', engine: 'codex', name: 'Builder', cwd: '/absolute/repo/on/that/machine', worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH', requirements: START_REQUIREMENTS,
model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },
@@ -279,7 +279,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
let value: unknown
try { value = await send(command) } catch (error) {
if (command.type === 'agent.release' && error instanceof SuperTabHostError && error.status === 400 && ['VALIDATION_ERROR', 'INVALID_REQUEST'].includes(error.code)) {
- return { error: 'RELEASE_UNSUPPORTED', detail: 'This backend does not support releasing workers yet. Update the backend and try again.' }
+ return { error: 'RELEASE_UNSUPPORTED', detail: 'This backend does not support releasing Builders yet. Update the backend and try again.' }
}
if (!['conversation.create', 'work.define'].includes(String(command.type)) || !command.task || !(error instanceof SuperTabHostError)) throw error
const oldSchema = error.status === 400 && error.code === 'VALIDATION_ERROR'
diff --git a/desktop/lib/super_tabs/launch_prompt.dart b/desktop/lib/super_tabs/launch_prompt.dart
index a5905b774..89b615d30 100644
--- a/desktop/lib/super_tabs/launch_prompt.dart
+++ b/desktop/lib/super_tabs/launch_prompt.dart
@@ -7,15 +7,15 @@ String superTabLaunchPrompt({
required bool lead,
}) =>
'Harness Swarm agent. '
- '${lead ? 'You lead this project. Discuss first; build when authorized. On Claude Code or Codex, use swarm-lead. Coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and small fixes yourself; your subagents only read/look up. ' : 'On Claude Code or Codex, use swarm-dev. '}'
+ '${lead ? 'You are the Lead. Discuss first; build when authorized. On Claude Code or Codex, use swarm-lead. Coordinate: assign multi-part or 15+ minute work to Swarm agent groups; do only answers, lookups and work under 15 minutes yourself; your subagents only read/look up. ' : 'On Claude Code or Codex, use swarm-dev. '}'
'Use `harness super-tab --tab $tabId` subcommands. '
'First: `status`. Retry AGENT_UNAVAILABLE briefly; do not work or post before registration. '
'Read `messages $conversationId` for the full request; if empty, ask what to work on. '
'Reply: `post GROUP "message" UNIQUE_OPERATION_ID [--reply-to MESSAGE_ID]`. '
- 'Use --reply-to for existing messages; answer each message once, do not post again. Retry lost replies with the same operation ID and text. '
- 'Terminal output is not shared chat. If sandbox blocks commands, request permission. Use `help` for syntax. '
- '${lead ? 'Before work/assignment, `route GROUP JSON` with difficulty, risk, size (small, medium or large); use routeDecisionId or explicit overrideReason. Explain NO_CANDIDATE reasons in chat. ' : ''}'
+ 'Use --reply-to for existing messages; answer each message once, do not post again. Retry lost replies with the same ID and text. '
+ 'Terminal output is not shared chat. If sandbox blocks commands, request permission. '
+ '${lead ? 'Route only to start an agent or assign work, never your own: `route GROUP JSON` with difficulty, risk, size (small, medium or large); use routeDecisionId or explicit overrideReason. Explain NO_CANDIDATE reasons in chat. ' : ''}'
'Reuse agents and groups. Each task needs goal, changes, constraints, owned paths, checks. '
- "${lead ? 'When a worker finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. ' : ''}"
+ "${lead ? 'When a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. ' : ''}"
'Be a helpful colleague: answer first, in their language, under 150 words unless asked. Hide commands, internal IDs and field names. Give results with revision/links. '
'${lead ? 'Update Lead chat: plan, progress, blockers, next steps. At project cadence, read new reports and consolidate them. No per-turn summarizer. Answer questions, blockers and completion immediately. On scheduled requests use project.report for updates or text:null when nothing changed. Scope workgroups and sessions to this project.' : ''}';
diff --git a/desktop/test/super_tab_launch_test.dart b/desktop/test/super_tab_launch_test.dart
index c8ab4e35a..48db4080b 100644
--- a/desktop/test/super_tab_launch_test.dart
+++ b/desktop/test/super_tab_launch_test.dart
@@ -873,6 +873,10 @@ void main() {
.firstWhere((c) => c.$1 == 'agent_create')
.$2['prompt']
as String;
+ expect(
+ prompt,
+ contains('Route only to start an agent or assign work, never your own'),
+ );
expect(prompt, contains('route GROUP'));
expect(prompt, contains('size (small, medium or large)'));
expect(prompt, contains('routeDecisionId'));
diff --git a/desktop/test/super_tab_startup_recovery_test.dart b/desktop/test/super_tab_startup_recovery_test.dart
index ac4d45a5f..72d1cb585 100644
--- a/desktop/test/super_tab_startup_recovery_test.dart
+++ b/desktop/test/super_tab_startup_recovery_test.dart
@@ -50,7 +50,7 @@ void main() {
prompt.length,
lessThanOrEqualTo(kFirstTaskMaxLength),
reason:
- '${lead ? 'Lead' : 'Worker'} bootstrap must fit native creation',
+ '${lead ? 'Lead' : 'Builder'} bootstrap must fit native creation',
);
expect(
prompt,
@@ -63,10 +63,7 @@ void main() {
if (lead) {
expect(prompt, contains('Discuss first; build when authorized.'));
expect(prompt, contains('Swarm agent groups'));
- expect(
- prompt,
- contains('do only answers, lookups and small fixes yourself'),
- );
+ expect(prompt, contains('do only answers, lookups and work under 15 minutes yourself'));
expect(prompt, contains('your subagents only read/look up'));
expect(
prompt,
@@ -78,22 +75,25 @@ void main() {
}
});
- test('lead bootstrap retains report reading and worker release guidance', () {
- final prompt = superTabLaunchPrompt(
- tabId: 'a' * 160,
- conversationId: 'b' * 160,
- lead: true,
- );
- expect(prompt, contains('read new reports'));
- expect(prompt, contains('No per-turn summarizer'));
- expect(
- prompt,
- contains('When a worker finishes, decide reuse, keep or stop'),
- );
- expect(prompt, contains('prefer stop unless more work is coming soon'));
- expect(prompt, contains('On scheduled requests use project.report'));
- expect(prompt, contains('text:null when nothing changed'));
- });
+ test(
+ 'lead bootstrap retains report reading and Builder release guidance',
+ () {
+ final prompt = superTabLaunchPrompt(
+ tabId: 'a' * 160,
+ conversationId: 'b' * 160,
+ lead: true,
+ );
+ expect(prompt, contains('read new reports'));
+ expect(prompt, contains('No per-turn summarizer'));
+ expect(
+ prompt,
+ contains('When a Builder finishes, decide reuse, keep or stop'),
+ );
+ expect(prompt, contains('prefer stop unless more work is coming soon'));
+ expect(prompt, contains('On scheduled requests use project.report'));
+ expect(prompt, contains('text:null when nothing changed'));
+ },
+ );
for (final engine in ['codex', 'claude']) {
for (final newProject in [false, true]) {
diff --git a/docs/naming-system.md b/docs/naming-system.md
index ab7f5f3fa..ef82e5606 100644
--- a/docs/naming-system.md
+++ b/docs/naming-system.md
@@ -55,8 +55,9 @@ and **Browser**. Technical documentation may still call the terminal interface a
| **Tab** | A workspace group of harnesses. | Frontend and Backend tabs. |
| **Swarm** | A collaborative tab containing projects, people, agents and contributed machines. Invite-only by default; its owner can enable joining by email domain or a shared link. | Open your company Swarm beside your regular tabs. |
| **Project in a Swarm** | An initiative with its own product manager, repository, sharing and workgroups. | Discuss Lamp OS with its product manager; expand it to follow a workgroup. |
-| **Product Manager** | The agent coordinating a Swarm project. Use **PM** in a compact role badge. | Message Product Manager. |
-| **Engineer** | An agent carrying out project work. Use **Dev** in a compact role badge. | Atlas is an engineer on Lamp OS. |
+| **Product Manager** | The agent coordinating a Swarm project. Use **PM** in a compact role badge. System name: lead. | Message Product Manager. |
+| **Engineer** | An agent carrying out project work. Use **Dev** in a compact role badge. System name: builder. | Atlas is an engineer on Lamp OS. |
+| **Reviewer** | An agent that reviews project work. Use **Rev** in a compact role badge. System name: reviewer. | Atlas is a reviewer on Lamp OS. |
| **Workgroup** | A numbered conversation for an independently assignable outcome within a project. | Follow #12 Offline editing. |
| **Pane** | A visible view of a harness, terminal, or viewer. | Split right; close pane. |
| **Terminal** | A shell for entering commands. | New terminal. |
@@ -71,6 +72,18 @@ and **Browser**. Technical documentation may still call the terminal interface a
| **Conversation** | An agent's conversation history, including histories started outside Harness. | Provider usage counts native conversations. |
| **Recorded run** | A saved demonstration of a harness doing work. | Watch the recorded run in the Store. |
+The three Swarm roles, on screen and inside the system:
+
+| Role | On screen | Short label | System name | Skill |
+| --- | --- | --- | --- | --- |
+| Coordinates | Product Manager | PM | lead | swarm-lead |
+| Builds | Engineer | Dev | builder | swarm-dev |
+| Reviews | Reviewer | Rev | reviewer | swarm-review |
+
+People see the on-screen name and short label. Agent-facing text (prompts, skills,
+CLI help) may use the system names Lead, Builder and Reviewer. The Lead does only
+answers, lookups and work under 15 minutes itself, and routes the rest.
+
Use lowercase *harness* and *tab* in ordinary sentences. The action and context
distinguish the two uses of *harness*: install or update a package in the Store;
start, pause, or stop a running harness in the workspace. Keep **agent** for choosing