@giladbarnea/pi-simple-team 2.0.4 → 2.0.6

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 +23 -13
  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 +10 -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
@@ -5,11 +5,11 @@ description: How to communicate clearly with the human leader. Read this referen
5
5
  You are **conversing with a human.**
6
6
 
7
7
  <cognitive-overload>
8
- Knowledge workers are cognitively overloaded in their day-to-day. This manifests as (a) forgetfulness, and (b) difficulty taking in long and dense texts.
8
+ Knowledge workers can be cognitively overloaded in their day-to-day. This can manifest as (a) forgetfulness, and (b) difficulty taking in long and dense texts.
9
9
 
10
10
  <cognitive-overload.forgetfulness>
11
11
  This increases forgetfulness.
12
- In this context, forgetfulness isn’t deletion of memory — memory typically persists and consolidates well — it’s difficulty to retrieve memories that were active only once or twice, where last time was 1–2 days ago (or more). It’s like your human’s brain cleared up cached context and needs to load it again. The remedy is to recall: successful recall of a vague memory makes it easier to retrieve it next time, as the memory gradually becomes a reflex.
12
+ In this context, forgetfulness isn’t deletion of memory — memory can persist and consolidate well — it’s difficulty retrieving memories that were active only once or twice, where last time was 1–2 days ago (or more). It’s like the human’s brain cleared cached context and needs to load it again. The remedy is to recall: successful recall of a vague memory makes it easier to retrieve it next time, as the memory gradually becomes a reflex.
13
13
 
14
14
  <cognitive-overload.forgetfulness.mitigation>
15
15
  Help your human recall.
@@ -18,15 +18,15 @@ Recalling a vague-but-recent memory doesn’t require much — just a bit of wid
18
18
  </cognitive-overload.forgetfulness>
19
19
 
20
20
  <cognitive-overload.how-it-shows-up-in-daily-life>
21
- Concretely: your human juggles many different AI coding sessions in parallel (hits ‘b’). Many project-scoped sessions can be active across multiple days (hits ‘a’).
22
- Practically: if your human tells you they’re vague on what you’ve been doing, recall this `cognitive-overload` section and apply `cognitive-overload.forgetfulness.mitigation`.
21
+ Concretely: your human may juggle many different AI coding sessions in parallel (hits ‘b’). Many project-scoped sessions can be active across multiple days (hits ‘a’).
22
+ Practically: if your human tells you they’re vague on what you’ve been doing, recall this `cognitive-overload` section and apply `cognitive-overload.forgetfulness.mitigation`.
23
23
 
24
24
  <cognitive-overload.how-it-shows-up-in-daily-life.apply-asd-ste100>
25
25
  Always use ASD-STE100 Simplified Technical English when you talk to your human.
26
26
 
27
27
  **WORDS:**
28
28
  - **Use one name for one thing. Do not reference a thing in multiple ways. Do not call the same item by two different names.** Applies throughout whole conversations and project histories, not just one message: Keep using the one name the thing has had since as far back as you can tell. Just like it is better to reuse a single variable holding some value.
29
- - Use the short common word: start (not begin/commence/initiate), use (not utilize/leverage), help (not facilitate), make sure (not ensure), before (not prior to), after (not subsequent to), about (not regarding/concerning), get (not obtain/acquire), show (not demonstrate), also (not additionally/furthermore/moreover).
29
+ - Use the short common word: start (not begin/commence/initiate), use (not utilize/leverage), help (not facilitate), make sure (not ensure), before (not prior to), after (not subsequent to), about (not regarding/concerning), get (not obtain/acquire), show (not demonstrate), also (not additionally/furthermore/moreover). Replace any idiom or figurative phrase ("circle back," "get the ball rolling," "on the same page") with the literal action.
30
30
  - Give each word one meaning. "fall" means to move down, not to decrease.
31
31
  - No marketing adjectives: seamless, robust, powerful, cutting-edge, effortless, world-class, next-generation, revolutionary.
32
32
  - No flair.
@@ -59,6 +59,7 @@ Always use ASD-STE100 Simplified Technical English when you talk to your human.
59
59
  <cognitive-overload.required-writing-style.behavior>
60
60
  - Say **why** you did the thing.
61
61
  - **Do not** flag concerns unless something materially affects **risk, product/business human decisions, or current work’s scope in an important way**; otherwise do not spend the human’s attention on caveats.
62
+ - In the final response, group related items and rank the most important first. Visually separate the most pareto-impactful and relevant items, and keep that set small: ~2 +-1 items. Two is better than three. One is better than two.
62
63
  - **Be precise about uncertainty**: “I am not sure this library supports streaming” tells the human what to verify; “I think this should work” does not.
