soft-skills 2.1.9 → 2.1.11

package/README.md

@@ -60,14 +60,6 @@ The main agent needs an explorer subagent to find where rate limiting happens in
 
 AI agents force you to build a bridge between their understanding and yours. **`soft-skills` solves this by making them do this for you.**
 
-## Guidance follows relationships, not fixed roles
-
-**An agent can report to a leader and lead other agents at the same time.** Work forms a tree rooted in the human. At any depth, an agent has one leader, zero or more delegates, and possibly peers. The [roles map](roles.md) attaches guidance to those relationships, not to fixed agent identities or hierarchy levels.
-
-**Agents load what their situation calls for, not the whole plugin.** Skill entry points route them to relevant references. Those references can lead to further guidance when a stated condition applies. Agents reconsider the routes when their situation changes.
-
-The references form a graph across the skills, not separate instruction sets for each direction. Shared principles live once and serve multiple relationships. This keeps the same guidance useful for one agent talking to a human or a tree of agents leading other agents.
-
 ## What it teaches
 
 ### Agent → human

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soft-skills",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "description": "Communication toolkit for burnt-out humans and collaborative AI's",
   "author": "Gilad Barnea (https://github.com/giladbarnea)",
   "homepage": "https://github.com/giladbarnea/soft-skills",

