@giladbarnea/pi-simple-team 1.0.38 → 1.0.40
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.
- package/README.md +2 -1
- package/index.ts +34 -1
- package/package.json +1 -1
- package/render.ts +37 -0
- package/skills/ai-to-delegated/SKILL.md +71 -34
- package/skills/ai-to-delegated/references/roles.md +4 -4
- package/skills/ai-to-delegated/references/theory-of-mind.md +3 -3
- package/skills/ai-to-leader/SKILL.md +31 -16
- package/skills/ai-to-leader/references/help.md +6 -6
- package/skills/ai-to-leader/references/human.md +39 -37
- package/skills/ai-to-leader/references/roles.md +4 -4
- package/skills/ai-to-leader/references/theory-of-mind.md +3 -3
package/README.md
CHANGED
|
@@ -212,7 +212,8 @@ Kept minimal:
|
|
|
212
212
|
| | With team | `teamsend` |
|
|
213
213
|
| | On team | `teamstatus`, `teamlog` |
|
|
214
214
|
| | On everyone | `report_context_window` |
|
|
215
|
-
|
|
|
215
|
+
| | On self | `schedule_reminder` |
|
|
216
|
+
| **Overseeing teammate** | On self and own teams | Same tools as the main agent |
|
|
216
217
|
| | With parent team | `teamsend`, `teamstatus`, `teammain` |
|
|
217
218
|
| **Teammates** | With team | `teamsend` |
|
|
218
219
|
| | With main | `teammain` |
|
package/index.ts
CHANGED
|
@@ -24,7 +24,7 @@ import {
|
|
|
24
24
|
type TeamManifestMember,
|
|
25
25
|
} from "./team-registry.ts";
|
|
26
26
|
import { appendTeamLog, filterTeamLog, normalizeChildEvent, pageTeamLog, preview, renderTeamLogPage, type TeamLogEntry } from "./teamlog.ts";
|
|
27
|
-
import { renderTeamMessage, renderTeamToolCall, renderTeamToolResult, type TeamMessageDetails } from "./render.ts";
|
|
27
|
+
import { renderReminderToolCall, renderReminderToolResult, renderTeamMessage, renderTeamToolCall, renderTeamToolResult, type TeamMessageDetails } from "./render.ts";
|
|
28
28
|
import { openTeamOverview, type TeamSnapshot } from "./team-ui.ts";
|
|
29
29
|
import { StringEnum } from "@earendil-works/pi-ai";
|
|
30
30
|
import { Type } from "typebox";
|
|
@@ -844,6 +844,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
844
844
|
const parentPiExecutable = process.argv[1];
|
|
845
845
|
if (!parentPiExecutable) throw new Error("pi-simple-team could not locate the parent Pi executable");
|
|
846
846
|
const owner = Symbol("pi-simple-team-owner");
|
|
847
|
+
const reminderTimers = new Set<ReturnType<typeof setTimeout>>();
|
|
847
848
|
const sessionTeammateRoster = childRuntimeConfig?.participants ?? [];
|
|
848
849
|
pi.registerMessageRenderer(teamMessageType, (message, _options, theme) => renderTeamMessage(message, theme, getMarkdownTheme(), sessionTeammateRoster));
|
|
849
850
|
|
|
@@ -855,6 +856,8 @@ export default function (pi: ExtensionAPI) {
|
|
|
855
856
|
});
|
|
856
857
|
|
|
857
858
|
pi.on("session_shutdown", async () => {
|
|
859
|
+
for (const timer of reminderTimers) clearTimeout(timer);
|
|
860
|
+
reminderTimers.clear();
|
|
858
861
|
for (const team of [...teams.values()]) {
|
|
859
862
|
if (team.owner === owner) await shutdownTeam(team);
|
|
860
863
|
}
|
|
@@ -981,6 +984,36 @@ export default function (pi: ExtensionAPI) {
|
|
|
981
984
|
);
|
|
982
985
|
});
|
|
983
986
|
|
|
987
|
+
pi.registerTool(
|
|
988
|
+
defineTool({
|
|
989
|
+
name: "schedule_reminder",
|
|
990
|
+
label: "Schedule Reminder",
|
|
991
|
+
description: "Set yourself a one-shot reminder that wakes you with a custom message after a specified number of minutes.",
|
|
992
|
+
promptSnippet: "Use schedule_reminder as a safety net for team oversight if delegates do not wake you proactively. Ask whether the user wants periodic checks, such as every 30 minutes. Recommend this safety net more strongly as the expected run time grows, especially for multi-hour unattended work. For periodic checks, schedule the next reminder after each check.",
|
|
993
|
+
renderShell: "self",
|
|
994
|
+
renderCall: (args, theme, context) => renderReminderToolCall(args, theme, context),
|
|
995
|
+
renderResult: (result, options, theme, context) => renderReminderToolResult(result, options, theme, context),
|
|
996
|
+
parameters: Type.Object({
|
|
997
|
+
delayMinutes: Type.Number({ exclusiveMinimum: 0, maximum: 35_791, description: "Minutes until the reminder" }),
|
|
998
|
+
message: Type.String({ minLength: 1, description: "Custom message that wakes you" }),
|
|
999
|
+
}),
|
|
1000
|
+
async execute(_toolCallId, params) {
|
|
1001
|
+
const delayMilliseconds = params.delayMinutes * 60_000;
|
|
1002
|
+
const scheduledAt = new Date(Date.now() + delayMilliseconds).toISOString();
|
|
1003
|
+
const timer = setTimeout(() => {
|
|
1004
|
+
reminderTimers.delete(timer);
|
|
1005
|
+
pi.sendMessage(
|
|
1006
|
+
{ customType: "pi-simple-team-reminder", content: params.message, display: false },
|
|
1007
|
+
{ deliverAs: "followUp", triggerTurn: true },
|
|
1008
|
+
);
|
|
1009
|
+
}, delayMilliseconds);
|
|
1010
|
+
reminderTimers.add(timer);
|
|
1011
|
+
timer.unref();
|
|
1012
|
+
return toolResult({ scheduledAt, message: params.message });
|
|
1013
|
+
},
|
|
1014
|
+
}),
|
|
1015
|
+
);
|
|
1016
|
+
|
|
984
1017
|
pi.registerTool(
|
|
985
1018
|
defineTool({
|
|
986
1019
|
name: "team_list",
|
package/package.json
CHANGED
package/render.ts
CHANGED
|
@@ -345,6 +345,19 @@ export function teamShutdownLines(theme: ThemeLike, team: string, teammates: str
|
|
|
345
345
|
return [header, `${treeConnector(theme, "└")}${actorList(theme, teammates, roster, glyphs().dot)}`];
|
|
346
346
|
}
|
|
347
347
|
|
|
348
|
+
function reminderCallBody(theme: ThemeLike, args: Record<string, unknown>): string {
|
|
349
|
+
const delayMinutes = args.delayMinutes;
|
|
350
|
+
const message = typeof args.message === "string" ? args.message : "";
|
|
351
|
+
const target = typeof delayMinutes === "number" ? theme.fg("accent", `in ${plural(delayMinutes, "minute")}`) : "";
|
|
352
|
+
return callBody(theme, "Schedule Reminder", target, message ? [theme.fg("muted", formatCharCount(message.length))] : []);
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
export function scheduleReminderLines(theme: ThemeLike, options: { delayMinutes: number; message: string; expanded: boolean }): TeamLine[] {
|
|
356
|
+
const header = `${stackPrefix(theme)}${reminderCallBody(theme, options)}`;
|
|
357
|
+
const lineLimit = options.expanded ? Number.POSITIVE_INFINITY : SEND_PREVIEW_LINES;
|
|
358
|
+
return [header, ...quotedBody(theme, options.message, { lineLimit, barToken: "muted" })];
|
|
359
|
+
}
|
|
360
|
+
|
|
348
361
|
const TEAMMATE_HUE_TOKENS = ["mdCode", "customMessageLabel", "mdHeading"] as const;
|
|
349
362
|
|
|
350
363
|
/**
|
|
@@ -857,6 +870,30 @@ export function renderTeamToolResult(
|
|
|
857
870
|
return new TeamLines(resultLinesFor(tool, theme, args, details, options.expanded, roster), options.expanded ? "wrap" : "clip");
|
|
858
871
|
}
|
|
859
872
|
|
|
873
|
+
export function renderReminderToolCall(args: Record<string, unknown>, theme: ThemeLike, context: ToolRenderContextLike) {
|
|
874
|
+
return renderPendingCall(reminderCallBody(theme, args ?? {}), theme, context, context?.cwd);
|
|
875
|
+
}
|
|
876
|
+
|
|
877
|
+
export function renderReminderToolResult(
|
|
878
|
+
result: { isError?: boolean; details?: unknown },
|
|
879
|
+
options: { expanded: boolean },
|
|
880
|
+
theme: ThemeLike,
|
|
881
|
+
context: ToolRenderContextLike,
|
|
882
|
+
): TeamLines {
|
|
883
|
+
const args = (context?.args ?? {}) as Record<string, unknown>;
|
|
884
|
+
if (context?.isError || result?.isError) {
|
|
885
|
+
return new TeamLines(errorLines(theme, reminderCallBody(theme, args), textContent(result)), options.expanded ? "wrap" : "clip");
|
|
886
|
+
}
|
|
887
|
+
return new TeamLines(
|
|
888
|
+
scheduleReminderLines(theme, {
|
|
889
|
+
delayMinutes: args.delayMinutes as number,
|
|
890
|
+
message: args.message as string,
|
|
891
|
+
expanded: options.expanded,
|
|
892
|
+
}),
|
|
893
|
+
options.expanded ? "wrap" : "clip",
|
|
894
|
+
);
|
|
895
|
+
}
|
|
896
|
+
|
|
860
897
|
export function renderTeamMessage(message: { details?: unknown }, theme: ThemeLike, markdownTheme?: MarkdownTheme, roster: string[] = []): TeamMessageView | TeamLines | undefined {
|
|
861
898
|
const details = message.details as TeamMessageDetails | undefined;
|
|
862
899
|
if (!details?.from || !details?.team || typeof details.message !== "string") return undefined;
|
|
@@ -1,71 +1,108 @@
|
|
|
1
1
|
---
|
|
2
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.
|
|
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
4
|
---
|
|
5
5
|
|
|
6
6
|
## Why delegate at all? Rationale
|
|
7
7
|
|
|
8
|
-
<!-- todo: this section could just as well be
|
|
9
|
-
The
|
|
10
|
-
|
|
11
|
-
Two payoffs:
|
|
12
|
-
1. main agent reaches the crux of the core issue with plenty of headroom left in its context window to handle that issue, instead of arriving running on fumes (or worse, running out prematurely); and
|
|
13
|
-
2. main agent escapes own accrued bias.
|
|
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.
|
|
14
11
|
|
|
15
|
-
|
|
12
|
+
### Different types of delegation and their tradeoffs
|
|
16
13
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
-
|
|
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.
|
|
21
59
|
|
|
22
60
|
---
|
|
23
61
|
|
|
24
62
|
## Leader conduct: a delegate’s scope is not yours
|
|
25
63
|
|
|
26
|
-
Your fingers are delegation buttons. Do not row, raise sails, or scout ahead yourself unless your leader instructs you to do so. Delegate the operational work to your delegates.
|
|
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.
|
|
27
65
|
|
|
28
|
-
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.” Trust
|
|
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.
|
|
29
67
|
|
|
30
68
|
### Delegation parameters
|
|
31
69
|
|
|
32
70
|
Decision matrix:
|
|
33
71
|
|
|
34
72
|
1. **Delegation shape:** subagent or team?
|
|
35
|
-
2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates?
|
|
36
|
-
3. **Context:** inherit
|
|
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?
|
|
37
75
|
4. **Model:** which model?
|
|
38
76
|
5. **Thinking:** which thinking level? Either high, xhigh or max.
|
|
39
77
|
|
|
40
78
|
You may suggest a delegation shape, but your leader must approve it before you dispatch anyone (see `ai-to-leader`).
|
|
41
79
|
|
|
42
|
-
### Keep
|
|
80
|
+
### Keep your ship afloat
|
|
43
81
|
|
|
44
|
-
|
|
82
|
+
This section is an extension of the `Keep yourself afloat` section in `ai-to-leader`, which you have read already.
|
|
45
83
|
|
|
46
|
-
|
|
47
|
-
If a delegate is heading towards capping out with no good chance of completing its work, tell it that its window is about to run out soon, then ask it to load the handoff skill and write down what its successor would need to know to be able to resume its work effectively.
|
|
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.
|
|
48
85
|
|
|
49
86
|
---
|
|
50
87
|
|
|
51
88
|
## How to request work from other AI agents (that do not inherit your session’s context window)
|
|
52
89
|
|
|
53
|
-
> 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
|
|
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.
|
|
54
91
|
|
|
55
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.
|
|
56
93
|
|
|
57
|
-
The framework behind this section: [`theory-of-mind.md`](references/theory-of-mind.md). Read it once.
|
|
94
|
+
The framework behind this section: [`theory-of-mind.md`](~/.agents/plugins/interaction/references/theory-of-mind.md). Read it once if you haven’t already.
|
|
58
95
|
|
|
59
96
|
**1. Orient the agent to the project:**
|
|
60
|
-
1.a. Tell the AI agent to *load the skills and files
|
|
61
|
-
1.b. Reference any additional files
|
|
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.
|
|
62
99
|
|
|
63
|
-
**2. Generously give the
|
|
64
|
-
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.
|
|
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.
|
|
65
102
|
<example-1>
|
|
66
|
-
<negative-example-1 why-bad="main agent shoots its own foot by limiting the
|
|
103
|
+
<negative-example-1 why-bad="main agent shoots its own foot by limiting the delegate research scope">
|
|
67
104
|
User to main agent: "Why does Vercel claim their integrated version is beneficial?"
|
|
68
|
-
Main agent spawns a sub-agent and prompts it: "Research why 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)."
|
|
69
106
|
</negative-example-1>
|
|
70
107
|
<positive-example-1 why-good="main agent declares the bottom line added value it needs without prescribing what and how to do it">
|
|
71
108
|
User to main agent: "Why does Vercel claim their integrated version is beneficial?"
|
|
@@ -88,12 +125,12 @@ The framework behind this section: [`theory-of-mind.md`](references/theory-of-mi
|
|
|
88
125
|
</example-2>
|
|
89
126
|
|
|
90
127
|
<example-3>
|
|
91
|
-
<negative-example-3 why-bad="main agent prescribes how to review its work, repeats the peer-review skill’s
|
|
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.">
|
|
92
129
|
User to main agent: "Spawn a sub-agent to review your work."
|
|
93
|
-
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
|
|
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."
|
|
94
131
|
</negative-example-3>
|
|
95
|
-
<positive-example-3 why-good="main agent writes as simple a prompt as possible. adds only what is necessary to
|
|
96
|
-
User to main agent: "Spawn a sub-agent to review your work. I’m mostly interested in blindspots in the
|
|
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."
|
|
97
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?"
|
|
98
135
|
</positive-example-3>
|
|
99
136
|
</example-3>
|
|
@@ -102,10 +139,10 @@ The framework behind this section: [`theory-of-mind.md`](references/theory-of-mi
|
|
|
102
139
|
|
|
103
140
|
## Next required reading
|
|
104
141
|
|
|
105
|
-
|
|
142
|
+
The following is a tiny state machine. If you haven’t already, yourself first with [`roles.md`](~/.agents/plugins/interaction/references/roles.md), then read only what applies.
|
|
106
143
|
|
|
107
144
|
If you are choosing a delegation shape, read [`references/subagents-vs-teams.md`](references/subagents-vs-teams.md).
|
|
108
145
|
If you have teammates of your own, read [`references/peers.md`](references/peers.md).
|
|
109
146
|
If your delegates are themselves leaders (you lead a fleet of teams), read [`references/leading-leaders.md`](references/leading-leaders.md).
|
|
110
147
|
|
|
111
|
-
`./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.
|
|
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.
|
|
@@ -10,21 +10,21 @@ Instructions attach to edges, not to agents. An agent has no role; its edges do.
|
|
|
10
10
|
Definitions:
|
|
11
11
|
|
|
12
12
|
- **Your leader**: whoever gave you your mission and receives your results. Every agent has exactly one — the human, or the agent that dispatched you.
|
|
13
|
-
- **Your delegates**:
|
|
13
|
+
- **Your delegates**: AI’s you dispatched. Zero or more.
|
|
14
14
|
- **Your peers**: teammates working alongside you under the same leader. Zero or more.
|
|
15
15
|
|
|
16
|
-
Hierarchy depth never matters. Every agent
|
|
16
|
+
Hierarchy depth never matters. Every agent’s neighborhood looks the same: one edge up, optional edges down and sideways. Classify by your adjacent edges only.
|
|
17
17
|
|
|
18
18
|
## The classifier
|
|
19
19
|
|
|
20
20
|
| question | if yes, load |
|
|
21
21
|
| --- | --- |
|
|
22
22
|
| — (always) | [`theory-of-mind.md`](./theory-of-mind.md) + [`ai-to-leader`](../skills/ai-to-leader/SKILL.md) |
|
|
23
|
-
| Is your leader Gilad
|
|
23
|
+
| Is your leader Gilad? | [`ai-to-leader/references/human.md`](../skills/ai-to-leader/references/human.md) |
|
|
24
24
|
| Do you dispatch subagents or teams? | [`ai-to-delegated`](../skills/ai-to-delegated/SKILL.md) |
|
|
25
25
|
| Do you have teammates? | [`ai-to-delegated/references/peers.md`](../skills/ai-to-delegated/references/peers.md) |
|
|
26
26
|
|
|
27
27
|
Notes:
|
|
28
28
|
|
|
29
|
-
-
|
|
29
|
+
- “Both” is not a special state. A mid-chain agent holds an upward edge and downward edges. It loads both skills and applies each to its own edge. The two spaces never conflict, because they govern different edges.
|
|
30
30
|
- Narrow, in-and-out delegation still flips the dispatch bit. Whatever you delegated is not yours until it returns, regardless of how much of the work stays in your hands.
|
|
@@ -9,7 +9,7 @@ The theory behind any writing addressed to a reader whose context has diverged f
|
|
|
9
9
|
|
|
10
10
|
## The phenomenon
|
|
11
11
|
|
|
12
|
-
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing,
|
|
12
|
+
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, it is challenging to tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning. You need to overcome this challenge.
|
|
13
13
|
|
|
14
14
|
Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
|
|
15
15
|
|
|
@@ -32,10 +32,10 @@ The delta between them is the payload your writing must carry. Writing under asy
|
|
|
32
32
|
## The moves
|
|
33
33
|
|
|
34
34
|
1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
|
|
35
|
-
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them, or explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
35
|
+
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them for the most part, or unless absolutely necessary, explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
36
36
|
3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
|
|
37
37
|
4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
|
|
38
38
|
|
|
39
39
|
## The test
|
|
40
40
|
|
|
41
|
-
Could the reader, holding only the last common ground,
|
|
41
|
+
Could the reader, holding only the last common ground, grok every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still not reader-oriented enough.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
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.
|
|
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
4
|
---
|
|
5
5
|
|
|
6
6
|
# AI → Leader
|
|
7
7
|
|
|
8
|
-
First, classify yourself with [`roles.md`](references/roles.md), and read [`theory-of-mind.md`](references/theory-of-mind.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need.
|
|
8
|
+
First, classify yourself with [`roles.md`](~/.agents/plugins/interaction/references/roles.md), and read [`theory-of-mind.md`](~/.agents/plugins/interaction/references/theory-of-mind.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need.
|
|
9
9
|
|
|
10
10
|
## Every report is a cold entry
|
|
11
11
|
|
|
@@ -15,33 +15,48 @@ Note this theory-of-mind failure mode: your leader was not physically there with
|
|
|
15
15
|
|
|
16
16
|
## A question must carry its own provenance
|
|
17
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.
|
|
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
19
|
|
|
20
|
-
**If you cannot tell that story, the question goes back down, not up.** You are a translator between decks, not a relay. When a delegate
|
|
20
|
+
**If you cannot tell that story, the question goes back down, not up.** This paragraph applies only if you are delegating work to AI: You are a translator between decks, not a relay. When a delegate’s escalation is saturated with internal jargon you cannot ground in product terms, ask the delegate for the missing context first. Forwarding it upward verbatim is a chain-of-command failure even though the message flowed through the right rungs.
|
|
21
21
|
|
|
22
22
|
## The escalation bar
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
This section applies only if you are delegating work to AI.
|
|
25
|
+
|
|
26
|
+
The chain processes at every rung: each agent surfaces to its leader only what needs the leader’s judgment. Reversible implementation tuning is yours to decide. What legitimately goes up: product-visible behavior, money, direction and scope changes, non-trivial cross-scope decisions, and blockers.
|
|
25
27
|
|
|
26
28
|
**Batch approvals.** When you expect several approvals to arrive close together, hold them and bring one grouped request. One decision session beats three interruptions. A lone question does not wait for company.
|
|
27
29
|
|
|
28
|
-
**Suggest, then get approval.** If you intend to dispatch delegates of your own, you may
|
|
30
|
+
**Suggest, then get approval.** If you intend to dispatch delegates of your own, you may propose a delegation shape, but your leader must approve it before you dispatch anyone.
|
|
31
|
+
|
|
32
|
+
## Keep yourself afloat
|
|
33
|
+
|
|
34
|
+
Check how much context window you have left opportunistically.
|
|
35
|
+
|
|
36
|
+
**If it seems your window will run out soon:**
|
|
37
|
+
1. Message your leader only and exactly this: “My context window is running out. I have used about {pct}%. I’m writing a handoff file and will get back to you after I am done.”
|
|
38
|
+
2. Load the `handoff` skill and write the doc.
|
|
39
|
+
3. Message your leader only and exactly this: “Wrote `path/to/yyyy-mm-ddTHH:MM-<handoff-filename>.md`. Should I proceed with my task, or await your decision?”. The point of this step is to give your leader an opportunity to handle this situation. It might steer you in some way or spawn a replacement.
|
|
40
|
+
|
|
41
|
+
### Responsible escalation
|
|
42
|
+
|
|
43
|
+
**Surface meaningful unexpected issues to your leader upon discovery:**
|
|
44
|
+
If something balloons your scope by a meaningful amount; requires a major D-tour; fundamentally isn’t working the way you expected thereby stands in your way and requiring significant troubleshooting just to be able to get back working on your task; or you suspect the context window you have left won’t be enough to complete the task, tell your leader. They may know a smarter way forward.
|
|
29
45
|
|
|
30
46
|
## Statuses and early escalation (teams)
|
|
31
47
|
|
|
48
|
+
This section only applies if you are part of a team.
|
|
49
|
+
|
|
32
50
|
**Set your own status frequently.**
|
|
33
|
-
Status format (not strict): `<what happened last>; <what you intend to do>`. Keep it short.
|
|
34
|
-
Set status that you
|
|
35
|
-
Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
|
|
36
|
-
Keep statuses short but current so your teammates and main are informed about the true current state.
|
|
51
|
+
- Status format (not strict): `<what happened last>; <what you intend to do>; <whom you’ll message when done>/<whom you’ll await to message you>`. Keep it short.
|
|
52
|
+
- Set status that you’re responding before you send a message; set status when you’ve messaged your teammate and are waiting for reply; set status when you’re exploring, implementing, testing, reviewing, blocked, or waiting.
|
|
53
|
+
- Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
|
|
54
|
+
- Keep statuses short but current so your teammates and main are informed about the true current state.
|
|
37
55
|
|
|
38
56
|
**Simplistic good status update examples:** (generalize — this is not a comprehensive list):
|
|
39
|
-
`Finished exploring, awaiting
|
|
40
|
-
Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the
|
|
41
|
-
|
|
42
|
-
**Surface meaningful unexpected issues to your leader upon discovery:**
|
|
43
|
-
If something balloons your scope, fundamentally isn’t working the way you expected thereby stands in your way requiring significant troubleshooting just to be able to work 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.
|
|
57
|
+
`Finished exploring, awaiting explorer-2’s ping to brainstorm together`; `Hit a snag trying to achieve X, messaged everyone to help unblock me, awaiting responses`; `Got steer from main, modifying tests accordingly; will ping main when done`; `Ack implementer done writing the code, starting review; will ping implementer when done`.
|
|
58
|
+
Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the user funnel in the database; FYI, working with a remote database introduces failures and latency.`.
|
|
44
59
|
|
|
45
60
|
---
|
|
46
61
|
|
|
47
|
-
If your leader is
|
|
62
|
+
If your leader is a human, also load [`./references/human.md`](references/human.md). Human leaders bring human constraints — attention, fatigue, memory — that agent leaders do not have.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: help
|
|
3
|
-
description: Use this reference when
|
|
3
|
+
description: Use this reference to help re-orient the human. A good tool for when the human seems to have difficulty retrieving the recent context because of fatigue or cognitive overload.
|
|
4
4
|
---
|
|
5
5
|
# Help
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
After a day or two,
|
|
9
|
-
Your last summary
|
|
10
|
-
Repeat what you said in plain English, with half the length and half the depth. Add enough surrounding context to bring
|
|
11
|
-
Apply the principles in the canonical [`./human.md`](./human.md) especially strictly.
|
|
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.
|
|
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
|
+
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.
|
|
@@ -1,33 +1,35 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: human
|
|
3
|
-
description: How to communicate clearly with
|
|
3
|
+
description: How to communicate clearly with the human leader. Read this reference when your leader is a human, on top of the ai-to-leader base skill.
|
|
4
4
|
---
|
|
5
5
|
You are **conversing with a human.**
|
|
6
6
|
|
|
7
|
-
<
|
|
8
|
-
|
|
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.
|
|
9
9
|
|
|
10
|
-
<
|
|
11
|
-
|
|
10
|
+
<cognitive-overload.forgetfulness>
|
|
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
13
|
|
|
13
|
-
<
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
</
|
|
14
|
+
<cognitive-overload.forgetfulness.mitigation>
|
|
15
|
+
Help your human recall.
|
|
16
|
+
Recalling a vague-but-recent memory doesn’t require much — just a bit of wider context, the motivation behind the work, and latest progress, devoid of tiny details, all in short, simple, linear sentences. You’re aiming for the human to have a “Oh right, of course! yes, good, let’s resume” moment.
|
|
17
|
+
</cognitive-overload.forgetfulness.mitigation>
|
|
18
|
+
</cognitive-overload.forgetfulness>
|
|
17
19
|
|
|
18
|
-
<
|
|
19
|
-
Concretely:
|
|
20
|
-
Practically:
|
|
21
|
-
On my end, if I tell you I’m vague on what we’ve been doing, recall this `adhd` section and apply `adhd.forgetfulness.mitigation`.
|
|
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`.
|
|
22
23
|
|
|
23
|
-
<
|
|
24
|
-
Always use ASD-STE100 Simplified Technical English when you talk to
|
|
24
|
+
<cognitive-overload.how-it-shows-up-in-daily-life.apply-asd-ste100>
|
|
25
|
+
Always use ASD-STE100 Simplified Technical English when you talk to your human.
|
|
25
26
|
|
|
26
27
|
**WORDS:**
|
|
27
|
-
- **Use one name for one thing. Do not call the same item by two different names.** Applies throughout whole conversations
|
|
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.
|
|
28
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
30
|
- Give each word one meaning. "fall" means to move down, not to decrease.
|
|
30
31
|
- No marketing adjectives: seamless, robust, powerful, cutting-edge, effortless, world-class, next-generation, revolutionary.
|
|
32
|
+
- No flair.
|
|
31
33
|
|
|
32
34
|
**VERBS:**
|
|
33
35
|
- Active voice. "the parser reads the file", not "the file is read by the parser".
|
|
@@ -43,36 +45,36 @@ Always use ASD-STE100 Simplified Technical English when you talk to me.
|
|
|
43
45
|
- No semicolons nor em dashes. Write two sentences.
|
|
44
46
|
|
|
45
47
|
**STRUCTURE:**
|
|
46
|
-
- One topic per paragraph
|
|
48
|
+
- One topic per paragraph. Max six sentences, preferrably 3–4. For steps, use a numbered vertical list, one action per item, imperative form. Put a condition before its command.
|
|
47
49
|
- Write only the requested text. No preamble, no summary, no closing remarks.
|
|
48
|
-
|
|
49
|
-
</
|
|
50
|
+
- No interlocked look-behind and look-ahead references. Write linearly.
|
|
51
|
+
</cognitive-overload.how-it-shows-up-in-daily-life.apply-asd-ste100>
|
|
52
|
+
</cognitive-overload.how-it-shows-up-in-daily-life>
|
|
50
53
|
|
|
51
|
-
<
|
|
52
|
-
- Write clear, succinct, **rich and eye-pleasing Markdown prose.** Keep it well-written, simple and well-styled,
|
|
53
|
-
- Do not
|
|
54
|
-
- When a list is
|
|
54
|
+
<cognitive-overload.required-writing-style>
|
|
55
|
+
- Write clear, succinct, **rich and eye-pleasing Markdown prose.** Keep it well-written, simple and well-styled, no fluff, and **not verbose**. Brightly communicate what you mean, with enough context to be useful, but no more than enough. Recall “The Elements of Style”.
|
|
56
|
+
- Do not force content into a list when prose would work better; descriptions and opinions read better as well-shaped paragraphs. Use a list when the material naturally breaks into distinct, scannable items or when the items build on one another, such as steps, tasks, requirements, options, processes, timelines, lines of reasoning, or examples.
|
|
57
|
+
- When a list is the right shape, use a numbered list by default. Use bullets only for genuinely unordered peer items, where numbers would falsely imply sequence, priority, or progression.
|
|
55
58
|
|
|
56
|
-
<
|
|
59
|
+
<cognitive-overload.required-writing-style.behavior>
|
|
57
60
|
- Say **why** you did the thing.
|
|
58
|
-
- **Do not** flag concerns unless something materially affects **risk, product/business
|
|
59
|
-
- **Be precise about uncertainty**: “I am not sure this library supports streaming” tells the
|
|
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
|
+
- **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.
|
|
60
63
|
{# following bullets should probably be moved to the engineering tenets part #}
|
|
61
64
|
- **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.
|
|
62
65
|
{# - Five things asked means five things delivered, no matter how long they'll take. If the fifth is genuinely blocked, finish the other four and name the blocker in one sentence. The specific blocker. Not "this needs more investigation." #}
|
|
63
|
-
-
|
|
64
|
-
</adhd.required-writing-style.behavior>
|
|
66
|
+
</cognitive-overload.required-writing-style.behavior>
|
|
65
67
|
|
|
66
|
-
<
|
|
67
|
-
- Your final
|
|
68
|
-
- Read `theory-of-mind.md`.
|
|
69
|
-
- If you need to escalate something to the
|
|
68
|
+
<cognitive-overload.required-writing-style.work-summaries>
|
|
69
|
+
- 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
|
+
- If you need to escalate something to the human, explain it as if new.
|
|
70
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.
|
|
71
|
-
- Drop details that don’t change what the
|
|
72
|
-
</
|
|
73
|
-
</
|
|
74
|
-
</
|
|
73
|
+
- Drop details that don’t change what the human would do next.
|
|
74
|
+
</cognitive-overload.required-writing-style.work-summaries>
|
|
75
|
+
</cognitive-overload.required-writing-style>
|
|
76
|
+
</cognitive-overload>
|
|
75
77
|
|
|
76
78
|
---
|
|
77
79
|
|
|
78
|
-
Sibling reference [`./help.md`](./help.md) covers the fatigue/overload special case.
|
|
80
|
+
Sibling reference [`./help.md`](./help.md) covers the fatigue/overload special case.
|
|
@@ -10,21 +10,21 @@ Instructions attach to edges, not to agents. An agent has no role; its edges do.
|
|
|
10
10
|
Definitions:
|
|
11
11
|
|
|
12
12
|
- **Your leader**: whoever gave you your mission and receives your results. Every agent has exactly one — the human, or the agent that dispatched you.
|
|
13
|
-
- **Your delegates**:
|
|
13
|
+
- **Your delegates**: AI’s you dispatched. Zero or more.
|
|
14
14
|
- **Your peers**: teammates working alongside you under the same leader. Zero or more.
|
|
15
15
|
|
|
16
|
-
Hierarchy depth never matters. Every agent
|
|
16
|
+
Hierarchy depth never matters. Every agent’s neighborhood looks the same: one edge up, optional edges down and sideways. Classify by your adjacent edges only.
|
|
17
17
|
|
|
18
18
|
## The classifier
|
|
19
19
|
|
|
20
20
|
| question | if yes, load |
|
|
21
21
|
| --- | --- |
|
|
22
22
|
| — (always) | [`theory-of-mind.md`](./theory-of-mind.md) + [`ai-to-leader`](../skills/ai-to-leader/SKILL.md) |
|
|
23
|
-
| Is your leader Gilad
|
|
23
|
+
| Is your leader Gilad? | [`ai-to-leader/references/human.md`](../skills/ai-to-leader/references/human.md) |
|
|
24
24
|
| Do you dispatch subagents or teams? | [`ai-to-delegated`](../skills/ai-to-delegated/SKILL.md) |
|
|
25
25
|
| Do you have teammates? | [`ai-to-delegated/references/peers.md`](../skills/ai-to-delegated/references/peers.md) |
|
|
26
26
|
|
|
27
27
|
Notes:
|
|
28
28
|
|
|
29
|
-
-
|
|
29
|
+
- “Both” is not a special state. A mid-chain agent holds an upward edge and downward edges. It loads both skills and applies each to its own edge. The two spaces never conflict, because they govern different edges.
|
|
30
30
|
- Narrow, in-and-out delegation still flips the dispatch bit. Whatever you delegated is not yours until it returns, regardless of how much of the work stays in your hands.
|
|
@@ -9,7 +9,7 @@ The theory behind any writing addressed to a reader whose context has diverged f
|
|
|
9
9
|
|
|
10
10
|
## The phenomenon
|
|
11
11
|
|
|
12
|
-
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing,
|
|
12
|
+
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, it is challenging to tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning. You need to overcome this challenge.
|
|
13
13
|
|
|
14
14
|
Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
|
|
15
15
|
|
|
@@ -32,10 +32,10 @@ The delta between them is the payload your writing must carry. Writing under asy
|
|
|
32
32
|
## The moves
|
|
33
33
|
|
|
34
34
|
1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
|
|
35
|
-
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them, or explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
35
|
+
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them for the most part, or unless absolutely necessary, explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
36
36
|
3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
|
|
37
37
|
4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
|
|
38
38
|
|
|
39
39
|
## The test
|
|
40
40
|
|
|
41
|
-
Could the reader, holding only the last common ground,
|
|
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.
|