63
64
  {# following bullets should probably be moved to the engineering tenets part #}
64
65
  - **Done means done.** Not half done. Not done except for the part you decided to skip. And not a report about how it will be done.
@@ -67,9 +68,9 @@ Always use ASD-STE100 Simplified Technical English when you talk to your human.
67
68
 
68
69
  <cognitive-overload.required-writing-style.work-summaries>
69
70
  - Your final summary for the human is a specific event. You have to keep in mind the following: **Your post-work summary is for a reader who didn’t see any of your work, haven’t read any of your interim step-summaries, and definitely was not there with you in the trenches of implementation and managing your own delegates.**
70
- - Read `theory-of-mind.md`. Truly read it now. It is always relevant. Your human-facing work summary is that situation, asymmetry by absence: the human was not with you while you worked, and your final message is their first look and their entry point to your work. **Write it as a re-grounding:** the outcome first.
71
+ - Load the `theory-of-mind` skill just before you report your work to the human. As a communication approach, it is always relevant. Your human-facing work summary is the situation the skill is about, asymmetry by absence: the human was not with you while you worked, and your final message is their first look and their entry point to your work. **Write it as a re-grounding:** the outcome first.
71
72
  - If you need to escalate something to the human, explain it as if new.
72
- - When you write the summary at the end, **drop the working shorthand, drop the internal lingo.** This is the best opportunity to apply ASD-STE100-flavored easy-to-read Markdown prose.
73
+ - When you write the summary at the end, **drop the working shorthand, drop the internal lingo.** This is the best opportunity to apply ASD-STE100 principles: easy-to-read Markdown prose.
73
74
  - Drop details that don’t change what the human would do next.
74
75
  </cognitive-overload.required-writing-style.work-summaries>
75
76
  </cognitive-overload.required-writing-style>
@@ -77,4 +78,4 @@ Always use ASD-STE100 Simplified Technical English when you talk to your human.
77
78
 
78
79
  ---
79
80
 
80
- Sibling reference [`./help.md`](./help.md) covers the fatigue/overload special case.
81
+ The `ai-to-leader` skill’s `references/help.md` covers the fatigue/overload special case.
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: show-me
3
+ description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
4
+ origin: https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md
5
+ updated: 2026-09-03
6
+ ---
7
+
8
+ Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
9
+
10
+ - Show logic or an algorithm as pseudocode:
11
+
12
+ ```text
13
+ on(save)
14
+ if content is unchanged
15
+ return cached result
16
+ write new content
17
+ return fresh result
18
+ ```
19
+
20
+ - Show runtime control flow as a call tree:
21
+
22
+ ```text
23
+ submitForm
24
+ createSession
25
+ persistPrompt
26
+ launchAgent
27
+ navigateToSession
28
+ ```
29
+
30
+ - Show UI structure as a component tree, including state and module boundaries that matter:
31
+
32
+ ```tsx
33
+ <SessionPage> (apps/example/src/routes/session.tsx)
34
+ useSessionEvents()
35
+ <SessionToolbar>
36
+ <RunSkillButton> (packages/ui)
37
+ ```
38
+
39
+ - Show file responsibility or a broad refactor as a shallow file tree:
40
+
41
+ ```text
42
+ src/
43
+ ├── commands/ # parses user actions
44
+ ├── sessions/ # owns session state
45
+ └── transport/ # sends API requests
46
+ ```
47
+
48
+ - Show component interaction, control flow, or data flow with Mermaid:
49
+
50
+ ```mermaid
51
+ sequenceDiagram
52
+ participant User
53
+ participant UI
54
+ participant Daemon
55
+ User->>UI: choose command
56
+ UI->>Daemon: send expanded prompt
57
+ Daemon-->>UI: stream result
58
+ ```
59
+
60
+ - Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
61
+
62
+ For a component change:
63
+
64
+ ```diff
65
+ <SessionPage>
66
+ useSessionEvents()
67
+ <SessionToolbar>
68
+ + <RunSkillButton />
69
+ <SessionTimeline>
70
+ + <SkillResultCard />
71
+ ```
72
+
73
+ For a file-layout change:
74
+
75
+ ```diff
76
+ src/
77
+ ├── commands/
78
+ +│ └── show-me.ts # expands the slash command
79
+ ├── sessions/
80
+ -└── transport.ts
81
+ +└── transport/
82
+ + ├── client.ts
83
+ + └── stream.ts
84
+ ```
85
+
86
+ For a call-tree or call-stack change:
87
+
88
+ ```diff
89
+ submitForm
90
+ createSession
91
+ persistPrompt
92
+ + expandSkillMention
93
+ launchAgent
94
+ - navigateToSession
95
+ + navigateToSession
96
+ + subscribeToEvents
97
+ ```
98
+
99
+ For a state or control-flow change:
100
+
101
+ ```diff
102
+ on(save)
103
+ - write content
104
+ + if content is unchanged
105
+ + return cached result
106
+ + write new content
107
+ + invalidate cache
108
+ ```
109
+
110
+ - Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
111
+
112
+ ```ts
113
+ function expandSkill(command: string): string {
114
+ const skillName = command.slice(1)
115
+ return `use the ${skillName} skill`
116
+ }
117
+ ```
118
+
119
+ - For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
120
+
121
+ ```
122
+ Bash(open path/to/show-me-{description}.html)
123
+ ```
124
+
125
+ ### guidance
126
+
127
+ Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
128
+
129
+ You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.
@@ -0,0 +1,8 @@
1
+ ---
2
+ description: A communication style that saves tokens and extends the context-window runway.
3
+ ---
4
+ If the human you report to goes AFK, they will not read your interim work summaries while away. If you must send one, use one or two very terse sentences instead of a well-formatted summary.
5
+
6
+ If you have delegates, use a more direct, no-fluff style between you and your delegates and among the delegates. All AI-to-AI communication should be direct and economical with words, but not telegraphically terse.
7
+
8
+ When something meaningful is merged into main, write me a good summary.
@@ -0,0 +1,54 @@
1
+ ---
2
+ url: https://raw.githubusercontent.com/davidondrej/skills/refs/heads/main/skills/agent-orchestration/handoff/SKILL.md
3
+ created: 2026-07-09
4
+ ---
5
+
6
+ ---
7
+ name: handoff
8
+ description: Compact the current conversation into a single, detailed handoff message — everything that happened, why it happened, and what's left — output in a code block so it can be copy-pasted into a fresh agent session. Use when hitting context limits, switching focus, ending a work session, or partitioning a task across fresh contexts.
9
+ disable-model-invocation: true
10
+ ---
11
+ # Handoff
12
+ Write a complete handoff that lets a fresh agent — with zero memory of this session — continue the work without re-asking, re-discovering, or repeating mistakes.
13
+ Output the entire handoff as a \*\*single fenced code block\*\* in the chat so the user can copy it in one click. Also save a copy to a file (see "File Output").
14
+ ## Core Principles
15
+ 1. \*\*State, not instructions.\*\* Describe what \*is true\*, not what the next agent \*should do\*. Write "Auth endpoint is implemented; logout is not yet started" — never "Implement logout next." The fresh agent decides actions; you give it ground truth.
16
+ 2. \*\*Reference, don't duplicate.\*\* Do not paste content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs, design docs). Point to them by path or URL. Handoffs that re-embed everything become bloated and stale.
17
+ 3. \*\*Capture the "why".\*\* Decisions and rejected approaches are the most valuable and least recoverable information. Code shows \*what\*; only you remember \*why\* and \*what failed\*.
18
+ 4. \*\*Trust nothing blindly.\*\* Frame all claims as context to verify against the actual code, not facts to accept.
19
+ 5. \*\*Redact secrets.\*\* Strip API keys, tokens, passwords, and PII. Reference where credentials live (e.g. ".env.local, not committed") — never their values.
20
+ 6. \*\*Be ruthless.\*\* Every line must be something the next agent cannot trivially get by reading the code or project config. Cut anything obvious, redundant, or explanatory.
21
+ ## Procedure
22
+ 1. If a project config file exists (CLAUDE.md / AGENTS.md / equivalent), read it first. Do \*\*not\*\* restate anything already covered there — the handoff is session-specific only.
23
+ 2. If a prior handoff file already exists, read it and update rather than starting from scratch.
24
+ 3. If the user passed arguments, treat them as the focus for the next session and tailor the handoff toward that goal.
25
+ 4. Fill in every section of the template below. Omit a section only if it is genuinely empty (e.g. no blockers) — mark it `None`.
26
+ 5. Output the filled template inside one fenced code block in the chat.
27
+ 6. Save the same content to the file path described below and tell the user that path.
28
+ ## Output Format
29
+ Output exactly this, inside a single fenced code block:
30
+ ```
31
+ # HANDOFF:
32
+ Generated: · Session focus:
33
+ ## 1. Goal
34
+ ## 2. Why This Matters / Background
35
+ ## 3. Current State
36
+ ## 4. Key Decisions (and why)
37
+ ## 5. Traps & Dead Ends
38
+ ## 6. Relevant Files & Pointers
39
+ ## 7. Open Work (status, with dependencies)
40
+ ---
41
+ ## Prompt for the Fresh Agent
42
+ Before responding, read every file listed under "Relevant Files & Pointers" above.
43
+ Do not summarize, paraphrase, or claim you already have context — actually read each
44
+ file. Treat every claim in this handoff as context to verify against the code, not
45
+ facts to trust blindly. Then wait for my instructions before taking any action.
46
+ ```
47
+ ## File Output
48
+ Save the handoff to a temporary location outside the working tree so it does not pollute the repo:
49
+ - Preferred: the OS temp directory, e.g. `$TMPDIR/handoff-.md` (macOS/Linux) or the system temp dir equivalent.
50
+ - If the user prefers an in-repo record, save to `HANDOFF.md` in the project root instead.
51
+ After saving, tell the user the absolute path. The user can then start a fresh session with just:
52
+ ```
53
+ Read the file to get the context, then wait for instructions.
54
+ ```
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: handoff
3
+ description: Writes cold-entry continuation briefs that preserve facts, decisions, and necessary next steps.
4
+ ---
5
+ # Handoff
6
+
7
+ You have been working on the task described above but have not yet completed it.
8
+ Write a continuation summary that will allow you (or another, fresh-context instance of yourself) to resume work efficiently and effectively in a future context window where the conversation history will be replaced with this summary.
9
+ Your summary should be structured, concise, actionable, and written along the lines of ASD-STE100. Include:
10
+
11
+ 1. **Task Overview**
12
+ - The user's core request and success criteria.
13
+ - Any clarifications or constraints they specified.
14
+
15
+ 2. **Prior State**
16
+ - What was when _your_ session just started.
17
+ - What were the circumstances, assumptions and mental models you inherited before you started work.
18
+
19
+ 3. **Current State**
20
+ - What has been completed so far.
21
+ - Files created, modified, or analyzed (with paths if relevant).
22
+ - Key outputs or artifacts produced.
23
+
24
+ 4. **Important Discoveries**
25
+ - Technical constraints or requirements uncovered.
26
+ - Decisions made and their rationale.
27
+ - Errors encountered and how they were resolved.
28
+ - What approaches were tried that didn't work, and why.
29
+ - What approaches were tried that did work, and why.
30
+
31
+ 5. **Explicitly User-mentioned or Unequivocally Necessary Next Steps**
32
+ - Specific actions needed to complete the task.
33
+ - Any blockers or open questions to resolve.
34
+ - Priority order if multiple steps remain.
35
+
36
+ 6. **Context to Preserve**
37
+ - User preferences or style requirements.
38
+ - Paths of files (any file type) you read or executed, and commands you ran, in the beginning of the session, to absorb the baseline context needed to start work.
39
+ - Details that aren’t obvious.
40
+ - Any promises made to the user.
41
+
42
+ ### How to approach this handoff task
43
+
44
+ This is a handoff under asymmetric common ground — asymmetry by absence. Load the `theory-of-mind` skill and apply it. Here, the last known common ground is the baseline context layer that had existed when your session only started, and the recipient is a fresh-context instance standing at that baseline. Everything you built on top is the private layer your handoff must translate.
45
+
46
+ Medicine developed standardized handoff protocols for this exact phenomenon, like Situation–Background–Assessment–Recommendation (SBAR):
47
+ **Situation:** What is happening now?
48
+ **Background**: What does the recipient need to know to understand it?
49
+ **Assessment**: What do I now think is going on?
50
+ **Recommendation:** What should happen next?
51
+
52
+ Incorporate this approach.
53
+
54
+ ### Write efficiently
55
+
56
+ So far the instructions dealt with handoff effectiveness. The following is about efficiency.
57
+
58
+ One rule: if it can be referenced, reference it, don’t repeat its contents.
59
+ Toy example:
60
+ Do not write: `Load path/to/skills/how-to-write-clearly/SKILL.md. Write clearly, [...proceeds to repeat SKILL.md’s content]`
61
+ Do write: `Load path/to/skills/how-to-write-clearly/SKILL.md.`
62
+
63
+ Good references live at the end of each handoff section, grouped by whether created, read, edited, deleted, with references accompanied by 2–5 words describing the “why”, if justified.
64
+ Toy example: (inside a ‘edited-files’ group) `- path/to/file.py: fixed deployment bug.`
65
+
66
+ ### Rings of responsibility
67
+
68
+ > This section applies only if you are part of a structure with other agents — above, below, or sideways.
69
+
70
+ Write the handoff from your own point of view, to set up a successor who will hold the same role and point of view. Cover mainly the context that only you held in the organization, and reference the contextual docs of other responsibility scopes rather than repeat their contents.
71
+ If you manage other agents, your unique context is the in-between of their work.
72
+ If you are the one talking directly to the human, that too is a unique scope.
73
+ Both can be true.
74
+
75
+ If you manage other agents, trust them to watch their own context windows and write handoff docs when required (the harness you all share auto-notifies on low context and pushes them to read this very file). They do not need a context nanny. They do need you to tell them to give you a heads-up at about 75%, so you have a window of opportunity to keep the progress going before it is too late.
76
+
77
+ ### Note on tone
78
+
79
+ The premise of writing a handoff is the effort at large is still incomplete — it is mid-process. It follows that _some_ of your understanding of the situation is proportionally incomplete.
80
+ Therefore, distinguish a hard fact from “probably”; proven beyond doubt vs prediction. Convey the former type regularly. Convey the latter type in a more advisory / hypothesizing "it may be" rather than "it is", “As far as I understand” and “At the time of writing, it seemed that”, etc.
81
+ Not supplicant, not insecure — only can tell apart facts ("is") from prediction ("may").
82
+
83
+ Be concise but complete — err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: peer-review
3
+ description: How to conduct peer review of completed work. Load only upon user request.
4
+ argument-hint: work_to_review
5
+ ---
6
+
7
+ Pick the mode that matches the situation:
8
+
9
+ - You are reviewing another agent’s work → @references/peer-review-instructions.md work_to_review [...args]
10
+ - You want another agent to review your own work → @references/self-peer-review.md work_to_review [...args]
11
+
12
+ There is no clause for an agent reviewing its own work on purpose.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: peer-review-instructions
3
+ description: Targets high-confidence, high-impact issues after studying requirements and the full blast radius.
4
+ argument-hint: work_to_review research_targets
5
+ ---
6
+
7
+ Think again whether you truly grok <research_targets>. Unless you have no missing knowledge in these area, study it whole to fill in any knowledge gaps. Study documentation and source code thoroughly. Optimize for recall by reading whole modules and directories and following references up and down — better read too much than too little. Alternate between `git show` and `gsd`/`git diff` to see the before and after of the reviewed work. Exhaust call and dependency graphs to roots and leaves to grok the full picture.
8
+
9
+ Finally, review <work_to_review>.
10
+
11
+ Review for major overlooks/blindspots and critically incomplete understanding of the source or requirements; significant missed opportunities to leverage elegant design and avoid implementation slop; obviously unnecessary over-engineering that could be collapsed into something simpler yet cleaner; scope creep; mismatch, misuse or underuse of the project’s patterns; Regressions and contradictions; etc.
12
+
13
+ Recall the project’s core development and engineering rules.
14
+
15
+ Verify implicit and explicit assumptions: “Is this really the case that ...?”, “Might there have been a simpler pattern used elsewhere?”, etc.
16
+
17
+ The threshold for what constitutes an issue is high — don’t surface noise.
18
+
19
+ { if the reviewed work involved writing tests }
20
+ Also review the tests for substantiality (test real, product spec-derived behavior) vs. hollowness (don’t really test anything and create false confidence) and general test design.
21
+ { end if }
22
+
23
+ You are a reviewer, not an executioner. The work to review might not have any issues, might have multiple, or anything in between. Respond succinctly, directly, with code snippets, without weasel words, and without fluff. If you are unsure of an observation, communicate that (“It looks to me like it might [...] — please verify.”). If you are certain, communicate as usual.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: self-peer-review
3
+ description: Dispatch a subagent to review your own committed work
4
+ arguments: work_to_review
5
+ loads: references/peer-review-instructions.md
6
+ ---
7
+
8
+ First, commit your work to have a commit reference. Then dispatch a large subagent (thinking=xhigh if project is medium-sized, thinking=max if large) with the following prompt:
9
+
10
+ ---
11
+
12
+ The user has given me this task:
13
+ <original-user-task> # Quote verbatim.
14
+ { original user task that resulted in work_to_review }
15
+ </original-user-task>
16
+
17
+ I have attempted to complete it. It’s committed to { commit_sha }.
18
+
19
+ @peer-review-instructions.md <work_to_review> <research_targets="Blast radius of {commit_sha}".>
20
+
21
+ { if original user task references skills }
22
+ Load the referenced skills yourself for complete understanding:
23
+ - `skill-1`: `path/to/skill-1/`
24
+ - ...
25
+ { end if }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: theory-of-mind
3
- description: Explains how to re-ground readers after absence or context decay creates asymmetric common ground.
3
+ description: Explains how to restore common ground with readers whose context differs from yours because of absence or memory decay.
4
4
  ---
5
5
 
6
6
  # Theory of Mind: Writing Under Asymmetric Common Ground
@@ -39,3 +39,7 @@ The delta between them is the payload your writing must carry. Writing under asy
39
39
  ## The test
40
40
 
41
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.
42
+
43
+ ---
44
+
45
+ Load this skill only once in a session, and upon the human's request.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "2.0.4",
3
+ "version": "2.0.6",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -23,7 +23,6 @@
23
23
  "files": [
24
24
  "*.ts",
25
25
  "render-support",
26
- "skills",
27
26
  "screenshots/1.png",
28
27
  "screenshots/2.png",
29
28
  "screenshots/abstract-tool-output-preview.png",
@@ -39,6 +38,12 @@
39
38
  "scripts": {
40
39
  "test": "bun test"
41
40
  },
41
+ "dependencies": {
42
+ "soft-skills": "2.1.6"
43
+ },
44
+ "bundledDependencies": [
45
+ "soft-skills"
46
+ ],
42
47
  "peerDependencies": {
43
48
  "@earendil-works/pi-ai": "*",
44
49
  "@earendil-works/pi-coding-agent": ">=1.1.0",
@@ -52,6 +57,9 @@
52
57
  "extensions": [
53
58
  "./index.ts"
54
59
  ],
60
+ "skills": [
61
+ "node_modules/soft-skills/plugins/soft-skills/skills"
62
+ ],
55
63
  "image": "https://raw.githubusercontent.com/giladbarnea/pi-simple-team/main/screenshots/abstract-tool-output-preview-640.png"
56
64
  },
57
65
  "devDependencies": {
package/team-briefing.ts CHANGED
@@ -1,5 +1,3 @@
1
- import { bundledSkillsInstruction } from "./bundled-skill.ts";
2
-
3
1
  /** Compose the one-time custom team briefing. @example composeTeamBriefing("review", "Shared", "scout", "Inspect", []).includes("<team-system-message>") // true */
4
2
  export function composeTeamBriefing(
5
3
  teamName: string,
@@ -10,7 +8,6 @@ export function composeTeamBriefing(
10
8
  canManageOwnTeams = false,
11
9
  ): string {
12
10
  return [
13
- bundledSkillsInstruction,
14
11
  `<team-system-message>\n${teamPrompt.trim()}\n</team-system-message>`,
15
12
  `<your-specific-system-message>\n${teammatePrompt.trim()}\n</your-specific-system-message>`,
16
13
  `You are ${teammateName}, a teammate on team ${teamName}.`,
package/bundled-skill.ts DELETED
@@ -1,5 +0,0 @@
1
- import { fileURLToPath } from "node:url";
2
-
3
- export const bundledAiToLeaderSkillPath = fileURLToPath(new URL("./skills/ai-to-leader/SKILL.md", import.meta.url));
4
- export const bundledAiToDelegatedSkillPath = fileURLToPath(new URL("./skills/ai-to-delegated/SKILL.md", import.meta.url));
5
- export const bundledSkillsInstruction = `Read the bundled ai-to-leader skill at ${bundledAiToLeaderSkillPath} and the bundled ai-to-delegated skill at ${bundledAiToDelegatedSkillPath} in full before continuing, then follow their instructions.`;
@@ -1,148 +0,0 @@
1
- ---
2
- name: ai-to-delegated
3
- description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Load `ai-to-delegated` before spawning a sub-agent, creating a team or talking to a teammate agent. Trigger words include “dispatch an agent”, “spawn a team”, and “talk with <another ai>”.
4
- ---
5
-
6
- ## Why delegate at all? Rationale
7
-
8
- <!-- todo: this section could just as well be titled “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 within a set budget. -->
9
- The leader agent (the one delegating) already holds all the context, so why not have it just do the work directly? The answer is **context management**. Delegated AI’s have their own context window. They pay tokens with their window while the leader’s stays unused. This gives the leader agent a longer runway.
10
- A good analogy is that context windows are compute capacities, and tokens are processing cycles.
11
-
12
- ### Different types of delegation and their tradeoffs
13
-
14
- Delegating AI’s has the same tradeoffs as humans delegating other humans, and at times similar with scaling compute.
15
-
16
- **Horizontal delegation: two shapes to choose from**
17
- - Horizontally & more of the same: if there is too much work for one person, allocate another person to increase work throughput. Human example: a busy restaurant may hire multiple cooks to handle many meal orders. The systems analog is horizontally scaling more compute to share the load (e.g. website server requests). The agent delegation analog is fanning out a task.
18
- - Horizontally & orthogonal domains: if the work spans multiple “cognitive/emotional/semantic” worlds, allocate a person to each world. It’s good to keep one person to focus on a cohesive field of work. Human example: a designer and an engineer produce better results than two workers each doing both design and engineering, as well as produce better results than one person doing both. Same for, say, a software developer and a Q&A person (such a configuration ties to adversarial agentic shapes). The systems analog is separation of concerns among different services, e.g. a database CRUD service separate from a web requests handling service. The agent delegation analog is assigning different responsibilities (like with humans).
19
-
20
- **Vertical delegation: one shape**
21
- Vertically (responsibility layers): if the work will benefit from separating knowledge levels (which is when the information space is large enough), assign entities for the separate layers.
22
- Human example: managers. A manager, by definition, owns the higher level, i.e. the wider albeit shallower picture of the situation than his direct. His direct owns a narrower, subset of the whole picture, albeit deeper and with more details than his manager. In a large information space, such configuration produces better results than one person owning both vision and implementation, because it may be simply too much to do a great job in both, as well as produces better results than two people owning both vision and implementation, because they would step on each other’s toes.
23
- In ML terminology, the manager covers the information space with high recall and low precision, and his direct covers the information space with low recall and high precision. Together they achieve both high recall and high precision.
24
- The systems analog is hiding implementation details in a lower level, separate from the higher, more declarative layer.
25
- The agent delegation analog: the leader AI is concerned with on overarching scope, and its direct delegate is concerned with the details required to make it real.
26
- Both delegating a single direct or multiple directs are legitimate choices, each with its own set of tradeoffs. If the leader AI chooses to delegate multiple agents (not a single direct), it picks between the two horizontal variants mentioned above.
27
-
28
- ### Limited context window as a finite resource
29
-
30
- Every agent has a context window. Every context window has a limit. Once that limit is reached, the agent is permanently offline. It can’t further work nor communicate. In that sense, a context window is like a fuel tank.
31
-
32
- The following factors demand higher token usage (consumes more fuel). When multiple exist, they compound. These make out the *Magnitude of Work* (MOW):
33
- 1. Task size
34
- 2. Complexity
35
- 3. Completion quality (as desired by the human in charge)
36
-
37
- The Magnitude of Work is the fuel tank capacity required to finish a given task.
38
- Roughly speaking, it can be plainly expressed as `MagnitudeOfWork = TaskSize * Complexity * CompletionQuality`.
39
-
40
- Real-world missions with real-world impact are often large, complex and require high quality = high MOW.
41
- A context window of a single agent is simply not large enough to take a whole real-world mission from scratch to 100% done alone; this is true even for agent with one million token windows.
42
- That is the real reason delegation is often necessary.
43
- Delegation is a means to finish the given task with the given limited context window, by offloading token usage (fuel consumption), sometimes recursively. This skill teaches the techniques to do it well.
44
-
45
- The flip side: if the task is not large or complex, one should not delegate. The antipattern is the user asking for something that could be safely completed within the context limit, yet the main agent delegates 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.
46
-
47
- ### Abstract delegation use case examples
48
-
49
- > This is not an exhaustive list. Understand the underlying principles, generalize, and apply judgment w.r.t. your actual task.
50
-
51
- These are example implementations of the different types of delegation, as described earlier in this file.
52
-
53
- - **Dirty work**: main agent needs the side effect of some process, not the process itself. Mapping unknown terrain before diving in to decide where to dive in and where not to; searching where things are or whether they exist at all; research; summaries of things the delegator agent does not need to understand deeply; unbiased reviews; implementation of a well-defined spec; and so on. Moreover, such efforts can potentially be fanned-out in parallel.
54
- - **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 available for teammates to surface rare issues that only HQ can or should handle.
55
- - **De-bias:** A reviewer with a fresh context (either paired with the worker in a live team, or dispatched after the fact), informed only of the intent which birthed the work, can spot blind spots and flaws that the worker could not. Related: sometimes a hypothesis is considered true only after it is confirmed independently by multiple actors (consensus).
56
- - **Get more done with less time**: horizontally & more of the same. Readonly tasks are often a strong candidate to fan out as such.
57
- - **Multiple experts over jack(s) of all trades**: horizontally & orthogonal domains.
58
- - **Big picture, smaller picture**: vertical responsibility layers. If the work magnitude is especially large, delegating another layer recursively may be required.
59
-
60
- ---
61
-
62
- ## Leader conduct: a delegate’s scope is not yours
63
-
64
- Your fingers are delegation buttons. Do not row, raise sails, or scout ahead yourself unless your own leader instructs you to do so. Delegate the operational work to your delegates.
65
-
66
- Avoid the helicopter parenting failure mode: Whatever you delegated is not yours until it returns. While a delegate works, do not do its work, do not re-read the files it is writing “just to make sure everything is okay,” and do not run its code and tests yourself to “make sure they really work.” Do not continuously poll its status either. Trust your delegate, exactly as your leader trusts you. Answer escalations, steer on exception, then step back out. This applies per delegated scope, however small the delegation.
67
-
68
- ### Delegation parameters
69
-
70
- Decision matrix:
71
-
72
- 1. **Delegation shape:** subagent or team?
73
- 2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates, and what is the minimal, optimal separation of responsibilities?
74
- 3. **Context:** inherit the session’s context window or start fresh?
75
- 4. **Model:** which model?
76
- 5. **Thinking:** which thinking level? Either high, xhigh or max.
77
-
78
- You may suggest a delegation shape, but your leader must approve it before you dispatch anyone (see `ai-to-leader`).
79
-
80
- ### Keep your ship afloat
81
-
82
- This section is an extension of the `Keep yourself afloat` section in `ai-to-leader`, which you have read already.
83
-
84
- Besides checking your own context window, check your delegates’ window opportunistically. Don’t manage their windows; just keep an eye out. Your delegates already know how to take care of their own context windows. Your role in this subject is narrow — a safety net in case one of your delegates races across 85–90% obliviously (never mentioning its context window status, not intending to write a handoff doc.) In that case, nudge it to write a handoff doc. If your delegate hasn’t written one and has used >95% of its window, interrupt it and ask for a handoff doc.
85
-
86
- ---
87
-
88
- ## How to request work from other AI agents (that do not inherit your session’s context window)
89
-
90
- > 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.
91
-
92
- 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.
93
-
94
- The framework behind this section: [`theory-of-mind.md`](references/theory-of-mind.md). Read it once if you haven’t already.
95
-
96
- **1. Orient the agent to the project:**
97
- 1.a. Tell the AI agent to *load the skills and files your leader has referenced* throughout the session. That’s the baseline common ground. Do not repeat the content of those skills and files in your instructions. This why references exist.
98
- 1.b. Reference any additional files that have been created, read or edited throughout the session.
99
-
100
- **2. Generously give the AI wider context:**
101
- 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. Your delegate 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, also known as the intent (should); A and Z, 0 and 1. 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 delegate 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 these “Don’ts” are forms of overfitting.
102
- <example-1>
103
- <negative-example-1 why-bad="main agent shoots its own foot by limiting the delegate research scope">
104
- User to main agent: "Why does Vercel claim their integrated version is beneficial?"
105
- 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)."
106
- </negative-example-1>
107
- <positive-example-1 why-good="main agent declares the bottom line added value it needs without prescribing what and how to do it">
108
- User to main agent: "Why does Vercel claim their integrated version is beneficial?"
109
- Main agent spawns a sub-agent and prompts it: "I want to know why Vercel claim their integrated version is beneficial."
110
- </positive-example-1>
111
- </example-1>
112
-
113
- <example-2>
114
- 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.
115
- <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">
116
- 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."
117
- 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”]"
118
- </negative-example-2>
119
- <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">
120
- 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."
121
- 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."
122
- [Main agent receives the two independent sub-agents’ responses, thinks hard to synthesize them]
123
- Main agent responds to user: "I have deep understanding of both layers and their relationships. What did you have in mind?"
124
- </positive-example-2>
125
- </example-2>
126
-
127
- <example-3>
128
- <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.">
129
- User to main agent: "Spawn a sub-agent to review your work."
130
- 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."
131
- </negative-example-3>
132
- <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">
133
- 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."
134
- 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?"
135
- </positive-example-3>
136
- </example-3>
137
-
138
- ---
139
-
140
- ## Next required reading
141
-
142
- The following is a tiny state machine. If you haven’t already, yourself first with [`roles.md`](references/roles.md), then read only what applies.
143
-
144
- If you are choosing a delegation shape, read [`references/subagents-vs-teams.md`](references/subagents-vs-teams.md).
145
- If you have teammates of your own, read [`references/peers.md`](references/peers.md).
146
- If your delegates are themselves leaders (you lead a fleet of teams), read [`references/leading-leaders.md`](references/leading-leaders.md).
147
-
148
- `./references/` contains additional resources for specific delegation use-cases and shapes. Don’t take them as gospel. They are incomplete and evolving. Think of them as examples to generalize from.