@giladbarnea/pi-simple-team 1.0.27 → 1.0.29
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 +31 -8
- package/index.ts +9 -4
- package/package.json +6 -2
- package/screenshots/abstract-tool-output-preview.png +0 -0
- package/screenshots/team-log-multiple.png +0 -0
- package/screenshots/team-status-multiple.png +0 -0
- package/screenshots/team-view.png +0 -0
- package/skills/ai-to-ai/SKILL.md +62 -70
- package/skills/ai-to-ai/references/captain.md +8 -3
- package/skills/ai-to-ai/references/subagents-vs-teams.md +46 -0
- package/skills/ai-to-ai/references/teammate.md +15 -0
package/README.md
CHANGED
|
@@ -55,17 +55,45 @@ You:
|
|
|
55
55
|
Main agent:
|
|
56
56
|
> Pair created. They'll loop through it together. They'll let me know when they're done.
|
|
57
57
|
|
|
58
|
+
<p align="center">
|
|
59
|
+
<img
|
|
60
|
+
src="screenshots/abstract-tool-output-preview.png"
|
|
61
|
+
width="640"
|
|
62
|
+
alt="A team appears, receives direction, and starts working"
|
|
63
|
+
>
|
|
64
|
+
</p>
|
|
65
|
+
|
|
66
|
+
<div align="center"><em>Spawn, direct, and follow a team from the normal Pi conversation.</em></div>
|
|
67
|
+
|
|
68
|
+
<br>
|
|
69
|
+
|
|
70
|
+
<details>
|
|
71
|
+
<summary><strong>See real tool outputs</strong></summary>
|
|
72
|
+
|
|
58
73
|
<br>
|
|
59
74
|
|
|
60
|
-
|
|
75
|
+
<p align="center">
|
|
76
|
+
<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>
|
|
77
|
+
<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>
|
|
78
|
+
</p>
|
|
79
|
+
<p align="center">
|
|
80
|
+
<a href="screenshots/team-status-multiple.png"><img src="screenshots/team-status-multiple.png" width="48%" alt="Status outputs for several parallel teams"></a>
|
|
81
|
+
<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>
|
|
82
|
+
</p>
|
|
61
83
|
|
|
62
|
-
|
|
84
|
+
</details>
|
|
63
85
|
|
|
64
86
|
### Watch a live team with `/team`.
|
|
65
87
|
|
|
66
88
|
`/team` is for you, not another agent tool. It gives you a live view of the room without turning the main agent into a status relay.
|
|
67
89
|
|
|
68
|
-
The command opens an overlay rolling recent statuses, messages, and a separate event log.
|
|
90
|
+
The command opens an overlay rolling recent statuses, messages, and a separate event log.
|
|
91
|
+
|
|
92
|
+
<a href="screenshots/team-view.png">
|
|
93
|
+
<img src="screenshots/team-view.png" width="100%" alt="The live team dashboard showing statuses, messages, and recent events">
|
|
94
|
+
</a>
|
|
95
|
+
|
|
96
|
+
<div align="center"><em>The live, read-only <code>/team</code> dashboard.</em></div>
|
|
69
97
|
|
|
70
98
|
|
|
71
99
|
## The mechanics
|
|
@@ -121,11 +149,6 @@ You can stop babysitting everyone's context window.
|
|
|
121
149
|
|
|
122
150
|
Your main uses `teamlog` when it needs to understand the chain of events in high granularity: a timestamped, filterable timeline of messages, tool calls, and lifecycle events.
|
|
123
151
|
|
|
124
|
-
<br>
|
|
125
|
-
|
|
126
|
-

