@giladbarnea/pi-simple-team 1.0.14 → 1.0.16

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.
Files changed (2) hide show
  1. package/README.md +113 -37
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -22,30 +22,87 @@
22
22
  ---
23
23
 
24
24
 
25
-
26
25
  ## Why
27
26
 
28
- The best work I've ever done happened in a small room with a few capable people, building something together.
27
+ I've always done my best work in a small room with a few capable people, building something together.
28
+
29
+ > <span style="color:grey">_[shouts]_</span> Has anyone figured out how to set up auth yet?
29
30
 
30
- Yell out "has anyone figured out the auth service yet?" instead of filing a "request for assistance".
31
+ Not filing a "request for assistance".
31
32
 
32
- Tap the person next to you and ask them to grind you on your idea.
33
+ > <span style="color:grey">_[taps shoulder]_</span> Dude can you grill me on this plan?
34
+
35
+ Not scheduling a meeting.
33
36
 
34
37
  **That's the whole design. Not a swarm, not a company. *A room.***
35
38
 
36
39
  ## Using `pi-simple-team`
37
40
 
38
- Ask your main agent for a team.
41
+ Tell your main agent:
42
+ > Spawn a team.
43
+
44
+ ### Throw a team at something hard.
45
+
46
+ The team takes the shape of the mission.
47
+
48
+ **Basic example: adversarial pair**
49
+
50
+ You:
51
+ > Create an implementer-reviewer team to complete `PLAN.md`.
39
52
 
40
- **Throw a team at something important.**
53
+ Main agent:
54
+ > Pair created. They'll loop through it together. They'll let me know when they're done.
41
55
 
42
- **You:** "Create an implementer–reviewer team to complete `PLAN.md`."
43
- **Main:** "Created the pair. They'll work through it together; they'll let me know when they're done."
56
+ <br>
57
+
58
+ **Better example: build an agentic graph**
59
+
60
+ You:
61
+ > **Team goal:**
62
+ > 1. map out all customer–product money streams in the database.
63
+ > 2. Feed this knowledge into the harness.
64
+ > 3. Then prove the data analysis agent passes the new evals.
65
+ >
66
+ > **Note:**
67
+ > - #1 and #3 are _loops._ Call them `1-map` and `3-eval`.
68
+ > - `1-map` and `3-eval` each gets a teamate.
69
+ > - Each teammate spawns _its own team_ to loop on its task.
70
+
71
+ <br>
72
+
73
+ <center>
74
+ <b>Because</b> it does nothing specially, <code>pi-simple-team</code> can construct any topography you wish it to.
75
+ </center>
76
+ <br>
77
+ That prompt gives you this graph:
78
+
79
+ ```mermaid
80
+ flowchart LR
81
+ subgraph map["1-map: map the money streams"]
82
+ scout["`**Scout**
83
+ Runs repeatedly to clear
84
+ out the fog of war.`"] <--> advocate["`**Devil’s advocate**
85
+ Points out what we
86
+ still don’t know.`"]
87
+ end
88
+
89
+ harness["`**2: subagent dispatch**
90
+ Feeds new understanding
91
+ into the harness.`"]
92
+
93
+ subgraph eval["3-eval: hill-climb the evals"]
94
+ engineer["`**Engineer**
95
+ Improves the harness.`"] <--> watcher["`**Performance watcher**
96
+ Suggests a fresh approach
97
+ when stuck. `"]
98
+ end
99
+
100
+ map --> harness --> eval
101
+ ```
44
102
 
45
- **Follow the breach wherever it leads.**
103
+ <br>
46
104
 
47
- **You:** "Find how the model got into our systems and trace everything it touched."
48
- **Main:** "Created an eight-agent incident team. They're tracing the intrusion from different angles, sharing new leads as they surface. The net will tighten around the model and take the shape of the blast radius."
105
+ ---
49
106
 
50
107
  <br>
51
108
 
@@ -55,46 +112,50 @@ Ask your main agent for a team.
55
112
 
56
113
  ## The mechanics
57
114
 
115
+ ### 🏋️ Woken up when needed. Works freely otherwise.
116
+
117
+ Tokens, intelligence and time are never wasted on busy-polling for messages.
58
118
 
119
+ Instead, `pi-simple-team` pushes messages to the receipients.
59
120
 
60
- ### Push, not pull.
121
+ This is both efficient and effective:
61
122
 
62
123
  - ✔ No inbox to forget.
63
- - ✔ no polling to exhaust your context window.
124
+ - ✔ Context window stays lean.
125
+ - ✔ Unlocks teams doing arbitrary workflows.
64
126
 
65
127
  *{screenshot of Codex filling up the entire visible chat with countless* `Waiting agents to finish...`*}*
66
128
 
