@giladbarnea/pi-simple-team 1.0.34 → 1.0.36
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 +2 -0
- package/package.json +1 -1
- package/skills/ai-to-ai/SKILL.md +1 -1
- package/skills/ai-to-ai/references/theory-of-mind.md +41 -0
- package/team-ui.ts +85 -34
package/README.md
CHANGED
|
@@ -81,6 +81,8 @@ Main agent:
|
|
|
81
81
|
|
|
82
82
|
The command opens an overlay rolling recent statuses, messages, and a separate event log.
|
|
83
83
|
|
|
84
|
+
Up/Down select the messages or log widget. Enter zooms it to the full overlay. Esc goes back.
|
|
85
|
+
|
|
84
86
|
<a href="screenshots/team-view.png">
|
|
85
87
|
<img src="screenshots/team-view.png" width="100%" alt="The live team dashboard showing statuses, messages, and recent events">
|
|
86
88
|
</a>
|
package/package.json
CHANGED
package/skills/ai-to-ai/SKILL.md
CHANGED
|
@@ -27,7 +27,7 @@ The flip side: if none of these payoffs apply, don't delegate. The anti-pattern
|
|
|
27
27
|
|
|
28
28
|
This section is a communication rulebook to all cases where an AI requests something from another AI: down, sideways and up — main to sub-agent, main to team, teammate to teammate, and delegated to delegator.
|
|
29
29
|
|
|
30
|
-
The framework behind this section: [`theory-of-mind.md`](
|
|
30
|
+
The framework behind this section: [`theory-of-mind.md`](references/theory-of-mind.md). Read it once.
|
|
31
31
|
|
|
32
32
|
**1. Orient the agent to the project:**
|
|
33
33
|
1.a. Tell the AI agent to *load the skills and files the user has referenced* throughout the session. That's the baseline common ground. Do not repeat the content of those skills and files in your prompt.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: theory-of-mind
|
|
3
|
+
description: Explains how to re-ground readers after absence or context decay creates asymmetric common ground.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Theory of Mind: Writing Under Asymmetric Common Ground
|
|
7
|
+
|
|
8
|
+
The theory behind any writing addressed to a reader whose context has diverged from yours.
|
|
9
|
+
|
|
10
|
+
## The phenomenon
|
|
11
|
+
|
|
12
|
+
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, you can no longer tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning.
|
|
13
|
+
|
|
14
|
+
Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
|
|
15
|
+
|
|
16
|
+
## Two ways the asymmetry arises
|
|
17
|
+
|
|
18
|
+
1. **Absence.** The reader was not there while you built the layer. Everything after the divergence point is private to you.
|
|
19
|
+
2. **Decay.** The reader once held the context, but it has gone cold. They keep the memory yet cannot retrieve it unaided.
|
|
20
|
+
|
|
21
|
+
Both reduce to the same obligation: model the reader's current state, not yours.
|
|
22
|
+
|
|
23
|
+
## The two models
|
|
24
|
+
|
|
25
|
+
Hold two models at once:
|
|
26
|
+
|
|
27
|
+
1. Your current understanding of the situation.
|
|
28
|
+
2. The last known common ground — what the reader actually holds right now.
|
|
29
|
+
|
|
30
|
+
The delta between them is the payload your writing must carry. Writing under asymmetry is therefore not summarizing your own experience. It is reconstructing the recipient's state of knowledge and designing their entry into the situation. Optimize for their entry, not your exit.
|
|
31
|
+
|
|
32
|
+
## The moves
|
|
33
|
+
|
|
34
|
+
1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
|
|
35
|
+
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them, or explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
36
|
+
3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
|
|
37
|
+
4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
|
|
38
|
+
|
|
39
|
+
## The test
|
|
40
|
+
|
|
41
|
+
Could the reader, holding only the last common ground, parse every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still saturated.
|
package/team-ui.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import {
|
|
2
|
+
import { getKeybindings, SelectList, sliceByColumn, truncateToWidth, visibleWidth, type Component, type SelectItem, type TUI } from "@earendil-works/pi-tui";
|
|
3
3
|
|
|
4
4
|
import {
|
|
5
5
|
actorHueToken,
|
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
type TeamStatusView,
|
|
13
13
|
type ThemeLike,
|
|
14
14
|
} from "./render.ts";
|
|
15
|
+
import { glyphs } from "./render-support/glyphs.ts";
|
|
15
16
|
import type { TeamLogEntry, TeamLogKind } from "./teamlog.ts";
|
|
16
17
|
|
|
17
18
|
export interface TeamSnapshot {
|
|
@@ -26,7 +27,13 @@ export interface TeamSnapshot {
|
|
|
26
27
|
export type TeamSnapshotSource = () => readonly TeamSnapshot[];
|
|
27
28
|
|
|
28
29
|
const RECENT_STATUS_LIMIT = 5;
|
|
29
|
-
|
|
30
|
+
|
|
31
|
+
type ZoomableWidget = "messages" | "log";
|
|
32
|
+
|
|
33
|
+
interface WidgetView {
|
|
34
|
+
title: string;
|
|
35
|
+
lines: string[];
|
|
36
|
+
}
|
|
30
37
|
const LIVE_REFRESH_INTERVAL_MILLISECONDS = 500;
|
|
31
38
|
const MESSAGE_LOG_KINDS = new Set<TeamLogKind>(["send", "deliver", "ack", "main_message"]);
|
|
32
39
|
|
|
@@ -147,6 +154,8 @@ class TeamOverviewOverlay implements Component {
|
|
|
147
154
|
private selector?: SelectList;
|
|
148
155
|
private selectorTeamNames?: string;
|
|
149
156
|
private selectedTeamName?: string;
|
|
157
|
+
private focusedWidget: ZoomableWidget = "messages";
|
|
158
|
+
private zoomedWidget?: ZoomableWidget;
|
|
150
159
|
private refreshTimer?: ReturnType<typeof setInterval>;
|
|
151
160
|
private closed = false;
|
|
152
161
|
|
|
@@ -190,17 +199,35 @@ class TeamOverviewOverlay implements Component {
|
|
|
190
199
|
this.tui.requestRender();
|
|
191
200
|
return;
|
|
192
201
|
}
|
|
193
|
-
|
|
202
|
+
const keybindings = getKeybindings();
|
|
203
|
+
if (keybindings.matches(data, "tui.select.cancel")) {
|
|
204
|
+
if (!this.zoomedWidget) {
|
|
205
|
+
this.close();
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
this.zoomedWidget = undefined;
|
|
209
|
+
this.tui.requestRender();
|
|
210
|
+
return;
|
|
211
|
+
}
|
|
212
|
+
if (!this.selectedTeamName || this.zoomedWidget) return;
|
|
213
|
+
if (keybindings.matches(data, "tui.select.up")) this.focusedWidget = "messages";
|
|
214
|
+
else if (keybindings.matches(data, "tui.select.down")) this.focusedWidget = "log";
|
|
215
|
+
else if (keybindings.matches(data, "tui.select.confirm")) this.zoomedWidget = this.focusedWidget;
|
|
216
|
+
else return;
|
|
217
|
+
this.tui.requestRender();
|
|
194
218
|
}
|
|
195
219
|
|
|
196
220
|
render(width: number): string[] {
|
|
197
221
|
const height = Math.max(4, Math.floor(this.tui.terminal.rows * 0.9));
|
|
198
222
|
const teams = this.teamSource();
|
|
199
|
-
if (this.selectedTeamName && !teams.some((candidate) => candidate.name === this.selectedTeamName))
|
|
223
|
+
if (this.selectedTeamName && !teams.some((candidate) => candidate.name === this.selectedTeamName)) {
|
|
224
|
+
this.selectedTeamName = undefined;
|
|
225
|
+
this.zoomedWidget = undefined;
|
|
226
|
+
}
|
|
200
227
|
if (!this.selectedTeamName && teams.length === 1) this.selectedTeamName = teams[0]!.name;
|
|
201
228
|
if (this.selectedTeamName) {
|
|
202
229
|
const team = teams.find((candidate) => candidate.name === this.selectedTeamName)!;
|
|
203
|
-
return this.dashboard(team, width, height);
|
|
230
|
+
return this.zoomedWidget ? this.zoom(team, this.zoomedWidget, width, height) : this.dashboard(team, width, height);
|
|
204
231
|
}
|
|
205
232
|
if (teams.length > 1) this.refreshSelector(teams);
|
|
206
233
|
else this.selector = undefined;
|
|
@@ -248,61 +275,85 @@ class TeamOverviewOverlay implements Component {
|
|
|
248
275
|
];
|
|
249
276
|
}
|
|
250
277
|
|
|
251
|
-
private
|
|
252
|
-
const contentWidth = Math.max(1, width - 2);
|
|
253
|
-
const contentHeight = Math.max(1, height - 2);
|
|
254
|
-
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
255
|
-
const desiredStatusHeight = Math.min(Object.keys(team.statuses).length, RECENT_STATUS_LIMIT) + 2;
|
|
256
|
-
const statusHeight = Math.max(1, Math.min(desiredStatusHeight, contentHeight - headerHeight - 2));
|
|
257
|
-
const feedHeight = contentHeight - headerHeight - statusHeight;
|
|
258
|
-
const messageHeight = Math.max(1, Math.min(feedHeight - 1, Math.round(feedHeight * 0.55)));
|
|
259
|
-
const logHeight = feedHeight - messageHeight;
|
|
260
|
-
|
|
278
|
+
private headerRegion(team: TeamSnapshot, hint: string, contentWidth: number, headerHeight: number, breadcrumb?: string): string[] {
|
|
261
279
|
const transport = team.showOnHerdrPanes ? "Herdr" : "RPC";
|
|
262
280
|
const metadata = [
|
|
263
281
|
`Created ${relativeTimeText(team.created)}`,
|
|
264
282
|
`${team.roster.length} teammate${team.roster.length === 1 ? "" : "s"}`,
|
|
265
283
|
transport,
|
|
266
|
-
|
|
267
|
-
"Esc close",
|
|
284
|
+
hint,
|
|
268
285
|
].join(" · ");
|
|
286
|
+
const title = breadcrumb ? `Team: ${team.name} ${glyphs().chevron} ${breadcrumb}` : `Team: ${team.name}`;
|
|
287
|
+
return this.region(this.theme.fg("accent", this.theme.bold(title)), [this.theme.fg("muted", metadata)], contentWidth, headerHeight);
|
|
288
|
+
}
|
|
269
289
|
|
|
270
|
-
|
|
271
|
-
const statuses = recentStatuses(team.statuses, Math.min(RECENT_STATUS_LIMIT, statusContentHeight));
|
|
272
|
-
const statusLines = statusRows(this.theme, statuses, team.roster, Math.max(0, contentWidth - 2));
|
|
273
|
-
|
|
290
|
+
private messageWidget(team: TeamSnapshot, contentHeight: number): WidgetView {
|
|
274
291
|
const allMessages = team.log.flatMap((entry) => {
|
|
275
292
|
const message = teamMessage(entry);
|
|
276
293
|
return message ? [message] : [];
|
|
277
294
|
});
|
|
278
295
|
const messageGroups = allMessages.map((message) => teamMessageLines(this.theme, message, team.roster).map(teamLineText));
|
|
279
|
-
const selectedMessages = selectNewestMessageLines(messageGroups, Math.max(0,
|
|
280
|
-
const
|
|
296
|
+
const selectedMessages = selectNewestMessageLines(messageGroups, Math.max(0, contentHeight));
|
|
297
|
+
const lines = selectedMessages.lines.length > 0 ? selectedMessages.lines : [this.theme.fg("muted", "No recent messages.")];
|
|
298
|
+
return { title: `Messages · latest ${selectedMessages.messageCount} of ${allMessages.length}`, lines };
|
|
299
|
+
}
|
|
281
300
|
|
|
301
|
+
private logWidget(team: TeamSnapshot, contentHeight: number): WidgetView {
|
|
282
302
|
const allLogEntries = team.log.filter((entry) => !MESSAGE_LOG_KINDS.has(entry.kind));
|
|
283
|
-
const recentLogEntries = allLogEntries.slice(-RECENT_LOG_ENTRY_LIMIT);
|
|
284
303
|
const renderedLogLines = teamLogLines(this.theme, {
|
|
285
304
|
team: team.name,
|
|
286
305
|
roster: team.roster,
|
|
287
|
-
entries:
|
|
306
|
+
entries: allLogEntries,
|
|
288
307
|
totalMatched: allLogEntries.length,
|
|
289
|
-
returned:
|
|
308
|
+
returned: allLogEntries.length,
|
|
290
309
|
}).slice(1);
|
|
291
|
-
const
|
|
292
|
-
|
|
310
|
+
const lines = renderedLogLines.slice(-Math.max(0, contentHeight));
|
|
311
|
+
return { title: `Team Log ${team.name} · latest ${lines.length} rows · ${allLogEntries.length} events`, lines };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
private dashboard(team: TeamSnapshot, width: number, height: number): string[] {
|
|
315
|
+
const contentWidth = Math.max(1, width - 2);
|
|
316
|
+
const contentHeight = Math.max(1, height - 2);
|
|
317
|
+
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
318
|
+
const desiredStatusHeight = Math.min(Object.keys(team.statuses).length, RECENT_STATUS_LIMIT) + 2;
|
|
319
|
+
const statusHeight = Math.max(1, Math.min(desiredStatusHeight, contentHeight - headerHeight - 2));
|
|
320
|
+
const feedHeight = contentHeight - headerHeight - statusHeight;
|
|
321
|
+
const messageHeight = Math.max(1, Math.min(feedHeight - 1, Math.round(feedHeight * 0.55)));
|
|
322
|
+
const logHeight = feedHeight - messageHeight;
|
|
323
|
+
|
|
324
|
+
const statusContentHeight = Math.max(0, statusHeight - 2);
|
|
325
|
+
const statuses = recentStatuses(team.statuses, Math.min(RECENT_STATUS_LIMIT, statusContentHeight));
|
|
326
|
+
const statusLines = statusRows(this.theme, statuses, team.roster, Math.max(0, contentWidth - 2));
|
|
327
|
+
|
|
328
|
+
const messages = this.messageWidget(team, messageHeight - 2);
|
|
329
|
+
const log = this.logWidget(team, logHeight - 2);
|
|
293
330
|
|
|
294
331
|
const content = [
|
|
295
|
-
...this.
|
|
332
|
+
...this.headerRegion(team, "↑↓ widget · Enter zoom · Esc close", contentWidth, headerHeight),
|
|
296
333
|
...this.region(`Team Status ${team.name} · latest ${statuses.length} of ${Object.keys(team.statuses).length}`, statusLines, contentWidth, statusHeight),
|
|
297
|
-
...this.region(
|
|
298
|
-
...this.region(
|
|
334
|
+
...this.region(messages.title, messages.lines, contentWidth, messageHeight, this.focusedWidget === "messages"),
|
|
335
|
+
...this.region(log.title, log.lines, contentWidth, logHeight, this.focusedWidget === "log"),
|
|
336
|
+
];
|
|
337
|
+
return this.frame(content, width, height);
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
private zoom(team: TeamSnapshot, widget: ZoomableWidget, width: number, height: number): string[] {
|
|
341
|
+
const contentWidth = Math.max(1, width - 2);
|
|
342
|
+
const contentHeight = Math.max(1, height - 2);
|
|
343
|
+
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
344
|
+
const widgetHeight = Math.max(1, contentHeight - headerHeight);
|
|
345
|
+
const view = widget === "messages" ? this.messageWidget(team, widgetHeight - 2) : this.logWidget(team, widgetHeight - 2);
|
|
346
|
+
const breadcrumb = widget === "messages" ? "Messages" : "Team Log";
|
|
347
|
+
const content = [
|
|
348
|
+
...this.headerRegion(team, "Esc back to team view", contentWidth, headerHeight, breadcrumb),
|
|
349
|
+
...this.region(view.title, view.lines, contentWidth, widgetHeight, true),
|
|
299
350
|
];
|
|
300
351
|
return this.frame(content, width, height);
|
|
301
352
|
}
|
|
302
353
|
|
|
303
|
-
private region(title: string, content: string[], width: number, height: number): string[] {
|
|
354
|
+
private region(title: string, content: string[], width: number, height: number, focused = false): string[] {
|
|
304
355
|
const frameWidth = Math.max(1, width);
|
|
305
|
-
const border = (text: string): string => this.theme.fg("border", text);
|
|
356
|
+
const border = (text: string): string => this.theme.fg(focused ? "borderAccent" : "border", text);
|
|
306
357
|
if (frameWidth < 3) {
|
|
307
358
|
const top = border(frameWidth === 1 ? "╭" : "╭╮");
|
|
308
359
|
if (height === 1) return [top];
|
|
@@ -312,7 +363,7 @@ class TeamOverviewOverlay implements Component {
|
|
|
312
363
|
|
|
313
364
|
const innerWidth = frameWidth - 2;
|
|
314
365
|
const labelWidth = Math.max(0, innerWidth - 3);
|
|
315
|
-
const label = middleTruncateToWidth(title, labelWidth);
|
|
366
|
+
const label = middleTruncateToWidth(focused ? `${glyphs().chevron} ${title}` : title, labelWidth);
|
|
316
367
|
const topFill = "─".repeat(Math.max(0, innerWidth - 3 - visibleWidth(label)));
|
|
317
368
|
const top = innerWidth < 3 ? border(`╭${"─".repeat(innerWidth)}╮`) : `${border("╭─ ")}${label}${border(` ${topFill}╮`)}`;
|
|
318
369
|
if (height === 1) return [top];
|