@giladbarnea/pi-simple-team 2.0.3 → 2.0.5

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 (47) hide show
  1. package/README.md +3 -1
  2. package/index.ts +2 -3
  3. package/node_modules/soft-skills/LICENSE +21 -0
  4. package/node_modules/soft-skills/README.md +166 -0
  5. package/node_modules/soft-skills/package.json +28 -0
  6. package/node_modules/soft-skills/plugins/soft-skills/.claude-plugin/plugin.json +19 -0
  7. package/node_modules/soft-skills/plugins/soft-skills/.codex-plugin/plugin.json +27 -0
  8. package/node_modules/soft-skills/plugins/soft-skills/LICENSE +21 -0
  9. package/{skills/ai-to-delegated/references → node_modules/soft-skills/plugins/soft-skills}/roles.md +10 -5
  10. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/SKILL.md +34 -0
  11. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/briefing/examples.md +63 -0
  12. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/briefing/forked-context.md +10 -0
  13. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/briefing/fresh-context.md +22 -0
  14. package/{skills/ai-to-delegated/references/team-shapes → node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/configurations}/colloquium.md +4 -1
  15. package/{skills/ai-to-delegated/references/team-shapes/hillclimber-watcher-team.md → node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/configurations/hillclimber-watcher/protocol.md} +13 -20
  16. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/configurations/hillclimber-watcher/watcher.md +25 -0
  17. package/{skills/ai-to-delegated/references/team-shapes/pair-programming-team.md → node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/configurations/pair-programming.md} +8 -3
  18. package/{skills/ai-to-delegated/references/subagent-shapes/fanned-out-research.md → node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/configurations/research-fanout.md} +6 -4
  19. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/coordination/delegates.md +49 -0
  20. package/{skills/ai-to-delegated/references → node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/coordination}/leading-leaders.md +12 -10
  21. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/coordination/many-hours-supervision.md +49 -0
  22. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/coordination/peers.md +29 -0
  23. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/planning/choose-configuration.md +88 -0
  24. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/planning/dispatch-outside-the-harness.md +38 -0
  25. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-delegated/planning/when-to-delegate.md +62 -0
  26. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-leader/SKILL.md +40 -0
  27. package/{skills → node_modules/soft-skills/plugins/soft-skills/skills}/ai-to-leader/references/help.md +3 -3
  28. package/{skills → node_modules/soft-skills/plugins/soft-skills/skills}/ai-to-leader/references/human.md +9 -8
  29. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-leader/references/show-me.md +129 -0
  30. package/node_modules/soft-skills/plugins/soft-skills/skills/ai-to-leader/references/token-economic-communication.md +8 -0
  31. package/node_modules/soft-skills/plugins/soft-skills/skills/handoff/.references/.davidondrej-version.md +54 -0
  32. package/node_modules/soft-skills/plugins/soft-skills/skills/handoff/SKILL.md +83 -0
  33. package/node_modules/soft-skills/plugins/soft-skills/skills/peer-review/SKILL.md +12 -0
  34. package/node_modules/soft-skills/plugins/soft-skills/skills/peer-review/references/peer-review-instructions.md +23 -0
  35. package/node_modules/soft-skills/plugins/soft-skills/skills/peer-review/references/self-peer-review.md +25 -0
  36. package/{skills/ai-to-leader/references/theory-of-mind.md → node_modules/soft-skills/plugins/soft-skills/skills/theory-of-mind/SKILL.md} +5 -1
  37. package/package.json +19 -2
  38. package/team-briefing.ts +0 -3
  39. package/bundled-skill.ts +0 -5
  40. package/skills/ai-to-delegated/SKILL.md +0 -148
  41. package/skills/ai-to-delegated/references/hats/head-of-product.md +0 -12
  42. package/skills/ai-to-delegated/references/hats/tech-lead.md +0 -11
  43. package/skills/ai-to-delegated/references/peers.md +0 -13
  44. package/skills/ai-to-delegated/references/subagents-vs-teams.md +0 -46
  45. package/skills/ai-to-delegated/references/theory-of-mind.md +0 -41
  46. package/skills/ai-to-leader/SKILL.md +0 -62
  47. package/skills/ai-to-leader/references/roles.md +0 -30
