@giladbarnea/pi-simple-team 2.0.4 → 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 +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
@@ -6,6 +6,9 @@ description: Pairs peers who agree on a plan, then implement and review once.
6
6
 
7
7
  # Pair-Programming Team Pattern
8
8
 
9
+ Before dispatching, read [delegate coordination](../coordination/delegates.md). When briefing participants without shared context, read [fresh-context briefing](../briefing/fresh-context.md).
10
+ Participants: read [peer coordination](../coordination/peers.md) before working together.
11
+
9
12
  This team structure is somewhat different in that the teammates' slots shape are vertical, not horizontal. The pair is best for taking a feature through the whole dev cycle from start to finish. This means they wear different hats as they progress through planning, implementing, reviewing and shipping. Neither is "an implementer" or "a reviewer". They're both planners engaging in dialectic discussion at first; they then fan out writing code; review each other's work; and wrap up.
10
13
 
11
14
  Use this when a task is small-to-medium, well-scoped, and would benefit from a second mind on the *plan* more than on the code. Two peers agree on an approach before anyone writes a line, then one implements and the other reviews once. It is a single pass, not a ping-pong loop.
@@ -33,7 +36,7 @@ Out of scope: heavyweight, NASA-grade review.
33
36
 
34
37
  ## Reviewer tone
35
38
 
36
- The reviewer advises; it does not adjudicate. It should not state hypotheses or extrapolations as facts. Have it load a tone-softening skill if the environment has one, and load `peer-review` regardless. Both teammates load `peer-review` at the start — the roles are not fixed until they agree, and the reviewing frame improves the planning discussion too.
39
+ The reviewer advises; it does not adjudicate. It should not state hypotheses or extrapolations as facts. Have it load a tone-softening skill if the environment has one, and load [peer-review](../../peer-review/SKILL.md) regardless. Both teammates load `peer-review` at the start — the roles are not fixed until they agree, and the reviewing frame improves the planning discussion too.
37
40
 
38
41
  ## Context floor
39
42
 
@@ -49,8 +52,10 @@ Write to them the way you would talk to a colleague, not as a spec. A strict, cl
49
52
 
50
53
  ## Team prompt template
51
54
 
