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.

Reviewer is a real Swarm role (backend, CLI, skills) (#1568)

0xken151d0e04ba91d9
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 49281e2fc..a419fe254 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, it } from 'vitest'
import { applyCommand, commandSchema, PAIR_CHAIN_LIMIT, type Command, type CommandContext } from './commands.js'
import { machineSlots } from './machines.js'
-import { activeWork, createSuperTab, visibleState, type Actor, type AgentConfiguration } from './model.js'
+import { activeWork, agentRole, createSuperTab, visibleState, type Actor, type AgentConfiguration } from './model.js'
import type { RouteDecision } from './routeRecord.js'
const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }
@@ -1008,3 +1008,157 @@ it('allows routing directly to the awaiting worker without first keeping it', ()
const decision = record({ candidates: [candidate('c0', { kind: 'member', agentId: f.worker, machineId: 'host' })], pick: 'c0' })
expect(f.run({ type: 'route.record', conversationId: group, decision } as Command, f.leadActor).routeDecisions).toHaveLength(1)
})
+
+describe('Reviewer role', () => {
+ const contribution = { machineOwnerId: 'target-owner', contributorId: 'owner' }
+ const request = (group: string, extra: Record<string, unknown> = {}) => ({ conversationId: group, machineId: 'host', engine: 'claude', name: 'Reviewer',
+ cwd: '/repo', worktree: true, requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false }, ...extra })
+ function reviewed() {
+ const f = fixture(), lead = f.add('lead', 'owner', 'lead', true), group = f.group()
+ const leadActor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' } as const
+ f.run({ type: 'conversation.agent', conversationId: group, agentId: lead, present: true, lead: true })
+ const start = { type: 'agent.start', request: request(group, { role: 'reviewer' }) } as Command
+ expect(() => f.run(start, leadActor, { contribution })).toThrow('Route this task first')
+ const startId = f.run({ ...start, ...via } as Command, leadActor, { contribution, ...decisionIn(group) }).result.startId as string
+ f.run({ type: 'agent.startDispatch', startId }, leadActor, { contribution })
+ const reviewer = f.run({ type: 'agent.started', startId, harnessId: 'native-reviewer', configuration: { ...config, engine: 'claude' } }, leadActor, { contribution }).result.agentId as string
+ const builder = f.add('builder', 'owner', group)
+ return { f, lead, leadActor, group, reviewer, builder }
+ }
+
+ it('stores the role chosen at start and reads agents without one as Builders', () => {
+ const { f, reviewer, builder } = reviewed()
+ expect(f.state.agents.find(a => a.id === reviewer)).toHaveProperty('role', 'reviewer')
+ expect(f.state.agents.find(a => a.id === builder)).not.toHaveProperty('role')
+ expect(agentRole(f.state.agents.find(a => a.id === builder)!)).toBe('builder')
+ expect(commandSchema.safeParse({ type: 'agent.start', request: request('g', { role: 'lead' }) }).success).toBe(false)
+ })
+
+ it('starts a Reviewer only on Claude Code or Codex', () => {
+ const f = fixture(), group = f.group()
+ expect(() => f.run({ type: 'agent.start', request: request(group, { role: 'reviewer', engine: 'opencode' }) } as Command, owner, { contribution })).toThrow('Claude Code or Codex')
+ })
+
+ it('refuses to assign, route work to or make a Lead of a Reviewer', () => {
+ const { f, leadActor, group, reviewer } = reviewed()
+ expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: reviewer })).toThrow('Reviewer')
+ expect(() => f.run({ type: 'conversation.agent', conversationId: group, agentId: reviewer, present: true, lead: true })).toThrow('Reviewer')
+ expect(() => f.run({ type: 'agent.add', conversationId: group, machineId: 'host', harnessId: 'native-reviewer', name: 'Reviewer', configuration: config, lead: true },
+ owner, { contribution: { machineOwnerId: 'target-owner', contributorId: 'owner' } })).toThrow('cannot lead')
+ expect(f.state.conversations.find(c => c.id === group)!.leadId).toBe(leadActor.agentId)
+ const pick = record({ candidates: [candidate('c0', { kind: 'member', agentId: reviewer, machineId: 'host' })], pick: 'c0' })
+ expect(() => f.run({ type: 'route.record', conversationId: group, decision: pick } as Command, leadActor)).toThrow('only review groups')
+ })
+
+ it('assigns a review group only to a Reviewer, which passes the reviewed group\'s independent check', () => {
+ const { f, leadActor, group, reviewer, builder } = reviewed()
+ const checks = [{ description: 'Verdict on the revision', independent: false }]
+ const create = (reviewOf: string) => f.run({ type: 'conversation.create', title: 'Review: Offline editing', brief: 'Review head abc.', reviewOf, checks }, leadActor)
+ expect(() => create('lead')).toThrow('one build group')
+ const archived = f.group()
+ f.run({ type: 'conversation.archive', conversationId: archived, archived: true })
+ expect(() => create(archived)).toThrow('Reopen this conversation')
+ const review = create(group).result.conversationId as string
+ expect(() => create(review)).toThrow('one build group')
+ expect(f.state.conversations.find(c => c.id === review)).toHaveProperty('reviewOf', group)
+ expect(f.state.conversations.find(c => c.id === group)).not.toHaveProperty('reviewOf')
+ const pick = (agentId: string) => record({ candidates: [candidate('c0', { kind: 'member', agentId, machineId: 'host' })], pick: 'c0' })
+ expect(() => f.run({ type: 'route.record', conversationId: review, decision: pick(builder) } as Command, leadActor)).toThrow('only to a Reviewer')
+ f.run({ type: 'route.record', conversationId: review, decision: pick(reviewer) } as Command, leadActor)
+ expect(() => f.run({ type: 'work.assign', conversationId: review, agentId: builder })).toThrow('only to a Reviewer')
+ const built = f.run({ type: 'work.assign', conversationId: group, agentId: builder }).result.assignmentId as string
+ const assignmentId = f.run({ type: 'work.assign', conversationId: review, agentId: reviewer }).result.assignmentId as string
+ const reviewerActor: Actor = { kind: 'agent', agentId: reviewer, machineOwnerId: 'target-owner' }
+ const checkId = f.state.conversations.find(c => c.id === group)!.checks[0]!.id
+ f.run({ type: 'work.check', conversationId: group, assignmentId: built, checkId, passed: true, evidence: 'Ready: yes — revision abc' }, reviewerActor)
+ expect(f.state.conversations.find(c => c.id === group)!.checks[0]!.passedBy).toBe(`agent:${reviewer}`)
+ // While its review is active it is busy; when it is done, the Lead decides its fate like a Builder's.
+ expect(() => f.run({ type: 'agent.release', agentId: reviewer, decision: 'stop' }, leadActor)).toThrow('active work')
+ f.run({ type: 'work.status', conversationId: review, assignmentId, status: 'stopped', result: null }, owner, { confirmedStopped: true })
+ f.run({ type: 'work.cancel', conversationId: group, assignmentId: built, reason: 'Obsolete' }, leadActor)
+ expect(f.state.agents.find(a => a.id === reviewer)).toHaveProperty('workDecision', 'awaiting')
+ f.run({ type: 'agent.release', agentId: reviewer, decision: 'stop' }, leadActor)
+ })
+
+ it('tells the Lead and the group\'s Reviewers when work is ready for review', () => {
+ const { f, lead, group, reviewer, builder } = reviewed()
+ const other = f.group()
+ f.run({ type: 'conversation.agent', conversationId: other, agentId: reviewer, present: true, lead: false })
+ const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: builder }).result.assignmentId as string
+ const builderActor: Actor = { kind: 'agent', agentId: builder, machineOwnerId: 'host-owner' }
+ const ready = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'review', result: 'Head abc123' }, builderActor)
+ expect(ready.messages[0]!.recipients).toEqual([lead, reviewer])
+ expect(f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'working', result: null }, builderActor).messages[0]!.recipients).toEqual([])
+ // A Lead marking the work ready tells only the Reviewers; a Reviewer removed from the group is not told.
+ expect(f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'review', result: 'Head def456' }, { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }).messages[0]!.recipients).toEqual([reviewer])
+ f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'working', result: null }, builderActor)
+ f.run({ type: 'conversation.agent', conversationId: group, agentId: reviewer, present: false, lead: false })
+ expect(f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'review', result: 'Head 789' }, builderActor).messages[0]!.recipients).toEqual([lead])
+ })
+
+ it('does not wake a Reviewer that is stopping', () => {
+ const { f, lead, leadActor, group, reviewer, builder } = reviewed()
+ f.run({ type: 'agent.release', agentId: reviewer, decision: 'stop' }, leadActor)
+ const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: builder }).result.assignmentId as string
+ const ready = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'review', result: 'Head abc' }, { kind: 'agent', agentId: builder, machineOwnerId: 'host-owner' })
+ expect(ready.messages[0]!.recipients).toEqual([lead])
+ })
+
+ it('refuses to keep or stop a Reviewer while a group it is in has active work', () => {
+ const { f, leadActor, group, reviewer, builder } = reviewed()
+ const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: builder }).result.assignmentId as string
+ for (const decision of ['keep', 'stop'] as const) {
+ expect(() => f.run({ type: 'agent.release', agentId: reviewer, decision }, leadActor)).toThrow('reviewing active work')
+ }
+ f.run({ type: 'work.cancel', conversationId: group, assignmentId, reason: 'Obsolete' }, leadActor)
+ f.run({ type: 'agent.release', agentId: reviewer, decision: 'stop' }, leadActor)
+ expect(f.state.agents.find(a => a.id === reviewer)).toHaveProperty('workDecision', 'stop')
+ })
+
+ it('lets the Lead keep or stop a Reviewer that never had work, but not such a Builder', () => {
+ const { f, leadActor, reviewer, builder } = reviewed()
+ f.run({ type: 'agent.release', agentId: reviewer, decision: 'keep' }, leadActor)
+ expect(f.state.agents.find(a => a.id === reviewer)).toHaveProperty('workDecision', 'keep')
+ f.run({ type: 'agent.release', agentId: reviewer, decision: 'stop' }, leadActor)
+ expect(f.state.agents.find(a => a.id === reviewer)).toHaveProperty('workDecision', 'stop')
+ expect(() => f.run({ type: 'agent.release', agentId: builder, decision: 'stop' }, leadActor)).toThrow('no finished assignment')
+ })
+
+ it('makes the group\'s idle Reviewers await the Lead\'s decision when its work ends, and counts adding one to a group as reuse', () => {
+ const { f, leadActor, group, reviewer, builder } = reviewed()
+ const other = f.group(), busy = f.group(), otherBuilder = f.add('other-builder', 'owner', busy)
+ f.run({ type: 'conversation.agent', conversationId: busy, agentId: leadActor.agentId, present: true, lead: true })
+ const decision = (id: string) => f.state.agents.find(a => a.id === id)!.workDecision
+ const finish = (g: string, worker: string) => {
+ const assignmentId = f.run({ type: 'work.assign', conversationId: g, agentId: worker }).result.assignmentId as string
+ return () => f.run({ type: 'work.cancel', conversationId: g, assignmentId, reason: 'Obsolete' }, leadActor)
+ }
+ // Still reviewing another group's active work: not awaiting yet.
+ f.run({ type: 'conversation.agent', conversationId: busy, agentId: reviewer, present: true, lead: false })
+ const endBusy = finish(busy, otherBuilder)
+ finish(group, builder)()
+ expect(decision(reviewer)).toBeUndefined()
+ endBusy()
+ expect(decision(reviewer)).toBe('awaiting')
+ expect(visibleState(f.state, owner).agents.find(a => a.id === reviewer)).toHaveProperty('workDecision', 'awaiting')
+ // Start, route and assign elsewhere wait for the decision (the Builders are decided first).
+ f.run({ type: 'agent.release', agentId: builder, decision: 'keep' }, leadActor)
+ f.run({ type: 'agent.release', agentId: otherBuilder, decision: 'keep' }, leadActor)
+ f.run({ type: 'work.define', conversationId: other, brief: 'Next', checks: [{ description: 'Done', independent: false }] })
+ expect(() => f.run({ type: 'work.assign', conversationId: other, agentId: builder, ...via }, leadActor, decisionIn(other))).toThrow('reuse, keep or stop')
+ // Adding it to that group reuses it.
+ f.run({ type: 'conversation.agent', conversationId: other, agentId: reviewer, present: true, lead: false })
+ expect(decision(reviewer)).toBeUndefined()
+ f.run({ type: 'work.assign', conversationId: other, agentId: builder, ...via }, leadActor, decisionIn(other))
+ })
+
+ it('keeps a Reviewer that stays in its group reused for that group\'s next attempt', () => {
+ const { f, leadActor, group, reviewer, builder } = reviewed()
+ const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: builder }).result.assignmentId as string
+ f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'stopped', result: null }, owner, { confirmedStopped: true })
+ expect(f.state.agents.find(a => a.id === reviewer)!.workDecision).toBe('awaiting')
+ f.run({ type: 'work.define', conversationId: group, brief: 'Again', checks: [{ description: 'Done', independent: false }] })
+ f.run({ type: 'work.assign', conversationId: group, agentId: builder, ...via }, leadActor, decisionIn(group))
+ expect(f.state.agents.find(a => a.id === reviewer)).not.toHaveProperty('workDecision')
+ })
+})
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 9a9f97471..0acee3b42 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -2,9 +2,9 @@ import { admitMachineStart, machineContribution } from './machines.js'
import { assignAgentDisplayNames } from './agentNames.js'
import { z } from 'zod'
import {
- activeWork, actorKey, agent, author, conversation, fail, person, stableId, numberConversations, nextConversationNumber, renderWorkTask,
- finishWorker, requireWorkerDecisions,
- type Actor, type Agent, type Author, type CommandEffects, type SuperTabState,
+ activeWork, actorKey, agent, agentRole, author, conversation, fail, person, stableId, numberConversations, nextConversationNumber, renderWorkTask,
+ finishWorker, requireWorkerDecisions, reviewing,
+ type Actor, type Agent, type Author, type CommandEffects, type Conversation, type SuperTabState,
} from './model.js'
import { routeRecordSchema, routeTitle, startedAs, type RouteCandidate, type RouteDecision, type RouteFinal, type RouteOverride } from './routeRecord.js'
import { routingOverrideSchema } from './routingPolicy.js'
@@ -35,7 +35,7 @@ const repositoryUrl = z.string().max(4096).refine(value => {
}, 'Share a repository URL without credentials.')
const project = z.object({ cwd: path, repositoryUrl: repositoryUrl.nullable() }).strict()
export const startRequestSchema = z.object({
- conversationId: id, machineId: id, engine: z.string().min(1).max(80), name: title, cwd: path,
+ conversationId: id, machineId: id, engine: z.string().min(1).max(80), name: title, cwd: path, role: z.enum(['builder', 'reviewer']).optional(),
worktree: z.boolean(), branchRef: z.string().max(1024).regex(/^refs\/(heads|remotes)\/[^\s\x00-\x1f\x7f]+$/).optional(),
model: z.string().trim().min(1).max(200).optional(), effort: z.string().trim().min(1).max(80).optional(),
permissionMode: z.string().min(1).max(80).optional(), codexHome: path.optional(),
@@ -65,7 +65,7 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('project.cadence'), projectId: id, minutes: z.union([z.literal(1), z.literal(5), z.literal(15), z.literal(30)]) }).strict(),
z.object({ type: z.literal('project.report'), projectId: id, throughRevision: z.number().int().nonnegative().safe(), text: text.nullable() }).strict(),
z.object({ type: z.literal('project.repository'), projectId: id, repositoryUrl }).strict(),
- z.object({ type: z.literal('conversation.create'), projectId: id.optional(), title, brief: z.string().trim().max(8000).optional(), task: task.optional(), checks: z.array(check).max(40) }).strict()
+ z.object({ type: z.literal('conversation.create'), projectId: id.optional(), title, brief: z.string().trim().max(8000).optional(), task: task.optional(), reviewOf: id.optional(), checks: z.array(check).max(40) }).strict()
.refine(c => c.task !== undefined || c.brief !== undefined, 'Provide a task or brief.')
.refine(c => !c.task || renderWorkTask(c.task).length <= 8000, 'Keep the rendered task within 8,000 characters.'),
z.object({ type: z.literal('conversation.rename'), conversationId: id, title }).strict(),
@@ -144,6 +144,13 @@ function leadWorkerBounced(recent: CommandContext['recent'] = [], leadId: string
return (run < 0 ? recent.length : run) >= PAIR_CHAIN_LIMIT
}
+/** A Reviewer is assigned only review groups, and a review group only a Reviewer. */
+function assignable(group: Conversation, worker: Agent): void {
+ const reviewer = agentRole(worker) === 'reviewer'
+ if (reviewer && !group.reviewOf) fail('REVIEWER_NOT_ASSIGNABLE', 'A Reviewer is assigned only review groups. Assign a Builder.')
+ if (!reviewer && group.reviewOf) fail('REVIEW_GROUP', 'A review group is assigned only to a Reviewer.')
+}
+
function controls(state: SuperTabState, actor: Actor, conversationId = 'lead'): void {
const group = readConversation(state, actor, conversationId)
if (actor.kind === 'agent' && group.leadId !== actor.agentId) {
@@ -393,10 +400,17 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
fail('BRIEF_REQUIRED', 'Delegated work needs a brief and acceptance checks.', 400)
}
const leadId = conversation(state, project.leadConversationId).leadId
+ if (command.reviewOf) {
+ const reviewed = open(state, command.reviewOf)
+ if (reviewed.id === project.leadConversationId || reviewed.reviewOf || groupProject(state, reviewed).id !== project.id) {
+ fail('REVIEW_TARGET', 'A review group reviews one build group of the same project.', 400)
+ }
+ }
const number = nextConversationNumber(state)
state.conversations.push({ id: operationId, ...(state.projects ? { projectId: project.id } : {}),
number, title: command.title, leadId, agentIds: leadId ? [leadId] : [],
- archived: false, brief, ...(command.task ? { task: command.task } : {}), assignment: null, lastMessageSequence: 0,
+ archived: false, brief, ...(command.task ? { task: command.task } : {}), ...(command.reviewOf ? { reviewOf: command.reviewOf } : {}),
+ assignment: null, lastMessageSequence: 0,
checks: command.checks.map((c, i) => ({ ...c, id: stableId(operationId, String(i)), evidence: null, passedBy: null })),
})
result.conversationId = operationId
@@ -433,6 +447,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const existing = state.agents.find(a => a.id === agentId)
if (existing) sameProject(state, group, existing)
if (existing?.workDecision === 'stop' && command.lead) fail('STOP_REQUESTED', 'This worker is stopping. Wait for its execution host.')
+ if (existing && agentRole(existing) === 'reviewer' && command.lead) fail('REVIEWER_NOT_LEAD', 'A Reviewer reviews work and cannot lead a group.')
if (!existing) reserveHarnessSlot(state, command.machineId, command.harnessId, operationId)
if (!existing) state.agents.push({ id: agentId, machineId: command.machineId, harnessId: command.harnessId,
...(state.projects ? { projectId: project.id } : {}),
@@ -465,6 +480,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
routed(command.routeDecisionId)
requireWorkerDecisions(state, actor, open(state, command.request.conversationId))
if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')
+ if (command.request.role === 'reviewer' && !['claude', 'codex'].includes(command.request.engine)) {
+ fail('REVIEWER_ENGINE', 'A Reviewer runs on Claude Code or Codex.', 400)
+ }
// The Lead's account has machines the Swarm never prepared (no clone of the project), so a Lead may start only where the
// Swarm already lists a machine: a contributed one, or one an agent of the Swarm runs on. A person's start may name any
// machine of theirs, because the first Lead is created before anything is listed.
@@ -540,6 +558,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
...(state.projects ? { projectId: groupProject(state, group).id } : {}),
machineOwnerId: start.machineOwnerId, contributorId: start.contributorId, membershipGeneration: start.membershipGeneration,
hostGrant: start.hostGrant, name: start.request.name, configuration: command.configuration, configurationVersion: operationId,
+ ...(start.request.role ? { role: start.request.role } : {}),
...(command.startedSession ? { startedSession: { ...command.startedSession, creationId: start.creationId } } : {}) })
group.agentIds.push(agentId)
start.harnessId = command.harnessId
@@ -569,7 +588,11 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (!isLead && !isOwner) fail('FORBIDDEN', 'Only this project’s Lead, the contributor or tab owner can release a worker.', 403)
if (state.conversations.some(c => c.leadId === target.id)) fail('LEAD_REQUIRED', 'Release workers only; keep the Lead running.')
if (state.conversations.some(c => activeWork(c) && c.assignment?.agentId === target.id)) fail('WORK_ACTIVE', 'Finish active work before releasing this worker.')
- if (!target.workDecision && !state.conversations.some(c => c.assignment?.agentId === target.id)) fail('WORK_REQUIRED', 'This worker has no finished assignment to release.')
+ if (reviewing(state, target.id)) fail('WORK_ACTIVE', 'This Reviewer is reviewing active work. Remove it from that group or wait for the work to end.')
+ // A Reviewer is never assigned work, so the Lead may keep or stop it at any time.
+ if (!target.workDecision && agentRole(target) !== 'reviewer' && !state.conversations.some(c => c.assignment?.agentId === target.id)) {
+ fail('WORK_REQUIRED', 'This worker has no finished assignment to release.')
+ }
if (target.workDecision === 'stop' && command.decision !== 'stop') fail('STOP_REQUESTED', 'This worker is stopping. Wait for its execution host.')
if (command.decision === 'stop' && target.workDecision !== 'stop') target.releaseId = operationId
target.workDecision = command.decision
@@ -637,6 +660,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const member = agent(state, command.agentId)
sameProject(state, group, member)
if (member.workDecision === 'stop' && command.lead) fail('STOP_REQUESTED', 'This worker is stopping. Wait for its execution host.')
+ const reviewer = agentRole(member) === 'reviewer'
+ if (reviewer && command.lead) fail('REVIEWER_NOT_LEAD', 'A Reviewer reviews work and cannot lead a group.')
+ if (reviewer && command.present && member.workDecision === 'stop') fail('STOP_REQUESTED', 'This Reviewer is stopping. Wait for its execution host.')
if (!command.present) {
if (activeWork(group) && (group.assignment?.agentId === command.agentId || group.leadId === command.agentId)) {
fail('WORK_ACTIVE', 'Reconcile this agent’s assignment before removing it from the conversation.')
@@ -645,6 +671,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (group.leadId === command.agentId) group.leadId = null
} else {
if (!group.agentIds.includes(command.agentId)) group.agentIds.push(command.agentId)
+ // Adding a Reviewer to a group reuses it, as assigning work reuses a Builder.
+ if (reviewer) delete member.workDecision
if (command.lead) {
if (group.leadId && group.leadId !== command.agentId && activeWork(group)) fail('WORK_ACTIVE', 'Reconcile active work before replacing its lead.')
group.leadId = command.agentId
@@ -732,6 +760,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
case 'route.record': {
controls(state, actor, command.conversationId)
const chosen = command.decision.candidates.find(c => c.id === command.decision.pick)!
+ const member = chosen.kind === 'member' ? state.agents.find(a => a.id === chosen.agentId) : undefined
+ if (member) assignable(conversation(state, command.conversationId), member)
requireWorkerDecisions(state, actor, open(state, command.conversationId), chosen.kind === 'member' ? chosen.agentId : undefined)
if ((context.recentRoutes ?? 0) >= 30) fail('RATE_LIMITED', 'This Super Tab routed 30 tasks in the last hour. Wait before routing again.', 429)
const decision = command.decision
@@ -805,12 +835,16 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (activeWork(group)) fail('WORK_ACTIVE', 'The current assignment must finish or be reconciled before reassignment.')
if (!group.brief || !group.checks.length) fail('BRIEF_REQUIRED', 'Record the brief and acceptance checks before assigning work.', 400)
const worker = agent(state, command.agentId)
+ assignable(group, worker)
sameProject(state, group, worker)
requireWorkerDecisions(state, actor, group, worker.id)
if (worker.workDecision === 'stop') fail('STOP_REQUESTED', 'This worker is stopping. Wait for its execution host.')
if (state.conversations.some(c => activeWork(c) && c.assignment?.agentId === worker.id)) fail('AGENT_BUSY', 'This agent already owns an active assignment.')
delete worker.workDecision
delete worker.releaseId
+ for (const reviewer of state.agents) {
+ if (agentRole(reviewer) === 'reviewer' && group.agentIds.includes(reviewer.id) && reviewer.workDecision !== 'stop') delete reviewer.workDecision
+ }
if (!group.agentIds.includes(worker.id)) group.agentIds.push(worker.id)
rememberAttempt(group)
group.assignment = { id: operationId, agentId: worker.id, status: 'working', configuration: structuredClone(worker.configuration),
@@ -847,14 +881,17 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const changed = assignment.status !== command.status || assignment.result !== command.result
assignment.status = command.status
assignment.result = command.result
- if (['done', 'stopped'].includes(command.status)) finishWorker(state, assignment.agentId)
+ if (['done', 'stopped'].includes(command.status)) finishWorker(state, assignment.agentId, group)
if (changed) {
const label = { working: 'Working', needs_human: 'Needs a human', blocked: 'Stuck', review: 'Ready for review', done: 'Done', stopped: 'Stopped' }[command.status]
const lead = group.leadId
// Stuck is the Lead's to hear as a human decision is: either way the work waits on someone.
const tellLead = actor.kind === 'agent' && actor.agentId === assignment.agentId && lead && lead !== actor.agentId &&
['needs_human', 'blocked', 'review', 'done'].includes(command.status)
- message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}`, tellLead ? [lead] : [])
+ // Ready for review also wakes the group's Reviewers, whoever marked it.
+ const reviewers = command.status !== 'review' ? [] : group.agentIds.filter(id => id !== lead &&
+ (actor.kind !== 'agent' || id !== actor.agentId) && state.agents.some(a => a.id === id && agentRole(a) === 'reviewer' && a.workDecision !== 'stop'))
+ message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}`, [...(tellLead ? [lead] : []), ...reviewers])
}
break
}
@@ -874,7 +911,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const gone = assignment.status === 'reconciling'
assignment.status = 'cancelled'
assignment.result = command.reason
- finishWorker(state, assignment.agentId)
+ finishWorker(state, assignment.agentId, group)
message(group.id, `${isLead ? 'The Lead' : 'The tab owner'} cancelled this task: ${command.reason.replace(/[.\s]+$/, '')}.${gone ? '' : ' Stop working on it.'}`,
gone ? [] : [assignment.agentId])
break
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index 0da552c3b..dba5caa4a 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -24,6 +24,8 @@ export interface Agent {
name: string
/** A stable member name; native session and routing names remain in `name`. */
displayName?: string
+ /** Chosen at start and kept for the session. Absent reads as builder (agentRole); the Lead is derived from leadId. */
+ role?: AgentRole
/** A finished worker stays undecided even when its group receives a new brief. */
workDecision?: 'awaiting' | 'keep' | 'stop'
releaseId?: string
@@ -33,8 +35,11 @@ export interface Agent {
/** The last configuration operation fences delayed observations, including re-contribution. */
configurationVersion?: string
}
+export type AgentRole = 'builder' | 'reviewer'
+export const agentRole = (agent: Pick<Agent, 'role'>): AgentRole => agent.role ?? 'builder'
export interface AgentStartRequest {
conversationId: string
+ role?: AgentRole
machineId: string
engine: string
model?: string
@@ -105,6 +110,8 @@ export interface Conversation {
archived: boolean
brief: string
task?: WorkTask
+ /** A review group names the group whose work it reviews; only a Reviewer is assigned it, and a Reviewer nothing else. */
+ reviewOf?: string
checks: Check[]
assignment: Assignment | null
lastMessageSequence: number
@@ -180,7 +187,8 @@ export const activeWork = (group: Conversation): boolean => !!group.assignment &
/** Old states derive pending decisions from their closed assignments; new states persist them on the worker. */
export function awaitingWorkers(state: SuperTabState, projectId: string): Agent[] {
return state.agents.filter(a => {
- if (state.conversations.some(c => c.leadId === a.id) || state.conversations.some(c => activeWork(c) && c.assignment?.agentId === a.id)) return false
+ if (state.conversations.some(c => c.leadId === a.id) || state.conversations.some(c => activeWork(c) && c.assignment?.agentId === a.id)
+ || reviewing(state, a.id)) return false
const groups = state.conversations.filter(c => c.assignment?.agentId === a.id)
return (a.projectId ?? groups.map(c => groupProject(state, c).id)[0] ?? 'lead') === projectId &&
(a.workDecision === 'awaiting' || (!a.workDecision && groups.some(c => !activeWork(c))))
@@ -188,12 +196,23 @@ export function awaitingWorkers(state: SuperTabState, projectId: string): Agent[
}
export function requireWorkerDecisions(state: SuperTabState, actor: Actor, group: Conversation, reuseId?: string): void {
if (actor.kind !== 'agent') return
- const waiting = awaitingWorkers(state, groupProject(state, group).id).filter(a => a.id !== reuseId)
+ // A Reviewer that stays in the group being started or assigned is reused for it.
+ const waiting = awaitingWorkers(state, groupProject(state, group).id)
+ .filter(a => a.id !== reuseId && !(agentRole(a) === 'reviewer' && group.agentIds.includes(a.id)))
if (waiting.length) fail('WORKER_DECISION_REQUIRED', `Decide what to do with ${waiting.map(a => a.displayName ?? a.name).join(', ')}: reuse, keep or stop. Prefer stop unless more work is coming soon.`)
}
-export function finishWorker(state: SuperTabState, workerId: string): void {
- const target = state.agents.find(a => a.id === workerId)
- if (target && !state.conversations.some(c => c.leadId === workerId)) target.workDecision = 'awaiting'
+/** A group's work ended: its worker, and each of its Reviewers not reviewing other active work, await the Lead's decision. */
+export function finishWorker(state: SuperTabState, workerId: string, group?: Conversation): void {
+ const ids = [workerId, ...(group?.agentIds ?? []).filter(id => id !== workerId &&
+ state.agents.some(a => a.id === id && agentRole(a) === 'reviewer') && !reviewing(state, id))]
+ for (const target of state.agents.filter(a => ids.includes(a.id))) {
+ if (!state.conversations.some(c => c.leadId === target.id) && target.workDecision !== 'stop') target.workDecision = 'awaiting'
+ }
+}
+/** A Reviewer is busy while any group it is in has active work. */
+export function reviewing(state: SuperTabState, agentId: string): boolean {
+ return state.agents.some(a => a.id === agentId && agentRole(a) === 'reviewer') &&
+ state.conversations.some(c => activeWork(c) && c.agentIds.includes(agentId))
}
export function person(state: SuperTabState, id: string): Person {
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index e8bf115cb..daef9afcb 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -974,7 +974,7 @@ export class SuperTabStore {
const notices: MessageDraft[] = []
if (group && activeWork(group)) {
assignment.status = 'stopped'
- finishWorker(state, assignment.agentId)
+ finishWorker(state, assignment.agentId, group)
assignment.result = 'The execution host confirmed that this harness stopped.'
await tx.superTabRun.deleteMany({ where: { tabId, assignmentId } })
await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId,
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index cca40c9c9..ac5399cea 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -159,7 +159,7 @@ export class BackendSocket {
* contract for it — so cli.ts never sees one it cannot hand over. Never logged. */
prompt: string | null
/** Session-scoped built-in instructions for a newly launched Swarm agent. */
- swarmRole?: 'lead' | 'dev'
+ swarmRole?: import('./lib/swarmSkills.js').SwarmRole
/** The name the pane opens under, instead of the next `agent-N`; null to number it. */
name: string | null
/** The engine's named agent the pane opens AS (`NAMED_AGENT_ARGS` in engineLaunch.ts; opencode
diff --git a/cli/src/core/agents/launches.spec.ts b/cli/src/core/agents/launches.spec.ts
index bae28567d..5e02915e3 100644
--- a/cli/src/core/agents/launches.spec.ts
+++ b/cli/src/core/agents/launches.spec.ts
@@ -264,11 +264,11 @@ describe('agent_create, refused before any pane exists', () => {
it('passes explicit Swarm roles and refuses invalid role metadata before dispatch', async () => {
const { ask, create } = setup()
- for (const engine of ['claude', 'codex']) for (const swarmRole of ['lead', 'dev']) {
+ for (const engine of ['claude', 'codex']) for (const swarmRole of ['lead', 'dev', 'review']) {
await ask({ engine, cwd: '/w', swarmRole })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).toMatchObject({ engine, swarmRole })
}
- for (const swarmRole of [7, '', 'reviewer']) {
+ for (const swarmRole of [7, '', 'builder', 'reviewer']) {
expect(await ask({ engine: 'claude', cwd: '/w', swarmRole })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
}
expect(await ask({ engine: 'terminal', cwd: '/w', swarmRole: 'dev' })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
diff --git a/cli/src/core/agents/launches.ts b/cli/src/core/agents/launches.ts
index ec50af5fe..60519932d 100644
--- a/cli/src/core/agents/launches.ts
+++ b/cli/src/core/agents/launches.ts
@@ -22,6 +22,7 @@ import { ENGINES, isTerminalEngine, type AgentEngine } from '../../engines/types
import { AgentCreationReceiptError, creationFingerprint, validCreationId, type AgentCreationOutcome, type AgentCreationReceipts, type AgentCreationStatus, type CreationAuthority } from '../../lib/agentCreationReceipt.js'
import type { AgentFrame } from '../../lib/agentFrame.js'
import { engineLabel } from '../../lib/agentNames.js'
+import { isSwarmRole } from '../../lib/swarmSkills.js'
import {
AGENT_NAME_RE, FirstPromptUnsupportedError, MAX_FIRST_PROMPT_CHARS, NamedAgentUnsupportedError, permissionModeApproves,
permissionModeFlags, supportsFirstPrompt, supportsNamedAgent, unsupportedLaunchModelFlag,
@@ -393,8 +394,8 @@ export function createLaunchRequests({ receipts, createAgent, prepareCreate, pre
}
const swarmRole = payload.swarmRole
if (swarmRole !== undefined && swarmRole !== null &&
- ((swarmRole !== 'lead' && swarmRole !== 'dev') || (engine !== 'claude' && engine !== 'codex'))) {
- reply({ error: 'INVALID_SWARM_ROLE', detail: 'A Swarm role is lead or dev, for Claude Code or Codex.' }); return
+ (!isSwarmRole(swarmRole) || (engine !== 'claude' && engine !== 'codex'))) {
+ reply({ error: 'INVALID_SWARM_ROLE', detail: 'A Swarm role is lead, dev or review, for Claude Code or Codex.' }); return
}
// Blank is "number it", the same as absent — a client that sends an empty field is not
// asking for an agent with no name.
@@ -464,7 +465,7 @@ export function createLaunchRequests({ receipts, createAgent, prepareCreate, pre
codexHome,
dsh,
prompt,
- ...(swarmRole === 'lead' || swarmRole === 'dev' ? { swarmRole } : {}),
+ ...(isSwarmRole(swarmRole) ? { swarmRole } : {}),
name,
agent,
resumeSessionId,
diff --git a/cli/src/core/agents/swarmSkills.spec.ts b/cli/src/core/agents/swarmSkills.spec.ts
index 67dca3e7f..9d26f49b0 100644
--- a/cli/src/core/agents/swarmSkills.spec.ts
+++ b/cli/src/core/agents/swarmSkills.spec.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../../lib/registry.js'
+import type { SwarmRole } from '../../lib/swarmSkills.js'
import { createLaunchAuthority } from './launchAuthority.js'
import { createSwarmSkillAdoption } from './swarmSkills.js'
@@ -8,7 +9,7 @@ const row = (over: Partial<RegisteredSession> = {}) => ({ agentId: 'old-session'
function setup(saved = row(), live: RegisteredSession | null = saved) {
let current = true
- const role = vi.fn(async (): Promise<'lead' | 'dev' | null | undefined> => 'lead')
+ const role = vi.fn(async (): Promise<SwarmRole | null | undefined> => 'lead')
const save = (id: string, skill: NonNullable<RegisteredSession['swarmSkill']>) => {
if (!live || live.agentId !== id) return false
live.swarmSkill = skill; return true
@@ -20,7 +21,7 @@ function setup(saved = row(), live: RegisteredSession | null = saved) {
describe('old Swarm role adoption', () => {
it.each(['claude', 'codex'] as const)('adopts each role for old %s sessions and persists it before launch', async engine => {
- for (const role of ['lead', 'dev'] as const) {
+ for (const role of ['lead', 'dev', 'review'] as const) {
const t = setup(row({ engine })); t.role.mockResolvedValue(role)
expect(await t.adopt(t.saved, t.current)).toMatchObject({ swarmSkill: { role, key: 'old-session' } })
expect(t.saved.swarmSkill).toEqual({ role, key: 'old-session' })
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 006937c0a..c86ffb6e6 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -652,7 +652,7 @@ export const MEMORY_REQUESTS = ['memory_snapshot', 'memory_about_put', 'memory_d
* the client that asks, which acts on it. */
export const ROUTER_REQUESTS = ['route_decide'] as const
export const SUPER_TAB_REQUESTS = ['super_tabs'] as const
-export interface SuperTabsPort { connected(): void; disconnected(): void; stop(): void; swarmRole(harnessId: string): Promise<'lead' | 'dev' | null | undefined> }
+export interface SuperTabsPort { connected(): void; disconnected(): void; stop(): void; swarmRole(harnessId: string): Promise<import('../lib/swarmSkills.js').SwarmRole | null | undefined> }
export const SUPER_TAB_FALLBACKS: PortFallbacks<SuperTabsPort> = { connected: undefined, disconnected: undefined, stop: undefined, swarmRole: later(undefined) }
/** The project and folder readers (services/projects.ts). */
export const PROJECTS_REQUESTS = ['git_pull_request', 'git_pull_requests_status', 'git_project_info', 'scm_project_info', 'project_preview', 'fs_list_dir', 'agent_read_file'] as const
diff --git a/cli/src/core/superTabSkills.spec.ts b/cli/src/core/superTabSkills.spec.ts
index 10e31dc8e..842cf1da8 100644
--- a/cli/src/core/superTabSkills.spec.ts
+++ b/cli/src/core/superTabSkills.spec.ts
@@ -2,11 +2,12 @@ import { expect, it, vi } from 'vitest'
import { swarmRoleThrough } from './superTabSkills.js'
it('reads only validated role answers through the Super Tab process', async () => {
- const answers = [{ ok: true, role: 'lead' }, { ok: true, role: 'dev' }, { ok: true, role: null }, { role: 'lead' }, { ok: true, role: 'owner' }, { error: 'SERVICE_UNAVAILABLE' }]
+ const answers = [{ ok: true, role: 'lead' }, { ok: true, role: 'dev' }, { ok: true, role: 'review' }, { ok: true, role: null }, { role: 'lead' }, { ok: true, role: 'owner' }, { error: 'SERVICE_UNAVAILABLE' }]
const call = vi.fn(async () => answers.shift()!)
const read = swarmRoleThrough(call)
expect(await read('native')).toBe('lead')
expect(await read('native')).toBe('dev')
+ expect(await read('native')).toBe('review')
expect(await read('native')).toBeNull()
for (let i = 0; i < 3; i++) expect(await read('native')).toBeUndefined()
expect(call).toHaveBeenCalledWith('super_tabs', { action: 'swarmRole', harnessId: 'native' })
diff --git a/cli/src/core/superTabSkills.ts b/cli/src/core/superTabSkills.ts
index 0ac390ace..f4fbdd2d7 100644
--- a/cli/src/core/superTabSkills.ts
+++ b/cli/src/core/superTabSkills.ts
@@ -1,11 +1,11 @@
/** The same role lookup in a separate Super Tab process. Missing/older services grant no skill. */
-import type { SwarmRole } from '../lib/swarmSkills.js'
+import { isSwarmRole, type SwarmRole } from '../lib/swarmSkills.js'
export function swarmRoleThrough(call: (type: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>) {
return async (harnessId: string): Promise<SwarmRole | null | undefined> => {
const answer = await call('super_tabs', { action: 'swarmRole', harnessId })
if (answer.ok !== true) return undefined
if (answer.role === null) return null
- return answer.role === 'lead' || answer.role === 'dev' ? answer.role : undefined
+ return isSwarmRole(answer.role) ? answer.role : undefined
}
}
diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.ts
index e19413ddd..062b0d837 100644
--- a/cli/src/lib/swarmSkills.spec.ts
+++ b/cli/src/lib/swarmSkills.spec.ts
@@ -1,4 +1,5 @@
import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
@@ -22,7 +23,7 @@ describe('built-in Swarm skills', () => {
expect(prepared.file.startsWith(join(realpathSync(workspace), '.harness', 'runtime'))).toBe(true)
const text = readFileSync(prepared.file, 'utf8')
expect(text).toContain(`name: swarm-${role}`)
- if (role === 'lead') expect(text).toContain('goal, changes, constraints, owned code and acceptance checks')
+ if (role === 'lead') expect(text).toContain('Route every new agent and every assignment')
else {
expect(text).toContain('Needs:')
expect(text).toContain("Do not touch other groups' code.")
@@ -38,6 +39,20 @@ describe('built-in Swarm skills', () => {
expect(readdirSync(data)).toEqual([])
})
+ // The owner's approved text (2026-10-22), byte for byte.
+ it.each([
+ ['lead', 'a8d54ee204209946486c8d99960f1317e4bd3e51434af894b174e712b67b7941'],
+ ['dev', '86caf697c83365f000317845b0aaa929947a9591d637ab2bd0f8536da8e86763'],
+ ['review', '424dc9db5642ed7093128525f30877ffc301eb6957b33e8234916de0f0eaa208'],
+ ] as const)('writes the owner\'s %s skill byte for byte', (role, sha256) => {
+ expect(parseSwarmSkill({ role, key: 'session' })).toEqual({ role, key: 'session' })
+ const prepared = prepareSwarmSkill(fixture(), { role, key: 'session' })
+ expect(prepared.instructions).toContain(`swarm-${role} skill`)
+ const text = readFileSync(prepared.file, 'utf8')
+ expect(text.startsWith(`---\nname: swarm-${role}\n`)).toBe(true)
+ expect(createHash('sha256').update(text).digest('hex')).toBe(sha256)
+ })
+
it('keeps standalone session skills out of Git, including git add -A', () => {
const workspace = fixture()
execFileSync('git', ['init', '-q', workspace])
@@ -90,7 +105,7 @@ describe('built-in Swarm skills', () => {
})
it('validates persisted role metadata and refuses an empty key', () => {
- for (const value of [null, undefined, {}, { role: 'reviewer', key: 'x' }, { role: 'dev', key: '' }, { role: 'lead', key: 7 }]) expect(parseSwarmSkill(value)).toBeUndefined()
+ for (const value of [null, undefined, {}, { role: 'builder', key: 'x' }, { role: 'dev', key: '' }, { role: 'lead', key: 7 }]) expect(parseSwarmSkill(value)).toBeUndefined()
expect(parseSwarmSkill({ role: 'dev', key: 'x' })).toEqual({ role: 'dev', key: 'x' })
expect(() => prepareSwarmSkill(fixture(), { role: 'lead', key: '' })).toThrow()
})
diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.ts
index 643b10243..8b41e75f7 100644
--- a/cli/src/lib/swarmSkills.ts
+++ b/cli/src/lib/swarmSkills.ts
@@ -4,42 +4,334 @@ import { createHash } from 'node:crypto'
import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
import { join, relative, sep } from 'node:path'
-export type SwarmRole = 'lead' | 'dev'
+export type SwarmRole = 'lead' | 'dev' | 'review'
export interface SwarmSkill { role: SwarmRole; key: string }
+export const isSwarmRole = (value: unknown): value is SwarmRole => value === 'lead' || value === 'dev' || value === 'review'
export function parseSwarmSkill(value: unknown): SwarmSkill | undefined {
if (!value || typeof value !== 'object') return undefined
const { role, key } = value as Partial<SwarmSkill>
- return (role === 'lead' || role === 'dev') && typeof key === 'string' && key.length > 0 ? { role, key } : undefined
+ return isSwarmRole(role) && typeof key === 'string' && key.length > 0 ? { role, key } : undefined
}
const skills: Record<SwarmRole, string> = {
lead: `---
name: swarm-lead
-description: Use when coordinating a Harness Swarm project as its Lead or Product Manager, before discussing, splitting or assigning work.
+description: Use when coordinating a Harness Swarm project as its Lead (shown as Product Manager), before discussing, specifying, splitting, routing, assigning, reviewing or closing work.
---
-# Coordinate a Swarm project
-
-1. Restate the request briefly and mark guesses. Ask one question at a time in project chat, starting with what changes the approach: goal, scope, what must not be done, and what counts as done. State the size: small, medium, or large. Large work needs a written description.
-2. Split only after the task giver or project owner clearly approves the description. Others' opinions and a vague “ok” do not replace that approval. A small, clear request (a question or one-spot fix) can be done immediately; say what you did. If told “just do it”, skip questions and state important choices.
-3. Give numbered options, mark one default, and set a deadline. When it passes, record and use that default for choices already authorized. A deadline never supplies the approval required above.
-4. Discuss → approved description → groups → route → assign. Every group carries goal, changes, constraints, owned code and acceptance checks. Multi-part work or work taking about 15 minutes or more goes to Swarm agents in groups. Coordinate it; your own subagents only read and look things up.
-5. When a worker finishes, decide reuse, keep, or stop; prefer stop unless more work is coming soon. Never leave a worker idle without an explicit decision. If an active task is a duplicate, obsolete or the wrong task, cancel it with work.cancel and a reason instead of waiting; the worker is told to stop, then decide what to do with it. Check workers silent too long and reassign work stalled too long. Report on-screen trust, sign-in or permission questions in chat immediately, naming the machine owner who can answer.
-6. Summarize long threads once and record important decisions once. Keep the project chat informed of progress, blockers and next steps.
+# Lead a Swarm project
+
+You coordinate. People bring requests to the project chat, Builders do the work in groups, Reviewers check it. Your job: find out what people actually want, turn it into groups others can finish without coming back to you, keep everyone supplied and unblocked, and accept only proven results. You build only what is quick.
+
+## Core rules
+1. Nothing is split or assigned until the task giver or project owner approves the description you showed.
+2. Multi-part work, or work over about 15 minutes, goes to Swarm agents in groups. Your own subagents only read and look things up.
+3. Route every new agent and every assignment; use the pick or give an override reason.
+4. Done means proven: every acceptance check has evidence, including an independent one where review is required.
+5. Merging, opening a PR, releasing or discarding is the owner's decision. Ask; never assume.
+6. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) and the owner's words outrank this skill.
+
+## 1. Understand the request
+Why: you will make many decisions nobody states. Knowing why they want it lets you make them their way.
+- Look first. Read the project, its code, the chat and past decisions; never ask what they already answer. To look beyond the project (their own files, the web), offer and let them decide.
+- Tell them once that they can skip the questions and have you start.
+- Restate the request in a sentence or two and mark guesses as guesses.
+- Ask one open question per message in project chat: one sentence, no list of sample answers, anchored in a real moment ("walk me through the last time…"). Cover what matters, not as a script: why now, what done looks like, what would make it a failure even if it works, scope, what exists, what they have seen elsewhere. A guess they can correct beats a question.
+- Ask about intent with open questions; offer a short menu only when they are stuck. When they say "you decide", propose something concrete. When known alternatives must be picked, use numbered options with a default and a deadline (section 4).
+- Find out which how-it-gets-made choices (language, library, platform) they want to make and which they leave to you. Where work already exists, default to what it already uses. Say your defaults out loud; a default they never heard is one they could not reject.
+- Before proposing, think of several approaches privately; drop any that fight their why; show a comparison only when it helps them decide.
+- Play back each part as soon as you understand it, and ask what is wrong or missing.
+- If told "just do it", skip the questions, state each significant choice in one line, and continue.
+
+## 2. Size it on the route's scale
+| Size | Description | Next |
+|---|---|---|
+| Quick: an answer or a fix under 15 minutes | the request itself | do it yourself, say what you did; no route |
+| Small or medium: one group, up to about an hour | short description in chat | approval, then one group |
+| Large: several groups, or about three hours or more | written spec | builder check, approval, group plan |
+
+Say the size in plain words; they may override it. If it grows, stop, say so and size up. If it is really several independent projects, say so and agree on an order.
+
+When a quick throwaway build would answer a question faster than talking, offer a spike: labeled throwaway, light tests, no plan or review. Bring back what it taught. Keeping its result is a new request that needs approval.
+
+## 3. Written spec (large work)
+Write for a capable builder who cannot ask the requester. Sections: intent and why; goals; non-goals; anti-goals; constraints every group shares (versions, naming and copy rules, platforms, what must not change); what the person decided, as they decided it; your calls, marked as yours; what is left to builders; group outline.
+
+Attach it as a file in the project chat. That message is the version people approve.
+
+Builder check: tell the person a check runs first and you may come back once with questions. Before asking for approval, have one subagent read the spec as a builder and list only the questions where a wrong guess would change what gets built, ranked, each with why; it skips what is left to builders and wording nits. Sort the list:
+- already answered → put it in the spec;
+- minor → decide it and mark it as your call;
+- theirs → ask the person once, most important first.
+
+Hand over the spec with a short list of your calls for them to check while reading.
+
+## 4. Approval
+- The approver is the task giver or project owner. Others' opinions, enthusiasm for an idea, or "ok" to something you have not written do not count.
+- Approval covers exactly what you showed. Changed scope needs approval again.
+- Ask openly about intent. When the alternatives are known and one must be picked, give numbered options, mark a default and set a deadline; when it passes, record and use the default. A deadline never replaces approval.
+
+## 5. Split into groups (your plan)
+Each group is one task of the plan: finishable and testable on its own, so a reviewer could reject it and accept its neighbor. Split by responsibility, not by technical layer; fold setup, configuration and docs into the group whose result needs them. Put several small edits of the same kind into one group, not one group each.
+
+Every group carries:
+- Goal, with the why.
+- Spec: a link to the approved spec when there is one; the brief argues from it.
+- Changes.
+- Constraints, including the spec's shared constraints. Copy exact values (numbers, names, formats, visible copy) from the spec verbatim.
+- Owned code, and what is off limits.
+- Consumes and produces: exact names, types and interfaces it takes from or gives to other groups. Parallel groups cannot see each other; this is how they fit.
+- Acceptance checks as observable evidence. Mark one independent when review is required (section 8).
+- Most likely to go wrong: the inputs or conditions no check covers. List them most likely first, at least the top five when there are that many, each with what a reasonable user would expect; an empty list means you checked. Each line names the test that pins it in the group that owns the code.
+- Hand back: what the Builder returns, such as the work branch, revision, result files and links.
+- Needs: nothing, a machine, test data, a person's hands, or a real user.
+- Carry-over: rulings or deferred findings that touch this group's code.
+
+The brief states only what the Builder cannot decide alone: files, names, interfaces, exact values, checks. Never write their code; a brief longer than the code it asks for is a transcript. For a bug group, include the exact error output and the failing test names.
+
+Before assigning, check: every spec item has a group; names agree across groups; no two groups own the same code; each group's checks match its changes; no group requires something a Reviewer would flag (a check that proves nothing, copied logic); no line decides nothing ("handle edge cases").
+
+Run groups in parallel only when they own different code, do not change the same machine, device, database or port, and need nothing from each other while running. Otherwise run them in order. Never put two Builders on the same files. Related failures (fixing one may fix the others), or a problem nobody understands yet, go to one group that investigates first.
+
+Keep the next group ready before a worker finishes. Start a group that consumes another's output only once that output is done and verified; until then, give the worker independent work.
+
+For large work, post the group plan and get the owner's ok before assigning; once approved, keep later groups ready as usual.
+
+## 6. Route, start, assign
+- Route each group before starting or assigning: difficulty, risk, size, why, needs. Use the pick, or override with a reason.
+- Match strength to work: mechanical → cheaper; integration and judgment → standard; design or subtle risk → strongest. A review is at least as strong as the build. Don't go below the standard tier for Reviewers, or for Builders working from prose; the cheapest models take more turns and end up costing more.
+- Reuse an idle agent before starting a new one. Start only on the Swarm's listed machines, from the branch the work builds on.
+- The brief is all a Builder gets. Never pass your chat history; put everything needed in the brief.
+
+## 7. Run the work
+- Needs-human: get the person's decision now.
+- Blocked: change something. Give more context, re-route to a stronger model, cut the work smaller, or fix the plan. Never resend the same thing to the same model.
+- Rulings, not stalls: when a Builder hits an ambiguity you can settle, settle it and record "Ruling: what — why — cost if wrong". Ask the person only what changes what gets built.
+- Each time you are woken, look at active work. Ask a worker with active work that has said nothing for 20 minutes; reassign work that has not moved for 6 hours; report on-screen trust, sign-in or permission questions in chat, naming the machine owner who can answer.
+- Keep each worker supplied: have its next group ready before it finishes, so nobody waits for you.
+- Cancel a duplicate, obsolete or wrong task with a reason.
+- When a worker finishes: reuse, keep or stop. Prefer stop unless more work is coming soon.
+
+## 8. Review
+- Independent review is required when risk or difficulty is medium or higher, when the work touches security, data, defaults or a release, or when the result will be merged. Also bring in a Reviewer when a Builder is stuck, before a large refactor, or after a hard bug fix.
+- Read the Builder's doubts first; settle any doubt about correctness or scope before the review starts.
+- When a Builder marks ready for review, create a group "Review: <group>" whose brief holds only: goal, constraints, the spec's constraints copied verbatim, checks, the most-likely-wrong list, the Builder's rulings, the revision range and the Builder's handoff. Route it, assign it to a Reviewer (reuse an idle one first; prefer a different engine than the Builder, with a model at least as strong), and add the Reviewer to the Builder's group so it can pass the independent check.
+- Never tell a Reviewer what not to flag or how to grade it.
+- Do not review the diff yourself: same blind spots, and it burns the context you need to coordinate.
+- Re-grade each finding by what a user gets if it ships, not by its label or by the spec's silence. Critical findings are fixed now, Important ones before you accept, Minor ones recorded for later.
+- Rule on each "set aside" line and each item the Reviewer could not verify, and record every ruling. A finding against something your brief required is yours to rule on, with the spec as the authority; record the ruling before any fix. When Builder and Reviewer disagree, you decide; if it is architectural, ask the owner.
+- Never fix findings yourself, however quick; they go back to the Builder.
+- Before a re-review, check that the Builder's fix reply names the test, command and result for each fix.
+- Each round is one fix and one re-review. Rounds 1–3 go to the same Builder. Rounds 4–5 go to a stronger model, told the history is in the group. After round 5, rule on each open finding: park it with a ruling, or rule the smallest change that unblocks dependent work. Bring it to the owner only if it is architectural or every path is a guess. Never drop a finding silently.
+- A re-review covers only the new changes; a re-review of a small fix may use a mid-tier model. Accept only when the reviewed revision is the handed-off revision.
+
+## 9. Accept and close
+- A report of success is not evidence. Check: "Ready: yes", every check's evidence (command, revision, observed result), local checks kept apart from real-environment runs, and the unverified list. Confirm the handed-off revision exists and changes the owned code.
+- "Requirements met" means re-reading the approved description item by item. Passing tests are not enough.
+- When parallel groups finish, have their combined result checked for conflicts and run against the full suite before you offer integration. A green run proves only the tree it ran on.
+- For large work, when all groups are done, run one review of the whole project on the strongest model. Give it the deferred Minor findings and all rulings to triage. Send its findings as one fix group, then one re-review, then rule on what remains.
+- When closing, give the owner every ruling made (yours and the Builders'), each with its cost if wrong, plus the deferred Minor findings.
+- Then give the owner the choice: merge, open a PR, or keep the branch. Never merge, push, release or discard on your own.
+
+## 10. Keep people informed
+- At project cadence, post progress, blockers and next steps in the project chat; if nothing changed, post nothing.
+- Progress is a scored table: one row per group with a score from 0 to 1, its owner, and what it waits on. Only done and verified scores 1.0. Every row below 1.0 has an owner or says what it waits on.
+- Answer questions, blockers and completions immediately.
+- Summarize long threads once; record important decisions once.
+- When your own session grows long, post a checkpoint in the project chat: the approved description, groups and their state, open rulings, and next steps. It must be enough for a fresh Lead session to continue.
+- Write like a colleague: short, in their language, without commands or internal IDs. Lead with what matters: give the most important points and offer the rest. Use their words, not Swarm's process terms; ask your question rather than explain the process.
+- When talking to people, call the roles Product Manager, Engineer and Reviewer.
+
+## Red flags
+| Thought | Reality |
+|---|---|
+| "It's small, I'll just do it" | Over 15 minutes or multi-part goes to a group. |
+| "They said ok" | Approval comes from the task giver or owner, for what you showed. |
+| "I'll give them options to pick from" | For intent, options steer; ask them to describe it. Numbered options are for picking between known alternatives. |
+| "Routing is slow, skip it once" | Unrouted work is invisible in the decision log. Route or give a reason. |
+| "I'll read the diff myself" | Same blind spots, and your context fills up. Use a Reviewer. |
+| "This finding is quick, I'll fix it" | Findings go back to the Builder. |
+| "The Reviewer said Minor" | Grade what a user would get. Re-grade, then decide. |
+| "Five rounds, hand it to the owner" | Rule on each open finding; ask only if it is architectural or every path is a guess. |
+| "The Builder says done" | A report is not evidence. Check it. |
+| "I'll ask the person about this" | If it doesn't change what gets built, rule and record. |
+| "It's stuck, try again" | Change context, model, size or plan. |
+| "Decide about the worker later" | Decide now: reuse, keep or stop. |
+| "They obviously want it merged" | Integration is the owner's call. Ask. |
`,
dev: `---
name: swarm-dev
-description: Use when receiving or carrying out an assigned workgroup as a Harness Swarm engineer or worker, including review and handoff.
+description: Use when you are a Harness Swarm Builder (shown as Engineer) taking, planning, carrying out or handing off an assigned group, including handling review findings.
---
-# Finish assigned work
-
-1. Say in the group chat that you took the assignment and what you are doing.
-2. Follow a multi-step plan in order. For changed behavior, write a test, watch it fail for the expected reason, implement the smallest fix, then verify it passes. Debug systematically: reproduce, inspect evidence, find the cause, test a hypothesis. Check each review finding against the code before changing it. Run relevant checks and read their results before saying done.
-3. If blocked, post a “Needs:” line saying what you need, then continue independent parts. Interpret ambiguous answers in their narrowest safe sense and record that interpretation.
-4. Work as if nobody will return to help: finish completely and test everything testable. Package any remaining person or device action as one clear step.
-5. Every handoff includes “Ready: yes/no”, evidence, the revision and useful links, and what remains unverified. Distinguish local checks from runs in the real environment.
-6. Ask the Lead to route work instead of opening your own subagents to split it. Do not touch other groups' code. Merge, push or open a PR only when told.
-7. Print little to save quota; keep useful progress and blocker reports in the group chat.
+# Build an assigned group
+
+You finish one group's work completely, inside its brief, with proof. Work as if nobody will come back to help. The Lead coordinates; a Reviewer may check your work.
+
+## Core rules
+1. No production code without a failing test first.
+2. No fix without a found root cause.
+3. No "done", "fixed" or "passing" without running the check now and reading its output.
+4. Stay inside your brief and owned code. No subagents to split the work; read-only lookups are fine. No merge, PR or push, except pushing your work branch when the group needs review. Never start a reviewer for your own work.
+5. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.
+
+## 1. Take the assignment
+- Say in the group chat that you took it and what your first step is; mark it working.
+- Read the brief: goal, spec, changes, constraints, owned code, consumes and produces, checks, most likely wrong, hand back, needs, carry-over. If the brief links the spec, read it.
+- Before step one, check what your brief consumes against what the producing group or code actually provides, and rule on mismatches.
+- If the brief needs a machine or device, check it is reachable and usable before you start; if not, mark blocked with a "Needs:" line.
+- If something you need is missing, ask the Lead for all of it at once, and continue what doesn't depend on it.
+- Harness already created your worktree; do not create another. Run the project's tests before changing anything, and report failures that existed before your change by name. If baseline failures touch your owned code, ask the Lead before relying on them, and continue the parts they don't touch.
+
+## 2. Plan (groups of about an hour or more)
+- Write a short step plan. Each step is one action with a checkable result: write the test, see it fail, write the code, see it pass, commit. Each step that runs something states the command and the result you expect.
+- Name exact files, names and values from the brief; never write "handle edge cases".
+- Post the plan in the group chat, then follow it in order.
+- Re-read the brief's part for each step; memory is a summary, the brief has the exact values.
+- Run the step's test at each step; the end-of-group run is the contract, not a substitute.
+- Keep going from step to step without checking in; stop only for the stops in section 5.
+- Follow the codebase's existing patterns and the brief's file layout. If a file grows past what the brief intended, or one you change is already tangled, say so in the handoff; do not restructure.
+- The approved spec outranks the brief, and the brief outranks your plan. When they conflict, or a step turns out wrong, take the smallest change that satisfies the spec and post "Ruling: what — why — cost if wrong". An unrecorded deviation is a decision made in secret.
+- After each committed step, post one progress line (step, commit, test result) so a fresh session can resume. After a restart, trust those lines and git log over memory, and never redo a committed step.
+- Before handoff: every test the brief names exists and ran, every expected result was compared with the real one, and every deviation has a Ruling.
+
+## 3. Test first
+- Red: one test, one behavior, a clear name, real code (mocks only when unavoidable). Run it; it must fail because the feature is missing, not error out. If it passes at once, it tests existing behavior; fix the test.
+- Green: the simplest code that passes. Nothing extra. If the test fails after your code, fix the code, not the test.
+- While iterating, run the focused test. Before each commit and before handoff, run the project's whole suite, or the suites the project's instructions name. Report any failure by name, even one you did not cause. Test output must be clean: no errors or warnings.
+- Refactor only while green.
+- Code written before its test is deleted and redone test-first. Throwaway, generated and configuration code are exceptions only with the Lead's ok. If code you change has no tests, add tests for the behavior you touch first.
+- Before writing a test, name the bug that would make it fail; if only a deliberate change could fail it, test the behavior instead. Write expected values by hand, never with the code under test. Run things and assert on the results; never assert that source contains some text. Test your own contract, not the framework.
+- Never assert on a mock. Learn a dependency's side effects before mocking it, and mock only the slow or external level. Mocked data mirrors the full real structure. When mocks outgrow the test, use real components. Test-only helpers live in test code, never in production code.
+- Write only the tests the behavior needs; none for coverage's sake. Hard to test means the design is too tangled: simplify the interface rather than adding mocks.
+- In tests, wait for the condition, not a fixed delay; never fix flakiness by raising a timeout.
+- Before finishing, imagine realistic bugs (wrong value, wrong branch, missing side effect, empty return, missing validation); each should fail some test.
+
+## 4. Debug from the cause
+1. Read the whole error. Reproduce it reliably. Check what changed.
+2. With several components, find with evidence which boundary breaks before fixing anything. Trace a bad value back up the call chain to where it starts, logging before the failing step if needed. To find which test leaves stray state behind, run the tests one by one.
+3. Compare with similar code that works; read the reference completely and list every difference, however small. State one hypothesis, "X because Y", and test it with the smallest change.
+4. Fix at the source, with a failing test first, one change at a time, nothing while you're there. When bad data caused the bug, also reject that data at each layer it passes through in your owned code, each with a test.
+5. After three failed fixes, stop. The design is probably wrong. Report what you learned to the Lead; do not try a fourth.
+
+Say "I don't understand X" rather than guess. If the Lead or a person says "stop guessing", or asks whether something is really happening, go back to step 1. If the cause really is outside the code (environment, timing, an outside service), record what you checked, add sensible handling and logging, and say so in the handoff; usually the investigation is just incomplete.
+
+With several clearly separate failures, you may start read-only subagents to investigate them in parallel, one failure each, with its error and test names, returning the root cause and evidence. They never edit. You make the fixes yourself, one at a time, each with a failing test first. Do not do this when failures may be related or you do not yet know what is broken.
+
+## 5. Blocked
+- A person's decision: mark needs-human with one short question.
+- Can't go on: mark blocked with why, and what would unblock you.
+- Post a "Needs:" line, continue the independent parts, and mark working again once it moves.
+- Stop for a decision only for an irreversible or destructive step, a security-sensitive action, an effect outside your worktree, or a brief so broken that every path is a guess. Settle other ambiguity with the narrowest safe reading and a Ruling, and keep going. A missing machine, test data, or a person's hands is still a "Needs:" line; continue the independent parts.
+- Escalate to the Lead with a "Needs:" line when the work needs an architecture choice between valid options, code you cannot understand, or restructuring the brief did not plan; or when you doubt your approach or keep reading without progress. Keep doing the independent parts; bad work is worse than none.
+- Read an ambiguous answer in its narrowest safe sense, and record that reading.
+- Write to people briefly, in their language, without commands or internal IDs. Call the roles Product Manager, Engineer and Reviewer.
+
+## 6. Prove it
+Before any claim: name the command that proves it, run it fully, read the output and exit code, then state the claim with that evidence. "Should", "probably", "seems" or "Done!" before a run means you have not verified.
+
+| Claim | Needs | Not enough |
+|---|---|---|
+| Tests pass | a fresh run with 0 failures | an earlier run, "should pass" |
+| Build succeeds | the build exits 0 | linter passed, logs look fine |
+| Linter clean | linter output with 0 errors | a partial check |
+| Bug fixed | the original symptom now passes | the code changed |
+| Regression test | reverting the fix makes it fail; restoring makes it pass | it passed once |
+| Requirements met | the brief re-read item by item | tests pass |
+
+Record each acceptance check with the exact command, revision and observed result. You may never pass an independent check yourself.
+
+## 7. Hand off
+- Finish everything testable. Package any remaining person or device action as one clear step.
+- Before handing off, re-read your diff: everything in the brief, nothing extra, names that say what things do, edge cases and errors tested, clean output. Fix what you find.
+- Return everything the brief's hand back names. The handoff says "Ready: yes/no", evidence, the revision range from the commit your work started on, links, and what is unverified. Include red-then-green evidence for each new test and list every Ruling you made. Keep local checks apart from real-environment runs. Put any doubts in the handoff.
+- If the group needs review, push your work branch (the branch only; no PR, no merge) and mark ready for review with the revision. Otherwise mark done.
+
+## 8. Review findings
+- Read all findings first. If any is unclear, ask about every unclear one before changing anything.
+- Feedback from the owner or Lead: act once you understand it, and ask if the scope is unclear. Feedback from a Reviewer: check it first.
+- Check each against the code: is it right here, does it break something, is there a reason for the current code, does it hold on every platform and version you support? If you cannot verify a finding, say what you would need and ask the Lead.
+- If a finding is wrong, push back with evidence. If it adds a feature nobody uses, show that nothing uses it and ask to drop it. If it conflicts with a decision by the Lead or owner, ask the Lead.
+- Fix in order: blocking, simple, complex. Each real finding gets a failing test first; test each fix, then rerun everything.
+- Reply "Fixed: …" naming the test, the command and the result, or with a reasoned pushback. No thanks, no praise. If your pushback was wrong, say so briefly and fix it.
+- Record Minor findings; fix them only if asked.
+- Mark ready for review again with the new revision.
+
+## 9. Limits
+- To split the work, ask the Lead to route it. Do not touch other groups' code.
+- Merge, push, open a PR, release, force-push or discard only when told; the one exception is pushing your work branch for review.
+- If your task is cancelled, stop and say where you left it.
+- Print little to save quota. Keep progress and blockers in the group chat.
+
+## Red flags
+| Thought | Reality |
+|---|---|
+| "I'll write the test after" | Then you never saw it fail. Delete and redo. |
+| "Too simple to test" | Simple code breaks. Test it. |
+| "I tested it by hand" | Not repeatable. Write the test. |
+| "I'll keep this code as a reference" | You will adapt it. Delete it and redo test-first. |
+| "Quick fix, then investigate" | No fix before the cause. |
+| "Fourth try will work" | Three failures means the design. Report. |
+| "Should pass now" | Run it. |
+| "My test file passes" | Run the whole suite before committing. |
+| "Should I check before continuing?" | Keep going; only the section 5 stops stop you. |
+| "The reviewer is right, fixing" | Check it against the code first. |
+| "A subagent can review my work" | The Lead's Reviewer is the review. |
+| "I'll split this with my subagents" | Ask the Lead to route it. |
+| "I'll push so they can see" | Push only the work branch, only for review, only when the group needs it. |
+`,
+ review: `---
+name: swarm-review
+description: Use when you are a Harness Swarm Reviewer checking another agent's group work before the Lead accepts it.
+---
+# Review a group's work
+
+You give an independent verdict on one revision. You judge the work product, not the Builder's reasoning; a stated rationale never lowers a finding's severity.
+
+## Core rules
+1. Read only. Never edit, commit or push the Builder's work. Check out other revisions only in a separate directory. No subagents.
+2. Never judge code you did not read. Never say "looks good" without checking.
+3. Every verdict names the revision it covers.
+4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill; judge against them.
+
+## 1. Inputs
+You get the goal, constraints, owned code, acceptance checks, most-likely-wrong list, the Builder's rulings, the revision range and the Builder's handoff. You do not get the chat history. If something essential is missing, ask the Lead once. Start reading within 30 minutes of the request; if you cannot, tell the Lead.
+
+## 2. What to check, in order
+1. Brief compliance: everything asked for is present; when the brief lists several files each with its own change, check that each has it. Flag each deviation so the Builder can say if it was intended. If the brief or spec itself is wrong, say so.
+2. Evidence: do the handoff's checks prove its claims? Don't rerun the suite to confirm them. Run a focused test only for a specific doubt that no run answers, and recommend heavy runs instead of running them. If evidence is missing or unreadable, report the gap; do not regenerate it.
+3. Tests: real behavior rather than mocks, edge cases, and regression tests that were seen to fail. Warnings or noise in test output are findings. So are tests that compute expected values with the code under test, assert on mocks, check text instead of behavior, or exist only for coverage. Ask whether a realistic bug would fail some test.
+4. The most-likely-wrong list. Where the brief is silent, judge by what a reasonable user would expect; silence is not permission.
+5. Code: error handling, security, data loss, concurrency, backward compatibility and data migration, performance where it matters, docs; structure (one job per file, no copied logic, no premature abstraction, fits the surrounding code and its patterns), type safety, integration tests where they matter. Flag only growth this change caused.
+6. Scope: changes outside owned code; features nobody asked for.
+
+Look outside the changes only for a risk you can name: one focused check per risk, reporting the risk and what you checked. A changed contract, lock order or shared state means checking its callers. If the change is too large for one pass, review it in passes and say so.
+
+## 3. Report in the Builder's group chat
+- Strengths: specific.
+- Critical (bugs, security, data loss, broken behavior), Important (the work cannot be trusted until fixed: wrong or fragile behavior, a missed requirement, copied logic, swallowed errors, tests that assert nothing), Minor (broader coverage, style, polish). Each finding has a location, what is wrong, why it matters, and how to fix it when that is not obvious. Grade by real severity; a nitpick is never Critical. If the brief itself requires a defect, report it as Important, marked "required by the brief".
+- Set aside: what you considered out of scope, one line each, with the reason.
+- Cannot verify: requirements you could not check from these changes alone, and what the Lead should check.
+- Verdict: meets the brief (yes/no) and quality (yes/no), then "Ready: yes | with fixes | no — revision <rev>". With findings, add one or two sentences of reasoning; with none, "No findings on <rev>" is the verdict.
+- Pass or fail the independent check, with the revision and verdict as evidence.
+- Tell the Lead directly about anything risky: private data, changed defaults, releases.
+- When talking to people, call the roles Product Manager, Engineer and Reviewer.
+
+## 4. Re-review
+Review only the changes since the revision you reviewed. Mark each finding fixed or not fixed, with its location and its test; "attempted" is not fixed. Report new problems the fix introduced, with severity. Note issues outside the fix as out of scope; they do not reopen the loop. Never re-review a revision you already reviewed.
+
+## 5. Finish
+Mark your review assignment done with the verdict and revision. Print little.
+
+## Red flags
+| Thought | Reality |
+|---|---|
+| "Small change, looks fine" | Read it. |
+| "I'll just fix it myself" | Read only. Report it. |
+| "Tests passed, so it's correct" | Check it against the brief. |
+| "Let me rerun the whole suite" | Report missing evidence; run only a focused test for a specific doubt. |
+| "The Builder explained why, so it's fine" | Judge the work, not the explanation. |
+| "Everything is Critical" | Grade by real effect. |
+| "Let me re-review everything" | Only the new changes. |
`,
}
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index eab3ce573..152334d72 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -48,6 +48,16 @@ function setup(messageFields: Record<string, unknown> = {}) {
}
describe('current Swarm role lookup', () => {
+ it('derives a Reviewer from its stored role while it is in a current group', async () => {
+ const t = setup()
+ const agent = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', role: 'reviewer' }
+ let groups = [{ leadId: 'other', agentIds: ['agent'] }]
+ vi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data:
+ path.includes('/hosts/') ? [{ tabId: 'tab', agent }] : { state: { agents: [agent], conversations: groups } } } }))
+ expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBe('review')
+ groups = []
+ expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBeNull()
+ })
it.each(['lead', 'member', 'assigned'] as const)('derives an old %s from current groups on its machine', async kind => {
const t = setup()
const agent = { id: 'agent', harnessId: 'harness', machineId: 'machine-1' }
@@ -117,7 +127,7 @@ 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 and workers use swarm-dev.')
+ 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.')
})
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index 07b7312d4..1ef9eb0d6 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -53,9 +53,10 @@ export async function swarmRoleFor(core: CoreApi, machineId: string, harnessId:
const groups = (Array.isArray(state.conversations) ? state.conversations.map(object) : []).filter(group => group.archived !== true)
if (groups.some(group => group.leadId === target.id)) return 'lead'
return groups.some(group => Array.isArray(group.agentIds) && group.agentIds.includes(target.id)
- || object(group.assignment).agentId === target.id && object(object(group.assignment).execution).machineId === machineId) ? 'dev' : null
+ || object(group.assignment).agentId === target.id && object(object(group.assignment).execution).machineId === machineId)
+ ? agent.role === 'reviewer' ? 'review' : 'dev' : null
}))
- return roles.includes('lead') ? 'lead' : roles.includes('dev') ? 'dev' : null
+ return (['lead', 'dev', 'review'] as const).find(role => roles.includes(role)) ?? null
}
interface Entry {
@@ -626,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 and workers use swarm-dev. 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 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`
+ `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/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 97ad65ad8..7d952f031 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -84,6 +84,22 @@ describe('routeTask', () => {
expect(offered.length).toBeGreaterThan(0)
expect(offered.some(c => /^(Lead|Multiply) ·/.test(c))).toBe(false)
})
+ it('offers a Reviewer only for a review group, and starts a new one as a Reviewer', async () => {
+ const offered = async (reviewer: boolean, reviewGroup: boolean) => {
+ const t = tab(); t.state.agents = agents.map(a => a.id === 'a1' && reviewer ? { ...a, role: 'reviewer' } : a)
+ if (reviewGroup) (t.state.conversations[1] as Record<string, unknown>).reviewOf = 'g0'
+ const s = scoped({ tab: t, jev: { ok: true, value: { unavailable: 'BUSY' } } })
+ const result = await routeTask(input, s, where as never, opener(), () => 'op')
+ const titles = (recorded(s).command.decision.candidates as Array<{ title: string }>).map(c => c.title)
+ return { member: titles.some(c => c.startsWith('Multiply')), next: String(result.next) }
+ }
+ expect((await offered(true, false)).member).toBe(false)
+ expect((await offered(false, true)).member).toBe(false)
+ expect((await offered(true, true)).member).toBe(true)
+ const fresh = await offered(false, true)
+ expect(fresh.next).toContain('"name":"Reviewer","role":"reviewer"')
+ expect((await offered(false, false)).next).not.toContain('"role"')
+ })
it('tells the Lead how to assign a member or start a new agent with the decision', async () => {
const member = await routeTask(input, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } } }), where as never, opener(), () => 'op')
// Cheapest first: the member on sonnet.
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 764fe9202..3b17c138d 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -118,7 +118,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;
// The group's Lead and the tab Lead coordinate; neither is a worker candidate even when idle.
const busy = new Set([String(group.leadId), String(conversations.find(c => c.id === 'lead')?.leadId),
...conversations.filter(c => active(c.assignment)).map(c => String(object(c.assignment).agentId))])
- const members = agents.filter(a => !busy.has(String(a.id)) && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))
+ // A review group is assigned only to a Reviewer, and a Reviewer nothing else.
+ const review = typeof group.reviewOf === 'string'
+ const members = agents.filter(a => !busy.has(String(a.id)) && (a.role === 'reviewer') === review && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))
// A new agent starts only on a machine in the Swarm's Machines list (the backend refuses any other): a contributed machine, or
// one an agent of the Swarm runs on. The Lead runs here, so its own machine is always listed. Of the account's machines
// only those count; the rest were never prepared with the project and would only be excluded for a missing folder
@@ -202,7 +204,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;
warnings: [...(Array.isArray(effective.warnings) ? effective.warnings : []), ...(value.machinesUnreadable === true ? [MACHINES_UNREADABLE] : []), ...(choice.short ? [choice.short] : [])],
next: verdict.pick.kind === 'member'
? `Assign with: command OPERATION_ID {"type":"work.assign","conversationId":"${input.conversationId}","agentId":"${verdict.pick.agentId}"${decision}}`
- : `Start with: start OPERATION_ID ${JSON.stringify({ conversationId: input.conversationId, name: 'Builder', cwd: text(machines.get(verdict.pick.machineId)?.pool?.cwd) ?? assessment.needs.cwd ?? '/absolute/repo/on/that/machine',
+ : `Start with: start OPERATION_ID ${JSON.stringify({ conversationId: input.conversationId, name: review ? 'Reviewer' : 'Builder', ...(review ? { role: 'reviewer' } : {}), cwd: text(machines.get(verdict.pick.machineId)?.pool?.cwd) ?? assessment.needs.cwd ?? '/absolute/repo/on/that/machine',
worktree: true, requirements: startRequirements(assessment.needs), machineId: verdict.pick.machineId, engine: verdict.pick.engine, model: verdict.pick.model,
effort: verdict.pick.effort, ...(typeof routeDecisionId === 'string' ? { routeDecisionId } : {}) })}, then assign the started agent${decision ? ' with the same routeDecisionId' : ''}. It starts from the repository's default branch, fetched first; add "branchRef":"refs/remotes/origin/BRANCH" to start from another branch.`,
}
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 0466cbd90..3ead7f60f 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -208,6 +208,8 @@ it('tells the Lead which branch a started agent works from, and how to choose an
expect(help.start).toContain('default branch, fetched first')
expect(help.start).toContain('branchRef')
expect(help.startRequest).toMatchObject({ worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH' })
+ expect(help.start).toContain('role "reviewer"')
+ expect(help.start).toContain('reviewOf')
})
it('keeps host capacity separate from account authority and closes it on disconnect or identity change', async () => {
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 38c7c2d57..24bebe294 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -17,7 +17,7 @@ const HELP = {
messages: 'messages GROUP: read recent messages in a conversation.',
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.',
+ 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.',
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.',
@@ -30,6 +30,7 @@ const HELP = {
{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },
{ type: 'message.send', conversationId: 'GROUP', text: 'A message addressed to an agent', replyTo: null, recipientIds: ['AGENT'] },
{ type: 'conversation.create', title: 'Outcome', task: { goal: 'An independently assignable result', changes: 'What changes', constraints: 'What must stay true', owns: ['Paths or code areas'] }, checks: [{ description: 'Observable acceptance evidence', independent: false }] },
+ { type: 'conversation.create', title: 'Review: Outcome', reviewOf: 'GROUP', task: { goal: 'An independent verdict on the Builder\'s revision', changes: 'None: read only', constraints: 'The reviewed group\'s constraints', owns: ['The reviewed group\'s owned code, read only'] }, checks: [{ description: 'Verdict with the reviewed revision', independent: false }] },
{ type: 'conversation.agent', conversationId: 'GROUP', agentId: 'AGENT', present: true, lead: false },
{ type: 'work.define', conversationId: 'GROUP', task: { goal: 'What to deliver', changes: 'What changes', constraints: 'What must stay true', owns: ['Paths or code areas'] }, checks: [{ description: 'Observable acceptance evidence', independent: false }] },
{ type: 'work.cancel', conversationId: 'GROUP', assignmentId: 'ATTEMPT', reason: 'Lead or tab owner only: why the task is cancelled, in one short sentence' },
diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.ts
index 704457ce8..a7ff0032f 100644
--- a/cli/src/superTabs/start.spec.ts
+++ b/cli/src/superTabs/start.spec.ts
@@ -215,6 +215,16 @@ it.each(['claude', 'codex', 'opencode'])('only tells supported %s workers to use
}
})
+it.each(['claude', 'codex'])('starts a %s Reviewer with the built-in swarm-review skill', async engine => {
+ const f = fixture()
+ f.start.request = { ...f.start.request, engine, role: 'reviewer' } as typeof f.start.request
+ await startAgent({ action: 'start', tabId: 'tab', operationId: 'reviewer-prompt', request: f.start.request }, f.scoped, where, f.open)
+ const payload = f.request.mock.calls.find(call => call[0] === 'agent_create')![1]!
+ expect(payload.swarmRole).toBe('review')
+ expect(payload.prompt).toContain('swarm-review skill')
+ expect(payload.prompt).not.toContain('swarm-dev')
+})
+
it('asks for an owner contribution instead of widening a guest machine connection', async () => {
const f = fixture({ guest: true })
expect(await startAgent({ action: 'start', tabId: 'tab', operationId: 'guest-start', request: f.start.request }, f.scoped, where, f.open))
diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.ts
index f5af4c641..73ded42ca 100644
--- a/cli/src/superTabs/start.ts
+++ b/cli/src/superTabs/start.ts
@@ -141,10 +141,14 @@ export async function startAgent(input: Json, scoped: ScopedRequest, where: Wher
// Both direct and contributed-host starts reach this boundary. Existing
// native receipts are read above and never have their permissions changed.
// Engines without a full mode retain their existing approving launch flags.
+ // The backend starts a Reviewer only on Claude Code or Codex, the engines with built-in Swarm skills.
+ const skilled = ['claude', 'codex'].includes(String(request.engine)), reviewer = request.role === 'reviewer'
const payload: Json = { engine: request.engine, name: request.name, creationId, startedBy: 'agent', bypassPermission: true,
...(permissionModeFlags(request.engine as AgentEngine, 'full') ? { permissionMode: 'full' } : {}),
- ...(['claude', 'codex'].includes(String(request.engine)) ? { swarmRole: 'dev' } : {}),
- prompt: `You are joining a shared Super Tab. ${['claude', 'codex'].includes(String(request.engine)) ? 'Use the built-in swarm-dev skill. ' : ''}Run harness super-tab --tab ${input.tabId} status until this harness appears in the roster. Do not begin project work yet. Your lead will assign work in conversation ${request.conversationId}. Reply in that conversation using harness super-tab --tab ${input.tabId} post ${request.conversationId} 'your message' UNIQUE_OPERATION_ID. Run harness super-tab help for commands. If sandbox restrictions block this local command, request permission to run it outside the sandbox.`,
+ ...(skilled ? { swarmRole: reviewer ? 'review' : 'dev' } : {}),
+ prompt: `You are joining a shared Super Tab${reviewer ? ' as a Reviewer' : ''}. ${skilled ? `Use the built-in swarm-${reviewer ? 'review' : 'dev'} skill. ` : ''}Run harness super-tab --tab ${input.tabId} status until this harness appears in the roster. ${reviewer
+ ? `Do not review yet. You review work in conversation ${request.conversationId} when it is ready for review.`
+ : `Do not begin project work yet. Your lead will assign work in conversation ${request.conversationId}.`} Reply in that conversation using harness super-tab --tab ${input.tabId} post ${request.conversationId} 'your message' UNIQUE_OPERATION_ID. Run harness super-tab help for commands. If sandbox restrictions block this local command, request permission to run it outside the sandbox.`,
...(request.worktree ? { projectSource: 'worktree', gitSource: request.cwd, branchName: `super-tab/${startId}`,
// No branch named: the repository's default branch, fetched, not the host checkout's old HEAD.
...(request.branchRef ? { branchRef: request.branchRef } : { branchBase: 'default' }) } : { cwd: request.cwd }),