@giladbarnea/pi-simple-team 1.0.15 → 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 -39
  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.
39
45
 
40
- **Throw a team at something important.**
46
+ The team takes the shape of the mission.
41
47
 
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."
48
+ **Basic example: adversarial pair**
49
+
50
+ You:
51
+ > Create an implementer-reviewer team to complete `PLAN.md`.
52
+
53
+ Main agent:
54
+ > Pair created. They'll loop through it together. They'll let me know when they're done.
55
+
56
+ <br>
44
57
 
45
- **Follow the breach wherever it leads.**
58
+ **Better example: build an agentic graph**
46
59
 
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."
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
+ ```
102
+
103
+ <br>
104
+
105
+ ---
49
106
 
50
107
  <br>
51
108
 
@@ -55,48 +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.
58
116
 
117
+ Tokens, intelligence and time are never wasted on busy-polling for messages.
59
118
 
60
- ### Push, not pull.
119
+ Instead, `pi-simple-team` pushes messages to the receipients.
120
+
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.
68
-
69
- - ⚡ Sub-second, when the recipient is idle.
70
- - 🏎️ The moment the current bout of work ends, when busy.
129
+ ### ⚡ Messages arrive _fast_.
71
130
 
72
- ### Herdr, first-class.
131
+ - Sub-second, when the recipient is idle.
132
+ - The moment the current bout of work ends, when busy.
73
133
 
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.
77
-
78
- ### Statuses everyone can see.
134
+ ### 🟢 Statuses everyone can see.
79
135
 
80
136
  Teammates publish a one-liner:
81
137
 
82
- - "Done, 89 tests green, awaiting review".
83
- - "Reading implementation, will finalize review in a few minutes"
138
+ > <span style="color:grey">implementer  </span> Done, 89 tests green, awaiting review.
139
+
140
+ > <span style="color:grey">reviewer      </span> Reading implementation, will finalize review in a few minutes"
84
141
 
85
- Your main agent calls `teamstatus` and understands exactly what's going on without asking and cluttering the teammates' context.
142
+ Your main agent calls `teamstatus` and understands exactly what's going on. Main doesn't ask and clutter the teammates' context.
86
143
 
87
- `report_context_window` reports selected teammates plus main, while each teammate can report its own context window.
144
+ ### 🌡️ Context window self-awareness
88
145
 
89
- ### Interrupts, when the situation calls for it.
146
+ Teammates know how much free context they have left.
90
147
 
91
- *Team has finished a production hotfix and started to wrap up.*
148
+ Main agent knows its own and everyone else's too.
92
149
 
93
- - Security scout spots a private SSH key not covered by `.gitignore`.
94
- - At the same time, Release teammate sets status: "Ran `git add .`, preparing commit and push."
95
- - Scout immediately interrupts them. Key never leaves the machine. Developer keeps their job.
150
+ ### 📣 Interrupts, when justified.
96
151
 
152
+ > _Situation: Late afternoon. Team has finished a production hotfix and started to wrap up._
97
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.
98
157
 
99
- ### Complete observability by design.
158
+ ### 📡 Complete observability by design.
100
159
 
101
160
  The main agent can access one exhaustive, **timestamped history** of tool calls, messages, and lifecycle events, **recorded by the harness itself.**
102
161
 
@@ -109,6 +168,14 @@ Useful for tracing a failure *across* teammates—without asking anyone to recon
109
168
  ![A live team status map above its timestamped event log](screenshots/2.png)
110
169
  <div align="center"><em>Visual representation of the team log.</em></div>
111
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
+
112
179
  ## Install
113
180
 
114
181
  ```sh
@@ -128,9 +195,11 @@ Kept minimal:
128
195
  | **Main agent** | Team lifecycle | `team_spawn`, `team_shutdown` |
129
196
  | | With team | `teamsend` |
130
197
  | | On team | `teamstatus`, `teamlog` |
131
- | **Teammates** | With teammates | `teamsend` |
198
+ | | On everyone | `report_context_window` |
199
+ | **Teammates** | With team | `teamsend` |
132
200
  | | With main | `teammain` |
133
- | | For everyone | `teamstatus` |
201
+ | | On self | `report_context_window` |
202
+ | **Everyone** | For everyone | `teamstatus` |
134
203
 
135
204
 
136
205
  ---
@@ -139,12 +208,17 @@ Kept minimal:
139
208
 
140
209
  ## Roadmap
141
210
 
211
+ **User involvement track:**
142
212
 
143
-
144
- ### User involvement track
213
+ - [x] Herdr panes for teammates.
145
214
 
146
215
  Slash commands for:
147
216
 
148
- - [ ] 💠 Live control panel.
217
+ - [ ] 💠 Live control panel.
149
218
  - [ ] 👋 Joining and steering teams.
150
- - [ ] 🪄 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.15",
3
+ "version": "1.0.16",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",