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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: unknowntry { 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 errorconst 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.dartindex 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.dartindex 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.dartindex 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.mdindex 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 contextdistinguish 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