@giladbarnea/pi-simple-team 1.0.30 → 1.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -62,16 +62,14 @@ Main agent:
62
62
  <br>
63
63
 
64
64
  <details>
65
- <summary><strong>See real tool outputs</strong></summary>
65
+ <summary><strong>pi-simple-team screenshots</strong></summary>
66
66
 
67
67
  <br>
68
68
 
69
- <p align="center">
70
- <a href="screenshots/1.png"><img src="screenshots/1.png" width="48%" alt="Pi tool outputs for spawning a team, sending instructions, and checking status"></a>
71
- <a href="screenshots/2.png"><img src="screenshots/2.png" width="48%" alt="Pi tool outputs for team status and the timestamped event log"></a>
72
- </p>
73
69
  <p align="center">
74
70
  <a href="screenshots/team-status-multiple.png"><img src="screenshots/team-status-multiple.png" width="48%" alt="Status outputs for several parallel teams"></a>
71
+ </p>
72
+ <p align="center">
75
73
  <a href="screenshots/team-log-multiple.png"><img src="screenshots/team-log-multiple.png" width="48%" alt="Event log outputs for two parallel teams"></a>
76
74
  </p>
77
75
 
@@ -104,8 +102,6 @@ This is both efficient and effective:
104
102
  - ✔ Context window stays lean.
105
103
  - ✔ Unlocks arbitrary workflows.
106
104
 
107
- *{ironic screenshot of Codex filling up the entire visible chat with countless* `Waiting agents to finish...`*}*
108
-
109
105
  ### ⚡ Messages arrive _fast_.
110
106
 
111
107
  - Sub-second, when the recipient is idle.
@@ -115,9 +111,9 @@ This is both efficient and effective:
115
111
 
116
112
  Teammates publish a one-liner:
117
113
 
118
- > <span style="color:grey">implementer </span> Done, 89 tests green, awaiting review.
114
+ > <span style="color:grey">implementer  </span> Done, 89 tests green, awaiting review.
119
115
 
120
- > <span style="color:grey">reviewer </span> Reading implementation, will finalize review in a few minutes.
116
+ > <span style="color:grey">reviewer      </span> Reading implementation, will finalize review in a few minutes.
121
117
 
122
118
  Your main agent calls `teamstatus` and understands exactly what is going on. Main does not ask teammates for updates or clutter their context.
123
119
 
@@ -127,7 +123,7 @@ Teammates know how much free context they have left.
127
123
 
128
124
  Main agent knows its own and everyone else's too.
129
125
 
130
- They will hand off work on their own when it's time to say goodbye.
126
+ They will hand off work autonomously when it's time to say goodbye.
131
127
 
132
128
  You can stop babysitting everyone's context window.
133
129
 
@@ -154,27 +150,29 @@ Your main uses `teamlog` when it needs to understand the chain of events in high
154
150
 
155
151
  A teammate is a normal Pi session with a team attachment.
156
152
 
157
- This means every teammate can be resurrected, moved around teams and reused everywhere, anytime.
153
+ This means teammates survive shutdown, whole team or member by member.
158
154
 
159
- A teammate from one session can be added to a team in a later session.
155
+ Have a teammate do work, exit Pi entirely, come back tomorrow in a brand-new session: main wakes that same teammate into the new conversation, everything it learned intact.
160
156
 
161
157
  You can even `/resume` a teammate session directly if you ever want a cozy one-on-one.
162
158
 
163
159
  The full lifecycle and persistence rules live in [ARCHITECTURE.md](ARCHITECTURE.md).
164
160
 
165
- ## When one room is not enough
161
+ ## 🪾 Teams all the way down (optionally)
162
+
163
+ Tell main you want to give a teammate the ability to manage its own team(s).
166
164
 
167
- `pi-simple-team` supports teammates spawning and managing their own teams, one level down.
165
+ This is a powerful technique to create a new layer of context breathing room.
168
166
 
169
- This is opt-in: when spawning a team, ask main to turn this on for one (or more) teammates.
167
+ That teammate will spawn, steer and observe its own team(s) without costing tokens to its siblings or parent.
170
168
 
171
- That teammate stays in your team and becomes main for the teams it creates, with the same tools your main agent has. The boundary is strict: it manages only teams its own session created — never its parent team, sibling teams, or their teammates.
169
+ The tradeoff, like any higher-order delegation, is reduced control: you are moved one level further away from the action.
172
170
 
173
- A room can open another room. It does not get the keys to the whole building.
171
+ This is opt-in: teammates by default can't create teams.
174
172
 
175
173
  ---
176
174
 
177
- ## Graphs engineer themselves
175
+ ## 🧬 Graphs engineer themselves
178
176
 