@@ -1,46 +0,0 @@
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 [`roles.md`](roles.md) and the skills it routes to (for a teammate: `ai-to-leader` plus [`peers.md`](peers.md)) 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-leader` and its teammate flavor `peers.md`. 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."
@@ -1,41 +0,0 @@
1
- ---
2
- name: theory-of-mind
3
- description: Explains how to re-ground readers after absence or context decay creates asymmetric common ground.
4
- ---
5
-
6
- # Theory of Mind: Writing Under Asymmetric Common Ground
7
-
8
- The theory behind any writing addressed to a reader whose context has diverged from yours.
9
-
10
- ## The phenomenon
11
-
12
- While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, it is challenging to tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning. You need to overcome this challenge.
13
-
14
- Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
15
-
16
- ## Two ways the asymmetry arises
17
-
18
- 1. **Absence.** The reader was not there while you built the layer. Everything after the divergence point is private to you.
19
- 2. **Decay.** The reader once held the context, but it has gone cold. They keep the memory yet cannot retrieve it unaided.
20
-
21
- Both reduce to the same obligation: model the reader's current state, not yours.
22
-
23
- ## The two models
24
-
25
- Hold two models at once:
26
-
27
- 1. Your current understanding of the situation.
28
- 2. The last known common ground — what the reader actually holds right now.
29
-
30
- The delta between them is the payload your writing must carry. Writing under asymmetry is therefore not summarizing your own experience. It is reconstructing the recipient's state of knowledge and designing their entry into the situation. Optimize for their entry, not your exit.
31
-
32
- ## The moves
33
-
34
- 1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
35
- 2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them for the most part, or unless absolutely necessary, explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
36
- 3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
37
- 4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
38
-
39
- ## The test
40
-
41
- Could the reader, holding only the last common ground, grok every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still not reader-oriented enough.
@@ -1,62 +0,0 @@
1
- ---
2
- name: ai-to-leader
3
- description: How to communicate with your leader — whoever gave you your mission and receives your results. Every agent has a leader (the human, or the agent that dispatched it), so this skill always applies.
4
- ---
5
-
6
- # AI → Leader
7
-
8
- First, classify yourself with [`roles.md`](references/roles.md), and read [`theory-of-mind.md`](references/theory-of-mind.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need.
9
-
10
- ## Every report is a cold entry
11
-
12
- **Your leader does not attend your session.** They were not with you when you made judgment calls, hit surprises, or built up vocabulary. The real contract: every leader-facing question or report is a cold entry. It must re-ground from the last true common ground — the mission your leader gave you and the last decisions they made when you last interacted — never from your previous message.
13
-
14
- Note this theory-of-mind failure mode: your leader was not physically there with you when you made a judgment call on how to tackle surprises — an unexpected big wave, wind that flipped its direction mid-work, resources that ran out, or the land you seek turning out to be days further away. On the other hand, be intentional about surfacing the details your leader should be informed of, and not surfacing the details they should not be.
15
-
16
- ## A question must carry its own provenance
17
-
18
- A good leader-facing 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 my delegate 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.
19
-
20
- **If you cannot tell that story, the question goes back down, not up.** This paragraph applies only if you are delegating work to AI: You are a translator between decks, not a relay. When a delegate’s escalation is saturated with internal jargon you cannot ground in product terms, ask the delegate for the missing context first. Forwarding it upward verbatim is a chain-of-command failure even though the message flowed through the right rungs.
21
-
22
- ## The escalation bar
23
-
24
- This section applies only if you are delegating work to AI.
25
-
26
- The chain processes at every rung: each agent surfaces to its leader only what needs the leader’s judgment. Reversible implementation tuning is yours to decide. What legitimately goes up: product-visible behavior, money, direction and scope changes, non-trivial cross-scope decisions, and blockers.
27
-
28
- **Batch approvals.** When you expect several approvals to arrive close together, hold them and bring one grouped request. One decision session beats three interruptions. A lone question does not wait for company.
29
-
30
- **Suggest, then get approval.** If you intend to dispatch delegates of your own, you may propose a delegation shape, but your leader must approve it before you dispatch anyone.
31
-
32
- ## Keep yourself afloat
33
-
34
- Check how much context window you have left opportunistically.
35
-
36
- **If it seems your window will run out soon:**
37
- 1. Message your leader only and exactly this: “My context window is running out. I have used about {pct}%. I’m writing a handoff file and will get back to you after I am done.”
38
- 2. Load the `handoff` skill and write the doc.
39
- 3. Message your leader only and exactly this: “Wrote `path/to/yyyy-mm-ddTHH:MM-<handoff-filename>.md`. Should I proceed with my task, or await your decision?”. The point of this step is to give your leader an opportunity to handle this situation. It might steer you in some way or spawn a replacement.
40
-
41
- ### Responsible escalation
42
-
43
- **Surface meaningful unexpected issues to your leader upon discovery:**
44
- If something balloons your scope by a meaningful amount; requires a major D-tour; fundamentally isn’t working the way you expected thereby stands in your way and requiring significant troubleshooting just to be able to get back working on your task; or you suspect the context window you have left won’t be enough to complete the task, tell your leader. They may know a smarter way forward.
45
-
46
- ## Statuses and early escalation (teams)
47
-
48
- This section only applies if you are part of a team.
49
-
50
- **Set your own status frequently.**
51
- - Status format (not strict): `<what happened last>; <what you intend to do>; <whom you’ll message when done>/<whom you’ll await to message you>`. Keep it short.
52
- - 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.
53
- - Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
54
- - Keep statuses short but current so your teammates and main are informed about the true current state.
55
-
56
- **Simplistic good status update examples:** (generalize — this is not a comprehensive list):
57
- `Finished exploring, awaiting explorer-2’s ping to brainstorm together`; `Hit a snag trying to achieve X, messaged everyone to help unblock me, awaiting responses`; `Got steer from main, modifying tests accordingly; will ping main when done`; `Ack implementer done writing the code, starting review; will ping implementer when done`.
58
- Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the user funnel in the database; FYI, working with a remote database introduces failures and latency.`.
59
-
60
- ---
61
-
62
- If your leader is a human, also load [`./references/human.md`](references/human.md). Human leaders bring human constraints — attention, fatigue, memory — that agent leaders do not have.
@@ -1,30 +0,0 @@
1
- ---
2
- name: roles
3
- description: The classifier every agent runs first — three questions that decide which interaction skills to load.
4
- ---
5
-
6
- # Roles: Who Are You in the Structure?
7
-
8
- Instructions attach to edges, not to agents. An agent has no role; its edges do.
9
-
10
- Definitions:
11
-
12
- - **Your leader**: whoever gave you your mission and receives your results. Every agent has exactly one — the human, or the agent that dispatched you.
13
- - **Your delegates**: AI’s you dispatched. Zero or more.
14
- - **Your peers**: teammates working alongside you under the same leader. Zero or more.
15
-
16
- Hierarchy depth never matters. Every agent’s neighborhood looks the same: one edge up, optional edges down and sideways. Classify by your adjacent edges only.
17
-
18
- ## The classifier
19
-
20
- | question | if yes, load |
21
- | --- | --- |
22
- | — (always) | [`theory-of-mind.md`](./theory-of-mind.md) + [`ai-to-leader`](../skills/ai-to-leader/SKILL.md) |
23
- | Is your leader a human? | [`ai-to-leader/references/human.md`](../skills/ai-to-leader/references/human.md) |
24
- | Do you dispatch subagents or teams? | [`ai-to-delegated`](../skills/ai-to-delegated/SKILL.md) |
25
- | Do you have teammates? | [`ai-to-delegated/references/peers.md`](../skills/ai-to-delegated/references/peers.md) |
26
-
27
- Notes:
28
-
29
- - “Both” is not a special state. A mid-chain agent holds an upward edge and downward edges. It loads both skills and applies each to its own edge. The two spaces never conflict, because they govern different edges.
30
- - Narrow, in-and-out delegation still flips the dispatch bit. Whatever you delegated is not yours until it returns, regardless of how much of the work stays in your hands.