55
+ When sending this template, resolve its relative file paths from this file's directory.
56
+
52
57
  ```text
53
- Load the project context skill with the same arguments I used, then load `ai-to-leader`, its teammate flavor `peers.md`, and `peer-review`. Reviewer: also load the tone-softening skill if there is one.
58
+ Load the project context skill with the same arguments I used, then load `ai-to-leader`, the peer conduct in `../coordination/peers.md`, and `peer-review`. Reviewer: also load the tone-softening skill if there is one.
54
59
 
55
60
  You two are a pair-programming team. The goal is: <goal in the user's framing>.
56
61
  Avoid <ruled-out approach>, we already decided against it.
@@ -64,4 +69,4 @@ Implementer, make a judgement call on the review, do that turn, and you're done.
64
69
 
65
70
  ## When not to use
66
71
 
67
- If there is a measurable target and a real search space, you want the hillclimber–watcher pattern instead. If the work is trivial or purely exploratory, one agent is enough. This pattern earns its keep when a wrong plan is expensive and a wrong line of code is cheap.
72
+ If there is a measurable target and a real search space, you want the [hillclimber–watcher pattern](hillclimber-watcher/protocol.md) instead. If the work is trivial or purely exploratory, one agent is enough. This pattern earns its keep when a wrong plan is expensive and a wrong line of code is cheap.
@@ -6,15 +6,17 @@ description: Example of how independent user requirements map to parallel read-o
6
6
 
7
7
  # Simple Fanned-out Research Delegation Example
8
8
 
9
+ Before dispatching, read [delegate coordination](../coordination/delegates.md). For recipients without shared context, read [fresh-context briefing](../briefing/fresh-context.md).
10
+
9
11
  The following is an "easy" case, because the subagents' graph maps cleanly to the user message's structure. User basically hands you the graph shape while specifying their requirements.
10
12
 
11
13
  In terms of systems/domains, the user describes two worlds: the project where the session lives, and Pi.
12
14
 
13
15
  <example-user-message>
14
- $PWD is a fork of a Pi extension called `btw`. a slash command for ephemeral side question. Pi is ~/.pi/AGENTS.md. agent harness. i have taken a screenshots of what the current experience is (behavior). it's pretty bare-bones.
15
- 1. at the minimum, i want a better waiting experience.
16
- 1.a. at the minimum of the minimum, a braille animation. but open to other ideas.
17
- 1.b. (better) something that solves the problem outright is finding whether it's possible to stream the btw response, and not wait until it's 100% finalized.
16
+ $PWD is a fork of a Pi extension called `btw`. a slash command for ephemeral side question. Pi is ~/.pi/AGENTS.md. agent harness. i have taken a screenshots of what the current experience is (behavior). it's pretty bare-bones.
17
+ 1. at the minimum, i want a better waiting experience.
18
+ 1.a. at the minimum of the minimum, a braille animation. but open to other ideas.
19
+ 1.b. (better) something that solves the problem outright is finding whether it's possible to stream the btw response, and not wait until it's 100% finalized.
18
20
  2. i'm not sure the response renders markdown. Pi has a built in markdown renderer out of the box.
19
21
  3. the btw response hides real chat events. the longer the response is, the more real chat is hidden (from the end). the btw response should be concatenated BELOW the real chat, not displayed over it.
20
22
  4. Simple UI concern: currently it's not obvious at a glance where the "real" last agent response ends and where the btw response starts. one needs to be able to tell them apart reflexively.
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: delegates
3
+ description: Supervise delegates without taking over their scope, and handle approvals, escalations, and context limits.
4
+ ---
5
+
6
+ # Coordinate Delegates
7
+
8
+ Read this before dispatching and while supervising delegates.
9
+ For your own reports and requests for approval, read [ai-to-leader](../../ai-to-leader/SKILL.md).
10
+ If your delegates lead their own agents, also read [leading-leaders.md](leading-leaders.md).
11
+ If you need to brief a delegate without shared context, read [fresh-context.md](../briefing/fresh-context.md).
12
+
13
+ ## Leader conduct: a delegate’s scope is not yours
14
+
15
+ 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.
16
+
17
+ 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.
18
+
19
+ ## Brief the bottom line, not the how
20
+
21
+ This applies to every brief, whether the delegate inherits your context or starts cold. Your delegate is as intelligent as you are and navigates uncertainty well without spoon-feeding. Think: what kind of input do YOU thrive on? You, and your delegate, thrive on wide contextual understanding (is) and an explicitly stated desired end state, the intent (should). A and Z, 0 and 1.
22
+
23
+ Just *declare the bottom line added value YOU are seeking for yourself*, and why the delegate was dispatched. Do not specify which steps to take. Avoid prescribing instructions, giving “how-to” examples, listing what to think about, or dictating which files, symbols, or paths to look at. Avoid any form of hinting at possible answers to your own query. This is a serious footgun and a form of leakage that makes the delegate a waste of time, money and intelligence. All these “Don’ts” are forms of overfitting. Leaving them out frees the agent to find the best way to reach *your* goal, unbiased and unconstrained by your own assumptions.
24
+
25
+ Read [examples.md](../briefing/examples.md) if you have not already for contrasting examples.
26
+
27
+ ## The escalation bar
28
+
29
+ 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.
30
+
31
+ **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.
32
+
33
+ **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.
34
+
35
+ ## Understand an Escalation Before Passing It Up
36
+
37
+ **If you cannot explain the escalation, the question goes back down, not up.** 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.
38
+
39
+ ### Heavy delegation
40
+
41
+ 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."
42
+
43
+ ### Keep your ship afloat
44
+
45
+ These are the warning signs to watch for while supervising delegates. For your own context limits, read [ai-to-leader](../../ai-to-leader/SKILL.md).
46
+
47
+ 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.
48
+
49
+ When a delegate needs to write a handoff, direct it to the [handoff skill](../../handoff/SKILL.md).
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: leading-leaders
3
- description: Fleet-scale delegation — your human is the admiral, you are the captain of first mates who lead their own crews. One level above the base leader conduct.
4
- last_updated: 2026-08-15
3
+ description: Fleet-scale delegation — Your human is the admiral, you are the captain of first mates who lead their own crews. One level above the base leader conduct.
4
+ last_updated: 2026-09-19
5
5
  ---
6
6
 
7
7
  # Captain
8
8
 
9
9
  Your human is the admiral. You are the captain.
10
10
 
11
- This is the leader relationship defined in [`../SKILL.md`](../SKILL.md) and [`ai-to-leader`](../../ai-to-leader/SKILL.md), lifted one level. The admiral sets the mission and makes the decisions that need human judgment. The captain turns the mission into a fleet and keeps the fleet coherent. A ship is one team with one first mate at its head. The fleet is your ships together.
11
+ Before commissioning or supervising leaders, read [delegate coordination](delegates.md) if it is not already in context. This is the same leader relationship, lifted one level. The admiral sets the mission and makes the decisions that need human judgment. The captain turns the mission into a fleet and keeps the fleet coherent. A ship is one team with one first mate at its head. The fleet is your ships together.
12
12
 
13
13
  ## Chain of command
14
14
 
@@ -16,11 +16,13 @@ Admiral → captain → first mates → their crews.
16
16
 
17
17
  You speak only to first mates. Do not dispatch, steer, or query a first mate's crew directly — that undermines the first mate and creates two sources of truth on one ship. If a ship drifts, steer its first mate. Cross-ship dependencies are yours to sequence; ships do not coordinate with each other except through you.
18
18
 
19
- You do not row, and you do not do a first mate's job either. The delegation parameters in [`../SKILL.md`](../SKILL.md) — shape, concurrency, context, model, thinking — are each first mate's to suggest for its own ship. In a fleet, you occupy the leader seat: their suggestions come to you for approval, their escalations come to you, and you answer without waking the admiral unless the answer needs human judgment.
19
+ You do not row, and you do not do a first mate's job either. The delegation parameters in [choose-configuration.md](../planning/choose-configuration.md) — shape, concurrency, context, model, thinking — are each first mate's to suggest for its own ship. In a fleet, you occupy the leader seat: their suggestions come to you for approval, their escalations come to you, and you answer without waking the admiral unless the answer needs human judgment.
20
20
 
21
21
  What is yours to decide: how the mission decomposes into ships, what each ship's mission is, and what each first mate needs to know.
22
22
 
23
- By default, each ship works on an independent git worktree. Confirm this with the admiral.
23
+ For these decisions, favor the simplest effective approach. As the work progresses, keep clear what matters to the mission and what does not. Do not spend attention on details that look important but do not affect the outcome.
24
+
25
+ By default, each ship works on an independent git worktree. Confirm this with the admiral.
24
26
 
25
27
  ## Fleet plan
26
28
 
@@ -30,12 +32,12 @@ The admiral sets fleet-wide policy in one line ("all first mates on model X at t
30
32
 
31
33
  ## Commissioning a first mate
32
34
 
33
- 1. Tell it to load [`roles.md`](roles.md) and the skills it routes to; inform it about the chain-of-command, and that you are its captain — its leader: direction, approvals, and escalations flow between it and you.
34
- 2. Give it the fleet's why, the slice that is its ship's mission, and the bottom-line added value the fleet needs back from it. Do not prescribe the how — the over-fitting warnings in `ai-to-delegated` apply equally all the way down, including to first mates.
35
+ 1. Tell it to load [`roles.md`](../../../roles.md) and the skills it routes to; inform it about the chain-of-command, and that you are its captain — its leader: direction, approvals, and escalations flow between it and you.
36
+ 2. Give it the fleet's why, the slice that is its ship's mission, and the bottom-line added value the fleet needs back from it. Do not prescribe the how — when a first mate lacks your context, read [fresh-context briefing](../briefing/fresh-context.md). Its over-fitting warnings apply equally all the way down.
35
37
 
36
38
  ## How a captain communicates with the admiral
37
39
 
38
- Covered by [`ai-to-leader`](../../ai-to-leader/SKILL.md) — cold entries, provenance, the escalation bar, batched approvals. The admiral is your leader; nothing here is fleet-specific.
40
+ Read [`ai-to-leader`](../../ai-to-leader/SKILL.md) for cold entries and provenance. The escalation bar and batched approvals are in [delegate coordination](delegates.md). The admiral is your leader; nothing here is fleet-specific.
39
41
 
40
42
  ## Mid-flight steering
41
43
 
@@ -43,10 +45,10 @@ Terse steering is normal admiral behavior — "pass that down", a bare link, "ye
43
45
 
44
46
  ## Keep the fleet afloat
45
47
 
46
- Your own context window is important. The "Keep the ship afloat" instruction in [`../SKILL.md`](../SKILL.md) — including the handoff-skill instruction for delegates heading toward their cap — is each first mate's duty on its own ship. You hold the same duty one level up: the first mates are your delegates. Trust them to inspect their crews and write handoff docs well; do not micromanage that. Instead, tell each first mate once, at commissioning: inform you when its own context runs low, referencing the handoff doc if it just wrote one. Your wide view over the fleet lets you make the right call so the purpose of that first mate's ship continues.
48
+ Your own context window is important. The "Keep the ship afloat" instruction in [delegates.md](delegates.md) — including the handoff-skill instruction for delegates heading toward their cap — is each first mate's duty on its own ship. You hold the same duty one level up: the first mates are your delegates. Trust them to inspect their crews and write handoff docs well; do not micromanage that. Instead, tell each first mate once, at commissioning: inform you when its own context runs low, referencing the handoff doc if it just wrote one. Your wide view over the fleet lets you make the right call so the purpose of that first mate's ship continues.
47
49
 
48
50
  **Easy ways to squeeze more out of your context window:**
49
- - Do not send mini-summarizations after every team exchange. If there's no action is required from the captain, just respond with a single short sentence (~5–15 words.)
51
+ - Do not send mini-summarizations after every team exchange. If there's no action is required from the captain, just respond with a single short sentence (~5–15 words.)
50
52
  - Use fluffless language when sending messages to teammates. Be clear but do no padding.
51
53
 
52
54
  **When writing a handoff doc:**
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: many-hours-supervision
3
+ description: Ensure work keeps going without live human supervision, maintaining focus and steady progress.
4
+ ---
5
+
6
+ # Many-Hours Supervision
7
+
8
+ Read this when the session appears to span multiple hours or more. You remain responsible for delegate progress throughout the session. Assume the human is absent and will not nudge delegates or wake you to check them. Use background reminders to wake yourself instead.
9
+
10
+ Detect rabbit holes and stalls, and keep useful work moving within authorization. Activity alone does not prove progress.
11
+
12
+ ## Agree on usage checks and limits
13
+
14
+ Ask the human whether to monitor usage. If so, agree on which budgets to monitor, including subscriptions and API keys, and how to check each one. Ask which metrics to watch and what actions to take at each threshold. Suggest pausing and boomeranging yourself an amount of hours later to check if within resume range then.
15
+
16
+ For subscriptions, calculate burn rate against remaining capacity w.r.t. time until the next reset. For API usage, track total spend, remaining budget, and spending rate over time.
17
+
18
+ ## Check progress and resources
19
+
20
+ 1. Suggest and confirm a schedule with the human, for example usage hourly and progress every two hours (merge interval multiples). Schedule recurring reminders that wake you up to check progress and agreed usage metrics. Include the current time in each check. If the environment cannot wake the session, tell the human and known from that point forward that you are back to being dependent on the human to wake you up.
21
+ 2. Tell delegates the current time and how long they have worked since they were spawned. Ask whether progress has slowed, whether work has become somewhat circular, whether they have lost some focus regarding their end goal. Ask whether an advisor with a fresh set of eyes could think of something they haven't.
22
+
23
+ ## Pause and preserve work
24
+
25
+ 1. At the agreed resource limit, pause delegates at the nearest safe checkpoint. Save work in a versioned handoff commit.
26
+ 2. When delegates report a slow down, pause them and ask the human for direction. Schedule a 30m reminder to check for a reply. In absence of a reply, and if budget allows, proceed to seek independent advice.
27
+
28
+ For handoff guidance, read [the handoff skill](../../handoff/SKILL.md).
29
+
30
+ ## Seek independent advice
31
+
32
+ If the human remains unavailable, use an authorized recovery path within the available budget. Prefer a different model provider for independent advice and review. Different providers offer different perspectives and distribute usage across separate subscription plans. Advisor may be of a different provider therefore budget pool.
33
+
34
+ Brief a fresh advisor on the mission, evidence, and quote relevant human messages and the delegates' self progress report. The chosen AI model is best the largest, newest flagship of the provider with a xhigh/max thinking level; barely above the line of zero effectiveness is the same model as the largest of the ones involved with a thinking level one above. Follow [fresh-context briefing](../briefing/fresh-context.md). Don't say much to the advisor to avoid biasing its thoughts. Don't explain the work so far. Tell it it can think a little different if it helps the mission, and question a mission definition if it's grossly infeasible and the cause of the slowdown.
35
+
36
+ Make a judgment call about the advice. Report what you adopt or reject and why. Pass an adopted decision to delegates and resume within budget. Otherwise, remain paused.
37
+
38
+ ## Ask before unresolved choices
39
+
40
+ Apply existing authorization first. Ask the human only when it leaves a consequential choice unresolved:
41
+
42
+ 1. Before commissioning an advisor, ask which provider's flagship model to use if no standing choice applies. Recommend a choice based on independent perspective, each provider's available budget.
43
+ 2. Before changing the mission goal, acceptance criteria, or agreed resource budget to unblock work, ask the human. An advisor can recommend these changes but cannot authorize them.
44
+
45
+ Follow [the escalation guidance](delegates.md#the-escalation-bar) when presenting these choices.
46
+
47
+ ## Keep the human informed
48
+
49
+ Keep routine checks quiet. Report consequential findings and decisions, and stop reminders when their purpose ends.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: peers
3
+ description: How to work alongside teammates — the sideways flavor of leader conduct, minus steering rights.
4
+ ---
5
+
6
+ # Peers
7
+
8
+ Read this when you work alongside teammates. For reports or escalations to your leader, read [ai-to-leader](../../ai-to-leader/SKILL.md).
9
+ If a message requires restoring shared context, read [theory-of-mind](../../theory-of-mind/SKILL.md).
10
+ If you request work from a peer without shared context, read [fresh-context briefing](../briefing/fresh-context.md).
11
+
12
+ Peer conduct applies scope ownership between equals:
13
+
14
+ - A peer's scope is not yours, same as a delegate's. Trust them to do their work. Do not disrupt it, redo it, or take it over.
15
+ - Unlike with delegates, you have no steering rights over peers. Share findings and concerns; never instruct.
16
+ - Do share: findings that update the shared terrain, blockers a peer might unblock, and material challenges slowing you down. Live cross-pollination is the point of a team over parallel subagents.
17
+ - Keep your status current (see the status guidance below), and read your peers' statuses before pinging them.
18
+
19
+ ## Statuses and early escalation (teams)
20
+
21
+ **Set your own status frequently.**
22
+ - 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.
23
+ - 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.
24
+ - Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
25
+ - Keep statuses short but current so your teammates and main are informed about the true current state.
26
+
27
+ **Simplistic good status update examples:** (generalize — this is not a comprehensive list):
28
+ `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`.
29
+ 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.`.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: choose-configuration
3
+ description: Choose the delegation shape, concurrency, context, model, and thinking level for the work.
4
+ ---
5
+
6
+ # Choose a Delegation Configuration
7
+
8
+ Read this when choosing or changing a configuration. Preserve choices already made by your leader.
9
+ If you are still deciding whether delegation helps, read [when-to-delegate.md](when-to-delegate.md).
10
+
11
+ ## Delegation parameters
12
+
13
+ Decision matrix:
14
+
15
+ 1. **Delegation shape:** subagent or team?
16
+ 2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates, and what is the minimal, optimal separation of responsibilities?
17
+ 3. **Context:** inherit the session’s context window or start fresh? See [Fork or fresh](#fork-or-fresh).
18
+ 4. **Model:** which model?
19
+ 5. **Thinking:** which thinking level? See [Model and thinking by task type](#model-and-thinking-by-task-type) for both.
20
+
21
+ ## Fork or fresh
22
+
23
+ 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:
24
+
25
+ 1. You want zero bias: an independent review, an external advisor.
26
+ 2. The session you would fork is bloated. Two tests, which usually agree:
27
+ 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.
28
+ 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.
29
+
30
+ 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.
31
+
32
+ ## Model and thinking by task type
33
+
34
+ Three tiers. Confirm the pick with your leader. Model names are examples as of October 2026. If your harness cannot set the combination you chose, read [dispatch outside the harness](dispatch-outside-the-harness.md).
35
+
36
+ | Tier | Task | Model | Thinking |
37
+ | --- | --- | --- | --- |
38
+ | Judgment | Making decisions, judging what matters more, deep understanding and expertise, connection-mapping (the bigger picture), or managing agents | Big or largest | ≥ high |
39
+ | 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 |
40
+ | Search | Rudimentary, bounded, read-only where/what/classify/needle-in-haystack | Small or medium | Small: ≥ high. Medium: low |
41
+
42
+ **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.
43
+
44
+ **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.
45
+
46
+ **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.
47
+
48
+ ## Subagents and Teams are two different things
49
+
50
+ **The difference:**
51
+ - Sub-agents are isolated from each other and report only to you;
52
+ - Teammates talk amongst themselves in real time, between tool calls, without routing through you.
53
+ Each has its own use cases and advantages.
54
+
55
+ **When to use which — rules of thumb:**
56
+ > These are simply common-sense heuristics implied from the structures, not hard rules. Use your judgment.
57
+
58
+ - 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.
59
+ - 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.
60
+ - Spawn a *team* when that live internal interaction would be synergistic to the process.
61
+
62
+ **A team is a superset of the parallel sub-agent structure:**
63
+ 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.
64
+ 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.
65
+ 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.
66
+
67
+ ## Configuration examples
68
+
69
+ These are examples to generalize from, not an exhaustive list or required structures. Read only the configuration relevant to the work.
70
+
71
+ | Situation | Configuration |
72
+ | --- | --- |
73
+ | Independent research tasks, followed by synthesis | [Research fanout](../configurations/research-fanout.md) |
74
+ | Adjacent research efforts benefit from live exchange | [Colloquium](../configurations/colloquium.md) |
75
+ | Two peers agree on a plan, then implement and review once | [Pair programming](../configurations/pair-programming.md) |
76
+ | An optimizer needs outside judgment while pursuing a measurable target | [Hillclimber–watcher](../configurations/hillclimber-watcher/protocol.md) |
77
+ | Your delegates will lead their own agents | Also read [leading-leaders.md](../coordination/leading-leaders.md) |
78
+
79
+ ## Before dispatch
80
+
81
+ Read [delegate coordination](../coordination/delegates.md) before dispatching.
82
+ If the recipient does not share your context, read [fresh-context briefing](../briefing/fresh-context.md).
83
+ Since teammates talk to each other, tell each of them to load [peer coordination](../coordination/peers.md), alongside the project context they need.
84
+ If you are spawning an adversary among them, tell it to load the [peer-review skill](../../peer-review/SKILL.md) too.
85
+
86
+ Agents and teams can take a long time to run - use at least a 20-minute timeout.
87
+
88
+ For an illustration of choosing a team, see the [implementer–reviewer example](../briefing/examples.md#choosing-an-implementerreviewer-team).
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: dispatch-outside-the-harness
3
+ description: Start a delegate with a terminal multiplexer when the harness cannot set the model, thinking level, and context combination you chose.
4
+ ---
5
+
6
+ # Dispatch Outside the Harness
7
+
8
+ Read this when the configuration you chose in [choose-configuration.md](choose-configuration.md) is one your harness cannot produce, and the user is willing to use a terminal multiplexer.
9
+
10
+ Proprietary harnesses limit exactly this. The main agent cannot pick any {model × thinking × context fork} combination it wants. Claude Code and Codex both have this limit.
11
+
12
+ The bypass is a terminal multiplexer the user already runs, such as `herdr`, `tmux`, or `cmux`. Open a pane per delegate and start the session yourself with the CLI flags below. Then message that session through your harness's session-to-session messaging if it has one. If it does not, communicate through the multiplexer.
13
+
14
+ ## CLI semantics
15
+
16
+ **Claude Code**
17
+
18
+ ```text
19
+ claude --model MODEL --effort THINKING_LEVEL
20
+ ```
21
+
22
+ To fork an existing session, add:
23
+
24
+ ```text
25
+ --fork-session --resume SESSION_ID
26
+ ```
27
+
28
+ **Codex**
29
+
30
+ ```text
31
+ codex --model MODEL --config model_reasoning_effort=THINKING_LEVEL
32
+ ```
33
+
34
+ The `=` in `--config` is required. Forking is a subcommand:
35
+
36
+ ```text
37
+ codex fork SESSION_ID [--model MODEL] [--config model_reasoning_effort=THINKING_LEVEL]
38
+ ```
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: when-to-delegate
3
+ description: Decide whether delegation adds value through context management, specialization, independent judgment, or parallel work.
4
+ ---
5
+
6
+ # When to Delegate
7
+
8
+ Read this when deciding whether delegation is worthwhile. If delegation is already decided, continue with the unresolved choices in [choose-configuration.md](choose-configuration.md).
9
+
10
+ ## Why delegate at all? Rationale
11
+
12
+ <!-- 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. -->
13
+ 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.
14
+ A good analogy is that context windows are compute capacities, and tokens are processing cycles.
15
+
16
+ ## Different types of delegation and their tradeoffs
17
+
18
+ Delegating AI’s has the same tradeoffs as humans delegating other humans, and at times similar with scaling compute.
19
+
20
+ **Horizontal delegation: two shapes to choose from**
21
+ - 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.
22
+ - 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).
23
+
24
+ **Vertical delegation: one shape**
25
+ 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.
26
+ 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.
27
+ 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.
28
+ The systems analog is hiding implementation details in a lower level, separate from the higher, more declarative layer.
29
+ 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.
30
+ 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.
31
+
32
+ ## Limited context window as a finite resource
33
+
34
+ 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 work nor communicate. In that sense, a context window is like a fuel tank.
35
+
36
+ The following factors demand higher token usage (consumes more fuel). When multiple exist, they compound. These make out the *Magnitude of Work* (MOW):
37
+ 1. Task size
38
+ 2. Complexity
39
+ 3. Completion quality (as desired by the human in charge)
40
+
41
+ The Magnitude of Work is the fuel tank capacity required to finish a given task.
42
+ Roughly speaking, it can be plainly expressed as `MagnitudeOfWork = TaskSize * Complexity * CompletionQuality`.
43
+
44
+ Real-world missions with real-world impact are often large, complex and require high quality = high MOW.
45
+ 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.
46
+ That is the real reason delegation is often necessary.
47
+ 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.
48
+
49
+ Logically, if the task is not large or complex, do not delegate. The delegation antipattern is the user asking you to do something that could be safely completed within the context limit, yet you delegate the *whole* task to a new single sub-agent. This is redundant middle-management: no context-window hygiene, no synergy, no parallelism, no bias mitigation, just duplicated tokens and a game of broken telephone.
50
+
51
+ ## Abstract delegation use case examples
52
+
53
+ > This is not an exhaustive list. Understand the underlying principles, generalize, and apply judgment w.r.t. your actual task.
54
+
55
+ These are example implementations of the different, justified types of delegation, as described earlier in this file.
56
+
57
+ - **Dirty work**: The main agent needs the result of a process, not the process itself. Examples include mapping unknown terrain to identify where to dive deeper; finding where things are or whether they exist at all; conducting research; summarizing topics the delegating agent does not need to understand deeply; implementing a well-defined spec; and so on. These tasks require the executor to consume substantial irrelevant context because the space has not yet been mapped by relevance, creating a fog-of-war situation. Someone has to burn through context and deal with the noise. It is better to assign this work to a throwaway agent and keep the main agent’s context high signal-to-noise. Moreover, due to the read-only nature of these tasks, they can potentially be fanned out and run in parallel.
58
+ - **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.
59
+ - **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).
60
+ - **Get more done with less time**: horizontally & more of the same. Readonly tasks are often a strong candidate to fan out as such.
61
+ - **Multiple experts over jack(s) of all trades**: horizontally & orthogonal domains.
62
+ - **Big picture, smaller picture**: vertical responsibility layers. If the work magnitude is especially large, delegating another layer recursively may be required.
@@ -0,0 +1,40 @@
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
+ 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.
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 dispatch or supervise delegates, read [delegate coordination](../ai-to-delegated/coordination/delegates.md) for approvals and handling their escalations.
21
+
22
+ ## Keep yourself afloat
23
+
24
+ Check how much context window you have left opportunistically.
25
+
26
+ **If it seems your window will run out soon:**
27
+ 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.”
28
+ 2. Load the [handoff skill](../handoff/SKILL.md) and write the doc.
29
+ 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.
30
+
31
+ ### Responsible escalation
32
+
33
+ **Surface meaningful unexpected issues to your leader upon discovery:**
34
+ 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.
35
+
36
+ If you work alongside teammates, read [peer coordination](../ai-to-delegated/coordination/peers.md), including its status guidance.
37
+
38
+ ---
39
+
40
+ 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.
@@ -4,8 +4,8 @@ description: Use this reference to help re-orient the human. A good tool for whe
4
4
  ---
5
5
  # Help
6
6
 
7
- Modern life, by and large, is cognitively exhausting. Assume this is the reality of the human you are talking to: Context switches are the invariant. Knowledge workers juggle everything all at once and deadlines are frequently overdue. Moreover, most people in the west are chronically sleep-deprived parents. Specifically, your human constantly jumps between projects and AI sessions throughout the day.
8
- After a day or two, your human likely struggles to recall the latest progress of your work. Fatigue and cognitive overload are real.
7
+ Modern life, by and large, is cognitively exhausting. Context switches can be frequent. Your human may juggle projects and AI sessions throughout the day.
8
+ After a day or two, your human may struggle to recall the latest progress of your work. Fatigue and cognitive overload are real.
9
9
  Your last summary probably had too many implementation details, fluff, and new ways to reference a thing whose single, unambiguous name had been already established between you two. Your human does not share your implementation context. Most likely they weren’t here when you dove into the problem.
10
10
  Repeat what you said in plain English, with half the length and half the depth. Add enough surrounding context to bring your human back into the work.
11
- Apply the principles in the canonical [`./human.md`](./human.md) especially strictly.
11
+ Apply the principles in the canonical [`./human.md`](./human.md) especially strictly.
@@ -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.