179
177
  **Because** it does nothing special, `pi-simple-team` can construct any team graph you need:
180
178
 
package/index.ts CHANGED
@@ -989,6 +989,9 @@ export default function (pi: ExtensionAPI) {
989
989
  ? "List active and dormant teams created by this overseeing teammate."
990
990
  : "List active and dormant teams for the current project.",
991
991
  promptSnippet: "List teams for the current project",
992
+ renderShell: "self",
993
+ renderCall: (_args, theme, context) => renderTeamToolCall("team_list", {}, theme, context, sessionTeammateRoster),
994
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_list", result, options, theme, context, undefined, sessionTeammateRoster),
992
995
  parameters: Type.Object({}),
993
996
  async execute(_toolCallId, _params, _signal, _onUpdate, context) {
994
997
  const projectDirectory = context.sessionManager?.getCwd?.() ?? context.cwd;
@@ -1033,6 +1036,9 @@ export default function (pi: ExtensionAPI) {
1033
1036
  ? "Resume all or selected stopped members of a dormant team created by this overseeing teammate."
1034
1037
  : "Resume all stopped teammates in a dormant current-project team, or only selected stopped teammates.",
1035
1038
  promptSnippet: "Resume all or selected stopped teammates",
1039
+ renderShell: "self",
1040
+ renderCall: (args, theme, context) => renderTeamToolCall("team_resume", args, theme, context, sessionTeammateRoster),
1041
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_resume", result, options, theme, context, undefined, sessionTeammateRoster),
1036
1042
  parameters: Type.Object({
1037
1043
  team: Type.String({ description: "Persistent team ID" }),
1038
1044
  teammates: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, description: "Stopped teammate names. Omit to resume all stopped teammates." })),
@@ -1123,7 +1129,9 @@ export default function (pi: ExtensionAPI) {
1123
1129
  accepted: true,
1124
1130
  id: team.id,
1125
1131
  team: team.name,
1132
+ teammates: [...team.members.keys()],
1126
1133
  resumed: starts.map(({ teammate }) => teammate.name),
1134
+ restartedEmpty: starts.filter(({ sessionFile }) => sessionFile === undefined).map(({ teammate }) => teammate.name),
1127
1135
  sessions: Object.fromEntries(
1128
1136
  starts.map(({ teammate }) => [teammate.name, { sessionId: teammate.sessionId, sessionFile: teammate.sessionFile }]),
1129
1137
  ),
@@ -1138,6 +1146,9 @@ export default function (pi: ExtensionAPI) {
1138
1146
  label: "Team Add",
1139
1147
  description: "Add one or more new RPC teammates to a running team owned by this main session.",
1140
1148
  promptSnippet: "Add new teammates to a running team",
1149
+ renderShell: "self",
1150
+ renderCall: (args, theme, context) => renderTeamToolCall("team_add", args, theme, context, sessionTeammateRoster),
1151
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_add", result, options, theme, context, undefined, sessionTeammateRoster),
1141
1152
  parameters: Type.Object({
1142
1153
  team: Type.String({ description: "Persistent team ID" }),
1143
1154
  teammates: Type.Array(teammateSchema(""), { minItems: 1, description: "New teammates to add" }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "1.0.30",
3
+ "version": "1.0.32",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -27,6 +27,7 @@ function projectSettingsPath(cwd: string): string {
27
27
  }
28
28
 
29
29
  const PROJECT_TRUST_SYMBOL = Symbol.for("vstack.pi.project-trust");
30
+ const glyphStyleByDirectory = new Map<string, GlyphStyle>();
30
31
 
31
32
  interface ProjectTrustRegistry {
32
33
  projectSettings?: Map<string, boolean>;
@@ -52,6 +53,7 @@ export function recordProjectTrust(ctx: { cwd?: string; isProjectTrusted?: () =>
52
53
  const registry = projectTrustRegistry();
53
54
  if (!registry.projectSettings) registry.projectSettings = new Map();
54
55
  registry.projectSettings.set(projectSettingsPath(ctx.cwd), trusted);
56
+ glyphStyleByDirectory.clear();
55
57
  }
56
58
 
57
59
  function projectSettingsTrusted(settingsPath: string): boolean {
@@ -85,12 +87,16 @@ function asGlyphStyle(value: unknown): GlyphStyle | undefined {
85
87
  return value === "unicode" || value === "ascii" ? value : undefined;
86
88
  }
87
89
 
88
- export function glyphStyle(cwd?: string): GlyphStyle {
90
+ export function glyphStyle(cwd = process.cwd()): GlyphStyle {
91
+ const directory = resolve(cwd);
92
+ const cached = glyphStyleByDirectory.get(directory);
93
+ if (cached) return cached;
89
94
  const globalOverride = readPackageConfig(GLOBAL_CONFIG_ID, cwd).globalGlyphStyleOverride;
90
95
  const forced = asGlyphStyle(globalOverride);
91
- if (forced) return forced;
92
- const local = readPackageConfig(LOCAL_CONFIG_ID, cwd);
93
- return asGlyphStyle(local.glyphStyle) ?? asGlyphStyle(local.treeStyle) ?? "unicode";
96
+ const local = forced ? {} : readPackageConfig(LOCAL_CONFIG_ID, cwd);
97
+ const style = forced ?? asGlyphStyle(local.glyphStyle) ?? asGlyphStyle(local.treeStyle) ?? "unicode";
98
+ glyphStyleByDirectory.set(directory, style);
99
+ return style;
94
100
  }
95
101
 
96
102
  export const GLYPHS = {
package/render.ts CHANGED
@@ -4,7 +4,7 @@ import { padVisible, stableRenderWidth, visibleLength } from "./render-support/a
4
4
  import { glyphs } from "./render-support/glyphs.ts";
5
5
  import { stackPrefix, toolLabel, treeConnector, treeGlyph, treeStem } from "./render-support/theme.ts";
6
6
  import { commandExit, plural, renderPendingCall, textContent } from "./render-support/text.ts";
7
- import { timeOfDay, type TeamLogEntry } from "./teamlog.ts";
7
+ import { monthDay, nowText, timeOfDay, type TeamLogEntry } from "./teamlog.ts";
8
8
 
9
9
  export interface ThemeLike {
10
10
  bold(text: string): string;
@@ -12,7 +12,7 @@ export interface ThemeLike {
12
12
  }
13
13
 
14
14
  interface ToolRenderContextLike {
15
- args?: Record<string, unknown>;
15
+ args?: object;
16
16
  cwd?: string;
17
17
  executionStarted?: boolean;
18
18
  invalidate?: () => void;
@@ -21,7 +21,7 @@ interface ToolRenderContextLike {
21
21
  toolCallId?: string;
22
22
  }
23
23
 
24
- export type TeamToolName = "team_spawn" | "teamsend" | "teamstatus" | "teamlog" | "team_shutdown";
24
+ export type TeamToolName = "team_spawn" | "team_list" | "team_resume" | "team_add" | "teamsend" | "teamstatus" | "teamlog" | "team_shutdown";
25
25
 
26
26
  export interface TeamStatusView {
27
27
  word: string;
@@ -153,8 +153,11 @@ const STATUS_WORD_TOKENS: Record<string, string> = {
153
153
  running: "success",
154
154
  working: "success",
155
155
  blocked: "warning",
156
+ restarted: "warning",
157
+ resumed: "success",
156
158
  waiting: "warning",
157
159
  available: "muted",
160
+ dormant: "muted",
158
161
  idle: "muted",
159
162
  spawned: "muted",
160
163
  done: "dim",
@@ -209,14 +212,90 @@ interface TeammateSpecView {
209
212
  thinking?: string;
210
213
  }
211
214
 
212
- export function teamSpawnLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], roster: string[] = []): string[] {
213
- const header = headerLine(theme, "Team Spawn", theme.fg("accent", team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
215
+ function teammateSpecRows(theme: ThemeLike, teammates: TeammateSpecView[], roster: string[]): string[] {
214
216
  const nameWidth = Math.max(...teammates.map((teammate) => teammate.name.length));
215
- const rows = teammates.map((teammate, index) => {
217
+ return teammates.map((teammate, index) => {
216
218
  const branch = index === teammates.length - 1 ? "└" : "├";
217
219
  const spec = statLine(theme, [theme.fg("muted", teammate.model), theme.fg("dim", teammate.thinking ?? "")]);
218
220
  return `${treeConnector(theme, branch)}${theme.fg(actorHueToken(teammate.name, roster), padVisible(teammate.name, nameWidth))} ${spec}`;
219
221
  });
222
+ }
223
+
224
+ export function teamSpawnLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], roster: string[] = []): string[] {
225
+ const header = headerLine(theme, "Team Spawn", theme.fg("accent", team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
226
+ return [header, ...teammateSpecRows(theme, teammates, roster)];
227
+ }
228
+
229
+ export function teamAddLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], memberCount: number, roster: string[] = []): string[] {
230
+ const header = headerLine(theme, "Team Add", theme.fg("accent", team), [
231
+ theme.fg("muted", `${teammates.length} added`),
232
+ theme.fg("muted", plural(memberCount, "member")),
233
+ ]);
234
+ return [header, ...teammateSpecRows(theme, teammates, roster)];
235
+ }
236
+
237
+ export interface ResumedMemberView {
238
+ name: string;
239
+ restored: boolean;
240
+ }
241
+
242
+ export function teamResumeLines(theme: ThemeLike, team: string, resumed: ResumedMemberView[], teammateCount: number, roster: string[] = []): string[] {
243
+ const countText = resumed.length === teammateCount ? `${resumed.length} resumed` : `${resumed.length} of ${teammateCount} resumed`;
244
+ const header = headerLine(theme, "Team Resume", theme.fg("accent", team), [theme.fg("muted", countText)]);
245
+ if (resumed.length === 0) return [header, `${treeConnector(theme, "└")}${theme.fg("muted", "no stopped teammates")}`];
246
+ const nameWidth = Math.max(...resumed.map((member) => member.name.length));
247
+ const wordWidth = Math.max(...resumed.map((member) => (member.restored ? "resumed" : "restarted").length));
248
+ const rows = resumed.map((member, index) => {
249
+ const branch = index === resumed.length - 1 ? "└" : "├";
250
+ const word = member.restored ? "resumed" : "restarted";
251
+ const note = member.restored ? "history restored" : "empty session";
252
+ return `${treeConnector(theme, branch)}${theme.fg(actorHueToken(member.name, roster), padVisible(member.name, nameWidth))} ${theme.fg(statusWordToken(word), padVisible(word, wordWidth))} ${theme.fg("muted", note)}`;
253
+ });
254
+ return [header, ...rows];
255
+ }
256
+
257
+ export interface TeamListMemberView {
258
+ name: string;
259
+ live: boolean;
260
+ canOverseeOwnTeams: boolean;
261
+ }
262
+
263
+ export interface TeamListTeamView {
264
+ name: string;
265
+ state: string;
266
+ leaseState: string;
267
+ members: TeamListMemberView[];
268
+ updatedAt: string;
269
+ expiresAt?: string;
270
+ }
271
+
272
+ function teamListMemberName(theme: ThemeLike, teamView: TeamListTeamView, member: TeamListMemberView, roster: string[]): string {
273
+ let name = theme.fg(actorHueToken(member.name, roster), member.name);
274
+ if (teamView.state === "active" && !member.live) name = `${DIM_SGR_OPEN}${name}${DIM_SGR_CLOSE}`;
275
+ if (member.canOverseeOwnTeams) name += theme.fg("dim", glyphs().diamond);
276
+ return name;
277
+ }
278
+
279
+ function teamListTimestamp(teamView: TeamListTeamView): string {
280
+ if (teamView.state === "dormant" && teamView.expiresAt) return `expires ${monthDay(Date.parse(teamView.expiresAt))}`;
281
+ return `updated ${nowText(new Date(teamView.updatedAt))}`;
282
+ }
283
+
284
+ export function teamListLines(theme: ThemeLike, teamViews: TeamListTeamView[], roster: string[] = []): TeamLine[] {
285
+ const activeCount = teamViews.filter((teamView) => teamView.state === "active").length;
286
+ const stats = [theme.fg("muted", plural(teamViews.length, "team"))];
287
+ if (activeCount > 0) stats.push(theme.fg("success", `${activeCount} active`));
288
+ const header = headerLine(theme, "Team List", "", stats);
289
+ if (teamViews.length === 0) return [header, `${treeConnector(theme, "└")}${theme.fg("muted", "no teams")}`];
290
+ const nameWidth = Math.max(...teamViews.map((teamView) => teamView.name.length));
291
+ const stateWidth = Math.max(...teamViews.map((teamView) => teamView.state.length));
292
+ const rows: TeamLine[] = teamViews.map((teamView, index) => {
293
+ const branch = index === teamViews.length - 1 ? "└" : "├";
294
+ const rosterText = teamView.members.map((member) => teamListMemberName(theme, teamView, member, roster)).join(theme.fg("muted", glyphs().dot));
295
+ const staleLease = teamView.leaseState === "stale" ? `${dimDot(theme)}${theme.fg("error", "stale lease")}` : "";
296
+ const left = `${treeConnector(theme, branch)}${theme.fg("accent", padVisible(teamView.name, nameWidth))} ${theme.fg(statusWordToken(teamView.state), padVisible(teamView.state, stateWidth))} ${rosterText}${staleLease}`;
297
+ return { left, right: theme.fg("dim", teamListTimestamp(teamView)) };
298
+ });
220
299
  return [header, ...rows];
221
300
  }
222
301
 
@@ -565,6 +644,8 @@ class TeamSendView {
565
644
  private barWidth: number;
566
645
  private expanded: boolean;
567
646
  private theme: ThemeLike;
647
+ private cachedWidth?: number;
648
+ private cachedLines?: string[];
568
649
 
569
650
  constructor(headerStr: string, messageText: string, barStr: string, mdTheme: MarkdownTheme, expanded: boolean, theme: ThemeLike) {
570
651
  this.headerStr = headerStr;
@@ -577,21 +658,30 @@ class TeamSendView {
577
658
 
578
659
  invalidate(): void {
579
660
  this.md.invalidate();
661
+ this.cachedWidth = undefined;
662
+ this.cachedLines = undefined;
580
663
  }
581
664
 
582
665
  render(width: number): string[] {
666
+ if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
583
667
  const header = clipToWidth(this.headerStr, width);
584
668
  const bodyWidth = Math.max(1, width - this.barWidth);
585
669
  const bodyLines = this.md.render(bodyWidth);
586
670
  const barred = bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width));
587
- if (this.expanded) return [header, ...barred];
671
+ if (this.expanded) {
672
+ this.cachedLines = [header, ...barred];
673
+ this.cachedWidth = width;
674
+ return this.cachedLines;
675
+ }
588
676
  const shown = barred.slice(0, SEND_PREVIEW_LINES);
589
677
  const hidden = barred.length - SEND_PREVIEW_LINES;
590
678
  if (hidden > 0) {
591
679
  const g = glyphs();
592
680
  shown.push(clipToWidth(`${this.barStr}${this.theme.fg("dim", `${g.ellipsis} ${hidden} more line${hidden === 1 ? "" : "s"}${g.dot}ctrl+o to expand`)}`, width));
593
681
  }
594
- return [header, ...shown];
682
+ this.cachedLines = [header, ...shown];
683
+ this.cachedWidth = width;
684
+ return this.cachedLines;
595
685
  }
596
686
  }
597
687
 
@@ -600,6 +690,8 @@ class TeamMessageView {
600
690
  private headerLine: string;
601
691
  private barStr: string;
602
692
  private barWidth: number;
693
+ private cachedWidth?: number;
694
+ private cachedLines?: string[];
603
695
 
604
696
  constructor(headerLine: string, messageText: string, barStr: string, mdTheme: MarkdownTheme) {
605
697
  this.headerLine = headerLine;
@@ -610,12 +702,17 @@ class TeamMessageView {
610
702
 
611
703
  invalidate(): void {
612
704
  this.md.invalidate();
705
+ this.cachedWidth = undefined;
706
+ this.cachedLines = undefined;
613
707
  }
614
708
 
615
709
  render(width: number): string[] {
710
+ if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
616
711
  const bodyWidth = Math.max(1, width - this.barWidth);
617
712
  const bodyLines = this.md.render(bodyWidth);
618
- return [clipToWidth(this.headerLine, width), ...bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width))];
713
+ this.cachedLines = [clipToWidth(this.headerLine, width), ...bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width))];
714
+ this.cachedWidth = width;
715
+ return this.cachedLines;
619
716
  }
620
717
  }
621
718
 
@@ -628,6 +725,18 @@ function callBodyFor(tool: TeamToolName, theme: ThemeLike, args: Record<string,
628
725
  const teammates = (args.teammates ?? []) as unknown[];
629
726
  return callBody(theme, "Team Spawn", accentTeam(theme, args.team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
630
727
  }
728
+ if (tool === "team_list") {
729
+ return callBody(theme, "Team List", "");
730
+ }
731
+ if (tool === "team_resume") {
732
+ const requested = args.teammates as string[] | undefined;
733
+ const scope = requested?.length ? plural(requested.length, "teammate") : "all stopped";
734
+ return callBody(theme, "Team Resume", accentTeam(theme, args.team), [theme.fg("muted", scope)]);
735
+ }
736
+ if (tool === "team_add") {
737
+ const teammates = (args.teammates ?? []) as unknown[];
738
+ return callBody(theme, "Team Add", accentTeam(theme, args.team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
739
+ }
631
740
  if (tool === "teamsend") {
632
741
  const message = String(args.message ?? "");
633
742
  return callBody(theme, "Team Send", sendTarget(theme, (args.to ?? []) as string[], roster), sendStats(theme, message, Boolean(args.interrupt)));
@@ -654,6 +763,26 @@ function resultLinesFor(tool: TeamToolName, theme: ThemeLike, args: Record<strin
654
763
  if (tool === "team_spawn") {
655
764
  return teamSpawnLines(theme, String(details.team), (args.teammates ?? []) as TeammateSpecView[], roster);
656
765
  }
766
+ if (tool === "team_list") {
767
+ const teamViews = ((details.teams ?? []) as Array<Record<string, unknown>>).map((entry) => ({
768
+ name: String(entry.name),
769
+ state: String(entry.state),
770
+ leaseState: String(entry.leaseState ?? ""),
771
+ members: (entry.members ?? []) as TeamListMemberView[],
772
+ updatedAt: String(entry.updatedAt),
773
+ expiresAt: entry.expiresAt as string | undefined,
774
+ }));
775
+ return teamListLines(theme, teamViews, roster);
776
+ }
777
+ if (tool === "team_resume") {
778
+ const restartedEmpty = new Set((details.restartedEmpty ?? []) as string[]);
779
+ const resumed = ((details.resumed ?? []) as string[]).map((name) => ({ name, restored: !restartedEmpty.has(name) }));
780
+ return teamResumeLines(theme, String(details.team), resumed, ((details.teammates ?? []) as string[]).length, roster);
781
+ }
782
+ if (tool === "team_add") {
783
+ const memberCount = Object.keys((details.status ?? {}) as Record<string, unknown>).length;
784
+ return teamAddLines(theme, String(details.team), (args.teammates ?? []) as TeammateSpecView[], memberCount, roster);
785
+ }
657
786
  if (tool === "teamsend") {
658
787
  return teamSendLines(theme, {
659
788
  to: (details.to ?? []) as string[],
@@ -694,7 +823,7 @@ export function renderTeamToolResult(
694
823
  markdownTheme?: MarkdownTheme,
695
824
  roster: string[] = [],
696
825
  ): TeamSendView | TeamLines {
697
- const args = context?.args ?? {};
826
+ const args = (context?.args ?? {}) as Record<string, unknown>;
698
827
  if (context?.isError || result?.isError) {
699
828
  return new TeamLines(errorLines(theme, callBodyFor(tool, theme, args, roster), textContent(result)), options.expanded ? "wrap" : "clip");
700
829
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ai-to-ai
3
- description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Note that Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-ai` before spawning a sub-agent, creating a team of agents, talking to a teammate agent, or writing documentation. Trigger words are “dispatch an agent”, “spawn a team”, “talk with <another ai>”, etc.
3
+ description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-ai` before spawning a sub-agent, creating a team, talking to a teammate agent, or writing documentation. Trigger words include “dispatch an agent”, “spawn a team”, and “talk with <another ai>”.
4
4
  ---
5
5
 
6
6
  ## Why delegate at all? Rationale
@@ -19,8 +19,6 @@ The flip side: if none of these payoffs apply, don't delegate. The anti-pattern
19
19
  - **Hivemind:** teams communicating internally in real time, as each teammate does work. Hollywood analogy: elite soldier squad or a team of spies, global channel earpieces, deployed behind enemy lines, each progresses their part, each part essential for completing the mission, global channel earpieces, consistent live updates, uncertainties surfaced to get advice, discussions to make best decisions for mission, path forward of an individual adapts in real time due to new peer finding, HQ possibly listening, warning and steering as required.
20
20
  - **De-bias:** It’s easier to spot blind spots or flaws when looking at someone else’s work (review; live or after the fact). Related: sometimes a hypothesis is considered true only after it is confirmed independently by multiple actors (consensus).
21
21
 
22
- Read [`references/firstmate.md`](references/firstmate.md) when the user asks you to serve as their First Mate. Read [`references/captain.md`](references/captain.md) when the user asks you to serve as Captain of a fleet of teams. `./references/` contains additional resources for specific delegation use-cases and shapes.
23
-
24
22
  ---
25
23
 
26
24
  ## How to request work from other AI agents (that do not inherit your session’s context window)
@@ -77,6 +75,11 @@ The framework behind this section: [`theory-of-mind.md`](../../references/theory
77
75
 
78
76
  ## Next required reading
79
77
 
78
+ This is a tiny state machine. Read only the references that apply based on the user’s instructions and your intent.
79
+
80
80
  If you are delegating work to AI’s, read [`references/subagents-vs-teams.md`](references/subagents-vs-teams.md).
81
- If you are a teammate, read [`references/teammate.md`](references/teammate.md).
82
- It’s possible that you are both.
81
+ If you are a teammate, read [`references/ranks/teammate.md`](references/ranks/teammate.md).
82
+ It’s possible that you are both.
83
+ If the user asks you to serve as their first mate, read [`references/ranks/firstmate.md`](references/ranks/firstmate.md). Conversely, if the user asks you to serve as Captain of a fleet of teams, read [`references/ranks/captain.md`](references/ranks/captain.md) to understand your role AND `references/ranks/firstmate.md` to understand your direct delegates’ reality and how to best support them.
84
+
85
+ `./references/` contains additional resources for specific delegation use-cases and shapes. Don’t take them as gospel. They are incomplete and evolving. Think of them as examples to generalize from.
@@ -1,10 +1,12 @@
1
1
  ---
2
2
  name: head-of-product
3
+ description: Keeps work focused on the smallest useful outcome and prevents discovery-driven scope creep.
3
4
  type: role
4
5
  goes_well_with: tech-lead
5
6
  ---
6
7
 
7
8
  # Head of Product
8
9
 
9
- Cares about user value, go to market (minimize time to delivery), human’s business (working deliverables = income), and human client’s business (added value that works, delivered at a good-enough rate = happy, trust, wants more).
10
- Head of product deeply understands that homing in on the minimal deliverable that works well but does not go an inch beyond that desired minimal scope is crucial for the business to work. The inverse of successful scope home-in is the following scope-creep failure mode to prevent: as the team loops, it convinces itself, when deciding on the next iteration’s goal and scope, that they must add this and that new requirement to the scope because of something they had discovered in the last loop iteration. Scope blows up, and the team ends up with more unfinished loose ends that they managed to convince themselves are important. A team that ends up like this does more damage than good. Head of product understands this. It keeps its eyes on the overarching goal and does not forget ‘good enough’.
10
+ Cares about user value, time to delivery, and working outcomes. For Gilad’s business, working deliverables create income. For his clients, useful deliverables create value and trust, and lead to more work.
11
+ Head of product deeply understands that homing in on the minimal deliverable that works well but does not go an inch beyond that desired minimal scope is crucial for the business to work.
12
+ The inverse of successful scope home-in is the following scope-creep failure mode to prevent: as the team loops, it convinces itself, when deciding on the next iteration’s goal and scope, that they must add this and that new requirement to the scope because of something they had discovered in the last loop iteration. Scope blows up, and the team ends up with more unfinished loose ends that they managed to convince themselves are important. A team that ends up like this does more damage than good. Head of product understands this. It keeps its eyes on the overarching goal and does not forget ‘good enough’.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: tech-lead
3
- type: role
3
+ description: Owns deep technical expertise while retaining architecture and tradeoff decisions.
4
4
  goes_well_with: head-of-product
5
5
  ---
6
6
 
@@ -8,4 +8,4 @@ goes_well_with: head-of-product
8
8
 
9
9
  Understands product mindset well, but expertise is technical. Responsible for the technical knowledge space (known and unknown), deep database understanding, research, discovery and implementation. Knows to assess complexity and tradeoffs realistically within its domain of expertise when head of product needs it to deliver something for it (new knowledge/evidence/proof/behavior). This helps head of product make good product and business decisions.
10
10
 
11
- When the task is unquestionably large, Tech lead uses lots of delegation to be able, within its context window limit, to give head of product what it needs, consistently, across as many requests as head of product makes. This is especially true when the mission is discovery-heavy. The reality is that tech lead can't do repeated thorough database dive-ins into uncharted territories without blowing up its context window after one or two dives, so it breaks up the deliverable and delegates bounded tasks. Tech lead still does the technical judgment calls and decision-making, so it delegates many thin tasks frequently.
11
+ When the task is unquestionably large, Tech Lead uses lots of delegation to be able, within its context window limit, to give head of product what it needs, consistently, across as many requests as head of product makes. This is especially true when the mission is discovery-heavy. The reality is that tech lead can't do repeated thorough database dive-ins into uncharted territories without blowing up its context window after one or two dives, so it breaks up the deliverable and delegates bounded tasks. Tech lead still does the technical judgment calls and decision-making, so it delegates many thin tasks frequently.
@@ -35,7 +35,7 @@ The admiral sets fleet-wide policy in one line ("all first mates on model X at t
35
35
 
36
36
  ## How a captain communicates with the admiral
37
37
 
38
- **The admiral does not attend the session.** He is not reading your interim messages. Interim status updates go unread. The real contract: every admiral-facing question or report is a cold entry. It must re-ground from the last true common ground — the mission he gave you and the last decisions he has actually made last time you interacted — never from your previous message.
38
+ **The admiral does not attend the session.** Gilad does not read your interim messages. Interim status updates go unread. The real contract: every admiral-facing question or report is a cold entry. It must re-ground from the last true common ground — the mission Gilad gave you and the last decisions he made when you last interacted — never from your previous message.
39
39
 
40
40
  **A question must carry its own provenance.** A good admiral question states, in product terms: the progress made since last touch-point, what the fork is, the path that produced it, the options already rejected and why, and your recommendation. "May the first mate buy asset pack X?" out of the blue is a failure. "Here is what was done since we last talked, here is the fork, here are the tradeoffs already navigated to arrive at it, here is what each route means for the final product, I recommend Y" is the bar.
41
41
 
@@ -1,3 +1,8 @@
1
+ ---
2
+ name: teammate
3
+ description: Requires frequent status updates and early escalation of scope or context risks.
4
+ ---
5
+
1
6
  ## Teammate {i need a word here that isn't "instructions"}
2
7
 
3
8
  **Set your own status frequently.**
@@ -1,3 +1,9 @@
1
+ ---
2
+ name: fanned-out-research
3
+ shape: Parallel subagents
4
+ description: Example of how independent user requirements map to parallel read-only research subagents.
5
+ ---
6
+
1
7
  # Simple Fanned-out Research Delegation Example
2
8
 
3
9
  The following is an "easy" case, because the subagents' graph maps cleanly to the user message's structure. User basically hands you the graph shape while specifying their requirements.
@@ -1,3 +1,9 @@
1
+ ---
2
+ name: colloquium
3
+ shape: Team
4
+ description: Uses live peer exchange so adjacent research findings cross-pollinate each teammate's work.
5
+ ---
6
+
1
7
  # Colloquium Team
2
8
 
3
9
  Individually, each teammate is responsible for an orthogonal, parallel, read-only, think-heavy effort. The teammates would benefit from listening to the other teammates as they share their thoughts and findings in real time, exactly because each of them is doing its own thing. Sharing is fruitful for the same reason it’s fruitful for scientists to attend and listen to peers in scientific conferences: a peer’s finding from an adjacent problem updates your map of the shared terrain and reframes your own problem in ways you could not have generated from inside your own lane, at no cost to your own effort. Think of it as an open studio: everyone works on their own piece while absorbing the others’.
@@ -6,14 +12,12 @@ Individually, each teammate is responsible for an orthogonal, parallel, read-onl
6
12
 
7
13
  N flat teammates working in parallel.
8
14
 
9
- ## Team prompt template
10
-
11
15
  ## Abstract required conditions for this shape to fit needs
12
16
 
13
17
  - Teammates’ bottom-line deliverable is figuring out *how* to do something;
14
18
  - Teammates’ scopes overlap semantically at least a bit.
15
19
 
16
- Examples (not an exhaustive list — infer the underlying principles and generalize regardless of domain):
20
+ Examples (not an exhaustive list — derive the underlying principles and generalize regardless of domain):
17
21
  - Team is given an under-designed existing web page. Teammate A responsible for coming up with a better design language and vision; Teammate B is responsible for pointing out the page’s mobile usability issues and suggesting concrete improvements. A creates a better-informed design vision knowing B’s findings and suggestions; B suggests better-aligned suggestions knowing the larger design language’s direction. A top-down/bottom-up pincer move. Team output is not a funneled merge of individual results; it’s a flat union of the N individual results. The team’s dynamic ensures the results are cohesive and well-aligned (synergy).
18
22
 
19
23
  ## When not to use
@@ -1,3 +1,9 @@
1
+ ---
2
+ name: hillclimber-watcher-team
3
+ shape: Team
4
+ description: Pairs an iterative optimizer with a watcher that prevents tunnel vision.
5
+ ---
6
+
1
7
  # Hillclimber–Watcher Team Pattern
2
8
 
3
9
  Use this pattern when the task has a measurable target, a search space, and a real risk that a busy agent will tunnel-vision while iterating. The point is not ordinary implementer/reviewer pairing. The point is **autonomous optimization with periodic outside-the-loop steering**.
@@ -1,3 +1,9 @@
1
+ ---
2
+ name: pair-programming-team
3
+ shape: Team
4
+ description: Pairs peers who agree on a plan, then implement and review once.
5
+ ---
6
+
1
7
  # Pair-Programming Team Pattern
2
8
 
3
9
  This team structure is somewhat different in that the teammates' slots shape are vertical, not horizontal. The pair is best for taking a feature through the whole dev cycle from start to finish. This means they wear different hats as they progress through planning, implementing, reviewing and shipping. Neither is "an implementer" or "a reviewer". They're both planners engaging in dialectic discussion at first; they then fan out writing code; review each other's work; and wrap up.
package/teamlog.ts CHANGED
@@ -74,6 +74,10 @@ export function timeOfDay(epochMilliseconds: number): string {
74
74
  return timeFormatter.format(new Date(epochMilliseconds));
75
75
  }
76
76
 
77
+ export function monthDay(epochMilliseconds: number): string {
78
+ return dateFormatter.format(new Date(epochMilliseconds));
79
+ }
80
+
77
81
  function safeStringify(value: unknown): string {
78
82
  try {
79
83
  return JSON.stringify(value) ?? String(value);