67
- ### Messages arrive without breaking stride.
129
+ ### ⚡ Messages arrive _fast_.
68
130
 
69
- - ⚡ Sub-second, when the recipient is idle.
70
- - 🏎️ The moment the current bout of work ends, when busy.
131
+ - Sub-second, when the recipient is idle.
132
+ - The moment the current bout of work ends, when busy.
71
133
 
72
- ### Herdr, first-class.
134
+ ### 🟢 Statuses everyone can see.
73
135
 
74
- `pi-simple-team` gives each teammate a Pi session in its own [Herdr](https://herdr.dev) pane. Just ask your agent to do that.
75
-
76
- You get a live view of the room. Main and teammates keep using the same tools.
136
+ Teammates publish a one-liner:
77
137
 
78
- ### Statuses everyone can see.
138
+ > <span style="color:grey">implementer  </span> Done, 89 tests green, awaiting review.
79
139
 
80
- Teammates publish a one-liner:
140
+ > <span style="color:grey">reviewer      </span> Reading implementation, will finalize review in a few minutes"
81
141
 
82
- - "Done, 89 tests green, awaiting review".
83
- - "Reading implementation, will finalize review in a few minutes"
142
+ Your main agent calls `teamstatus` and understands exactly what's going on. Main doesn't ask and clutter the teammates' context.
84
143
 
85
- Your main agent calls `teamstatus` and understands exactly what's going on without asking and cluttering the teammates' context.
144
+ ### 🌡️ Context window self-awareness
86
145
 
87
- ### Interrupts, when the situation calls for it.
146
+ Teammates know how much free context they have left.
88
147
 
89
- *Team has finished a production hotfix and started to wrap up.*
148
+ Main agent knows its own and everyone else's too.
90
149
 
91
- - Security scout spots a private SSH key not covered by `.gitignore`.
92
- - At the same time, Release teammate sets status: "Ran `git add .`, preparing commit and push."
93
- - Scout immediately interrupts them. Key never leaves the machine. Developer keeps their job.
150
+ ### 📣 Interrupts, when justified.
94
151
 
152
+ > _Situation: Late afternoon. Team has finished a production hotfix and started to wrap up._
95
153
 
154
+ - 17:32:00: Security scout spots a private SSH key not covered by `.gitignore`.
155
+ - 17:32:01: Release teammate sets status: "Ran `git add .`, preparing commit and push."
156
+ - 17:32:02: Scout immediately interrupts. Key never leaves the machine. Developer keeps their job.
96
157
 
97
- ### Complete observability by design.
158
+ ### 📡 Complete observability by design.
98
159
 
99
160
  The main agent can access one exhaustive, **timestamped history** of tool calls, messages, and lifecycle events, **recorded by the harness itself.**
100
161
 
@@ -107,6 +168,14 @@ Useful for tracing a failure *across* teammates—without asking anyone to recon
107
168
  ![A live team status map above its timestamped event log](screenshots/2.png)
108
169
  <div align="center"><em>Visual representation of the team log.</em></div>
109
170
 
171
+ ### 🪟 Herdr Mode
172
+
173
+ `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.
174
+
175
+ - Live view of the room.
176
+ - Talk directly with teammates.
177
+
178
+
110
179
  ## Install
111
180
 
112
181
  ```sh
@@ -126,9 +195,11 @@ Kept minimal:
126
195
  | **Main agent** | Team lifecycle | `team_spawn`, `team_shutdown` |
127
196
  | | With team | `teamsend` |
128
197
  | | On team | `teamstatus`, `teamlog` |
129
- | **Teammates** | With teammates | `teamsend` |
198
+ | | On everyone | `report_context_window` |
199
+ | **Teammates** | With team | `teamsend` |
130
200
  | | With main | `teammain` |
131
- | | For everyone | `teamstatus` |
201
+ | | On self | `report_context_window` |
202
+ | **Everyone** | For everyone | `teamstatus` |
132
203
 
133
204
 
134
205
  ---
@@ -137,12 +208,17 @@ Kept minimal:
137
208
 
138
209
  ## Roadmap
139
210
 
211
+ **User involvement track:**
140
212
 
141
-
142
- ### User involvement track
213
+ - [x] Herdr panes for teammates.
143
214
 
144
215
  Slash commands for:
145
216
 
146
- - [ ] 💠 Live control panel.
217
+ - [ ] 💠 Live control panel.
147
218
  - [ ] 👋 Joining and steering teams.
148
- - [ ] 🪄 Spawning teams directly.
219
+ - [ ] 🪄 Spawning teams directly.
220
+
221
+ **Functional:**
222
+
223
+ - [ ] Add new teammates after team has spawned.
224
+ - [ ] Main forces `/compact` on select teammate.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "1.0.14",
3
+ "version": "1.0.16",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",