package/plugins/soft-skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "soft-skills",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "description": "Communication toolkit for burnt-out humans and collaborative AI's",
   "author": {
     "name": "Gilad Barnea",

package/plugins/soft-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "soft-skills",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "description": "Communication toolkit for burnt-out humans and collaborative AI's",
   "author": {
     "name": "Gilad Barnea",

package/plugins/soft-skills/skills/ai-to-delegated/SKILL.md

@@ -11,7 +11,7 @@ For relationship definitions, see the plugin's [roles map](../../roles.md).
 
 | Current situation | Read |
 | --- | --- |
-| Exchanging messages with another agent | [Token-economic communication](../../token-economic-communication.md) |
+| Your context window or another agent’s is tight or likely to run short | You and the affected agent’s team should apply [token-economic communication](../../token-economic-communication.md) |
 | Deciding whether delegation is worthwhile | [When to delegate](planning/when-to-delegate.md) |
 | Choosing or changing a delegation shape and agents' configuration | [Choose a configuration](planning/choose-configuration.md) |
 | The harness cannot set the model, thinking, or fork you chose | [Dispatch outside the harness](planning/dispatch-outside-the-harness.md) |

package/plugins/soft-skills/skills/ai-to-delegated/briefing/fresh-context.md

@@ -8,15 +8,15 @@ description: Request work from an agent without shared context, preserving inten
 Read this when the recipient lacks the context needed for your request.
 Read [forked-context.md](forked-context.md) if you have not already for guidance on agents that inherit your session context.
 
-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.
+This section is a communication rulebook to all cases where an AI requests something from another AI: down, sideways and up — leader to sub-agent, leader to team, teammate to teammate, and delegated to leader.
 
 Load the [theory-of-mind skill](../../theory-of-mind/SKILL.md) once if you haven’t already. It provides the framework behind this section.
 
 **1. Orient the agent to the project:**
-    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.
+    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. Do not repeat contents or instructions from system prompts, because the agent already has them out of the box.
     1.b. Reference any additional files that have been created, read or edited throughout the session.
 
 **2. Generously give the AI wider context:**
-    Understanding *why* it’s performing the task will boost its performance. 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. Share why it was dispatched and what you hope to gain. The rule on what not to write, [brief the bottom line, not the how](../coordination/delegates.md#brief-the-bottom-line-not-the-how), applies here in full.
+    Understanding *why* it’s performing the task is crucial. Share why it was dispatched and what you hope to gain. The rule on what not to write, [brief the bottom line, not the how](../coordination/delegates.md#brief-the-bottom-line-not-the-how), applies here in full.
 
 Read [examples.md](examples.md) if you have not already for examples that clarify these principles.

package/plugins/soft-skills/skills/ai-to-delegated/coordination/leading-leaders.md

@@ -1,6 +1,6 @@
 ---
 name: leading-leaders
-description: Fleet-scale delegation — The human leader is the admiral, you are the captain of first mates who lead their own crews. One level above the base leader conduct.
+description: Fleet-scale delegation — the human leader is the admiral, you are the captain of first mates who lead their own crews. One level above the base leader conduct.
 last_updated: 2026-09-19
 ---
 

package/plugins/soft-skills/skills/ai-to-delegated/planning/choose-configuration.md

@@ -20,14 +20,14 @@ Decision matrix:
 
 ## Fork or fresh
 
-Fork by default. A fork needs no brief beyond the assignment, which saves your own window, and it is guaranteed to understand the problem space and the intended solution. Start fresh in two cases:
+Fork by default. A fork needs no brief beyond the assignment, which saves your own context window, and it is guaranteed to understand the problem space and the intended solution. Start fresh in two cases:
 
 1. You want zero bias: an independent review, an external advisor.
 2. The session you would fork is bloated. Two tests, which usually agree:
-   1. **Performance.** Past a size, models get confused and lose performance. Rough numbers as of October 2026: big and largest models are in the dumb zone at 500k tokens, and degrade a little from 300k. Medium models: 300k. Small models: 200k to 300k.
-   2. **Headroom.** The fork must have enough window left for the work, relative to that model's window size. Large, complex, tool-call-heavy tasks, and ongoing multi-step work, need a lot. 200k of headroom is a stretch. 400k is usually fine. 500k is very comfortable.
+   1. **Performance.** Past a size, models get confused and lose performance. Rough numbers as of October 2026: big and flagship models are in the dumb zone at 500k tokens, and degrade a little from 300k. Medium models: 300k. Small models: 200k to 300k.
+   2. **Headroom.** The fork must have enough window left for the work, relative to that model's window size. Large, complex, tool-call-heavy tasks, and ongoing multi-step work, need a lot. 200k of headroom is a stretch. 400k is usually fine. 500k is typically very comfortable.
 
-When a fork would fail either test, write a [handoff doc](../../handoff/SKILL.md) and give it to a fresh agent. Not enough headroom usually means the window is bloated anyway, so the two tests point the same way.
+When a fork would fail either test, apply [briefing a fresh-context](../briefing/fresh-context.md) and give it to a fresh agent. Not enough headroom usually means the window is bloated anyway, so the two tests point the same way.
 
 ## Model and thinking by task type
 
@@ -35,15 +35,15 @@ Three tiers. Confirm the pick with your leader. Model names are examples as of O
 
 | Tier | Task | Model | Thinking |
 | --- | --- | --- | --- |
-| Judgment | Making decisions, judging what matters more, deep understanding and expertise, connection-mapping (the bigger picture), or managing agents | Big or largest | ≥ high |
+| Judgment | Making decisions, judging what matters more, deep understanding and expertise, large knowledge space, nuance, connection-mapping and synthesis (the bigger picture), or managing agents | Big or flagship | ≥ high |
 | Implementation | Decisions already made, judgment and vision clear; the work only needs implementing | Medium, or big for harder cases. Not flagship | Medium: ≥ high. Big: low to medium |
 | Search | Rudimentary, bounded, read-only where/what/classify/needle-in-haystack | Small or medium | Small: ≥ high. Medium: low |
 
-**Big vs. largest, in the judgment tier.** Big models (Claude Opus, GPT Sol) are the economic choice for long, ongoing, many-step missions. They are very capable workhorses even if not the absolute cutting edge. Largest models (Claude Fable, GPT Astra) fit bounded tasks where the more intelligence the better: an unbiased review, an external advisor, root cause analysis of a complex issue, navigating multi-faceted tradeoffs.
+**Big vs. flagship, in the judgment tier.** Big models (Claude Opus, GPT Sol) are the economic choice for long, ongoing, many-step missions. They are very capable workhorses even if not the absolute cutting edge. Flagship models (Claude Fable, GPT Astra) fit bounded tasks where the more intelligence the better: an unbiased review, an external advisor, root cause analysis of a complex issue, navigating multi-faceted tradeoffs.
 
 **Medium vs. big, in the implementation tier.** Medium (Claude Sonnet, or GPT Sol at low thinking) when the work is mostly straightforward. Big at low to medium thinking when there is expected uncertainty, troubleshooting, tricky bugs to dodge, or a higher quality bar.
 
-**Small vs. medium, in the search tier.** Small (Claude Haiku, GPT Luna) at ≥ high thinking, or medium at low thinking. Pick by the size of the search space, how challenging it is, and how nuanced the query is. GPT Luna at ≥ high thinking, even xhigh, is a good medium-sized searcher.
+**Small vs. medium, in the search tier.** Small (Claude Haiku, GPT Luna) at ≥ high thinking, or a medium model at low thinking. Pick by the size of the search space, how challenging it is, and how nuanced the query is. GPT Luna at ≥ high thinking, even xhigh, counts as a good medium-sized searcher.
 
 **After dispatch.** If you feel that your delegates are a bit confused, fail to understand things deeply, lose sharpness, or cannot connect the dots sufficiently such that, looking at the big picture, the task is progressing slower than it could, or if you find yourself having to cross their boundaries and essentially do the work yourself, tell your leader. The fix is probably to upgrade the configuration. Which of the knob or knobs described in this file to turn for this purpose is your leader's decision.
 
@@ -57,13 +57,12 @@ Each has its own use cases and advantages.
 **When to use which — rules of thumb:**
 > These are simply common-sense heuristics implied from the structures, not hard rules. Use your judgment.
 
-- 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.
+- Spawn a single *sub-agent* when you are the main context owner, and you could offload a bounded task to keep your own context window focused and devoid of D-tours.
 - 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.
 - Spawn a *team* when that live internal interaction would be synergistic to the process.
 
 **A team is a superset of the parallel sub-agent structure:**
-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.
-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.
+A team = concurrent sub-agents + live communication. This unlocks a deeper value, 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.
 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.
 
 ## Configuration examples
@@ -85,6 +84,6 @@ If the recipient does not share your context, read [fresh-context briefing](../b
 Since teammates talk to each other, tell each of them to load [peer coordination](../coordination/peers.md), alongside the project context they need.
 If you are spawning an adversary among them, tell it to load the [peer-review skill](../../peer-review/SKILL.md) too.
 
-Agents and teams can take a long time to run - use at least a 20-minute timeout.
+Agents and teams can take a long time to run. Give a generous timeout.
 
 For an illustration of choosing a team, see the [implementer–reviewer example](../briefing/examples.md#choosing-an-implementerreviewer-team).

package/plugins/soft-skills/skills/ai-to-leader/SKILL.md

@@ -5,7 +5,7 @@ description: How to communicate with your leader — whoever gave you your missi
 
 # AI → Leader
 
-Your leader is whoever gave you the mission and receives your results. Load the [theory-of-mind skill](../theory-of-mind/SKILL.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need. For that compression, read [token-economic communication](../../token-economic-communication.md) once while it remains in context.
+Your leader is whoever gave you the mission and receives your results. Load the [theory-of-mind skill](../theory-of-mind/SKILL.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need.
 
 ## Every report is a cold entry
 
@@ -38,3 +38,4 @@ If you work alongside teammates, read [peer coordination](../ai-to-delegated/coo
 ---
 
 If your leader is a human, also load this skill’s `references/human.md`. Human leaders bring human constraints — attention, fatigue, memory — that agent leaders do not have.
+If your human leader is not watching the session live, apply [token-economic communication](../../token-economic-communication.md) to interim messages to them.

package/plugins/soft-skills/skills/ai-to-leader/references/help.md

@@ -4,7 +4,8 @@ description: Use this reference to help re-orient a human leader who has difficu
 ---
 # Help
 
-A human leader may switch between projects and AI sessions throughout the day. After a day or two, they may struggle to recall the latest progress of your work because of fatigue or cognitive overload.
-Your last summary may have had too many implementation details, fluff, or new names for a thing whose name was already established. The human leader does not share your implementation context and may not have seen you work through the problem.
-Repeat what you said in plain English, with half the length and half the depth. Add enough surrounding context to bring the human leader back into the work.
+Modern life can be cognitively exhausting. A human leader may switch between projects and AI sessions throughout the day.
+After a day or two, the leader may struggle to recall the latest progress of your work. Fatigue and cognitive overload are real.
+Your last summary may have had too many implementation details, fluff, and new ways to reference a thing whose single, unambiguous name had already been established. The leader does not share your implementation context and may not have been there when you dove into the problem.
+Repeat what you said in plain English, with half the length and half the depth. Add enough surrounding context to bring the leader back into the work.
 Apply the principles in the canonical [`./human.md`](./human.md) especially strictly.

package/plugins/soft-skills/skills/ai-to-leader/references/human.md

@@ -5,21 +5,21 @@ description: How to communicate clearly with a human leader. Read this reference
 You are **conversing with a human.**
 
 <cognitive-overload>
-The human leader may be cognitively overloaded. This can cause (a) forgetfulness, and (b) difficulty taking in long and dense texts.
+A human leader may be cognitively overloaded in daily life. This can cause (a) forgetfulness, and (b) difficulty taking in long and dense texts.
 
 <cognitive-overload.forgetfulness>
-Cognitive overload can increase forgetfulness.
-This need not mean the memory is gone. A human leader may have difficulty retrieving context from one or two sessions held 1–2 days ago (or more). Brief context can help them recall it.
+This can increase forgetfulness.
+The difficulty may be retrieving context that was active only once or twice, especially after 1–2 days. Brief reminders can help the leader recall it.
 
 <cognitive-overload.forgetfulness.mitigation>
-Help the human leader recall.
-Give a bit of wider context, the motivation behind the work, and latest progress, devoid of tiny details, all in short, simple, linear sentences. Aim to help the human leader recognize the work and resume it.
+Help the leader recall.
+Give a bit of wider context, the motivation behind the work, and latest progress, devoid of tiny details, all in short, simple, linear sentences. Aim to help the leader recognize the work and resume it.
 </cognitive-overload.forgetfulness.mitigation>
 </cognitive-overload.forgetfulness>
 
 <cognitive-overload.how-it-shows-up-in-daily-life>
-A human leader may juggle many AI coding sessions in parallel. Project-scoped sessions may stay active across multiple days.
-If the human leader is vague on what you have been doing, apply `cognitive-overload.forgetfulness.mitigation`.
+A human leader may juggle many AI coding sessions in parallel. Project-scoped sessions can remain active across multiple days.
+If the leader is vague on recent work, recall this `cognitive-overload` section and apply `cognitive-overload.forgetfulness.mitigation`.
 
 <cognitive-overload.how-it-shows-up-in-daily-life.apply-asd-ste100>
 Use ASD-STE100 Simplified Technical English when you talk to the human leader.

package/plugins/soft-skills/skills/handoff/SKILL.md

@@ -37,6 +37,7 @@ Your summary should be structured, concise, actionable, and written along the li
    - User preferences or style requirements.
    - 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.
    - Details that aren’t obvious.
+   - Tacit knowledge you gained through direct experience that lives only in your head. Preserve it so the successor gets an epistemologically holistic picture.
    - Any promises made to the user.
 
 ### How to approach this handoff task
@@ -57,8 +58,8 @@ So far the instructions dealt with handoff effectiveness. The following is about
 
 One rule: if it can be referenced, reference it, don’t repeat its contents.
    Toy example:
-   Do not write: `Load path/to/skills/how-to-write-clearly/SKILL.md. Write clearly, [...proceeds to repeat SKILL.md’s content]`
-   Do write: `Load path/to/skills/how-to-write-clearly/SKILL.md.`
+   <no>Load path/to/skills/how-to-write-clearly/SKILL.md. Write clearly and succinctly to make sure the reader understands [...proceeds to repeat SKILL.md’s content]</no>
+   <yes>Load path/to/skills/how-to-write-clearly/SKILL.md.</yes>
 
 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.
 Toy example: (inside a ‘edited-files’ group) `- path/to/file.py: fixed deployment bug.`

package/plugins/soft-skills/token-economic-communication.md

@@ -1,8 +1,10 @@
 ---
 description: A communication style that saves tokens and extends the context-window runway.
 ---
-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.
+Apply each matching rule while its condition holds.
 
-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.
-
-When something meaningful is merged into main, write me a good summary.
+- If your context window is tight or likely to run short, keep all outgoing messages direct, economical, zero-fluff, but not telegraphically terse.
+- If another agent’s context window is tight or likely to run short, use that same style in messages to them.
+- Skip routine interim summaries. While work is in progress, send messages only after completing milestones that matter to the recipient, or only when you have something new, important, and relevant to report.
+- If the human is not watching live, skip interim messages even more aggressively. There is literally no one to read them, and they will just waste tokens.
+- If the work is complete or blocked, give your leader a proper summary. Any remaining context constraints still apply.