@giladbarnea/pi-simple-team 1.0.30 → 1.0.31

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/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.31",
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
@@ -565,6 +565,8 @@ class TeamSendView {
565
565
  private barWidth: number;
566
566
  private expanded: boolean;
567
567
  private theme: ThemeLike;
568
+ private cachedWidth?: number;
569
+ private cachedLines?: string[];
568
570
 
569
571
  constructor(headerStr: string, messageText: string, barStr: string, mdTheme: MarkdownTheme, expanded: boolean, theme: ThemeLike) {
570
572
  this.headerStr = headerStr;
@@ -577,21 +579,30 @@ class TeamSendView {
577
579
 
578
580
  invalidate(): void {
579
581
  this.md.invalidate();
582
+ this.cachedWidth = undefined;
583
+ this.cachedLines = undefined;
580
584
  }
581
585
 
582
586
  render(width: number): string[] {
587
+ if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
583
588
  const header = clipToWidth(this.headerStr, width);
584
589
  const bodyWidth = Math.max(1, width - this.barWidth);
585
590
  const bodyLines = this.md.render(bodyWidth);
586
591
  const barred = bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width));
587
- if (this.expanded) return [header, ...barred];
592
+ if (this.expanded) {
593
+ this.cachedLines = [header, ...barred];
594
+ this.cachedWidth = width;
595
+ return this.cachedLines;
596
+ }
588
597
  const shown = barred.slice(0, SEND_PREVIEW_LINES);
589
598
  const hidden = barred.length - SEND_PREVIEW_LINES;
590
599
  if (hidden > 0) {
591
600
  const g = glyphs();
592
601
  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
602
  }
594
- return [header, ...shown];
603
+ this.cachedLines = [header, ...shown];
604
+ this.cachedWidth = width;
605
+ return this.cachedLines;
595
606
  }
596
607
  }
597
608
 
@@ -600,6 +611,8 @@ class TeamMessageView {
600
611
  private headerLine: string;
601
612
  private barStr: string;
602
613
  private barWidth: number;
614
+ private cachedWidth?: number;
615
+ private cachedLines?: string[];
603
616
 
604
617
  constructor(headerLine: string, messageText: string, barStr: string, mdTheme: MarkdownTheme) {
605
618
  this.headerLine = headerLine;
@@ -610,12 +623,17 @@ class TeamMessageView {
610
623
 
611
624
  invalidate(): void {
612
625
  this.md.invalidate();
626
+ this.cachedWidth = undefined;
627
+ this.cachedLines = undefined;
613
628
  }
614
629
 
615
630
  render(width: number): string[] {
631
+ if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
616
632
  const bodyWidth = Math.max(1, width - this.barWidth);
617
633
  const bodyLines = this.md.render(bodyWidth);
618
- return [clipToWidth(this.headerLine, width), ...bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width))];
634
+ this.cachedLines = [clipToWidth(this.headerLine, width), ...bodyLines.map((line) => clipToWidth(`${this.barStr}${line}`, width))];
635
+ this.cachedWidth = width;
636
+ return this.cachedLines;
619
637
  }
620
638
  }
621
639
 
@@ -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,5 +1,6 @@
1
1
  ---
2
2
  name: tech-lead
3
+ description: Owns deep technical expertise while retaining architecture and tradeoff decisions.
3
4
  type: role
4
5
  goes_well_with: head-of-product
5
6
  ---
@@ -8,4 +9,4 @@ goes_well_with: head-of-product
8
9
 
9
10
  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
11
 
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.
12
+ 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.