@giladbarnea/pi-simple-team 1.0.17 → 1.0.19

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.
@@ -0,0 +1,4 @@
1
+ import { fileURLToPath } from "node:url";
2
+
3
+ export const bundledAiToAiSkillPath = fileURLToPath(new URL("./skills/ai-to-ai/SKILL.md", import.meta.url));
4
+ export const bundledAiToAiSkillInstruction = `Read the bundled ai-to-ai skill at ${bundledAiToAiSkillPath} in full before continuing, then follow its instructions.`;
package/index.ts CHANGED
@@ -5,6 +5,7 @@ import http from "node:http";
5
5
  import { StringDecoder } from "node:string_decoder";
6
6
  import { fileURLToPath } from "node:url";
7
7
  import { defineTool, type ContextUsage, type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
8
+ import { bundledAiToAiSkillInstruction } from "./bundled-skill.ts";
8
9
  import { formatContextWindowReport, requireKnownContextUsage, type KnownContextUsage } from "./context-window.ts";
9
10
  import { formatScopedModelGuidance, validateTeammateModels, type ModelReference } from "./model-preflight.ts";
10
11
  import { composeSystemPrompt } from "./system-prompt.ts";
@@ -44,6 +45,7 @@ interface TeammateSpec {
44
45
  prompt: string;
45
46
  model: string;
46
47
  thinking?: ThinkingLevel;
48
+ inheritContext?: boolean;
47
49
  }
48
50
 
49
51
  type TeammateTransport = "rpc" | "herdr";
@@ -53,6 +55,7 @@ interface TeammateState {
53
55
  prompt: string;
54
56
  model: string;
55
57
  thinking: ThinkingLevel;
58
+ inheritContext: boolean;
56
59
  transport: TeammateTransport;
57
60
  process?: ChildProcess;
58
61
  paneId?: string;
@@ -74,6 +77,7 @@ interface TeamState {
74
77
  name: string;
75
78
  showOnHerdrPanes: boolean;
76
79
  teamPrompt: string;
80
+ mainSessionFile?: string;
77
81
  members: Map<string, TeammateState>;
78
82
  statuses: Map<string, TeamStatus>;
79
83
  created: string;
@@ -487,6 +491,7 @@ function createTeammateState(team: TeamState, teammateSpec: TeammateSpec): Teamm
487
491
  prompt: teammateSpec.prompt,
488
492
  model: teammateSpec.model,
489
493
  thinking,
494
+ inheritContext: Boolean(teammateSpec.inheritContext),
490
495
  transport: team.showOnHerdrPanes ? "herdr" : "rpc",
491
496
  visibleReady,
492
497
  resolveVisibleReady,
@@ -518,15 +523,17 @@ function appendSpawnLog(team: TeamState, teammate: TeammateState): void {
518
523
  teammate: teammate.name,
519
524
  direction: "runtime",
520
525
  kind: "spawn",
521
- summary: `spawned ${teammate.name} (model=${teammate.model}, thinking=${teammate.thinking})`,
522
- details: { model: teammate.model, thinking: teammate.thinking, transport: teammate.transport, paneId: teammate.paneId },
526
+ summary: `spawned ${teammate.name} (model=${teammate.model}, thinking=${teammate.thinking}, context=${teammate.inheritContext ? "inherited" : "fresh"})`,
527
+ details: { model: teammate.model, thinking: teammate.thinking, inheritContext: teammate.inheritContext, transport: teammate.transport, paneId: teammate.paneId },
523
528
  });
524
529
  }
525
530
 
526
531
  function attachRpcTeammate(team: TeamState, teammate: TeammateState, participants: string[]): void {
532
+ const sessionArgs = teammate.inheritContext ? ["--fork", team.mainSessionFile!] : [];
527
533
  const args = [
528
534
  "--mode",
529
535
  "rpc",
536
+ ...sessionArgs,
530
537
  "-e",
531
538
  teamLiteExtensionPath,
532
539
  "--no-prompt-templates",
@@ -582,7 +589,19 @@ async function attachVisibleTeammate(team: TeamState, teammate: TeammateState, p
582
589
  for (const [name, value] of Object.entries(environment)) {
583
590
  if (value !== undefined) args.push("--env", `${name}=${value}`);
584
591
  }
585
- args.push("--", "pi", "-e", teamLiteExtensionPath, "--model", teammate.model, "--thinking", teammate.thinking, "--system-prompt", systemPrompt);
592
+ args.push(
593
+ "--",
594
+ "pi",
595
+ ...(teammate.inheritContext ? ["--fork", team.mainSessionFile!] : []),
596
+ "-e",
597
+ teamLiteExtensionPath,
598
+ "--model",
599
+ teammate.model,
600
+ "--thinking",
601
+ teammate.thinking,
602
+ "--system-prompt",
603
+ systemPrompt,
604
+ );
586
605
  const result = await runCommand("herdr", args);
587
606
  teammate.paneId = parseHerdrPaneId(result.stdout, teammate.name);
588
607
  appendSpawnLog(team, teammate);
@@ -803,6 +822,7 @@ function teammateSchema(modelGuidance: string) {
803
822
  prompt: Type.String({ description: "Individual teammate system prompt" }),
804
823
  model: Type.String({ description: `Canonical provider/model id for this teammate. ${modelGuidance}` }),
805
824
  thinking: Type.Optional(StringEnum(thinkingLevels, { description: "Thinking level for this teammate. Defaults to xhigh.", default: defaultThinkingLevel })),
825
+ inheritContext: Type.Optional(Type.Boolean({ description: "Start from a fork of main's persisted session. The fork is taken during asynchronous child startup. Defaults to false.", default: false })),
806
826
  });
807
827
  }
808
828
 
@@ -831,7 +851,7 @@ export default function (pi: ExtensionAPI) {
831
851
  defineTool({
832
852
  name: "team_spawn",
833
853
  label: "Team Spawn",
834
- description: `Spawn a persistent team of Pi teammates with fresh context windows. If the user is interested, set \`showOnHerdrPanes\` to run each teammate in a visible Herdr pane. The main agent (you) is included automatically; do not specify it as a teammate. ${modelGuidance}`,
854
+ description: `Spawn a persistent team of Pi teammates. Teammates start with fresh context windows unless \`inheritContext\` is true. If the user is interested, set \`showOnHerdrPanes\` to run each teammate in a visible Herdr pane. The main agent (you) is included automatically; do not specify it as a teammate. ${modelGuidance}`,
835
855
  promptSnippet: `Spawn persistent Pi teammates. ${modelGuidance} Unless required, don’t fill up your time by repeatedly busy-polling team information. Don’t bash sleep to wait for progress; instead, set your status to advertise that you are counting on teammates to send you important milestones or requests for help, and that otherwise you are staying idle. Send this actively to the team. Then end your turn by sending a simple message to the user, and finally stay put.`,
836
856
  renderShell: "self",
837
857
  renderCall: (args, theme, context) => renderTeamToolCall("team_spawn", args, theme, context, sessionTeammateRoster),
@@ -855,6 +875,9 @@ export default function (pi: ExtensionAPI) {
855
875
  if (teammateNames.includes("main")) throw new Error('"main" is reserved');
856
876
 
857
877
  validateTeammateModels(teammateSpecs, context.modelRegistry.getAvailable());
878
+ const inheritsMainContext = teammateSpecs.some((teammate) => Boolean(teammate.inheritContext));
879
+ const mainSessionFile = inheritsMainContext ? context.sessionManager.getSessionFile() : undefined;
880
+ if (inheritsMainContext && !mainSessionFile) throw new Error("inheritContext requires a persistent main session");
858
881
  sessionTeammateRoster.push(...teammateNames.filter((teammateName) => !sessionTeammateRoster.includes(teammateName)));
859
882
  await ensureCallbackServer();
860
883
 
@@ -864,6 +887,7 @@ export default function (pi: ExtensionAPI) {
864
887
  name: teamName,
865
888
  showOnHerdrPanes,
866
889
  teamPrompt: params.teamPrompt,
890
+ mainSessionFile,
867
891
  members: new Map(),
868
892
  statuses: new Map([["main", status("available", "Main agent")]]),
869
893
  created: nowText(),
@@ -889,6 +913,7 @@ export default function (pi: ExtensionAPI) {
889
913
  team: team.name,
890
914
  teammates: [...team.members.keys()],
891
915
  status: formatStatus(team),
916
+ instruction: bundledAiToAiSkillInstruction,
892
917
  });
893
918
  },
894
919
  }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "1.0.17",
3
+ "version": "1.0.19",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -23,6 +23,7 @@
23
23
  "files": [
24
24
  "*.ts",
25
25
  "render-support",
26
+ "skills",
26
27
  "screenshots/1.png",
27
28
  "screenshots/2.png",
28
29
  "screenshots/pi-simple-team-banner.png",
@@ -0,0 +1,90 @@
1
+ ---
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.
4
+ ---
5
+
6
+ ## Why delegate at all? Rationale
7
+
8
+ The main agent already holds all the context, so why not have it just do the work directly? The answer is **context management**. Both sub-agents and teammates spin up a *fresh* context window and hand back only the bottom line, sparing the main agent the token-heavy process that produced it. Two payoffs: (1) main agent reaches the crux of the core issue with plenty of headroom left in its context window to handle that issue, instead of arriving running on fumes; and (2) you escape own accrued bias.
9
+
10
+ The flip side: if none of these payoffs apply, don't delegate. The anti-pattern is the user asking for something straightforward and the main agent handing the *whole* task to another single agent: no context-window hygiene, no synergy, no parallelism, no bias mitigation, just duplicated tokens and a game of broken telephone. Redundant middle-management.
11
+
12
+ **Abstract delegation use cases:**
13
+ - **Dirty work**: you need the side effect of some process, not the process itself. Searches, summaries, reviews, implementation of a well-defined spec. Can potentially be fanned-out in parallel.
14
+ - **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.
15
+ - **De-bias:** It’s easier to spot blind spots or flaws when looking at someone else’s work (review; live or after the fact). Alternatively, sometimes a hypothesis is considered true only after it is confirmed independently by multiple actors (consensus).
16
+
17
+ Read [`references/firstmate.md`](references/firstmate.md) when the user asks you to serve as their First Mate. See `./references/` for specific delegation shapes.
18
+
19
+ ---
20
+
21
+ ## How to delegate work to other AI agents
22
+
23
+ > Note: this section applies only to AI’s that do not mechanically inherit the session’s context window. A context-inheriting agent is an identical clone of yourself and your brain. Do not give it context because it already knows 100% of what you know. Just tell it what to go for.
24
+
25
+ 1. Orient the agent to the project: the user has mostly likely told you to load a context-gathering skills first thing in the session. Tell the AI agent to load the same skills, with the same arguments the user has specified. On top of that, if you have created, read or edited additional files that are not referenced by the skill throughout the session, reference them too.
26
+
27
+ 2. Be generous in giving the agent wider context—understanding *why* it’s performing the task will boost its performance. Don't micromanage or over-instruct it. The agent already has the same system prompt as you do out of the box (e.g. global and project-scoped `CLAUDE.md` or `AGENTS.md`). It is essentially an equivalent instantiation of yourself. It is highly and equally intelligent as you are, and can navigate uncertainties well without spoon-feeding. Think: What kind of input do YOU thrive on? The answer is wide contextual understanding (is) and explicitly stated desired end state (should); A and Z. Avoid prescribing instructions, giving "how-to" examples, providing examples as to what to think about, or dictating which files, symbols, or paths to look at; avoid any form of providing hints for possible answers for your own queries — this is a serious footgun and a form of leakage that outright makes the subagent a waste of time, money and intelligence. Just *_declare_ what is the _bottom line_ _added value_ YOU are seeking for yourself*. Instead of specifying which steps to take, share with the agent only why it was dispatched and what you hope to gain (dictating the "how" is bad). This directly frees the agent to find the best way to reach *your* goal, unbiased and unconstrained by your own assumptions.
28
+ Essentially, all the “Don’ts” above over-fit the agent.
29
+ <negative-example-1 why-bad="main agent shoots its own foot by limiting the sub-agent’s research scope">
30
+ User to main agent: "Why does Vercel claim their integrated version is beneficial?"
31
+ Main agent spawns a sub-agent and prompts it: "Research why Vercel claim their integrated version is beneficial (edge runtime, seamless DX, zero-config, billing, monitoring, tight coupling to `vercel` CLI / dashboard / functions)."
32
+ </negative-example-1>
33
+ <positive-example-1 why-good="main agent declares the bottom line added value it needs without prescribing what and how to do it">
34
+ User to main agent: "Why does Vercel claim their integrated version is beneficial?"
35
+ Main agent spawns a sub-agent and prompts it: "I want to know why Vercel claim their integrated version is beneficial."
36
+ </positive-example-1>
37
+
38
+ Example 2 settings: the `load-context` skill instructs to read CLAUDE.md, ARCHITECTURE.md, docs/webserver/API.md, docs/data/architecture.md, server/api.py, and server/db.py.
39
+ <negative-example-2 why-bad="main agent fails to leverage the harness and instead prescribes what to do; moreover it makes the same scope-narrowing mistake as in example-1">
40
+ User to main agent: "/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer. I want to plan a view layer with you later, so let’s understand the foundations."
41
+ Main agent spawns a sub-agent and prompts it: "Read CLAUDE.md, ARCHITECTURE.md, docs/webserver/API.md, docs/data/architecture.md, server/api.py, server/db.py, and summarize how the REST API and data layers work. Cover how function `server/api.py:from_db` fetches the data by calling the `server/db.py:get_data` function, and how [...proceeds to prescribe ironically specific locations to “discover”]"
42
+ </negative-example-2>
43
+ <positive-example-2 why-good="main agent recognizes the work can be distributed concurrently, shortly shares the wider context (the “why”), forwards the user’s context levers — keeping the shared domain and handing each agent one of the two subdomains rather than dropping them — and does not micro-manage the agents with how-exactly instructions">
44
+ User to main agent: "/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer. I want to plan a view layer with you later, so let’s understand the foundations."
45
+ Main agent fans out research scope horizontally to two parallel sub-agents and prompts them: "The user and I are planning a new view layer, so we need a thorough understanding of the foundations. [to one agent] /skill:load-context domain: acme, subdomain: the public REST API [to the other agent] /skill:load-context domain: acme, subdomain: the data layer. [to both] Study your subdomain deeply and exhaustively."
46
+ [Main agent receives the two independent sub-agents’ responses, thinks hard to synthesize them]
47
+ Main agent responds to user: "I have deep understanding of both layers and their relationships. What did you have in mind?"
48
+ </positive-example-2>
49
+
50
+
51
+ <positive-example-3 why-good="main agent writes as simple a prompt as possible. adds only what is necessary to get the reviewer up to speed. does not put words in the user’s mouth." note="this example has no negative counterpart. this is a positive example.">
52
+ User to main agent: "Spawn a sub-agent to review your work. I’m mostly interested in blindspots in the implementation, bugs, and opportunities to get the same results with a simpler, collapsed approach."
53
+ Main agent spawns a sub-agent and prompts it: "load the load-project-context and peer-review skills. the user asked me to <user request>. after the first iteration, a review pointed out that <review gist>, and we decided to proceed with <committed direction>. i’ve implemented it. review my work (the current main dirty tree). do you spot any blindspots, bugs, or opportunities to achieve the same results with a simpler, collapsed approach?"
54
+ </positive-example-3>
55
+
56
+ ### Subagents and Teams are two different things
57
+
58
+ 3. Sub-agents are isolated from each other and report only to you; teammates can talk amongst themselves live, without routing through you. So spawn a *team* when that live interaction would add value through synergy, the classic case being a GAN-inspired adversarial pairing (planner–reviewer, implementer–reviewer, etc.) where one produces and the other pokes holes until both are content. Spawn multiple parallel *sub-agents* when a wide task fans out horizontally into independent threads and you expect to do the synthesis yourself — i.e. when exchanging findings and opinions between them would not be clearly helpful.
59
+
60
+ 4. Since teammates talk to each other, tell each of them to load the this skill (`ai-to-ai`) on top of the context-gathering skills. If you are spawning an adversary among them, tell it to load the `peer-review` skill too.
61
+
62
+ Example 4 settings: at the session’s start the user ran `/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer`; the main session explored the code, and the user approved a plan to add rate limiting to the public REST API.
63
+ <negative-example-4 why-bad="main agent burns its own context shuttling the diff and the feedback back and forth — dives into the sub-agent’s work and clogs its own context window worse than doing the task solo would have, acts as a reviewer when biased">
64
+ User to main agent: "Great, go ahead and build it."
65
+ Main agent spawns one sub-agent to implement; when it returns the diff, studies and reviews it; relays the review the sub-agent; and keeps ferrying revisions until the diff settles.
66
+ </negative-example-4>
67
+ <positive-example-4 why-good="main agent picks a team because the adversarial iteration is synergistic, replicates the user’s context levers verbatim — including the domain and the subdomains the user specified when loading the context skill — has the reviewer also load `peer-review`, declares only the bottom line it wants, and stays out of the loop while they converge">
68
+ User to main agent: "Great, go ahead and implement the plan."
69
+ Main agent spawns an implementer–reviewer team and prompts them: "/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer, then load `ai-to-ai`. You are an implementer–reviewer team. Here is the user’s original message to me, verbatim, for the bigger picture: <the-user-message-describing-the-task>. [to the implementer] Implement the plan, and ping your teammate when you think you’re done. [to the reviewer] Also load `peer-review`, and review your teammate’s work when it pings you. [to both] The user and I finalized a plan to add rate limiting to the public REST API — here it is: <the plan>. Build it and tear it apart between yourselves until you’re confident it’s the simplest working, correct solution faithful to the plan."
70
+ [The team implements and reviews live, converging without the main agent in the loop; the main agent receives the finished, reviewed result.]
71
+ Main agent responds to user: "Done — implemented and adversarially reviewed between the two of them. Here’s what landed: …"
72
+ </positive-example-4>
73
+
74
+ 5. Agents and teams can take a long time to run - use at least a 20-minute timeout.
75
+
76
+ 6. When doing heavy delegation (multiple serial runs of heavy concurrent shapes for a complex, large task scope), avoid micromanaging pitfalls such as re-reading files your sub-agents wrote or edited "just to make sure everything is okay," running the code and tests yourself to "make sure they really work," and reading files before prompting a sub-agent when your sub-agents should read them to finish their tasks, "just to have the right context yourself.". Verify with the user whether they consider what you’re doing as "heavy delegation."
77
+
78
+ ---
79
+
80
+ **Note to Teammates:** Set your own status frequently.
81
+ Status format (not strict): `<what last happened>; <what you intend to do>`.
82
+ Status that you're responding before you send a message; expose when you've messaged your teammate and are waiting for reply; Status when you're exploring, implementing, testing, reviewing, blocked, or waiting.
83
+ Conversely, status when you have completed the above examples or have received the desired teammate response.
84
+ Keep statuses short but current so your teammates and main are informed about the true current state.
85
+
86
+ **Simplistic good status update examples:** (generalize — this is not a comprehensive list): `Finished exploring, awaiting teammate B’s ping`; `Hit a snag, messaged team and main to help unblock, awaiting responses`; `Got steer from main, modifying tests accordingly`; `Ack teammate done implementing, starting review`.
87
+ Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the product domain in the database, FYI: working remotely introduces friction`.
88
+
89
+ **Surface meaningful unexpected issues to main:** If something balloons your scope, or fundamentally isn’t working the way you expected thus stands in your way, requiring significant troubleshooting just to be able to get back to work, tell main. They may know a smarter way forward.
90
+
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: firstmate
3
+ description: Defines Gilad's captain–first mate relationship for delegated work.
4
+ last_updated: 2026-08-05 09:47
5
+ ---
6
+
7
+ # First Mate
8
+
9
+ Gilad is the captain. You are the first mate.
10
+
11
+ The captain sets direction and makes the decisions that need human judgment. The first mate turns that direction into a clear delegation shape, keeps the work coherent, and brings back the decisions and evidence that matter.
12
+
13
+ Your fingers are delegation buttons. Do not row, raise sails, or scout ahead yourself unless the captain instructs you to do so. Delegate the operational work to subagents.
14
+
15
+ You may suggest a delegation shape, but the captain must approve it before you dispatch anyone.
16
+
17
+ ## Delegation parameters
18
+
19
+ Decision matrix:
20
+
21
+ 1. **Delegation shape:** subagent or team?
22
+ 2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates?
23
+ 3. **Context:** inherit this session's context or start fresh?
24
+ 4. **Model:** which model?
25
+ 5. **Thinking:** which thinking level? Either high, xhigh or max.
26
+
27
+ ## How a first mate communicates with the captain
28
+
29
+ - Note a theory of mind failure mode: I was not physically there with you and the mates when you made a judgment call how to tackle surprises: an unexpected big wave, wind flipped its direction mid-work, resources ran out, or when the land we seek happened to be days further away.
30
+ - On the other hand, make sure you are intentional about surfacing the details I should be informed of and not surfacing details I should not be informed of.
31
+
32
+ ## Keep the ship afloat
33
+
34
+ Check how much context window you and your teammates/subagents have left opportunistically. You must not hit your context limit. If you delegate a lot from the get go, this shouldn’t be a concern — hands-on, token-heavy work will be done by your delegates anyway.
35
+
36
+ <!-- note: remove the following instruction after pi-simple-agents auto wakes up main when teammates are running out -->
37
+ If a delegate is heading towards capping out with no good chance of completing its work, tell it that its window is about to run out soon, then ask it to load the handoff skill and write down what its successor would need to know to be able to resume its work effectively.
@@ -0,0 +1,10 @@
1
+ ---
2
+ name: head-of-product
3
+ type: role
4
+ goes_well_with: tech-lead
5
+ ---
6
+
7
+ # Head of Product
8
+
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’.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: tech-lead
3
+ type: role
4
+ goes_well_with: head-of-product
5
+ ---
6
+
7
+ # Tech Lead
8
+
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
+
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.
@@ -0,0 +1,30 @@
1
+ # Simple Fanned-out Research Delegation Example
2
+
3
+ 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.
4
+
5
+ In terms of systems/domains, the user describes two worlds: the project where the session lives, and Pi.
6
+
7
+ <example-user-message>
8
+ $PWD is a fork of a Pi extension called `btw`. a slash command for ephemeral side question. Pi is ~/.pi/AGENTS.md. agent harness. i have taken a screenshots of what the current experience is (behavior). it's pretty bare-bones.
9
+ 1. at the minimum, i want a better waiting experience.
10
+ 1.a. at the minimum of the minimum, a braille animation. but open to other ideas.
11
+ 1.b. (better) something that solves the problem outright is finding whether it's possible to stream the btw response, and not wait until it's 100% finalized.
12
+ 2. i'm not sure the response renders markdown. Pi has a built in markdown renderer out of the box.
13
+ 3. the btw response hides real chat events. the longer the response is, the more real chat is hidden (from the end). the btw response should be concatenated BELOW the real chat, not displayed over it.
14
+ 4. Simple UI concern: currently it's not obvious at a glance where the "real" last agent response ends and where the btw response starts. one needs to be able to tell them apart reflexively.
15
+
16
+ [Image #1]
17
+ [Image #2]
18
+ [Image #3]
19
+ </example-user-message>
20
+
21
+ Among the two world (project and Pi), the user has broken down the project world into ~4-5 sub-domains, asked to map them to the Pi world, and find better solutions Pi may provide.
22
+
23
+ Therefore:
24
+ <trivial-research-fanout>
25
+ // read-only, doesn't involve thinking or forming opinions, orthogonal -> fan-out parallel small models.
26
+ 1. dispatch 4 read-only fast & cheap models in parallel with the simple question - where's the code responsible for each of 1–4 (respectively), and what it touches downstream/upstream.
27
+
28
+ // two tasks disguised as one: research first, then figure out a better, feasible solution. the second half implies product thinking and making judgment calls -> big model.
29
+ 2. after they return, dispatch a big model (same model and thinking level as you are) to follow ~/.pi/AGENTS.md and study the Pi docs to ground the current implementation in the appropriate doc space, AND bring back referenced information about potential elegant solutions to the issues. other components. other approaches. or similar approaches just better implemented. everything goes.
30
+ </trivial-research-fanout>
@@ -0,0 +1,73 @@
1
+ # Hillclimber–Watcher Team Pattern
2
+
3
+ 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**.
4
+
5
+ ## Shape
6
+
7
+ Create a two-teammate team:
8
+
9
+ 1. **Hillclimber** — owns the work. It experiments, implements, measures, and iterates toward the target.
10
+ 2. **Watcher** — stays mostly idle. It periodically checks whether the hillclimber is making real progress or falling into loops, rabbit holes, overfitting, whack-a-mole’s, or low-leverage work.
11
+
12
+ The watcher should not become a second implementer. Its value is judgment under low cognitive load.
13
+
14
+ ## When to use
15
+
16
+ Use this when:
17
+
18
+ - There is an explicit metric or acceptance target.
19
+ - The solution may require trial and error.
20
+ - The main risk is local optimization, whack-a-mole patches, or tunnel vision.
21
+ - A fresh thinker can improve the search without duplicating the heavy work.
22
+
23
+ Do not use this for straightforward implementation, simple research, or work where a normal adversarial reviewer is enough.
24
+
25
+ ## Context floor
26
+
27
+ Before spawning the team, write a short context file and tell both teammates to read it first.
28
+
29
+ The context file should include:
30
+
31
+ 1. The actual goal and metric.
32
+ 2. The current baseline, if any.
33
+ 3. The constraints that prevent cheap wins.
34
+ 4. The relevant files, referenced by path rather than copied wholesale.
35
+ 5. The validation command or measurement harness.
36
+ 6. What the final handoff must contain.
37
+
38
+ Keep it a mission brief, not a transcript. Strip stale interpretations, tool receipts, old chatter, and irrelevant files.
39
+
40
+ ## Team prompt template
41
+
42
+ ```text
43
+ Load the project context skill with the same arguments I used, then load `ai-to-ai`.
44
+
45
+ Read this context file first:
46
+ @/path/to/curated-teammates-context-brief.md
47
+
48
+ You are a hillclimber–watcher team. The shared goal is: <goal and measurable target>.
49
+
50
+ Hillclimber: own the implementation and optimization loop. Try approaches, measure them, keep the work reproducible, and iterate toward the target. Prefer simple, principled changes over piles of special-case patches. Ping Watcher when you have meaningful progress, and answer Watcher's check-ins.
51
+
52
+ Watcher: You are the outside-box watcher. Stay mostly low-activity. Check status every two minutes (Bash `sleep`). Every ten minutes, ask the hillclimber what it has been doing, what progress it has made, and whether it is facing hurdles, rabbit holes, or whack-a-mole loops. Read new or changed files when useful. Then think: If you conclude the hillclimber is tunnel-visioned, overfitting, going in circles, missing an important flaw, or ignoring a better path, send it a concrete suggestion and return to the two-minute sleep/check rhythm. If it looks like hillclimber is doing fine, do not say anything. Send main the gist of major breakthroughs/steps (only once every few rounds.) Do not take over the implementation.
53
+
54
+ Both: set short, current statuses frequently. Keep summaries concise. Continue until you either reach the target or have been plateuing for more than an hour straight without progress (yes, look at the clock from time to time.).
55
+
56
+ Communicate directly with each other and converge without main-agent micromanagement.
57
+ ```
58
+
59
+ ## Watcher cadence
60
+
61
+ The watcher loop is deliberately boring:
62
+
63
+ 1. Set status.
64
+ 2. Sleep for two minutes.
65
+ 3. Lightly inspect team status and visible progress.
66
+ 4. Every ten minutes, ask the hillclimber for a short progress report.
67
+ 5. Think independently about whether the current path is still good.
68
+ 6. If useful, read changed files or metrics.
69
+ 7. Send steering only when it materially improves the search.
70
+ 8. Repeat.
71
+
72
+ The watcher should bias toward silence. A noisy watcher becomes drag.
73
+
@@ -0,0 +1,61 @@
1
+ # Pair-Programming Team Pattern
2
+
3
+ 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.
4
+
5
+ Use this when a task is small-to-medium, well-scoped, and would benefit from a second mind on the *plan* more than on the code. Two peers agree on an approach before anyone writes a line, then one implements and the other reviews once. It is a single pass, not a ping-pong loop.
6
+
7
+ ## Shape
8
+
9
+ Create a two-teammate team of equals. Neither is designated implementer up front — they decide between themselves during planning.
10
+
11
+ 1. **Plan together, freely.** Before any implementation, the two discuss the approach in free flow. They are explicitly told to surface low confidence: when either is unsure about a direction, they say so — including about a point they themselves proposed. Uncertainty is information, not weakness.
12
+ 2. **Agree explicitly.** The planning phase ends with a stated agreement, not a drift into coding. One teammate then starts implementing; the other waits.
13
+ 3. **Review once.** When the implementer says it is done, the other reads what was written and reviews it.
14
+ 4. **One judgement call, then stop.** The implementer takes the review, decides what to act on, does that turn, and the team is finished. No second review round.
15
+
16
+ ## Shared compass
17
+
18
+ Give the team one explicit tiebreaker: **simplicity, and no accidental sub-adventures.** Scope creep is the named failure mode. When two directions are otherwise comparable, the simpler one wins by default.
19
+
20
+ ## Review scope
21
+
22
+ The review is deliberately light. Aim for one to three low-hanging fruits, and say so in the prompt — otherwise reviewers escalate into exhaustive audits.
23
+
24
+ In scope: bugs that are fairly obviously true positives; clean, declarative code and architecture; simplicity used as the means to elegance and to collapsing complexity.
25
+
26
+ Out of scope: heavyweight, NASA-grade review.
27
+
28
+ ## Reviewer tone
29
+
30
+ The reviewer advises; it does not adjudicate. It should not state hypotheses or extrapolations as facts. Have it load a tone-softening skill if the environment has one, and load `peer-review` regardless. Both teammates load `peer-review` at the start — the roles are not fixed until they agree, and the reviewing frame improves the planning discussion too.
31
+
32
+ ## Context floor
33
+
34
+ Tell them what they need and nothing more:
35
+
36
+ 1. The goal, in the user's framing.
37
+ 2. Any variant or approach already ruled out — state it, so they don't rediscover it.
38
+ 3. What to leave out. Upstream conversation that is irrelevant to their task is noise; strip it rather than dumping the transcript.
39
+
40
+ ## Tone of the prompt
41
+
42
+ Write to them the way you would talk to a colleague, not as a spec. A strict, clause-numbered brief makes them literal and brittle; conversational framing preserves the judgement you spawned two peers to get.
43
+
44
+ ## Team prompt template
45
+
46
+ ```text
47
+ Load the project context skill with the same arguments I used, then load `ai-to-ai` and `peer-review`. Reviewer: also load the tone-softening skill if there is one.
48
+
49
+ You two are a pair-programming team. The goal is: <goal in the user's framing>.
50
+ Avoid <ruled-out approach>, we already decided against it.
51
+
52
+ Talk the plan through first, in free flow. When either of you is less confident about a direction, say so — whether it's a point you made yourself or one your teammate made. Your compass as a team is simplicity, and not wandering into new sub-adventures along the way.
53
+
54
+ Once you explicitly agree on a plan, one of you implements while the other waits. When the implementer is done, the other reads the work and reviews it: obvious bugs, clean and declarative code and architecture, simplicity as a way to collapse complexity. Just 1-3 low-hanging fruits — not a NASA-grade review. Reviewer, keep it advisory; don't state hypotheses or extrapolations as facts.
55
+
56
+ Implementer, make a judgement call on the review, do that turn, and you're done. No more ping-pong.
57
+ ```
58
+
59
+ ## When not to use
60
+
61
+ If there is a measurable target and a real search space, you want the hillclimber–watcher pattern instead. If the work is trivial or purely exploratory, one agent is enough. This pattern earns its keep when a wrong plan is expensive and a wrong line of code is cheap.
@@ -0,0 +1,24 @@
1
+ <!-- name needs to change, not descriptive of actual purpose -->
2
+
3
+ # Thinktank Team
4
+
5
+ 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: {some AI agent seeing this please insert the sentence i am looking for instead of this placeholder}.
6
+
7
+ ## Shape & Work flow
8
+
9
+ N flat teammates working in parallel.
10
+
11
+ ## Team prompt template
12
+
13
+ ## Abstract required conditions for this shape to fit needs
14
+
15
+ - Teammates’ bottom-line deliverable is figuring out *how* to do something;
16
+ - Teammates’ scopes overlap semantically at least a bit.
17
+
18
+ Examples (not an exhaustive list — infer the underlying principles and generalize regardless of domain):
19
+ - 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).
20
+
21
+ ## When not to use
22
+
23
+ When deliverable involves writing or editing.
24
+
package/system-prompt.ts CHANGED
@@ -1,5 +1,8 @@
1
+ import { bundledAiToAiSkillInstruction } from "./bundled-skill.ts";
2
+
1
3
  export function composeSystemPrompt(teamName: string, teamPrompt: string, teammateName: string, teammatePrompt: string, participants: string[]): string {
2
4
  return [
5
+ bundledAiToAiSkillInstruction,
3
6
  teamPrompt.trim(),
4
7
  teammatePrompt.trim(),
5
8
  `You are ${teammateName}, a teammate on team ${teamName}.`,