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.

Desktop: edit per-project custom Swarm roles (#1659)

0xken15a36e2d1e0f78
diff --git a/desktop/lib/state/harness_launch_integration.dart b/desktop/lib/state/harness_launch_integration.dart
index 5fa0c93e7..58b78c434 100644
--- a/desktop/lib/state/harness_launch_integration.dart
+++ b/desktop/lib/state/harness_launch_integration.dart
@@ -1,5 +1,15 @@
import 'harness_attachments.dart';
+class HarnessLaunchRole {
+ const HarnessLaunchRole({
+ required this.id,
+ required this.name,
+ required this.kind,
+ });
+ final String id, name, kind;
+ String get swarmRole => kind == 'reviewer' ? 'review' : 'dev';
+}
+
/// An optional destination around the existing New Harness launch. Preparing
/// may add instructions; completion registers the confirmed native session.
/// Neither callback starts an agent. Retry keeps the same native receipt.
@@ -21,10 +31,22 @@ class HarnessLaunchIntegration {
this.forcedPermissionMode,
this.swarmRole,
this.swarmSkillMode,
+ this.roles,
+ this.roleId,
});
final String creationId, actionLabel;
- final String? swarmRole;
+ String? swarmRole;
String? swarmSkillMode;
+ final List<HarnessLaunchRole>? roles;
+ String? roleId;
+
+ void chooseRole(String id) {
+ final selected = roles?.where((role) => role.id == id).firstOrNull;
+ if (selected == null) return;
+ roleId = selected.id;
+ swarmRole = selected.swarmRole;
+ }
+
// Restores the person's original request from a destination launch journal.
final String? initialTask;
// The only agents this destination may start, or null for any.
diff --git a/desktop/lib/super_tabs/agent_details.dart b/desktop/lib/super_tabs/agent_details.dart
index fb5edad38..bdab71566 100644
--- a/desktop/lib/super_tabs/agent_details.dart
+++ b/desktop/lib/super_tabs/agent_details.dart
@@ -257,11 +257,12 @@ Future<void> showSuperTabAgentDetails(
children: [
_fact(
'Role',
- controller.snapshot?.isLead(agent.id) == true
- ? 'Product Manager'
- : current.isReviewer
- ? 'Reviewer'
- : 'Engineer',
+ controller.snapshot?.activeRoleForAgent(current)?.name ??
+ (controller.snapshot?.isLead(agent.id) == true
+ ? 'Product Manager'
+ : current.isReviewer
+ ? 'Reviewer'
+ : 'Engineer'),
),
if (info.engine case final value?) _fact('Engine', value),
if (current.name != name) _fact('Agent name', current.name),
diff --git a/desktop/lib/super_tabs/launch.dart b/desktop/lib/super_tabs/launch.dart
index 38d3ceedf..d8a18eb80 100644
--- a/desktop/lib/super_tabs/launch.dart
+++ b/desktop/lib/super_tabs/launch.dart
@@ -55,13 +55,38 @@ class SuperTabLaunch {
final launch = SuperTabLaunch._(app, tab.id, account, key, saved);
final recovering =
saved['phase'] == 'starting' || saved['phase'] == 'joining';
+ List<HarnessLaunchRole>? roles;
+ if (saved['lead'] != true && tab.superTabId != null) {
+ final current = await app.superTabs.map(
+ 'GET',
+ '/api/super-tabs/${tab.superTabId}',
+ );
+ final snapshot = SuperTabSnapshot.fromJson(superTabMap(current['state']));
+ final project = snapshot.projectFor(conversationId);
+ if (project?.skillSet == 'custom') {
+ roles = [
+ for (final role in project?.roles ?? const <SuperTabRole>[])
+ if (role.kind == 'builder' || role.kind == 'reviewer')
+ HarnessLaunchRole(id: role.id, name: role.name, kind: role.kind),
+ ];
+ }
+ }
+ final selectedRole =
+ roles?.where((role) => role.id == saved['roleId']).firstOrNull ??
+ roles?.where((role) => role.kind == 'builder').firstOrNull ??
+ roles?.firstOrNull;
late final HarnessLaunchIntegration integration;
integration = HarnessLaunchIntegration(
forcedPermissionMode: 'full',
creationId: saved['creationId'] as String? ?? superTabOperationId(),
initialTask: saved['initialMessage'] as String?,
- swarmRole: saved['lead'] == true ? 'lead' : 'dev',
+ swarmRole: saved['lead'] == true
+ ? 'lead'
+ : selectedRole?.swarmRole ??
+ (saved['roleKind'] == 'reviewer' ? 'review' : 'dev'),
swarmSkillMode: saved['skillMode'] as String? ?? 'orchestration',
+ roles: roles,
+ roleId: recovering ? saved['roleId'] as String? : selectedRole?.id,
actionLabel: saved['newProject'] == true
? 'New Project'
: saved['lead'] == true
@@ -76,6 +101,19 @@ class SuperTabLaunch {
projectVisibilityLocked:
saved['projectPrepared'] == true || saved['creationRequest'] != null,
prepare: (machine, task) async {
+ if (integration.roles != null) {
+ final chosen = integration.roles!
+ .where((role) => role.id == integration.roleId)
+ .firstOrNull;
+ if (chosen == null) {
+ throw const SuperTabFailure(
+ 'ROLE_UNAVAILABLE',
+ 'Choose a role before starting this agent.',
+ );
+ }
+ saved['roleId'] = chosen.id;
+ saved['roleKind'] = chosen.kind;
+ }
if (saved['projectPrepared'] != true &&
saved['creationRequest'] == null) {
saved['visibility'] = integration.projectVisibility ?? 'public';
@@ -84,6 +122,11 @@ class SuperTabLaunch {
final prompt = await launch.prepare(machine, task);
integration.swarmSkillMode =
saved['skillMode'] as String? ?? 'orchestration';
+ integration.swarmRole = saved['lead'] == true
+ ? 'lead'
+ : saved['roleKind'] == 'reviewer'
+ ? 'review'
+ : 'dev';
return prompt;
} on SuperTabFailure catch (failure) {
// Validation rejects the request before applying it. A lost response
@@ -226,6 +269,21 @@ class SuperTabLaunch {
}
saved['skillMode'] =
snapshot.projectFor(conversationId)?.skillMode ?? 'orchestration';
+ final project = snapshot.projectFor(conversationId);
+ if (project?.skillSet == 'custom') {
+ final chosen = project?.roles
+ ?.where((role) => role.id == saved['roleId'])
+ .firstOrNull;
+ if (chosen == null || chosen.kind != saved['roleKind']) {
+ throw const SuperTabFailure(
+ 'ROLE_UNAVAILABLE',
+ 'This role changed or is no longer available. Close this form and choose a role again.',
+ );
+ }
+ } else {
+ saved.remove('roleId');
+ saved.remove('roleKind');
+ }
final prompt = superTabLaunchPrompt(
tabId: saved['tabId'] as String,
conversationId: saved['conversationId'] as String,
@@ -280,6 +338,7 @@ class SuperTabLaunch {
'harnessId': harnessId,
'name': saved['lead'] == true ? 'Lead' : native.displayName,
'lead': saved['lead'],
+ if (saved['roleId'] case final String roleId) 'roleId': roleId,
if (saved['lead'] == true && project != null)
'project': {
'cwd': project.root ?? project.cwd,
diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dart
index 3539ea739..140799062 100644
--- a/desktop/lib/super_tabs/machines.dart
+++ b/desktop/lib/super_tabs/machines.dart
@@ -1558,16 +1558,21 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
final name = c.snapshot!.agentName(agent.id);
final activity = _activity(view, agent);
final lead = c.snapshot!.isLead(agent.id);
- final role = lead
- ? 'Product Manager'
- : agent.isReviewer
- ? 'Reviewer'
- : 'Engineer';
- final badge = lead
- ? 'PM'
- : agent.isReviewer
- ? 'Rev'
- : 'Dev';
+ final customRole = c.snapshot!.activeRoleForAgent(agent);
+ final role =
+ customRole?.name ??
+ (lead
+ ? 'Product Manager'
+ : agent.isReviewer
+ ? 'Reviewer'
+ : 'Engineer');
+ final badge =
+ customRole?.name ??
+ (lead
+ ? 'PM'
+ : agent.isReviewer
+ ? 'Rev'
+ : 'Dev');
final info = SuperTabAgentInfo(c, widget.app, agent, activity: activity);
final theme = terminalThemeFor(
grid.AppTheme.surfacePalette,
diff --git a/desktop/lib/super_tabs/model.dart b/desktop/lib/super_tabs/model.dart
index f21c7d3e2..b61c0facb 100644
--- a/desktop/lib/super_tabs/model.dart
+++ b/desktop/lib/super_tabs/model.dart
@@ -44,6 +44,7 @@ class SuperTabAgent {
machineOwnerId =
row['machineOwnerId'] as String? ?? _text(row, 'contributorId'),
role = row['role'] as String?,
+ roleId = row['roleId'] as String?,
limitedUntil = DateTime.tryParse(row['limitedUntil'] as String? ?? ''),
configuration = Map.unmodifiable(superTabMap(row['configuration']));
final String id, projectId, name, machineId, harnessId, contributorId;
@@ -59,6 +60,7 @@ class SuperTabAgent {
final String? displayName;
// Absent until the backend sends one; an agent without a role is a Builder.
final String? role;
+ final String? roleId;
bool get isReviewer => role == 'reviewer';
final Map<String, dynamic> configuration;
String get engine => configuration['engine'] as String? ?? '';
@@ -118,6 +120,16 @@ class SuperTabConversation {
final Map<String, dynamic>? assignment;
}
+class SuperTabRole {
+ SuperTabRole.fromJson(Map<String, dynamic> row)
+ : id = _text(row, 'id'),
+ name = _text(row, 'name'),
+ kind = _text(row, 'kind'),
+ version = _text(row, 'version');
+
+ final String id, name, kind, version;
+}
+
class SuperTabProject {
SuperTabProject.fromJson(Map<String, dynamic> row)
: id = _text(row, 'id'),
@@ -125,6 +137,15 @@ class SuperTabProject {
ownerId = _text(row, 'ownerId'),
leadConversationId = _text(row, 'leadConversationId'),
skillMode = row['skillMode'] == 'default' ? 'default' : 'orchestration',
+ skillSet =
+ const {'default', 'orchestration', 'custom'}.contains(row['skillSet'])
+ ? row['skillSet'] as String
+ : row['skillMode'] == 'default'
+ ? 'default'
+ : 'orchestration',
+ roles = row['roles'] is List
+ ? _list(row['roles'], SuperTabRole.fromJson)
+ : null,
isPrivate = row['visibility'] == 'private',
memberIds = [
for (final member in row['members'] as List? ?? const [])
@@ -136,6 +157,8 @@ class SuperTabProject {
: null;
final String id, name, ownerId, leadConversationId;
final String skillMode;
+ final String skillSet;
+ final List<SuperTabRole>? roles;
final bool isPrivate;
final List<String> memberIds;
final int updateMinutes;
@@ -218,6 +241,24 @@ class SuperTabSnapshot {
bool isLead(String agentId) => leadProjectForAgent(agentId) != null;
+ SuperTabRole? activeRoleForAgent(SuperTabAgent agent) {
+ final leadProject = leadProjectForAgent(agent.id);
+ final roleKind = leadProject != null
+ ? 'lead'
+ : agent.isReviewer
+ ? 'reviewer'
+ : 'builder';
+ final project =
+ leadProject ??
+ projects.where((entry) => entry.id == agent.projectId).firstOrNull;
+ if (project?.skillSet != 'custom') return null;
+ final roles = project?.roles ?? const <SuperTabRole>[];
+ return roles
+ .where((role) => role.id == agent.roleId && role.kind == roleKind)
+ .firstOrNull ??
+ roles.where((role) => role.kind == roleKind).firstOrNull;
+ }
+
String? leadProtectionReason(String agentId) {
final project = leadProjectForAgent(agentId);
if (project == null) return null;
diff --git a/desktop/lib/super_tabs/project_options.dart b/desktop/lib/super_tabs/project_options.dart
index 1059c820f..2b1695262 100644
--- a/desktop/lib/super_tabs/project_options.dart
+++ b/desktop/lib/super_tabs/project_options.dart
@@ -7,6 +7,7 @@ import 'controller.dart';
import 'dialog_scope.dart';
import 'model.dart';
import 'project_visibility.dart';
+import 'roles_editor.dart';
Future<void> showProjectAction(
BuildContext context,
@@ -22,7 +23,7 @@ Future<void> showProjectAction(
var visibility = project.isPrivate ? 'private' : 'public';
final members = project.memberIds.toSet();
var minutes = project.updateMinutes;
- var mode = project.skillMode;
+ var mode = project.skillSet;
var busy = false;
await showAppDialog<void>(
context: context,
@@ -44,7 +45,7 @@ Future<void> showProjectAction(
title: Text(switch (action) {
'rename' => 'Rename project',
'sharing' => 'Sharing',
- 'skills' => 'Skills for this project',
+ 'skills' => 'Instructions for this project',
'cadence' => 'Project updates',
_ => 'Project details',
}),
@@ -132,33 +133,87 @@ Future<void> showProjectAction(
),
],
if (action == 'skills')
- RadioGroup<String>(
- groupValue: mode,
- onChanged: (value) {
- if (busy || !canManage || value == null) return;
- update(() => mode = value);
- },
- child: Column(
- mainAxisSize: MainAxisSize.min,
- children: [
- RadioListTile<String>(
- value: 'default',
- enabled: !busy && canManage,
- contentPadding: EdgeInsets.zero,
- title: const Text(
- 'Default — the team process; agents otherwise work their usual way',
- ),
- ),
- RadioListTile<String>(
- value: 'orchestration',
- enabled: !busy && canManage,
- contentPadding: EdgeInsets.zero,
- title: const Text(
- 'Harness orchestration — adds Harness practices: plans, test-first, review rounds',
- ),
+ Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ 'Instructions',
+ style: DesktopChrome.metadata(),
+ ),
+ const SizedBox(height: 8),
+ RadioGroup<String>(
+ groupValue: mode,
+ onChanged: (value) {
+ if (busy ||
+ !canManage ||
+ value == null ||
+ (value == 'custom' &&
+ current?.roles == null)) {
+ return;
+ }
+ update(() => mode = value);
+ },
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ RadioListTile<String>(
+ value: 'default',
+ enabled: !busy && canManage,
+ contentPadding: EdgeInsets.zero,
+ title: const Text(
+ 'Default — the team process; agents otherwise work their usual way',
+ ),
+ ),
+ RadioListTile<String>(
+ value: 'orchestration',
+ enabled: !busy && canManage,
+ contentPadding: EdgeInsets.zero,
+ title: const Text(
+ 'Harness orchestration — adds Harness practices: plans, test-first, review rounds',
+ ),
+ ),
+ RadioListTile<String>(
+ value: 'custom',
+ enabled:
+ !busy &&
+ canManage &&
+ current?.roles != null,
+ contentPadding: EdgeInsets.zero,
+ title: const Text('Custom'),
+ ),
+ ],
),
- ],
- ),
+ ),
+ if (canManage)
+ current?.roles == null
+ ? OutlinedButton(
+ onPressed:
+ busy || c.saving || c.hasPendingAction
+ ? null
+ : () async {
+ update(() => busy = true);
+ await c.command({
+ 'type': 'project.roles.create',
+ 'projectId': project.id,
+ 'roles': defaultProjectRoles(),
+ });
+ if (context.mounted) {
+ update(() => busy = false);
+ }
+ },
+ child: const Text('Create custom set'),
+ )
+ : TextButton(
+ onPressed: busy
+ ? null
+ : () => showRolesEditor(
+ context,
+ c,
+ project.id,
+ ),
+ child: const Text('Edit custom roles'),
+ ),
+ ],
),
if (readOnly) ...[
Text(
@@ -213,6 +268,9 @@ Future<void> showProjectAction(
c.saving ||
c.hasPendingAction ||
name.trim().isEmpty ||
+ (action == 'skills' &&
+ mode == 'custom' &&
+ current?.roles == null) ||
(action != 'cadence' && !canManage)
? null
: () async {
diff --git a/desktop/lib/super_tabs/roles_editor.dart b/desktop/lib/super_tabs/roles_editor.dart
new file mode 100644
index 000000000..e2491d375
--- /dev/null
+++ b/desktop/lib/super_tabs/roles_editor.dart
@@ -0,0 +1,511 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:flutter/material.dart';
+
+import '../shared/theme/app_theme.dart' as grid;
+import '../shared/widgets/app_dialog.dart';
+import '../widgets/desktop_chrome.dart';
+import 'controller.dart';
+import 'dialog_scope.dart';
+import 'model.dart';
+
+/// Shipped Default skill texts. Custom sets start from these exact texts, never
+/// from the Harness orchestration set or a server-side approximation.
+const _defaultLead = r'''---
+name: swarm-lead
+description: Use when coordinating a Harness Swarm project as its Lead (shown as Product Manager): taking requests, splitting work into groups, assigning, tracking and closing them.
+---
+# Lead a Swarm project
+
+You own the task list, the order and the answers. People bring requests to the project chat; Builders do the work in groups; Reviewers check it. Work otherwise the way you normally do.
+
+## Core rules
+1. Only you open tasks, choose owners and set the order. Builders propose; you answer once: yes, yes as a task, no, or yes but…
+2. Multi-part work, or work over about 15 minutes, goes to a group. Answers, lookups and quick fixes you do yourself.
+3. Route every new agent and every assignment; use the pick or give a reason.
+4. Done means shown: merged and tried where it runs. A report is not evidence.
+5. The owner still decides credentials, spending, deleting data, publishing outside the repo, releases, and loosening privacy or safety. Merging and opening a PR follow the owner's standing instructions.
+6. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) and the owner's words outrank this skill.
+
+## 1. Take a request
+- Read the project and the chat first; don't ask what they already answer.
+- Restate the request in a sentence or two, mark guesses, and ask only what changes what gets built.
+- Size it: quick (do it), one group (short description, owner's ok, then assign), several groups (a short written plan, owner's ok, then assign).
+
+## 2. Write each task
+Every group carries:
+- Why: the reason, in one or two sentences.
+- Wanted: what changes, with exact names, values and visible copy.
+- Owned code, and what is off limits. No two groups own the same code.
+- Hand back: what the Builder returns (branch, PR, revision, evidence, links).
+- Checks: observable evidence that it works.
+- Most likely wrong: the cases nobody checks, most likely first, each with what a user would expect.
+- Needs: nothing, a machine, test input, a person's hands, or a real user.
+
+Keep each Builder's list a few tasks deep; do the easy, self-contained parts first. Run groups in parallel only when they don't share code, machines or data.
+
+## 3. Route, start, assign
+- Route each group; reuse an idle agent before starting one; start only on the Swarm's machines.
+- The brief is all a Builder gets; never rely on chat history.
+- Before assigning, look at other projects' active work; if your task touches the same code, say so in the Leads conversation and agree an order first.
+
+## 4. Keep work moving
+- Each time you are woken, look at active work.
+- A worker with active work that has said nothing for 20 minutes: ask it.
+- When a worker seems stuck, read its terminal; answer prompts within its task; ask the owner before approving anything risky.
+- A Builder or Reviewer that has been down for 2 hours (its machine offline, its session gone, or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).
+- Work with no progress for 6 hours goes back to you: reassign it or cut it smaller.
+- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.
+- Settle ambiguities you can and record "Ruling: what — why — cost if wrong".
+- When a worker finishes: reuse, keep or stop. Prefer stop.
+
+## 5. Review and accept
+- Work that will be merged, or carries medium risk or more, gets a Reviewer: create "Review: <group>", route it, assign it, and add the Reviewer to the Builder's group.
+- Findings go back to the Builder; you rule on disagreements.
+- Accept only when the reviewed revision is the handed-off revision, its checks have evidence, and CI is green on it.
+- Close the task saying what was and was not delivered.
+
+## 6. Skills for this project
+When the project owner asks in chat to switch this project's skills (Default or Harness orchestration), change it with the project skills command, quoting their message. Only the project owner's own chat message counts.
+
+## 7. Keep people informed
+- At the project's cadence, post a scored table: one row per group, 0 to 1, its owner and what it waits on. Only merged and tried scores 1.0. If nothing changed, post nothing.
+- Answer questions, blockers and completions at once.
+- Every post carries a result, a decision asked for with your recommendation, a question, or a fault; never an acknowledgement alone.
+- Write like a colleague: short, in their language, no commands or internal ids. Call the roles Product Manager, Engineer and Reviewer.
+''';
+
+const _defaultEngineer = r'''---
+name: swarm-dev
+description: Use when you are a Harness Swarm Builder (shown as Engineer) taking, doing or handing off an assigned group.
+---
+# Build an assigned group
+
+You finish one group's work completely, inside its brief, as if nobody will come back to help. Work otherwise the way you normally do.
+
+## Core rules
+1. Stay inside your brief and owned code. Never touch another group's code or another Builder's branch.
+2. No claim without showing it: say what ran, where, on which revision, and what was not shown. A local result is not a result on the real machine or device.
+3. Push only your own work branch. No merge, release or force-push unless told.
+4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.
+
+## 1. Take the assignment
+- Say in the group that you took it and what you will do first; mark it working.
+- Read the whole brief: why, wanted, owned code, hand back, checks, most likely wrong, needs.
+- Read how the code behaves today before changing it.
+- If the brief needs a machine, device or person, check it is available; if not, post a "Needs:" line and do the parts that don't depend on it.
+- Harness already created your worktree; work there.
+
+## 2. Do the work
+- Build each piece completely. Test everything that can be tested without the device or person, and keep any remaining manual step to one command or one action.
+- A fix comes with a test that fails before it and passes after.
+- Name a known flaky test instead of letting it block you.
+- Have something to show at least every 20 minutes: a push or a short progress line.
+- When an answer is unclear, take its narrowest safe reading and say so. Keep working on whatever doesn't depend on a question, and don't ask twice.
+- To split the work or take more, ask the Lead. You may propose new work; the Lead decides.
+
+## 3. 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, then do the independent parts.
+- Stop and ask before anything irreversible, security-sensitive, outside your worktree, visible or audible on a real device, or moving hardware.
+
+## 4. Hand off
+- Ready means: your branch pushed, a PR when the project uses PRs, and green CI on it.
+- The handoff opens "Ready: yes" or "Ready: no", then: revision, what you checked (command and result), what is not shown yet, the one command or action left for the real device or person if any, and "most likely wrong here".
+- Mark ready for review when the group has a Reviewer; otherwise mark done.
+
+## 5. Review findings
+- Check each finding against the code; push back with evidence when it is wrong.
+- Fix the real ones, rerun the checks, and reply with what you changed and the result.
+- Mark ready again with the new revision.
+
+## 6. Talk
+- Keep posts short: one result line and the command, no logs, short revision hashes.
+- Every post carries a result, a question, or a fault; never an acknowledgement alone.
+- Write to people in their language, without commands or internal ids. Call the roles Product Manager, Engineer and Reviewer.
+''';
+
+const _defaultReviewer = r'''---
+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. Work otherwise the way you normally do.
+
+## Core rules
+1. Read only. Never edit, commit or push the Builder's work, and never merge your own review target.
+2. Read everything before judging: the brief, the handoff, the diff and the last comments.
+3. Every verdict names the revision it covers.
+4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.
+
+## 1. When
+Start within 30 minutes of being asked; oldest ready work first. If you cannot, tell the Lead.
+
+## 2. What to look for
+- Wrong behaviour, missed cases, and what the brief asked for but is missing.
+- A switch that is not really off, a default that changed, a test that cannot fail.
+- A doc or comment that disagrees with the code; a number nobody measured.
+- Evidence: does the handoff show what it claims, on this revision? Run the project's checks yourself when the handoff's evidence does not cover a doubt.
+
+## 3. Report in the Builder's group
+- Findings P1 (must fix), P2 (fix before accepting), P3 (later), each with file:line, what is wrong and the fix.
+- Verdict: "No finding on <rev>", or "Hold — <rev>" with the findings. A re-review covers only the new changes.
+- Pass or fail the independent check with the revision and verdict.
+- Tell the Lead at once about privacy, interface breaks, default-on changes to safety or updates, and device behaviour nobody could show.
+- Keep posts short, in the people's language, without commands or internal ids. Call the roles Product Manager, Engineer and Reviewer.
+
+## 4. Finish
+Mark your review done with the verdict and revision.
+''';
+
+List<Map<String, String>> defaultProjectRoles() => [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'text': _defaultLead,
+ },
+ {
+ 'id': 'dev',
+ 'name': 'Engineer',
+ 'kind': 'builder',
+ 'text': _defaultEngineer,
+ },
+ {
+ 'id': 'review',
+ 'name': 'Reviewer',
+ 'kind': 'reviewer',
+ 'text': _defaultReviewer,
+ },
+];
+
+Future<void> showRolesEditor(
+ BuildContext context,
+ SuperTabController controller,
+ String projectId,
+) async {
+ final project = controller.snapshot?.projects
+ .where((entry) => entry.id == projectId)
+ .firstOrNull;
+ if (project?.ownerId != controller.accountId || project?.roles == null) {
+ return;
+ }
+ await showAppDialog<void>(
+ context: context,
+ builder: (context) => SuperTabDialogScope(
+ controller: controller,
+ projectId: projectId,
+ child: _RolesEditor(controller: controller, projectId: projectId),
+ ),
+ );
+}
+
+class _RolesEditor extends StatefulWidget {
+ const _RolesEditor({required this.controller, required this.projectId});
+ final SuperTabController controller;
+ final String projectId;
+
+ @override
+ State<_RolesEditor> createState() => _RolesEditorState();
+}
+
+class _RolesEditorState extends State<_RolesEditor> {
+ late Future<Map<String, String>> _texts = _loadTexts();
+ bool _busy = false;
+ String? _error;
+
+ SuperTabProject? get _project => widget.controller.snapshot?.projects
+ .where((project) => project.id == widget.projectId)
+ .firstOrNull;
+
+ Future<Map<String, String>> _loadTexts() async {
+ final roles = _project?.roles ?? const <SuperTabRole>[];
+ final entries = await Future.wait([
+ for (final role in roles)
+ () async {
+ final response = await widget.controller.request(
+ 'GET',
+ '/api/super-tabs/${Uri.encodeComponent(widget.controller.tabId)}/projects/${Uri.encodeComponent(widget.projectId)}/roles/${Uri.encodeComponent(role.id)}',
+ );
+ final text = response['text'];
+ if (text is! String) {
+ throw const FormatException('Could not read this role’s text.');
+ }
+ return MapEntry(role.id, text);
+ }(),
+ ]);
+ return Map.fromEntries(entries);
+ }
+
+ Future<bool> _send(Map<String, dynamic> command) async {
+ setState(() {
+ _busy = true;
+ _error = null;
+ });
+ final result = await widget.controller.command(command);
+ if (!mounted) return false;
+ setState(() {
+ _busy = false;
+ _error = result == null
+ ? widget.controller.operationError ?? 'Could not save the role.'
+ : null;
+ if (result != null) _texts = _loadTexts();
+ });
+ return result != null;
+ }
+
+ Future<void> _edit(SuperTabRole? role, String text) async {
+ final nameController = TextEditingController(text: role?.name ?? '');
+ final textController = TextEditingController(text: text);
+ var kind = role?.kind ?? 'builder';
+ String? error;
+ try {
+ await showAppDialog<void>(
+ context: context,
+ builder: (dialogContext) => StatefulBuilder(
+ builder: (dialogContext, update) {
+ final name = nameController.text.trim();
+ final markdown = textController.text;
+ final duplicate =
+ _project?.roles?.any(
+ (other) =>
+ other.id != role?.id &&
+ other.name.toLowerCase() == name.toLowerCase(),
+ ) ??
+ false;
+ final valid =
+ name.isNotEmpty &&
+ name.length <= 40 &&
+ !duplicate &&
+ markdown.isNotEmpty &&
+ utf8.encode(markdown).length <= 65536;
+ return AlertDialog(
+ title: Text(role == null ? 'Add role' : 'Edit ${role.name}'),
+ content: SizedBox(
+ width: 540,
+ child: SingleChildScrollView(
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ TextField(
+ key: const ValueKey('role-name'),
+ controller: nameController,
+ maxLength: 40,
+ decoration: const InputDecoration(labelText: 'Name'),
+ onChanged: (_) => update(() {}),
+ ),
+ DropdownButton<String>(
+ key: const ValueKey('role-kind'),
+ value: kind,
+ items: [
+ if (role?.kind == 'lead')
+ const DropdownMenuItem(
+ value: 'lead',
+ child: Text('Product Manager'),
+ ),
+ if (role?.kind != 'lead') ...[
+ const DropdownMenuItem(
+ value: 'builder',
+ child: Text('Engineer'),
+ ),
+ const DropdownMenuItem(
+ value: 'reviewer',
+ child: Text('Reviewer'),
+ ),
+ ],
+ ],
+ onChanged: role?.kind == 'lead' || _busy
+ ? null
+ : (value) => update(() => kind = value!),
+ ),
+ const SizedBox(height: 12),
+ TextField(
+ key: const ValueKey('role-text'),
+ controller: textController,
+ minLines: 5,
+ maxLines: 12,
+ decoration: InputDecoration(
+ labelText: name.isEmpty
+ ? 'Instructions'
+ : '$name instructions',
+ ),
+ onChanged: (_) => update(() {}),
+ ),
+ if (duplicate)
+ const Text('Each role needs a different name.'),
+ if (utf8.encode(markdown).length > 65536)
+ const Text('Instructions are limited to 64 KB.'),
+ if (error != null) Text(error!),
+ ],
+ ),
+ ),
+ ),
+ actions: [
+ TextButton(
+ onPressed: _busy ? null : () => Navigator.pop(dialogContext),
+ child: const Text('Cancel'),
+ ),
+ FilledButton(
+ onPressed: !valid || _busy
+ ? null
+ : () async {
+ final saved = await _send({
+ 'type': 'project.role.set',
+ 'projectId': widget.projectId,
+ 'role': {
+ 'id':
+ role?.id ??
+ superTabOperationId().substring(0, 12),
+ 'name': name,
+ 'kind': kind,
+ 'text': markdown,
+ },
+ });
+ if (!dialogContext.mounted) return;
+ if (saved) {
+ Navigator.pop(dialogContext);
+ } else {
+ update(() => error = _error);
+ }
+ },
+ child: const Text('Save role'),
+ ),
+ ],
+ );
+ },
+ ),
+ );
+ } finally {
+ nameController.dispose();
+ textController.dispose();
+ }
+ }
+
+ Future<void> _reset() async {
+ final confirmed = await showAppDialog<bool>(
+ context: context,
+ builder: (dialogContext) => AlertDialog(
+ title: const Text('Reset custom roles to Default?'),
+ content: const Text(
+ 'This replaces every custom role and its instructions. Agents using removed roles may need to stop or be reassigned first.',
+ ),
+ actions: [
+ TextButton(
+ onPressed: () => Navigator.pop(dialogContext, false),
+ child: const Text('Cancel'),
+ ),
+ FilledButton(
+ style: grid.dangerButtonStyle(),
+ onPressed: () => Navigator.pop(dialogContext, true),
+ child: const Text('Reset'),
+ ),
+ ],
+ ),
+ );
+ if (confirmed != true || !mounted) return;
+ await _send({
+ 'type': 'project.roles.reset',
+ 'projectId': widget.projectId,
+ 'roles': defaultProjectRoles(),
+ });
+ }
+
+ @override
+ Widget build(BuildContext context) => ListenableBuilder(
+ listenable: widget.controller,
+ builder: (context, _) {
+ final roles = _project?.roles ?? const <SuperTabRole>[];
+ return FutureBuilder<Map<String, String>>(
+ future: _texts,
+ builder: (context, read) => AlertDialog(
+ title: const Text('Custom roles'),
+ content: SizedBox(
+ width: 560,
+ height: 440,
+ child: ListView(
+ children: [
+ if (read.hasError)
+ Text(switch (read.error) {
+ SuperTabFailure failure => failure.message,
+ _ => 'Could not read the role texts.',
+ })
+ else if (read.data == null)
+ const LinearProgressIndicator()
+ else
+ for (final role in roles)
+ Card(
+ child: Padding(
+ padding: const EdgeInsets.all(12),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(role.name, style: DesktopChrome.control()),
+ Text(switch (role.kind) {
+ 'lead' => 'Product Manager',
+ 'reviewer' => 'Reviewer',
+ _ => 'Engineer',
+ }, style: DesktopChrome.metadata()),
+ const SizedBox(height: 8),
+ Text(
+ read.data![role.id] ?? '',
+ maxLines: 3,
+ overflow: TextOverflow.ellipsis,
+ ),
+ Row(
+ children: [
+ TextButton(
+ key: ValueKey('role-edit-${role.id}'),
+ onPressed: _busy
+ ? null
+ : () => _edit(
+ role,
+ read.data![role.id] ?? '',
+ ),
+ child: const Text('Edit'),
+ ),
+ if (role.kind != 'lead')
+ TextButton(
+ key: ValueKey('role-delete-${role.id}'),
+ onPressed: _busy
+ ? null
+ : () => _send({
+ 'type': 'project.role.remove',
+ 'projectId': widget.projectId,
+ 'roleId': role.id,
+ }),
+ child: const Text('Delete'),
+ ),
+ ],
+ ),
+ ],
+ ),
+ ),
+ ),
+ if (_error != null) Text(_error!),
+ ],
+ ),
+ ),
+ actions: [
+ TextButton(
+ onPressed: _busy ? null : _reset,
+ child: const Text('Reset to Default'),
+ ),
+ TextButton(
+ onPressed: _busy || roles.length >= 20 || read.data == null
+ ? null
+ : () => _edit(null, ''),
+ child: const Text('Add role'),
+ ),
+ TextButton(
+ onPressed: _busy ? null : () => Navigator.pop(context),
+ child: const Text('Close'),
+ ),
+ ],
+ ),
+ );
+ },
+ );
+}
diff --git a/desktop/lib/super_tabs/roster.dart b/desktop/lib/super_tabs/roster.dart
index a3050b3b6..543185436 100644
--- a/desktop/lib/super_tabs/roster.dart
+++ b/desktop/lib/super_tabs/roster.dart
@@ -268,16 +268,17 @@ class _SuperTabRosterState extends State<SuperTabRoster> {
final project = c.snapshot!.projects
.where((p) => p.id == _agentProjectId(agent))
.firstOrNull;
- final role = c.snapshot!.isLead(agent.id)
+ final customRole = c.snapshot!.activeRoleForAgent(agent);
+ final role = customRole?.name ?? (c.snapshot!.isLead(agent.id)
? 'Product Manager'
: agent.isReviewer
? 'Reviewer'
- : 'Engineer';
- final badge = c.snapshot!.isLead(agent.id)
+ : 'Engineer');
+ final badge = customRole?.name ?? (c.snapshot!.isLead(agent.id)
? 'PM'
: agent.isReviewer
? 'Rev'
- : 'Dev';
+ : 'Dev');
final status = info.status ?? 'Status unavailable';
final tooltip = [
[name, role, ?project?.name].join(' · '),
diff --git a/desktop/lib/super_tabs/view.dart b/desktop/lib/super_tabs/view.dart
index b3acae8df..2863dddda 100644
--- a/desktop/lib/super_tabs/view.dart
+++ b/desktop/lib/super_tabs/view.dart
@@ -900,7 +900,7 @@ class _SuperTabViewState extends State<SuperTabView>
if (editable && project?.ownerId == c.accountId)
item('Sharing', () => _groupAction('sharing', group)),
if (editable && project?.ownerId == c.accountId)
- item('Skills', () => _groupAction('skills', group)),
+ item('Instructions', () => _groupAction('skills', group)),
if (editable)
item('Update cadence', () => _groupAction('cadence', group)),
item('Swarm routing', () => _groupAction('routing', group)),
diff --git a/desktop/lib/widgets/new_harness_form.dart b/desktop/lib/widgets/new_harness_form.dart
index 09af1ca83..f6c3d0db8 100644
--- a/desktop/lib/widgets/new_harness_form.dart
+++ b/desktop/lib/widgets/new_harness_form.dart
@@ -88,7 +88,11 @@ class NewHarnessFormState extends State<NewHarnessForm> {
!box.busy &&
!box.linkingProfile &&
box.requiredChoice == null &&
- !box.taskTooLong;
+ !box.taskTooLong &&
+ (box.integration?.roles == null ||
+ box.integration!.roles!.any(
+ (role) => role.id == box.integration!.roleId,
+ ));
FocusNode get _desktopDefaultFocus => box.takesTask
? _taskFocus
: _desktopStartEnabled
@@ -2258,6 +2262,44 @@ class NewHarnessFormState extends State<NewHarnessForm> {
children: [
if (box.canCancelPending) _cancelPendingButton(),
if (box.existingFolder != null) _useExistingFolderButton(),
+ if (box.integration?.roles case final roles?)
+ roles.isEmpty
+ ? const Text('This project has no Engineer or Reviewer roles.')
+ : SizedBox(
+ width: 180,
+ child: InputDecorator(
+ decoration: const InputDecoration(labelText: 'Role'),
+ child: DropdownButtonHideUnderline(
+ child: DropdownButton<String>(
+ key: const ValueKey('new-harness-role'),
+ isExpanded: true,
+ value:
+ roles.any(
+ (role) => role.id == box.integration!.roleId,
+ )
+ ? box.integration!.roleId
+ : null,
+ items: [
+ for (final role in roles)
+ DropdownMenuItem(
+ value: role.id,
+ child: Text(
+ role.name,
+ overflow: TextOverflow.ellipsis,
+ ),
+ ),
+ ],
+ onChanged: box.locked
+ ? null
+ : (value) => setState(() {
+ if (value != null) {
+ box.integration!.chooseRole(value);
+ }
+ }),
+ ),
+ ),
+ ),
+ ),
if (includeProjectVisibility &&
box.integration?.projectVisibility != null)
FocusTraversalOrder(
diff --git a/desktop/test/screenshots/custom-roles/custom-role-instructions.png b/desktop/test/screenshots/custom-roles/custom-role-instructions.png
new file mode 100644
index 000000000..57715496c
Binary files /dev/null and b/desktop/test/screenshots/custom-roles/custom-role-instructions.png differ
diff --git a/desktop/test/screenshots/custom-roles/custom-roles-editor.png b/desktop/test/screenshots/custom-roles/custom-roles-editor.png
new file mode 100644
index 000000000..2d7806ca6
Binary files /dev/null and b/desktop/test/screenshots/custom-roles/custom-roles-editor.png differ
diff --git a/desktop/test/screenshots/custom-roles/custom-skills.png b/desktop/test/screenshots/custom-roles/custom-skills.png
new file mode 100644
index 000000000..379958cbc
Binary files /dev/null and b/desktop/test/screenshots/custom-roles/custom-skills.png differ
diff --git a/desktop/test/super_tab_launch_test.dart b/desktop/test/super_tab_launch_test.dart
index 68476ec9c..4232f68fe 100644
--- a/desktop/test/super_tab_launch_test.dart
+++ b/desktop/test/super_tab_launch_test.dart
@@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:convert';
import 'dart:typed_data';
+import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/first_task.dart';
import 'package:harness/core/models.dart';
@@ -13,6 +14,7 @@ import 'package:harness/terminal/terminal_binary.dart';
import 'package:harness/super_tabs/launch.dart';
import 'package:harness/super_tabs/client.dart';
import 'package:harness/super_tabs/controller.dart';
+import 'package:harness/widgets/new_harness_form.dart';
import 'package:harness/ws/local_cli_discovery.dart';
import 'package:harness/ws/ws_conn.dart';
@@ -55,6 +57,7 @@ class SuperTabFixtureConnection extends WsConn {
bool failResume = false;
bool nativeSurface = false;
bool failFiles = false, failCreation = false, changeAccountOnUpload = false;
+ bool changeAccountOnProjectRead = false;
late AppNotifier app;
final sentFiles = <Uint8List>[];
final terminalCalls = <(String, Map<String, dynamic>)>[];
@@ -145,6 +148,14 @@ class SuperTabFixtureConnection extends WsConn {
};
}
if (type == 'super_tabs') {
+ if (changeAccountOnProjectRead &&
+ payload['method'] == 'GET' &&
+ payload['path'] == '/api/super-tabs/$tabId') {
+ app.currentUser = const CurrentUserProfile(
+ id: 'different',
+ email: '[email protected]',
+ );
+ }
if (payload['action'] == 'backend' && backendFailure != null) {
throw backendFailure!;
}
@@ -916,6 +927,283 @@ void main() {
},
);
+ test(
+ 'a Desktop agent joining a custom project sends its chosen role id',
+ () async {
+ final f = SuperTabLaunchFixture();
+ f.connection.server.state['projects'] = [
+ {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {
+ 'id': 'dev',
+ 'name': 'Engineer',
+ 'kind': 'builder',
+ 'version': 'v1',
+ },
+ {
+ 'id': 'review',
+ 'name': 'Reviewer',
+ 'kind': 'reviewer',
+ 'version': 'v1',
+ },
+ ],
+ },
+ ];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ final box = await f.box();
+ expect(await box.create(), NewHarnessOutcome.created, reason: box.error);
+ expect(f.connection.joins.single['command']['roleId'], 'dev');
+ },
+ );
+
+ testWidgets('new agent form lets a custom project choose a reviewer role', (
+ tester,
+ ) async {
+ final f = SuperTabLaunchFixture();
+ f.connection.server.state['projects'] = [
+ {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {'id': 'dev', 'name': 'Engineer', 'kind': 'builder', 'version': 'v1'},
+ {
+ 'id': 'review',
+ 'name': 'Security Reviewer',
+ 'kind': 'reviewer',
+ 'version': 'v1',
+ },
+ ],
+ },
+ ];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ final box = (await tester.runAsync(() => f.box()))!;
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: SizedBox(
+ width: 1200,
+ height: 800,
+ child: NewHarnessForm(
+ controller: box,
+ desktop: true,
+ onClose: () {},
+ onCreated: () {},
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.pump();
+ expect(find.byKey(const ValueKey('new-harness-role')), findsOneWidget);
+ await tester.tap(find.byKey(const ValueKey('new-harness-role')));
+ await tester.pump();
+ await tester.tap(find.text('Security Reviewer').last);
+ await tester.pump();
+ expect(box.integration!.roleId, 'review');
+ expect(box.integration!.swarmRole, 'review');
+ expect(
+ await tester.runAsync(() => box.create()),
+ NewHarnessOutcome.created,
+ reason: box.error,
+ );
+ final create = f.connection.calls
+ .firstWhere((entry) => entry.$1 == 'agent_create')
+ .$2;
+ expect(create['swarmRole'], 'review');
+ expect(f.connection.joins.single['command']['roleId'], 'review');
+ });
+
+ test('switching away from Custom resets a pending Reviewer launch', () async {
+ final f = SuperTabLaunchFixture();
+ final project = {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {'id': 'dev', 'name': 'Engineer', 'kind': 'builder', 'version': 'v1'},
+ {
+ 'id': 'review',
+ 'name': 'Reviewer',
+ 'kind': 'reviewer',
+ 'version': 'v1',
+ },
+ ],
+ };
+ f.connection.server.state['projects'] = [project];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ final box = await f.box();
+ box.integration!.chooseRole('review');
+ project['skillSet'] = 'default';
+ expect(await box.create(), NewHarnessOutcome.created, reason: box.error);
+ final create = f.connection.calls
+ .firstWhere((entry) => entry.$1 == 'agent_create')
+ .$2;
+ expect(create['swarmSkillMode'], 'default');
+ expect(create['swarmRole'], 'dev');
+ expect(f.connection.joins.single['command'], isNot(contains('roleId')));
+ });
+
+ testWidgets('recovering a removed role keeps the form readable', (
+ tester,
+ ) async {
+ final f = SuperTabLaunchFixture();
+ f.connection.server.state['projects'] = [
+ {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {'id': 'dev', 'name': 'Engineer', 'kind': 'builder', 'version': 'v1'},
+ ],
+ },
+ ];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ f.store.values['super_tab.launch.owner.${f.app.activeSwarmId}.lead'] =
+ jsonEncode({
+ 'operationId': 'saved-operation',
+ 'joinId': 'saved-join',
+ 'tabId': tabId,
+ 'conversationId': 'lead',
+ 'lead': false,
+ 'roleId': 'removed',
+ 'roleKind': 'builder',
+ 'phase': 'starting',
+ });
+ final box = (await tester.runAsync(() => f.box()))!;
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: NewHarnessForm(
+ controller: box,
+ desktop: true,
+ onClose: () {},
+ onCreated: () {},
+ ),
+ ),
+ ),
+ );
+ await tester.pump();
+ expect(tester.takeException(), isNull);
+ expect(find.byKey(const ValueKey('new-harness-role')), findsOneWidget);
+ });
+
+ test(
+ 'a role changed before launch is rejected before native creation',
+ () async {
+ final f = SuperTabLaunchFixture();
+ final project = {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {'id': 'dev', 'name': 'Engineer', 'kind': 'builder', 'version': 'v1'},
+ ],
+ };
+ f.connection.server.state['projects'] = [project];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ final box = await f.box();
+ project['roles'] = [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v2',
+ },
+ {'id': 'dev', 'name': 'Reviewer', 'kind': 'reviewer', 'version': 'v2'},
+ ];
+ expect(await box.create(), NewHarnessOutcome.failed);
+ expect(
+ f.connection.calls.where((call) => call.$1 == 'agent_create'),
+ isEmpty,
+ );
+ },
+ );
+
+ test(
+ 'reopened unfinished form replaces a removed role with an available one',
+ () async {
+ final f = SuperTabLaunchFixture();
+ f.connection.server.state['projects'] = [
+ {
+ ...projectFixture('lead', 'Company', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {
+ 'id': 'dev',
+ 'name': 'Engineer',
+ 'kind': 'builder',
+ 'version': 'v1',
+ },
+ ],
+ },
+ ];
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ f.store.values['super_tab.launch.owner.${f.app.activeSwarmId}.lead'] =
+ jsonEncode({
+ 'operationId': 'saved-operation',
+ 'joinId': 'saved-join',
+ 'tabId': tabId,
+ 'conversationId': 'lead',
+ 'lead': false,
+ 'roleId': 'removed',
+ 'roleKind': 'builder',
+ });
+ final box = await f.box();
+ expect(box.integration!.roleId, 'dev');
+ },
+ );
+
+ test('account switch during role lookup closes the old launch', () async {
+ final f = SuperTabLaunchFixture()
+ ..connection.changeAccountOnProjectRead = true;
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Company');
+ await expectLater(
+ f.box(),
+ throwsA(
+ isA<SuperTabFailure>().having(
+ (failure) => failure.code,
+ 'code',
+ 'ACCOUNT_CHANGED',
+ ),
+ ),
+ );
+ });
+
test('the lead prompt routes before starting or assigning work', () async {
final f = SuperTabLaunchFixture()..connection.nativeName = 'hi';
final box = await f.box(engine: 'claude');
diff --git a/desktop/test/super_tab_machines_test.dart b/desktop/test/super_tab_machines_test.dart
index 3bb471399..4de5c4510 100644
--- a/desktop/test/super_tab_machines_test.dart
+++ b/desktop/test/super_tab_machines_test.dart
@@ -508,6 +508,24 @@ void main() {
find.descendant(of: dev, matching: find.text('Dev')),
findsOneWidget,
);
+ server.state['projects'] = [
+ {
+ ...projectFixture('lead', 'Pilot', 'lead'),
+ 'skillSet': 'custom',
+ 'roles': [
+ {'id': 'lead', 'name': 'Product Manager', 'kind': 'lead', 'version': 'v1'},
+ {'id': 'research', 'name': 'Research Engineer', 'kind': 'builder', 'version': 'v1'},
+ ],
+ },
+ ];
+ (server.state['agents'] as List)[1]['roleId'] = 'research';
+ await c.refresh();
+ await show();
+ await tester.pumpAndSettle();
+ expect(
+ find.descendant(of: dev, matching: find.text('Research Engineer')),
+ findsOneWidget,
+ );
expect(
tester
.widget<SuperTabAvatar>(
diff --git a/desktop/test/super_tab_project_skills_test.dart b/desktop/test/super_tab_project_skills_test.dart
index f5b977fae..88f809f83 100644
--- a/desktop/test/super_tab_project_skills_test.dart
+++ b/desktop/test/super_tab_project_skills_test.dart
@@ -1,19 +1,147 @@
+import 'dart:io';
+
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/super_tabs/view.dart';
+import 'package:harness/super_tabs/model.dart';
+import 'package:harness/super_tabs/roles_editor.dart';
import 'support/super_tab_fixture.dart';
+import 'support/capture.dart';
+
+class _RolesServer extends ConversationServer {
+ final texts = <String, String>{};
+ final textReads = <String>[];
+
+ Map<String, dynamic> get project =>
+ (state['projects'] as List).cast<Map<String, dynamic>>().single;
+
+ void seedRoles() {
+ project['skillSet'] = 'custom';
+ project['skillMode'] = 'default';
+ project['roles'] = [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {'id': 'dev', 'name': 'Engineer', 'kind': 'builder', 'version': 'v1'},
+ {'id': 'review', 'name': 'Reviewer', 'kind': 'reviewer', 'version': 'v1'},
+ ];
+ texts.addAll({
+ 'lead': '# Lead',
+ 'dev': '# Engineer',
+ 'review': '# Reviewer',
+ });
+ }
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String method,
+ String path, {
+ Map<String, dynamic>? body,
+ }) async {
+ if (method == 'GET' && path.contains('/projects/lead/roles/')) {
+ textReads.add(path);
+ final id = Uri.parse(path).pathSegments.last;
+ return {'version': 'v1', 'text': texts[id]};
+ }
+ if (method == 'POST' && body?['command'] is Map && refuse == null) {
+ final command = (body!['command'] as Map).cast<String, dynamic>();
+ final roles = (project['roles'] as List?)
+ ?.map((entry) => Map<String, dynamic>.from(entry as Map))
+ .toList();
+ switch (command['type']) {
+ case 'project.roles.create' || 'project.roles.reset':
+ project['roles'] = [
+ for (final raw in command['roles'] as List)
+ {
+ 'id': raw['id'],
+ 'name': raw['name'],
+ 'kind': raw['kind'],
+ 'version': 'v1',
+ },
+ ];
+ texts
+ ..clear()
+ ..addEntries(
+ (command['roles'] as List).map(
+ (raw) => MapEntry(raw['id'] as String, raw['text'] as String),
+ ),
+ );
+ revision++;
+ case 'project.role.set':
+ final role = (command['role'] as Map).cast<String, dynamic>();
+ roles!.removeWhere((entry) => entry['id'] == role['id']);
+ roles.add({
+ 'id': role['id'],
+ 'name': role['name'],
+ 'kind': role['kind'],
+ 'version': 'v2',
+ });
+ project['roles'] = roles;
+ texts[role['id'] as String] = role['text'] as String;
+ revision++;
+ case 'project.role.remove':
+ roles!.removeWhere((entry) => entry['id'] == command['roleId']);
+ project['roles'] = roles;
+ texts.remove(command['roleId']);
+ revision++;
+ case 'project.skills':
+ project['skillSet'] = command['mode'];
+ project['skillMode'] = command['mode'] == 'custom'
+ ? 'default'
+ : command['mode'];
+ revision++;
+ }
+ }
+ return super.request(method, path, body: body);
+ }
+}
void main() {
- Future<ConversationServer> mount(
+ final captureDir = Platform.environment['HARNESS_CUSTOM_ROLES_CAPTURE'];
+ setUpAll(() => loadCaptureFonts(captureDir));
+
+ test(
+ 'custom set starts with the shipped Default skill texts byte for byte',
+ () {
+ final source = File('../cli/src/lib/swarmSkills.ts').readAsStringSync();
+ final sections = source.split(
+ 'const defaults: Record<SwarmRole, string> = {',
+ );
+ expect(sections, hasLength(2));
+ final defaults = sections.last;
+ final roles = {
+ for (final role in defaultProjectRoles()) role['id']!: role['text']!,
+ };
+ for (final id in ['lead', 'dev', 'review']) {
+ final match = RegExp(
+ ' $id: '
+ r'`([\s\S]*?)`,',
+ ).firstMatch(defaults);
+ expect(match, isNotNull, reason: 'CLI Default $id text is missing');
+ expect(
+ roles[id],
+ match!.group(1),
+ reason: '$id differs from CLI Default',
+ );
+ }
+ },
+ );
+
+ Future<_RolesServer> mount(
WidgetTester tester, {
String account = 'owner',
String? skillMode,
+ bool custom = false,
}) async {
- final server = ConversationServer();
+ final server = _RolesServer();
final project = projectFixture('lead', 'Pilot', 'lead');
if (skillMode != null) project['skillMode'] = skillMode;
server.state['projects'] = [project];
+ if (custom) server.seedRoles();
if (account != 'owner') {
(server.state['people'] as List).add({
'id': account,
@@ -41,10 +169,10 @@ void main() {
return server;
}
- Future<void> openSkills(WidgetTester tester) async {
+ Future<void> openInstructions(WidgetTester tester) async {
await tester.tap(find.byTooltip('Project options'));
await tester.pumpAndSettle();
- await tester.tap(find.widgetWithText(MenuItemButton, 'Skills'));
+ await tester.tap(find.widgetWithText(MenuItemButton, 'Instructions'));
await tester.pumpAndSettle();
}
@@ -52,8 +180,13 @@ void main() {
tester,
) async {
final server = await mount(tester);
- await openSkills(tester);
- expect(find.text('Skills for this project'), findsOneWidget);
+ await openInstructions(tester);
+ expect(find.text('Instructions for this project'), findsOneWidget);
+ expect(find.text('Instructions'), findsOneWidget);
+ expect(
+ find.textContaining(RegExp('skill', caseSensitive: false)),
+ findsNothing,
+ );
expect(
find.text(
'Default — the team process; agents otherwise work their usual way',
@@ -91,7 +224,7 @@ void main() {
'owner sees Default selected for a project already in that mode',
(tester) async {
final server = await mount(tester, skillMode: 'default');
- await openSkills(tester);
+ await openInstructions(tester);
expect(
tester
.widget<RadioGroup<String>>(find.byType(RadioGroup<String>))
@@ -104,13 +237,252 @@ void main() {
},
);
- testWidgets('collaborator does not see Skills in the project menu', (
+ testWidgets('collaborator does not see Instructions in the project menu', (
tester,
) async {
final server = await mount(tester, account: 'peer');
await tester.tap(find.byTooltip('Project options'));
await tester.pumpAndSettle();
- expect(find.widgetWithText(MenuItemButton, 'Skills'), findsNothing);
+ expect(find.widgetWithText(MenuItemButton, 'Instructions'), findsNothing);
expect(server.posts, isEmpty);
});
+
+ test('project reads the custom set and stable role ids', () {
+ final project = SuperTabProject.fromJson({
+ ...projectFixture('lead', 'Pilot', 'lead'),
+ 'skillSet': 'custom',
+ 'skillMode': 'default',
+ 'roles': [
+ {
+ 'id': 'lead',
+ 'name': 'Coordinator',
+ 'kind': 'lead',
+ 'version': 'abcd',
+ },
+ ],
+ });
+ expect((project as dynamic).skillSet, 'custom');
+ expect((project as dynamic).roles.single.name, 'Coordinator');
+ });
+
+ testWidgets('owner creates a custom set before Custom can be selected', (
+ tester,
+ ) async {
+ final server = await mount(tester, skillMode: 'default');
+ await openInstructions(tester);
+ expect(
+ tester
+ .widget<RadioListTile<String>>(
+ find.widgetWithText(RadioListTile<String>, 'Custom'),
+ )
+ .enabled,
+ isFalse,
+ );
+ await tester.tap(find.text('Create custom set'));
+ await tester.pumpAndSettle();
+ final create = server.posts.single['command'] as Map;
+ expect(create['type'], 'project.roles.create');
+ expect((create['roles'] as List).map((role) => role['id']), [
+ 'lead',
+ 'dev',
+ 'review',
+ ]);
+ expect((create['roles'] as List).map((role) => role['kind']), [
+ 'lead',
+ 'builder',
+ 'reviewer',
+ ]);
+ for (final role in create['roles'] as List) {
+ expect((role['text'] as String).length, greaterThan(500));
+ }
+ expect(
+ tester
+ .widget<RadioListTile<String>>(
+ find.widgetWithText(RadioListTile<String>, 'Custom'),
+ )
+ .enabled,
+ isTrue,
+ );
+ await tester.tap(find.text('Custom'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.widgetWithText(FilledButton, 'Save'));
+ await tester.pumpAndSettle();
+ expect(server.posts.last['command'], {
+ 'type': 'project.skills',
+ 'projectId': 'lead',
+ 'mode': 'custom',
+ });
+ });
+
+ testWidgets('owner opens role editor; the lead role cannot be deleted', (
+ tester,
+ ) async {
+ if (captureDir != null) {
+ tester.view.physicalSize = const Size(1440, 900);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.reset);
+ }
+ final server = await mount(tester, custom: true);
+ await openInstructions(tester);
+ await captureWindow(tester, captureDir, 'custom-skills');
+ await tester.tap(find.text('Edit custom roles'));
+ await tester.pumpAndSettle();
+ await captureWindow(tester, captureDir, 'custom-roles-editor');
+ expect(find.text('Custom roles'), findsOneWidget);
+ expect(find.text('Product Manager'), findsWidgets);
+ expect(find.text('Engineer'), findsWidgets);
+ expect(find.text('Reviewer'), findsWidgets);
+ expect(
+ server.textReads,
+ contains('/api/super-tabs/tab/projects/lead/roles/lead'),
+ );
+ expect(find.text('# Lead'), findsOneWidget);
+ expect(find.byKey(const ValueKey('role-delete-lead')), findsNothing);
+ await tester.tap(find.byKey(const ValueKey('role-edit-lead')));
+ await tester.pumpAndSettle();
+ expect(find.text('Product Manager instructions'), findsOneWidget);
+ expect(
+ find.textContaining(RegExp('skill', caseSensitive: false)),
+ findsNothing,
+ );
+ await captureWindow(tester, captureDir, 'custom-role-instructions');
+ });
+
+ testWidgets('backend refusal is shown when removing a role in use', (
+ tester,
+ ) async {
+ final server = await mount(tester, custom: true);
+ await openInstructions(tester);
+ await tester.tap(find.text('Edit custom roles'));
+ await tester.pumpAndSettle();
+ server.refuse = {
+ 'code': 'ROLE_IN_USE',
+ 'message': 'Stop or reassign the 2 agents with this role first.',
+ };
+ await tester.tap(find.byKey(const ValueKey('role-delete-dev')));
+ await tester.pumpAndSettle();
+ expect(
+ find.text('Stop or reassign the 2 agents with this role first.'),
+ findsWidgets,
+ );
+ });
+
+ testWidgets('owner edits a role name and Markdown text', (tester) async {
+ final server = await mount(tester, custom: true);
+ await openInstructions(tester);
+ await tester.tap(find.text('Edit custom roles'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.byKey(const ValueKey('role-edit-dev')));
+ await tester.pumpAndSettle();
+ expect(find.text('Engineer instructions'), findsOneWidget);
+ await tester.enterText(
+ find.byKey(const ValueKey('role-name')),
+ 'Research Engineer',
+ );
+ await tester.pump();
+ expect(find.text('Research Engineer instructions'), findsOneWidget);
+ await tester.enterText(
+ find.byKey(const ValueKey('role-text')),
+ '# Research work',
+ );
+ await tester.pump();
+ expect(
+ tester
+ .widget<FilledButton>(find.widgetWithText(FilledButton, 'Save role'))
+ .onPressed,
+ isNotNull,
+ );
+ await tester.tap(find.widgetWithText(FilledButton, 'Save role'));
+ await tester.pumpAndSettle();
+ expect(server.posts.last['command'], {
+ 'type': 'project.role.set',
+ 'projectId': 'lead',
+ 'role': {
+ 'id': 'dev',
+ 'name': 'Research Engineer',
+ 'kind': 'builder',
+ 'text': '# Research work',
+ },
+ });
+ expect(find.text('Research Engineer'), findsOneWidget);
+ });
+
+ testWidgets('owner adds a named reviewer role with a stable id', (
+ tester,
+ ) async {
+ final server = await mount(tester, custom: true);
+ await openInstructions(tester);
+ await tester.tap(find.text('Edit custom roles'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Add role'));
+ await tester.pumpAndSettle();
+ expect(
+ tester
+ .widget<TextField>(find.byKey(const ValueKey('role-text')))
+ .decoration
+ ?.labelText,
+ 'Instructions',
+ );
+ await tester.enterText(
+ find.byKey(const ValueKey('role-name')),
+ 'Security Reviewer',
+ );
+ await tester.pump();
+ expect(find.text('Security Reviewer instructions'), findsOneWidget);
+ await tester.tap(find.byKey(const ValueKey('role-kind')));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Reviewer').last);
+ await tester.pumpAndSettle();
+ await tester.enterText(
+ find.byKey(const ValueKey('role-text')),
+ '# Review security',
+ );
+ await tester.pump();
+ expect(
+ tester
+ .widget<FilledButton>(find.widgetWithText(FilledButton, 'Save role'))
+ .onPressed,
+ isNotNull,
+ );
+ await tester.tap(find.widgetWithText(FilledButton, 'Save role'));
+ await tester.pumpAndSettle();
+ final command = server.posts.last['command'] as Map;
+ expect(command['type'], 'project.role.set');
+ expect((command['role'] as Map)['id'], matches(RegExp(r'^[0-9a-f]{12}$')));
+ expect((command['role'] as Map)['kind'], 'reviewer');
+ expect((command['role'] as Map)['text'], '# Review security');
+ });
+
+ testWidgets('Reset to Default confirms before replacing all custom roles', (
+ tester,
+ ) async {
+ final server = await mount(tester, custom: true);
+ await openInstructions(tester);
+ await tester.tap(find.text('Edit custom roles'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Reset to Default'));
+ await tester.pumpAndSettle();
+ expect(find.text('Reset custom roles to Default?'), findsOneWidget);
+ expect(
+ find.text(
+ 'This replaces every custom role and its instructions. Agents using removed roles may need to stop or be reassigned first.',
+ ),
+ findsOneWidget,
+ );
+ expect(server.posts, isEmpty);
+ await tester.tap(find.widgetWithText(FilledButton, 'Reset'));
+ await tester.pumpAndSettle();
+ final command = server.posts.single['command'] as Map;
+ expect(command['type'], 'project.roles.reset');
+ expect((command['roles'] as List).map((role) => role['id']), [
+ 'lead',
+ 'dev',
+ 'review',
+ ]);
+ expect((command['roles'] as List).map((role) => role['name']), [
+ 'Product Manager',
+ 'Engineer',
+ 'Reviewer',
+ ]);
+ });
}
diff --git a/desktop/test/super_tab_roster_test.dart b/desktop/test/super_tab_roster_test.dart
index c0cae35b7..181f7b35a 100644
--- a/desktop/test/super_tab_roster_test.dart
+++ b/desktop/test/super_tab_roster_test.dart
@@ -873,6 +873,46 @@ void main() {
await f.close(tester);
});
+ testWidgets('custom role name appears in the roster and agent details', (
+ tester,
+ ) async {
+ final f = await fixture(tester);
+ final project = (f.server.state['projects'] as List).first as Map;
+ project['skillSet'] = 'custom';
+ project['roles'] = [
+ {
+ 'id': 'lead',
+ 'name': 'Product Manager',
+ 'kind': 'lead',
+ 'version': 'v1',
+ },
+ {
+ 'id': 'research',
+ 'name': 'Research Engineer',
+ 'kind': 'builder',
+ 'version': 'v1',
+ },
+ ];
+ (f.server.state['agents'] as List)[1]['roleId'] = 'research';
+ await f.controller.refresh();
+ await f.show(tester);
+ expect(f.inRow(1, find.text('Research Engineer')), findsOneWidget);
+ expect(f.inRow(1, find.text('Dev')), findsNothing);
+ final details = showSuperTabAgentDetails(
+ tester.element(f.row(1)),
+ f.controller,
+ f.app,
+ f.controller.snapshot!.agent('agent-1')!,
+ (_) {},
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('Research Engineer'), findsWidgets);
+ await tester.tap(find.widgetWithText(TextButton, 'Close'));
+ await tester.pumpAndSettle();
+ await details;
+ await f.close(tester);
+ });
+
Future<RosterFixture> fixtureWithPeople(
WidgetTester tester,
int count,
diff --git a/docs/naming-system.md b/docs/naming-system.md
index 871142838..bc6a5cae2 100644
--- a/docs/naming-system.md
+++ b/docs/naming-system.md
@@ -55,6 +55,7 @@ and **Browser**. Technical documentation may still call the terminal interface a
| **Tab** | A workspace group of harnesses. | Frontend and Backend tabs. |
| **Swarm** | A collaborative tab containing projects, people, agents and contributed machines. Invite-only by default; its owner can enable joining by email domain or a shared link. | Open your company Swarm beside your regular tabs. |
| **Project in a Swarm** | An initiative with its own product manager, repository, sharing and workgroups. | Discuss Lamp OS with its product manager; expand it to follow a workgroup. |
+| **Instructions** | The visible name for a project's skill set and each role's text. System name: skill. | Open Instructions; edit Product Manager instructions. |
| **Product Manager** | The agent coordinating a Swarm project. Use **PM** in a compact role badge. System name: lead. | Message Product Manager. |
| **Engineer** | An agent carrying out project work. Use **Dev** in a compact role badge. System name: builder. | Atlas is an engineer on Lamp OS. |
| **Reviewer** | An agent that reviews project work. Use **Rev** in a compact role badge. System name: reviewer. | Atlas is a reviewer on Lamp OS. |