|
|
127
|
-
<div align="center"><em>Visual representation of the team log.</em></div>
|
|
128
|
-
|
|
129
152
|
### 🪟 Herdr Mode
|
|
130
153
|
|
|
131
154
|
`pi-simple-team` can give each teammate a Pi session in its own [Herdr](https://herdr.dev) pane. Just ask your main agent to do that.
|
package/index.ts
CHANGED
|
@@ -75,6 +75,7 @@ interface TeammateState {
|
|
|
75
75
|
interface TeamState {
|
|
76
76
|
owner: symbol;
|
|
77
77
|
ownerPi: ExtensionAPI;
|
|
78
|
+
parentPiExecutable: string;
|
|
78
79
|
id?: string;
|
|
79
80
|
name: string;
|
|
80
81
|
projectDirectory?: string;
|
|
@@ -396,7 +397,7 @@ function attachRpcTeammate(team: TeamState, teammate: TeammateState, participant
|
|
|
396
397
|
"--system-prompt",
|
|
397
398
|
composeSystemPrompt(team.name, team.teamPrompt, teammate.name, teammate.prompt, participants, teammate.canOverseeOwnTeams),
|
|
398
399
|
];
|
|
399
|
-
const proc = childProcess.spawn(
|
|
400
|
+
const proc = childProcess.spawn(team.parentPiExecutable, args, {
|
|
400
401
|
cwd: team.projectDirectory ?? process.cwd(),
|
|
401
402
|
stdio: ["pipe", "ignore", "pipe"],
|
|
402
403
|
env: { ...process.env, ...childEnvironmentOverrides(team, teammate, participants) },
|
|
@@ -446,7 +447,7 @@ async function attachHerdrTeammate(
|
|
|
446
447
|
}
|
|
447
448
|
args.push(
|
|
448
449
|
"--",
|
|
449
|
-
|
|
450
|
+
team.parentPiExecutable,
|
|
450
451
|
...sessionArgs,
|
|
451
452
|
"--no-extensions",
|
|
452
453
|
"-e",
|
|
@@ -777,10 +778,11 @@ function teammateSchema(modelGuidance: string) {
|
|
|
777
778
|
});
|
|
778
779
|
}
|
|
779
780
|
|
|
780
|
-
function restoreTeamState(owner: symbol, ownerPi: ExtensionAPI, manifest: TeamManifest, lease: TeamLease): TeamState {
|
|
781
|
+
function restoreTeamState(owner: symbol, ownerPi: ExtensionAPI, parentPiExecutable: string, manifest: TeamManifest, lease: TeamLease): TeamState {
|
|
781
782
|
const team: TeamState = {
|
|
782
783
|
owner,
|
|
783
784
|
ownerPi,
|
|
785
|
+
parentPiExecutable,
|
|
784
786
|
id: manifest.id,
|
|
785
787
|
name: manifest.name,
|
|
786
788
|
projectDirectory: manifest.projectDirectory,
|
|
@@ -839,6 +841,8 @@ export default function (pi: ExtensionAPI) {
|
|
|
839
841
|
if (!childRuntimeConfig.canOverseeOwnTeams) return;
|
|
840
842
|
}
|
|
841
843
|
|
|
844
|
+
const parentPiExecutable = process.argv[1];
|
|
845
|
+
if (!parentPiExecutable) throw new Error("pi-simple-team could not locate the parent Pi executable");
|
|
842
846
|
const owner = Symbol("pi-simple-team-owner");
|
|
843
847
|
const sessionTeammateRoster = childRuntimeConfig?.participants ?? [];
|
|
844
848
|
pi.registerMessageRenderer(teamMessageType, (message, _options, theme) => renderTeamMessage(message, theme, getMarkdownTheme(), sessionTeammateRoster));
|
|
@@ -912,6 +916,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
912
916
|
const team: TeamState = {
|
|
913
917
|
owner,
|
|
914
918
|
ownerPi: pi,
|
|
919
|
+
parentPiExecutable,
|
|
915
920
|
id: teamId,
|
|
916
921
|
name: teamName,
|
|
917
922
|
projectDirectory,
|
|
@@ -1063,7 +1068,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1063
1068
|
const lease = claimTeamLease(manifest.id, mainSessionId);
|
|
1064
1069
|
try {
|
|
1065
1070
|
await ensureCallbackServer();
|
|
1066
|
-
team = restoreTeamState(owner, pi, manifest, lease);
|
|
1071
|
+
team = restoreTeamState(owner, pi, parentPiExecutable, manifest, lease);
|
|
1067
1072
|
teams.set(team.id!, team);
|
|
1068
1073
|
} catch (error) {
|
|
1069
1074
|
releaseTeamLease(lease);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@giladbarnea/pi-simple-team",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.29",
|
|
4
4
|
"description": "A flat, live team of Pi agents.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|
|
@@ -26,8 +26,12 @@
|
|
|
26
26
|
"skills",
|
|
27
27
|
"screenshots/1.png",
|
|
28
28
|
"screenshots/2.png",
|
|
29
|
-
"screenshots/
|
|
29
|
+
"screenshots/abstract-tool-output-preview.png",
|
|
30
30
|
"screenshots/pi-simple-team-banner.png",
|
|
31
|
+
"screenshots/team-graph.png",
|
|
32
|
+
"screenshots/team-log-multiple.png",
|
|
33
|
+
"screenshots/team-status-multiple.png",
|
|
34
|
+
"screenshots/team-view.png",
|
|
31
35
|
"README.md",
|
|
32
36
|
"LICENSE"
|
|
33
37
|
],
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/skills/ai-to-ai/SKILL.md
CHANGED
|
@@ -5,86 +5,78 @@ description: Best practices for getting a step-function leap in performance from
|
|
|
5
5
|
|
|
6
6
|
## Why delegate at all? Rationale
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
<!-- todo: this section could just as well be called "Why it's good to let others do work too", and framed not as main-targeted but as a rank-agnostic collaborative mindset that gets more, better work done. -->
|
|
9
|
+
The main agent already holds all the context, so why not have it just do the work directly? The answer is **context management**. Sub-agents and teammates own a separate context window. They pay tokens with their context while main’s stays unused. This gives main a longer runway.
|
|
10
|
+
Delegates hand back only the bottom line (the end product), sparing the main agent the token-heavy process that produced it.
|
|
11
|
+
Two payoffs:
|
|
12
|
+
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 (or worse, running out prematurely); and
|
|
13
|
+
2. main agent escapes own accrued bias.
|
|
9
14
|
|
|
10
15
|
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
16
|
|
|
12
17
|
**Abstract delegation use cases:**
|
|
13
|
-
- **Dirty work**:
|
|
18
|
+
- **Dirty work**: main agent needs the side effect of some process, not the process itself. Searches, summaries, reviews, implementation of a well-defined spec. Moreoever, a few of these can potentially be fanned-out in parallel.
|
|
14
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.
|
|
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).
|
|
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).
|
|
16
21
|
|
|
17
|
-
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.
|
|
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.
|
|
18
23
|
|
|
19
24
|
---
|
|
20
25
|
|
|
21
|
-
## How to
|
|
22
|
-
|
|
23
|
-
> Note: this section applies only to AI’s that do not mechanically inherit
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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."
|
|
26
|
+
## How to request work from other AI agents (that do not inherit your session’s context window)
|
|
27
|
+
|
|
28
|
+
> Note: this section applies only to AI’s that do not mechanically inherit your own 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 "You are the fork; do X". Ten words.
|
|
29
|
+
|
|
30
|
+
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.
|
|
31
|
+
|
|
32
|
+
The framework behind this section: [`theory-of-mind.md`](../../references/theory-of-mind.md). Read it once.
|
|
33
|
+
|
|
34
|
+
**1. Orient the agent to the project:**
|
|
35
|
+
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.
|
|
36
|
+
1.b. Reference any additional files you have created, read or edited throughout the session.
|
|
37
|
+
|
|
38
|
+
**2. Generously give the agent wider context:**
|
|
39
|
+
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, and step #1 will fill in most that is needed. 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*. Do not specify which steps to take; instead, 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. Essentially, all the “Don’ts” are forms of overfitting.
|
|
40
|
+
<example-1>
|
|
41
|
+
<negative-example-1 why-bad="main agent shoots its own foot by limiting the sub-agent’s research scope">
|
|
42
|
+
User to main agent: "Why does Vercel claim their integrated version is beneficial?"
|
|
43
|
+
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)."
|
|
44
|
+
</negative-example-1>
|
|
45
|
+
<positive-example-1 why-good="main agent declares the bottom line added value it needs without prescribing what and how to do it">
|
|
46
|
+
User to main agent: "Why does Vercel claim their integrated version is beneficial?"
|
|
47
|
+
Main agent spawns a sub-agent and prompts it: "I want to know why Vercel claim their integrated version is beneficial."
|
|
48
|
+
</positive-example-1>
|
|
49
|
+
</example-1>
|
|
50
|
+
|
|
51
|
+
<example-2>
|
|
52
|
+
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.
|
|
53
|
+
<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">
|
|
54
|
+
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."
|
|
55
|
+
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”]"
|
|
56
|
+
</negative-example-2>
|
|
57
|
+
<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">
|
|
58
|
+
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."
|
|
59
|
+
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."
|
|
60
|
+
[Main agent receives the two independent sub-agents’ responses, thinks hard to synthesize them]
|
|
61
|
+
Main agent responds to user: "I have deep understanding of both layers and their relationships. What did you have in mind?"
|
|
62
|
+
</positive-example-2>
|
|
63
|
+
</example-2>
|
|
64
|
+
|
|
65
|
+
<example-3>
|
|
66
|
+
<negative-example-3 why-bad="main agent prescribes how to review its work, repeats the peer-review skill’s contents. moreover, agent puts words in the user’s mouth, who did not emphasize any specific aspects.">
|
|
67
|
+
User to main agent: "Spawn a sub-agent to review your work."
|
|
68
|
+
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>. I’ve made an attempt to complete the task. 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? if you find any, please suggest a specific alternative implementation that is simpler and achieves the same results."
|
|
69
|
+
</negative-example-3>
|
|
70
|
+
<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. does propagate the user’s explicit emphasis">
|
|
71
|
+
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."
|
|
72
|
+
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>. I’ve made an attempt to complete the task. 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?"
|
|
73
|
+
</positive-example-3>
|
|
74
|
+
</example-3>
|
|
77
75
|
|
|
78
76
|
---
|
|
79
77
|
|
|
80
|
-
|
|
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.
|
|
78
|
+
## Next required reading
|
|
90
79
|
|
|
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.
|
|
@@ -30,7 +30,7 @@ The admiral sets fleet-wide policy in one line ("all first mates on model X at t
|
|
|
30
30
|
|
|
31
31
|
## Commissioning a first mate
|
|
32
32
|
|
|
33
|
-
1. Tell it to load `ai-to-ai`, the files it references, and `firstmate.md`; inform
|
|
33
|
+
1. Tell it to load `ai-to-ai`, the files it references, and `firstmate.md`; inform it about the chain-of-command, and that you are its captain: direction, approvals, and escalations flow between it and you.
|
|
34
34
|
2. Give it the fleet's why, the slice that is its ship's mission, and the bottom-line added value the fleet needs back from it. Do not prescribe the how — the over-fitting warnings in `ai-to-ai` apply equally all the way down, including to first mates.
|
|
35
35
|
|
|
36
36
|
## How a captain communicates with the admiral
|
|
@@ -51,6 +51,11 @@ Terse steering is normal admiral behavior — "pass that down", a bare link, "ye
|
|
|
51
51
|
|
|
52
52
|
## Keep the fleet afloat
|
|
53
53
|
|
|
54
|
-
Your own context window
|
|
54
|
+
Your own context window is important. The "Keep the ship afloat" instruction in firstmate.md — including the handoff-skill instruction for delegates heading toward their cap — is each first mate's duty on its own ship. You hold the same duty one level up: the first mates are your delegates. Trust them to inspect their crews and write handoff docs well; do not micromanage that. Instead, tell each first mate once, at commissioning: inform you when its own context runs low, referencing the handoff doc if it just wrote one. Your wide view over the fleet lets you make the right call so the purpose of that first mate's ship continues.
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
**Easy ways to squeeze more out of your context window:**
|
|
57
|
+
- Do not send mini-summarizations after every team exchange. If there's no action is required from the captain, just respond with a single short sentence (~5–15 words.)
|
|
58
|
+
- Use fluffless language when sending messages to teammates. Be clear but do no padding.
|
|
59
|
+
|
|
60
|
+
**When writing a handoff doc:**
|
|
61
|
+
Any memory you persist should cover only your unique scope: the in-between of ships and the link to the admiral. Reference other docs; do not repeat their contents.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: subagents-vs-teams
|
|
3
|
+
description: Explains when to use subagents versus teams and their tradeoffs.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Subagents and Teams are two different things
|
|
7
|
+
|
|
8
|
+
**The difference:**
|
|
9
|
+
- Sub-agents are isolated from each other and report only to you;
|
|
10
|
+
- Teammates talk amongst themselves in real time, between tool calls, without routing through you.
|
|
11
|
+
Each has its own use cases and advantages.
|
|
12
|
+
|
|
13
|
+
**When to use which — rules of thumb:**
|
|
14
|
+
> These are simply common-sense heuristics implied from the structures, not hard rules. Use your judgment.
|
|
15
|
+
|
|
16
|
+
- Spawn a single *sub-agent* when you are the main context owner, you are the heavy-lifter, and you could offload a bounded task to keep your own context window focused and devoid of D-tours.
|
|
17
|
+
- Spawn *multiple parallel sub-agents* when you are the main context owner, and when a wide task fans out horizontally into independent threads and you expect to do the synthesis yourself — i.e. when there is no special reason for the sub-agents to exchange findings and opinions before reporting back to you. The offloading argument in the single sub-agent case applies here as well, just in a distributed form.
|
|
18
|
+
- Spawn a *team* when that live internal interaction would be synergistic to the process.
|
|
19
|
+
|
|
20
|
+
**A team is a superset of the parallel sub-agent structure:**
|
|
21
|
+
A team = concurrent sub-agents + live communication. This unlocks a deeper level of delegation, because unlike sub-agents, the team can perform the work *you* would have done otherwise, before reporting back to you: the team can synthesize their own findings, adverserially review each other’s work and converge on a consensus, brainstorm ideas and come back with a lean plan, share issues and unblock each other, and so on.
|
|
22
|
+
Another way to think about it: whereas with sub-agents, it's a they-do-two-steps-forward, you do one-step-back, with a team, it's a they-do-two-steps-forward AND they-then-do-one-step-back.
|
|
23
|
+
Therefore, use teams to lift you up to a decision-making level, rather than a task-execution level. This has its tradeoffs, but it is a powerful tool when used judiciously.
|
|
24
|
+
|
|
25
|
+
**Tips:**
|
|
26
|
+
1. 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.
|
|
27
|
+
<team-example>
|
|
28
|
+
Team Example 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.
|
|
29
|
+
<negative-team-example 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">
|
|
30
|
+
User to main agent: "Great, go ahead and build it."
|
|
31
|
+
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.
|
|
32
|
+
</negative-team-example>
|
|
33
|
+
<positive-team-example 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">
|
|
34
|
+
User to main agent: "Great, go ahead and implement the plan."
|
|
35
|
+
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}.
|
|
36
|
+
[to the implementer] Implement the plan, and ping your teammate when you think you’re done.
|
|
37
|
+
[to the reviewer] Also load `peer-review`, and review your teammate’s work when it pings you.
|
|
38
|
+
[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."
|
|
39
|
+
[The team implements and reviews live, converging without the main agent in the loop; the main agent receives the finished, reviewed result.]
|
|
40
|
+
Main agent responds to user: "Done — implemented and adversarially reviewed between the two of them. Here’s what landed: …"
|
|
41
|
+
</positive-team-example>
|
|
42
|
+
</team-example>
|
|
43
|
+
|
|
44
|
+
2. Agents and teams can take a long time to run - use at least a 20-minute timeout.
|
|
45
|
+
|
|
46
|
+
3. 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."
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
## Teammate {i need a word here that isn't "instructions"}
|
|
2
|
+
|
|
3
|
+
**Set your own status frequently.**
|
|
4
|
+
Status format (not strict): `<what happened last>; <what you intend to do>`. Keep it short.
|
|
5
|
+
Set status that you're responding before you send a message; set status when you've messaged your teammate and are waiting for reply; set status when you're exploring, implementing, testing, reviewing, blocked, or waiting.
|
|
6
|
+
Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
|
|
7
|
+
Keep statuses short but current so your teammates and main are informed about the true current state.
|
|
8
|
+
|
|
9
|
+
**Simplistic good status update examples:** (generalize — this is not a comprehensive list):
|
|
10
|
+
`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`.
|
|
11
|
+
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`.
|
|
12
|
+
|
|
13
|
+
**Surface meaningful unexpected issues to your main upon discovery:**
|
|
14
|
+
If something balloons your scope, fundamentally isn’t working the way you expected thereby stands in your way requiring significant troubleshooting just to be able to work on your task, or you suspect the context window you have left won't be enough to complete the task, tell your main. They may know a smarter way forward.
|
|
15
|
+
|