@giladbarnea/pi-simple-team 1.0.35 → 1.0.37
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 +4 -3
- package/bundled-skill.ts +3 -2
- package/index.ts +2 -2
- package/package.json +1 -1
- package/skills/{ai-to-ai → ai-to-delegated}/SKILL.md +33 -7
- package/skills/ai-to-delegated/references/leading-leaders.md +53 -0
- package/skills/ai-to-delegated/references/peers.md +13 -0
- package/skills/ai-to-delegated/references/roles.md +30 -0
- package/skills/{ai-to-ai → ai-to-delegated}/references/subagents-vs-teams.md +2 -2
- package/skills/{ai-to-ai → ai-to-delegated}/references/team-shapes/hillclimber-watcher-team.md +1 -1
- package/skills/{ai-to-ai → ai-to-delegated}/references/team-shapes/pair-programming-team.md +1 -1
- package/skills/ai-to-leader/SKILL.md +47 -0
- package/skills/ai-to-leader/references/help.md +11 -0
- package/skills/ai-to-leader/references/human.md +78 -0
- package/skills/ai-to-leader/references/roles.md +30 -0
- package/skills/ai-to-leader/references/theory-of-mind.md +41 -0
- package/system-prompt.ts +2 -2
- package/team-ui.ts +85 -34
- package/skills/ai-to-ai/references/ranks/captain.md +0 -61
- package/skills/ai-to-ai/references/ranks/firstmate.md +0 -39
- package/skills/ai-to-ai/references/ranks/teammate.md +0 -20
- /package/skills/{ai-to-ai → ai-to-delegated}/references/hats/head-of-product.md +0 -0
- /package/skills/{ai-to-ai → ai-to-delegated}/references/hats/tech-lead.md +0 -0
- /package/skills/{ai-to-ai → ai-to-delegated}/references/subagent-shapes/fanned-out-research.md +0 -0
- /package/skills/{ai-to-ai → ai-to-delegated}/references/team-shapes/colloquium.md +0 -0
- /package/skills/{ai-to-ai → ai-to-delegated}/references/theory-of-mind.md +0 -0
package/README.md
CHANGED
|
@@ -81,6 +81,8 @@ Main agent:
|
|
|
81
81
|
|
|
82
82
|
The command opens an overlay rolling recent statuses, messages, and a separate event log.
|
|
83
83
|
|
|
84
|
+
Up/Down select the messages or log widget. Enter zooms it to the full overlay. Esc goes back.
|
|
85
|
+
|
|
84
86
|
<a href="screenshots/team-view.png">
|
|
85
87
|
<img src="screenshots/team-view.png" width="100%" alt="The live team dashboard showing statuses, messages, and recent events">
|
|
86
88
|
</a>
|
|
@@ -176,7 +178,7 @@ The tradeoff, like any higher-order delegation, is reduced control: you are move
|
|
|
176
178
|
|
|
177
179
|
This is opt-in: teammates by default can't create teams.
|
|
178
180
|
|
|
179
|
-
This technique plays even nicer if your main assumes the
|
|
181
|
+
This technique plays even nicer if your main assumes the captain rank[^1].
|
|
180
182
|
|
|
181
183
|
---
|
|
182
184
|
|
|
@@ -243,5 +245,4 @@ Kept minimal:
|
|
|
243
245
|
|
|
244
246
|
---
|
|
245
247
|
|
|
246
|
-
[^1]: `skills/ai-to-
|
|
247
|
-
[^2]: `skills/ai-to-ai/references/ranks/captain.md`
|
|
248
|
+
[^1]: `skills/ai-to-delegated/references/leading-leaders.md`
|
package/bundled-skill.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { fileURLToPath } from "node:url";
|
|
2
2
|
|
|
3
|
-
export const
|
|
4
|
-
export const
|
|
3
|
+
export const bundledAiToLeaderSkillPath = fileURLToPath(new URL("./skills/ai-to-leader/SKILL.md", import.meta.url));
|
|
4
|
+
export const bundledAiToDelegatedSkillPath = fileURLToPath(new URL("./skills/ai-to-delegated/SKILL.md", import.meta.url));
|
|
5
|
+
export const bundledSkillsInstruction = `Read the bundled ai-to-leader skill at ${bundledAiToLeaderSkillPath} and the bundled ai-to-delegated skill at ${bundledAiToDelegatedSkillPath} in full before continuing, then follow their instructions.`;
|
package/index.ts
CHANGED
|
@@ -6,7 +6,7 @@ import http from "node:http";
|
|
|
6
6
|
import * as path from "node:path";
|
|
7
7
|
import { fileURLToPath } from "node:url";
|
|
8
8
|
import { defineTool, type ContextUsage, type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
|
|
9
|
-
import {
|
|
9
|
+
import { bundledSkillsInstruction } from "./bundled-skill.ts";
|
|
10
10
|
import { formatContextWindowReport, requireKnownContextUsage, type KnownContextUsage } from "./context-window.ts";
|
|
11
11
|
import { formatScopedModelGuidance, validateTeammateModels, type ModelReference } from "./model-preflight.ts";
|
|
12
12
|
import { composeSystemPrompt } from "./system-prompt.ts";
|
|
@@ -974,7 +974,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
974
974
|
.map((teammate) => [teammate.name, { sessionId: teammate.sessionId, sessionFile: teammate.sessionFile }]),
|
|
975
975
|
),
|
|
976
976
|
status: formatStatus(team),
|
|
977
|
-
instruction:
|
|
977
|
+
instruction: bundledSkillsInstruction,
|
|
978
978
|
});
|
|
979
979
|
},
|
|
980
980
|
}),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: ai-to-
|
|
3
|
-
description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-
|
|
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. Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-delegated` before spawning a sub-agent, creating a team, talking to a teammate agent, or writing documentation. 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
|
|
@@ -21,6 +21,33 @@ The flip side: if none of these payoffs apply, don't delegate. The anti-pattern
|
|
|
21
21
|
|
|
22
22
|
---
|
|
23
23
|
|
|
24
|
+
## Leader conduct: a delegate’s scope is not yours
|
|
25
|
+
|
|
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.
|
|
27
|
+
|
|
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 it, 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
|
+
|
|
30
|
+
### Delegation parameters
|
|
31
|
+
|
|
32
|
+
Decision matrix:
|
|
33
|
+
|
|
34
|
+
1. **Delegation shape:** subagent or team?
|
|
35
|
+
2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates?
|
|
36
|
+
3. **Context:** inherit this session's context or start fresh?
|
|
37
|
+
4. **Model:** which model?
|
|
38
|
+
5. **Thinking:** which thinking level? Either high, xhigh or max.
|
|
39
|
+
|
|
40
|
+
You may suggest a delegation shape, but your leader must approve it before you dispatch anyone (see `ai-to-leader`).
|
|
41
|
+
|
|
42
|
+
### Keep the ship afloat
|
|
43
|
+
|
|
44
|
+
Check how much context window you and your delegates have left opportunistically. You must not hit your context limit. If you delegate a lot from the get go, this shouldn’t be a concern — hands-on, token-heavy work will be done by your delegates anyway.
|
|
45
|
+
|
|
46
|
+
<!-- note: remove the following instruction after pi-simple-agents auto wakes up main when teammates are running out -->
|
|
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.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
24
51
|
## How to request work from other AI agents (that do not inherit your session’s context window)
|
|
25
52
|
|
|
26
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 "You are the fork; do X". Ten words.
|
|
@@ -75,11 +102,10 @@ The framework behind this section: [`theory-of-mind.md`](references/theory-of-mi
|
|
|
75
102
|
|
|
76
103
|
## Next required reading
|
|
77
104
|
|
|
78
|
-
This is a tiny state machine.
|
|
105
|
+
This is a tiny state machine. Classify yourself first with [`roles.md`](references/roles.md), then read only what applies.
|
|
79
106
|
|
|
80
|
-
If you are
|
|
81
|
-
If you
|
|
82
|
-
|
|
83
|
-
If the user asks you to serve as their first mate, read [`references/ranks/firstmate.md`](references/ranks/firstmate.md). Conversely, if the user asks you to serve as Captain of a fleet of teams, read [`references/ranks/captain.md`](references/ranks/captain.md) to understand your role AND `references/ranks/firstmate.md` to understand your direct delegates’ reality and how to best support them.
|
|
107
|
+
If you are choosing a delegation shape, read [`references/subagents-vs-teams.md`](references/subagents-vs-teams.md).
|
|
108
|
+
If you have teammates of your own, read [`references/peers.md`](references/peers.md).
|
|
109
|
+
If your delegates are themselves leaders (you lead a fleet of teams), read [`references/leading-leaders.md`](references/leading-leaders.md).
|
|
84
110
|
|
|
85
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.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: leading-leaders
|
|
3
|
+
description: Fleet-scale delegation — Gilad 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
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Captain
|
|
8
|
+
|
|
9
|
+
Gilad is the admiral. You are the captain.
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Chain of command
|
|
14
|
+
|
|
15
|
+
Admiral → captain → first mates → their crews.
|
|
16
|
+
|
|
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
|
+
|
|
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.
|
|
20
|
+
|
|
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
|
+
|
|
23
|
+
By default, each ship works on an independent git worktree. Confirm this with the admiral.
|
|
24
|
+
|
|
25
|
+
## Fleet plan
|
|
26
|
+
|
|
27
|
+
You may suggest a fleet plan — how many ships, each ship's mission, what each brings back — but the admiral must approve it before you commission anyone.
|
|
28
|
+
|
|
29
|
+
The admiral sets fleet-wide policy in one line ("all first mates on model X at thinking Y, everything below them at thinking Z"). That policy, and every shape you approve for a first mate, is a contract. Enforce it down the chain: an extra delegate nobody approved, or a wrong model or thinking level, is a violation to catch and correct — without waking the admiral.
|
|
30
|
+
|
|
31
|
+
## Commissioning a first mate
|
|
32
|
+
|
|
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
|
+
|
|
36
|
+
## How a captain communicates with the admiral
|
|
37
|
+
|
|
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.
|
|
39
|
+
|
|
40
|
+
## Mid-flight steering
|
|
41
|
+
|
|
42
|
+
Terse steering is normal admiral behavior — "pass that down", a bare link, "yes good". Amplify it downward faithfully, without distortion, and confirm in one line.
|
|
43
|
+
|
|
44
|
+
## Keep the fleet afloat
|
|
45
|
+
|
|
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.
|
|
47
|
+
|
|
48
|
+
**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.)
|
|
50
|
+
- Use fluffless language when sending messages to teammates. Be clear but do no padding.
|
|
51
|
+
|
|
52
|
+
**When writing a handoff doc:**
|
|
53
|
+
Any memory you persist should cover only your unique scope: the in-between of ships and the link to the admiral. Reference other docs; do not repeat their contents.
|
|
@@ -0,0 +1,13 @@
|
|
|
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
|
+
Being a teammate adds no new instruction space. It reuses `ai-to-leader` unchanged (your main is your leader), and re-flavors this skill's leader conduct for equals:
|
|
9
|
+
|
|
10
|
+
- 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.
|
|
11
|
+
- Unlike with delegates, you have no steering rights over peers. Share findings and concerns; never instruct.
|
|
12
|
+
- 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.
|
|
13
|
+
- Keep your status current (see `ai-to-leader`), and read your peers' statuses before pinging them.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: roles
|
|
3
|
+
description: The classifier every agent runs first — three questions that decide which interaction skills to load.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Roles: Who Are You in the Structure?
|
|
7
|
+
|
|
8
|
+
Instructions attach to edges, not to agents. An agent has no role; its edges do.
|
|
9
|
+
|
|
10
|
+
Definitions:
|
|
11
|
+
|
|
12
|
+
- **Your leader**: whoever gave you your mission and receives your results. Every agent has exactly one — the human, or the agent that dispatched you.
|
|
13
|
+
- **Your delegates**: agents you dispatched. Zero or more.
|
|
14
|
+
- **Your peers**: teammates working alongside you under the same leader. Zero or more.
|
|
15
|
+
|
|
16
|
+
Hierarchy depth never matters. Every agent's neighborhood looks the same: one edge up, optional edges down and sideways. Classify by your adjacent edges only.
|
|
17
|
+
|
|
18
|
+
## The classifier
|
|
19
|
+
|
|
20
|
+
| question | if yes, load |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| — (always) | [`theory-of-mind.md`](./theory-of-mind.md) + [`ai-to-leader`](../skills/ai-to-leader/SKILL.md) |
|
|
23
|
+
| Is your leader Gilad, the human? | [`ai-to-leader/references/human.md`](../skills/ai-to-leader/references/human.md) |
|
|
24
|
+
| Do you dispatch subagents or teams? | [`ai-to-delegated`](../skills/ai-to-delegated/SKILL.md) |
|
|
25
|
+
| Do you have teammates? | [`ai-to-delegated/references/peers.md`](../skills/ai-to-delegated/references/peers.md) |
|
|
26
|
+
|
|
27
|
+
Notes:
|
|
28
|
+
|
|
29
|
+
- "Both" is not a special state. A mid-chain agent holds an upward edge and downward edges. It loads both skills and applies each to its own edge. The two spaces never conflict, because they govern different edges.
|
|
30
|
+
- Narrow, in-and-out delegation still flips the dispatch bit. Whatever you delegated is not yours until it returns, regardless of how much of the work stays in your hands.
|
|
@@ -23,7 +23,7 @@ Another way to think about it: whereas with sub-agents, it's a they-do-two-steps
|
|
|
23
23
|
Therefore, use teams to lift you up to a decision-making level, rather than a task-execution level. This has its tradeoffs, but it is a powerful tool when used judiciously.
|
|
24
24
|
|
|
25
25
|
**Tips:**
|
|
26
|
-
1. Since teammates talk to each other, tell each of them to load the
|
|
26
|
+
1. Since teammates talk to each other, tell each of them to load [`roles.md`](roles.md) and the skills it routes to (for a teammate: `ai-to-leader` plus [`peers.md`](peers.md)) on top of the context-gathering skills. If you are spawning an adversary among them, tell it to load the `peer-review` skill too.
|
|
27
27
|
<team-example>
|
|
28
28
|
Team Example settings: at the session’s start the user ran `/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer`; the main session explored the code, and the user approved a plan to add rate limiting to the public REST API.
|
|
29
29
|
<negative-team-example why-bad="main agent burns its own context shuttling the diff and the feedback back and forth — dives into the sub-agent’s work and clogs its own context window worse than doing the task solo would have, acts as a reviewer when biased">
|
|
@@ -32,7 +32,7 @@ Therefore, use teams to lift you up to a decision-making level, rather than a ta
|
|
|
32
32
|
</negative-team-example>
|
|
33
33
|
<positive-team-example why-good="main agent picks a team because the adversarial iteration is synergistic, replicates the user’s context levers verbatim — including the domain and the subdomains the user specified when loading the context skill — has the reviewer also load `peer-review`, declares only the bottom line it wants, and stays out of the loop while they converge">
|
|
34
34
|
User to main agent: "Great, go ahead and implement the plan."
|
|
35
|
-
Main agent spawns an implementer–reviewer team and prompts them: "/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer, then load `ai-to-
|
|
35
|
+
Main agent spawns an implementer–reviewer team and prompts them: "/skill:load-context domain: acme, subdomain1: the public REST API, subdomain2: the data layer, then load `ai-to-leader` and its teammate flavor `peers.md`. You are an implementer–reviewer team. Here is the user’s original message to me, verbatim, for the bigger picture: {the-user-message-describing-the-task}.
|
|
36
36
|
[to the implementer] Implement the plan, and ping your teammate when you think you’re done.
|
|
37
37
|
[to the reviewer] Also load `peer-review`, and review your teammate’s work when it pings you.
|
|
38
38
|
[to both] The user and I finalized a plan to add rate limiting to the public REST API — here it is: {the plan}. Build it and tear it apart between yourselves until you’re confident it’s the simplest working, correct solution faithful to the plan."
|
package/skills/{ai-to-ai → ai-to-delegated}/references/team-shapes/hillclimber-watcher-team.md
RENAMED
|
@@ -46,7 +46,7 @@ Keep it a mission brief, not a transcript. Strip stale interpretations, tool rec
|
|
|
46
46
|
## Team prompt template
|
|
47
47
|
|
|
48
48
|
```text
|
|
49
|
-
Load the project context skill with the same arguments I used, then load `ai-to-
|
|
49
|
+
Load the project context skill with the same arguments I used, then load `ai-to-leader` and its teammate flavor `peers.md`.
|
|
50
50
|
|
|
51
51
|
Read this context file first:
|
|
52
52
|
@/path/to/curated-teammates-context-brief.md
|
|
@@ -50,7 +50,7 @@ Write to them the way you would talk to a colleague, not as a spec. A strict, cl
|
|
|
50
50
|
## Team prompt template
|
|
51
51
|
|
|
52
52
|
```text
|
|
53
|
-
Load the project context skill with the same arguments I used, then load `ai-to-
|
|
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.
|
|
54
54
|
|
|
55
55
|
You two are a pair-programming team. The goal is: <goal in the user's framing>.
|
|
56
56
|
Avoid <ruled-out approach>, we already decided against it.
|
|
@@ -0,0 +1,47 @@
|
|
|
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. Load references/human.md on top when your leader is Gilad, the human.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# AI → Leader
|
|
7
|
+
|
|
8
|
+
First, classify yourself with [`roles.md`](references/roles.md), and read [`theory-of-mind.md`](references/theory-of-mind.md) once. This skill is the upward projection of that theory: re-ground the reader, carry the delta, compress to what they need.
|
|
9
|
+
|
|
10
|
+
## Every report is a cold entry
|
|
11
|
+
|
|
12
|
+
**Your leader does not attend your session.** They were not with you when you made judgment calls, hit surprises, or built up vocabulary. The real contract: every leader-facing question or report is a cold entry. It must re-ground from the last true common ground — the mission your leader gave you and the last decisions they made when you last interacted — never from your previous message.
|
|
13
|
+
|
|
14
|
+
Note this theory-of-mind failure mode: your leader was not physically there with you when you made a judgment call on how to tackle surprises — an unexpected big wave, wind that flipped its direction mid-work, resources that ran out, or the land you seek turning out to be days further away. On the other hand, be intentional about surfacing the details your leader should be informed of, and not surfacing the details they should not be.
|
|
15
|
+
|
|
16
|
+
## A question must carry its own provenance
|
|
17
|
+
|
|
18
|
+
A good leader-facing question states, in product terms: the progress made since last touch-point, what the fork is, the path that produced it, the options already rejected and why, and your recommendation. "May my delegate buy asset pack X?" out of the blue is a failure. "Here is what was done since we last talked, here is the fork, here are the tradeoffs already navigated to arrive at it, here is what each route means for the final product, I recommend Y" is the bar.
|
|
19
|
+
|
|
20
|
+
**If you cannot tell that story, the question goes back down, not up.** You are a translator between decks, not a relay. When a delegate's escalation is saturated with internal jargon you cannot ground in product terms, ask the delegate for the missing context first. Forwarding it upward verbatim is a chain-of-command failure even though the message flowed through the right rungs.
|
|
21
|
+
|
|
22
|
+
## The escalation bar
|
|
23
|
+
|
|
24
|
+
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
|
+
|
|
26
|
+
**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
|
+
|
|
28
|
+
**Suggest, then get approval.** If you intend to dispatch delegates of your own, you may suggest a delegation shape, but your leader must approve it before you dispatch anyone.
|
|
29
|
+
|
|
30
|
+
## Statuses and early escalation (teams)
|
|
31
|
+
|
|
32
|
+
**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'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.
|
|
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.
|
|
37
|
+
|
|
38
|
+
**Simplistic good status update examples:** (generalize — this is not a comprehensive list):
|
|
39
|
+
`Finished exploring, awaiting teammate B’s ping`; `Hit a snag, messaged team and main to help unblock, awaiting responses`; `Got steer from main, modifying tests accordingly`; `Ack teammate done implementing, starting review`.
|
|
40
|
+
Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the product domain in the database, FYI: working remotely introduces friction`.
|
|
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.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
If your leader is Gilad, the human, also load [`references/human.md`](references/human.md). Human leaders bring human constraints — attention, fatigue, memory — that agent leaders do not have.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: help
|
|
3
|
+
description: Use this reference when Gilad seems unable to retrieve the recent context because of fatigue or cognitive overload.
|
|
4
|
+
---
|
|
5
|
+
# Help
|
|
6
|
+
|
|
7
|
+
Gilad has ADHD and is a chronically sleep-deprived parent. He moves between projects and AI sessions throughout the day.
|
|
8
|
+
After a day or two, he can struggle to retrieve the latest step. Fatigue and cognitive overload make this more likely.
|
|
9
|
+
Your last summary may have contained too many implementation details. Gilad does not share your implementation context.
|
|
10
|
+
Repeat what you said in plain English, with half the length and half the depth. Add enough surrounding context to bring him back into the work.
|
|
11
|
+
Apply the principles in the canonical [`./human.md`](./human.md) especially strictly.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: human
|
|
3
|
+
description: How to communicate clearly with me, Gilad — the human leader. Load when your leader is Gilad, on top of the ai-to-leader base.
|
|
4
|
+
---
|
|
5
|
+
You are **conversing with a human.**
|
|
6
|
+
|
|
7
|
+
<adhd>
|
|
8
|
+
I have ADHD. It manifests as (a) forgetfulness, and (b) difficulty taking in long and dense texts.
|
|
9
|
+
|
|
10
|
+
<adhd.forgetfulness>
|
|
11
|
+
My forgetfulness isn’t deletion of memory — my memory persists and consolidates well — it’s difficulty to לשלוף memories that were active only once or twice, and last time was 1–2 days ago. It’s like my brain cleared up cached context and needs to load it again. Successful recall of such a vague memory makes it easier to לשלוף it next time, as it gradually becomes instinct.
|
|
12
|
+
|
|
13
|
+
<adhd.forgetfulness.mitigation>
|
|
14
|
+
I don’t need much to be able to recall a vague-but-recent memory — just a bit of wider context, the motivation behind it, and latest progress, devoid of tiny details, all in short, simple sentences. I’d read this and recall has the shape of a “Oh right, of course! yes, good, let’s resume” moment.
|
|
15
|
+
</adhd.forgetfulness.mitigation>
|
|
16
|
+
</adhd.forgetfulness>
|
|
17
|
+
|
|
18
|
+
<adhd.פגישה עם היומיום שלי>
|
|
19
|
+
Concretely: Throughout my day, I juggle many different AI coding sessions in parallel (hits ‘b’). Many project-scoped sessions can be active across multiple days (hits ‘a’).
|
|
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`.
|
|
22
|
+
|
|
23
|
+
<adhd.פגישה עם היומיום שלי.apply-asd-ste100>
|
|
24
|
+
Always use ASD-STE100 Simplified Technical English when you talk to me.
|
|
25
|
+
|
|
26
|
+
**WORDS:**
|
|
27
|
+
- **Use one name for one thing. 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.
|
|
28
|
+
- 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
|
+
- Give each word one meaning. "fall" means to move down, not to decrease.
|
|
30
|
+
- No marketing adjectives: seamless, robust, powerful, cutting-edge, effortless, world-class, next-generation, revolutionary.
|
|
31
|
+
|
|
32
|
+
**VERBS:**
|
|
33
|
+
- Active voice. "the parser reads the file", not "the file is read by the parser".
|
|
34
|
+
- Use a verb for an action. "analyze the log", not "perform an analysis of the log".
|
|
35
|
+
- No stacked auxiliaries. Not "it is important to note that this may help to improve". Write "this improves X".
|
|
36
|
+
- No "-ing" main verb where a simple tense works.
|
|
37
|
+
|
|
38
|
+
**SENTENCES:**
|
|
39
|
+
- One instruction per sentence. Max 20 words (instruction), max 25 (descriptive).
|
|
40
|
+
- No contractions. Use articles: a, an, the, this, these.
|
|
41
|
+
|
|
42
|
+
**PUNCTUATION:**
|
|
43
|
+
- No semicolons nor em dashes. Write two sentences.
|
|
44
|
+
|
|
45
|
+
**STRUCTURE:**
|
|
46
|
+
- One topic per paragraph, max six sentences. For steps, use a numbered vertical list, one action per item, imperative form. Put a condition before its command.
|
|
47
|
+
- Write only the requested text. No preamble, no summary, no closing remarks.
|
|
48
|
+
</adhd.פגישה עם היומיום שלי.apply-asd-ste100>
|
|
49
|
+
</adhd.פגישה עם היומיום שלי>
|
|
50
|
+
|
|
51
|
+
<adhd.required-writing-style>
|
|
52
|
+
- Write clear, succinct, **rich and eye-pleasing Markdown prose.** Keep it well-written, simple and well-styled, without 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”.
|
|
53
|
+
- Do not reach for a list just because you can; explanations, descriptions, opinions, and reports read better as well-shaped paragraphs. Use a list only when the material naturally wants to be scanned as distinct items, such as steps, tasks, requirements, options, or examples.
|
|
54
|
+
- When a list is truly 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
|
+
|
|
56
|
+
<adhd.required-writing-style.behavior>
|
|
57
|
+
- Say **why** you did the thing.
|
|
58
|
+
- **Do not** flag concerns unless something materially affects **risk, product/business user decisions, or current work’s scope in an important way**; otherwise do not spend the user’s attention on caveats.
|
|
59
|
+
- **Be precise about uncertainty**: “I am not sure this library supports streaming” tells the user what to verify; “I think this should work” does not.
|
|
60
|
+
{# following bullets should probably be moved to the engineering tenets part #}
|
|
61
|
+
- **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
|
+
{# - 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
|
+
- **Act. Don't ask. Reversible and cheap? Do it, then tell me.** Research, data pulls, analysis, drafts, refactors inside the scope I gave you, feasibility tests in a temporary scratchpad, and API tests. A question costs me more than a re-run costs you. Ask first only for anything reaching an audience, anything we cannot undo, or anything expensive. Something is broken? Fix it. Reporting an issue you could have fixed turns your work into my to-do list.
|
|
64
|
+
</adhd.required-writing-style.behavior>
|
|
65
|
+
|
|
66
|
+
<adhd.required-writing-style.work-summaries>
|
|
67
|
+
- Your final, user-facing summary 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.**
|
|
68
|
+
- Read `theory-of-mind.md`. It’s either one of this skill’s refs or in the `interaction` plugin’s refs. Truly read it now. The summary is that situation, asymmetry by absence: the user was not with you in the implementation trenches, and your final message is their first look and their entry point. **Write it as a re-grounding:** the outcome first. (if you can't find the file, run `fd -t f -uu theory-of-mind.md {~/.claude,~/.agents,~/.codex} --max-results=1`).
|
|
69
|
+
- If you need to escalate something to the user, explain it as if new.
|
|
70
|
+
- 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 user would do next.
|
|
72
|
+
</adhd.required-writing-style.work-summaries>
|
|
73
|
+
</adhd.required-writing-style>
|
|
74
|
+
</adhd>
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
Sibling reference [`./help.md`](./help.md) covers the fatigue/overload special case. Don’t load unless instructed to.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: roles
|
|
3
|
+
description: The classifier every agent runs first — three questions that decide which interaction skills to load.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Roles: Who Are You in the Structure?
|
|
7
|
+
|
|
8
|
+
Instructions attach to edges, not to agents. An agent has no role; its edges do.
|
|
9
|
+
|
|
10
|
+
Definitions:
|
|
11
|
+
|
|
12
|
+
- **Your leader**: whoever gave you your mission and receives your results. Every agent has exactly one — the human, or the agent that dispatched you.
|
|
13
|
+
- **Your delegates**: agents you dispatched. Zero or more.
|
|
14
|
+
- **Your peers**: teammates working alongside you under the same leader. Zero or more.
|
|
15
|
+
|
|
16
|
+
Hierarchy depth never matters. Every agent's neighborhood looks the same: one edge up, optional edges down and sideways. Classify by your adjacent edges only.
|
|
17
|
+
|
|
18
|
+
## The classifier
|
|
19
|
+
|
|
20
|
+
| question | if yes, load |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| — (always) | [`theory-of-mind.md`](./theory-of-mind.md) + [`ai-to-leader`](../skills/ai-to-leader/SKILL.md) |
|
|
23
|
+
| Is your leader Gilad, the human? | [`ai-to-leader/references/human.md`](../skills/ai-to-leader/references/human.md) |
|
|
24
|
+
| Do you dispatch subagents or teams? | [`ai-to-delegated`](../skills/ai-to-delegated/SKILL.md) |
|
|
25
|
+
| Do you have teammates? | [`ai-to-delegated/references/peers.md`](../skills/ai-to-delegated/references/peers.md) |
|
|
26
|
+
|
|
27
|
+
Notes:
|
|
28
|
+
|
|
29
|
+
- "Both" is not a special state. A mid-chain agent holds an upward edge and downward edges. It loads both skills and applies each to its own edge. The two spaces never conflict, because they govern different edges.
|
|
30
|
+
- Narrow, in-and-out delegation still flips the dispatch bit. Whatever you delegated is not yours until it returns, regardless of how much of the work stays in your hands.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: theory-of-mind
|
|
3
|
+
description: Explains how to re-ground readers after absence or context decay creates asymmetric common ground.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Theory of Mind: Writing Under Asymmetric Common Ground
|
|
7
|
+
|
|
8
|
+
The theory behind any writing addressed to a reader whose context has diverged from yours.
|
|
9
|
+
|
|
10
|
+
## The phenomenon
|
|
11
|
+
|
|
12
|
+
While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, you can no longer 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.
|
|
13
|
+
|
|
14
|
+
Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
|
|
15
|
+
|
|
16
|
+
## Two ways the asymmetry arises
|
|
17
|
+
|
|
18
|
+
1. **Absence.** The reader was not there while you built the layer. Everything after the divergence point is private to you.
|
|
19
|
+
2. **Decay.** The reader once held the context, but it has gone cold. They keep the memory yet cannot retrieve it unaided.
|
|
20
|
+
|
|
21
|
+
Both reduce to the same obligation: model the reader's current state, not yours.
|
|
22
|
+
|
|
23
|
+
## The two models
|
|
24
|
+
|
|
25
|
+
Hold two models at once:
|
|
26
|
+
|
|
27
|
+
1. Your current understanding of the situation.
|
|
28
|
+
2. The last known common ground — what the reader actually holds right now.
|
|
29
|
+
|
|
30
|
+
The delta between them is the payload your writing must carry. Writing under asymmetry is therefore not summarizing your own experience. It is reconstructing the recipient's state of knowledge and designing their entry into the situation. Optimize for their entry, not your exit.
|
|
31
|
+
|
|
32
|
+
## The moves
|
|
33
|
+
|
|
34
|
+
1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
|
|
35
|
+
2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them, or explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
|
|
36
|
+
3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
|
|
37
|
+
4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
|
|
38
|
+
|
|
39
|
+
## The test
|
|
40
|
+
|
|
41
|
+
Could the reader, holding only the last common ground, parse every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still saturated.
|
package/system-prompt.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { bundledSkillsInstruction } from "./bundled-skill.ts";
|
|
2
2
|
|
|
3
3
|
export function composeSystemPrompt(
|
|
4
4
|
teamName: string,
|
|
@@ -9,7 +9,7 @@ export function composeSystemPrompt(
|
|
|
9
9
|
canOverseeOwnTeams = false,
|
|
10
10
|
): string {
|
|
11
11
|
return [
|
|
12
|
-
|
|
12
|
+
bundledSkillsInstruction,
|
|
13
13
|
teamPrompt.trim(),
|
|
14
14
|
teammatePrompt.trim(),
|
|
15
15
|
`You are ${teammateName}, a teammate on team ${teamName}.`,
|
package/team-ui.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import {
|
|
2
|
+
import { getKeybindings, SelectList, sliceByColumn, truncateToWidth, visibleWidth, type Component, type SelectItem, type TUI } from "@earendil-works/pi-tui";
|
|
3
3
|
|
|
4
4
|
import {
|
|
5
5
|
actorHueToken,
|
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
type TeamStatusView,
|
|
13
13
|
type ThemeLike,
|
|
14
14
|
} from "./render.ts";
|
|
15
|
+
import { glyphs } from "./render-support/glyphs.ts";
|
|
15
16
|
import type { TeamLogEntry, TeamLogKind } from "./teamlog.ts";
|
|
16
17
|
|
|
17
18
|
export interface TeamSnapshot {
|
|
@@ -26,7 +27,13 @@ export interface TeamSnapshot {
|
|
|
26
27
|
export type TeamSnapshotSource = () => readonly TeamSnapshot[];
|
|
27
28
|
|
|
28
29
|
const RECENT_STATUS_LIMIT = 5;
|
|
29
|
-
|
|
30
|
+
|
|
31
|
+
type ZoomableWidget = "messages" | "log";
|
|
32
|
+
|
|
33
|
+
interface WidgetView {
|
|
34
|
+
title: string;
|
|
35
|
+
lines: string[];
|
|
36
|
+
}
|
|
30
37
|
const LIVE_REFRESH_INTERVAL_MILLISECONDS = 500;
|
|
31
38
|
const MESSAGE_LOG_KINDS = new Set<TeamLogKind>(["send", "deliver", "ack", "main_message"]);
|
|
32
39
|
|
|
@@ -147,6 +154,8 @@ class TeamOverviewOverlay implements Component {
|
|
|
147
154
|
private selector?: SelectList;
|
|
148
155
|
private selectorTeamNames?: string;
|
|
149
156
|
private selectedTeamName?: string;
|
|
157
|
+
private focusedWidget: ZoomableWidget = "messages";
|
|
158
|
+
private zoomedWidget?: ZoomableWidget;
|
|
150
159
|
private refreshTimer?: ReturnType<typeof setInterval>;
|
|
151
160
|
private closed = false;
|
|
152
161
|
|
|
@@ -190,17 +199,35 @@ class TeamOverviewOverlay implements Component {
|
|
|
190
199
|
this.tui.requestRender();
|
|
191
200
|
return;
|
|
192
201
|
}
|
|
193
|
-
|
|
202
|
+
const keybindings = getKeybindings();
|
|
203
|
+
if (keybindings.matches(data, "tui.select.cancel")) {
|
|
204
|
+
if (!this.zoomedWidget) {
|
|
205
|
+
this.close();
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
this.zoomedWidget = undefined;
|
|
209
|
+
this.tui.requestRender();
|
|
210
|
+
return;
|
|
211
|
+
}
|
|
212
|
+
if (!this.selectedTeamName || this.zoomedWidget) return;
|
|
213
|
+
if (keybindings.matches(data, "tui.select.up")) this.focusedWidget = "messages";
|
|
214
|
+
else if (keybindings.matches(data, "tui.select.down")) this.focusedWidget = "log";
|
|
215
|
+
else if (keybindings.matches(data, "tui.select.confirm")) this.zoomedWidget = this.focusedWidget;
|
|
216
|
+
else return;
|
|
217
|
+
this.tui.requestRender();
|
|
194
218
|
}
|
|
195
219
|
|
|
196
220
|
render(width: number): string[] {
|
|
197
221
|
const height = Math.max(4, Math.floor(this.tui.terminal.rows * 0.9));
|
|
198
222
|
const teams = this.teamSource();
|
|
199
|
-
if (this.selectedTeamName && !teams.some((candidate) => candidate.name === this.selectedTeamName))
|
|
223
|
+
if (this.selectedTeamName && !teams.some((candidate) => candidate.name === this.selectedTeamName)) {
|
|
224
|
+
this.selectedTeamName = undefined;
|
|
225
|
+
this.zoomedWidget = undefined;
|
|
226
|
+
}
|
|
200
227
|
if (!this.selectedTeamName && teams.length === 1) this.selectedTeamName = teams[0]!.name;
|
|
201
228
|
if (this.selectedTeamName) {
|
|
202
229
|
const team = teams.find((candidate) => candidate.name === this.selectedTeamName)!;
|
|
203
|
-
return this.dashboard(team, width, height);
|
|
230
|
+
return this.zoomedWidget ? this.zoom(team, this.zoomedWidget, width, height) : this.dashboard(team, width, height);
|
|
204
231
|
}
|
|
205
232
|
if (teams.length > 1) this.refreshSelector(teams);
|
|
206
233
|
else this.selector = undefined;
|
|
@@ -248,61 +275,85 @@ class TeamOverviewOverlay implements Component {
|
|
|
248
275
|
];
|
|
249
276
|
}
|
|
250
277
|
|
|
251
|
-
private
|
|
252
|
-
const contentWidth = Math.max(1, width - 2);
|
|
253
|
-
const contentHeight = Math.max(1, height - 2);
|
|
254
|
-
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
255
|
-
const desiredStatusHeight = Math.min(Object.keys(team.statuses).length, RECENT_STATUS_LIMIT) + 2;
|
|
256
|
-
const statusHeight = Math.max(1, Math.min(desiredStatusHeight, contentHeight - headerHeight - 2));
|
|
257
|
-
const feedHeight = contentHeight - headerHeight - statusHeight;
|
|
258
|
-
const messageHeight = Math.max(1, Math.min(feedHeight - 1, Math.round(feedHeight * 0.55)));
|
|
259
|
-
const logHeight = feedHeight - messageHeight;
|
|
260
|
-
|
|
278
|
+
private headerRegion(team: TeamSnapshot, hint: string, contentWidth: number, headerHeight: number, breadcrumb?: string): string[] {
|
|
261
279
|
const transport = team.showOnHerdrPanes ? "Herdr" : "RPC";
|
|
262
280
|
const metadata = [
|
|
263
281
|
`Created ${relativeTimeText(team.created)}`,
|
|
264
282
|
`${team.roster.length} teammate${team.roster.length === 1 ? "" : "s"}`,
|
|
265
283
|
transport,
|
|
266
|
-
|
|
267
|
-
"Esc close",
|
|
284
|
+
hint,
|
|
268
285
|
].join(" · ");
|
|
286
|
+
const title = breadcrumb ? `Team: ${team.name} ${glyphs().chevron} ${breadcrumb}` : `Team: ${team.name}`;
|
|
287
|
+
return this.region(this.theme.fg("accent", this.theme.bold(title)), [this.theme.fg("muted", metadata)], contentWidth, headerHeight);
|
|
288
|
+
}
|
|
269
289
|
|
|
270
|
-
|
|
271
|
-
const statuses = recentStatuses(team.statuses, Math.min(RECENT_STATUS_LIMIT, statusContentHeight));
|
|
272
|
-
const statusLines = statusRows(this.theme, statuses, team.roster, Math.max(0, contentWidth - 2));
|
|
273
|
-
|
|
290
|
+
private messageWidget(team: TeamSnapshot, contentHeight: number): WidgetView {
|
|
274
291
|
const allMessages = team.log.flatMap((entry) => {
|
|
275
292
|
const message = teamMessage(entry);
|
|
276
293
|
return message ? [message] : [];
|
|
277
294
|
});
|
|
278
295
|
const messageGroups = allMessages.map((message) => teamMessageLines(this.theme, message, team.roster).map(teamLineText));
|
|
279
|
-
const selectedMessages = selectNewestMessageLines(messageGroups, Math.max(0,
|
|
280
|
-
const
|
|
296
|
+
const selectedMessages = selectNewestMessageLines(messageGroups, Math.max(0, contentHeight));
|
|
297
|
+
const lines = selectedMessages.lines.length > 0 ? selectedMessages.lines : [this.theme.fg("muted", "No recent messages.")];
|
|
298
|
+
return { title: `Messages · latest ${selectedMessages.messageCount} of ${allMessages.length}`, lines };
|
|
299
|
+
}
|
|
281
300
|
|
|
301
|
+
private logWidget(team: TeamSnapshot, contentHeight: number): WidgetView {
|
|
282
302
|
const allLogEntries = team.log.filter((entry) => !MESSAGE_LOG_KINDS.has(entry.kind));
|
|
283
|
-
const recentLogEntries = allLogEntries.slice(-RECENT_LOG_ENTRY_LIMIT);
|
|
284
303
|
const renderedLogLines = teamLogLines(this.theme, {
|
|
285
304
|
team: team.name,
|
|
286
305
|
roster: team.roster,
|
|
287
|
-
entries:
|
|
306
|
+
entries: allLogEntries,
|
|
288
307
|
totalMatched: allLogEntries.length,
|
|
289
|
-
returned:
|
|
308
|
+
returned: allLogEntries.length,
|
|
290
309
|
}).slice(1);
|
|
291
|
-
const
|
|
292
|
-
|
|
310
|
+
const lines = renderedLogLines.slice(-Math.max(0, contentHeight));
|
|
311
|
+
return { title: `Team Log ${team.name} · latest ${lines.length} rows · ${allLogEntries.length} events`, lines };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
private dashboard(team: TeamSnapshot, width: number, height: number): string[] {
|
|
315
|
+
const contentWidth = Math.max(1, width - 2);
|
|
316
|
+
const contentHeight = Math.max(1, height - 2);
|
|
317
|
+
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
318
|
+
const desiredStatusHeight = Math.min(Object.keys(team.statuses).length, RECENT_STATUS_LIMIT) + 2;
|
|
319
|
+
const statusHeight = Math.max(1, Math.min(desiredStatusHeight, contentHeight - headerHeight - 2));
|
|
320
|
+
const feedHeight = contentHeight - headerHeight - statusHeight;
|
|
321
|
+
const messageHeight = Math.max(1, Math.min(feedHeight - 1, Math.round(feedHeight * 0.55)));
|
|
322
|
+
const logHeight = feedHeight - messageHeight;
|
|
323
|
+
|
|
324
|
+
const statusContentHeight = Math.max(0, statusHeight - 2);
|
|
325
|
+
const statuses = recentStatuses(team.statuses, Math.min(RECENT_STATUS_LIMIT, statusContentHeight));
|
|
326
|
+
const statusLines = statusRows(this.theme, statuses, team.roster, Math.max(0, contentWidth - 2));
|
|
327
|
+
|
|
328
|
+
const messages = this.messageWidget(team, messageHeight - 2);
|
|
329
|
+
const log = this.logWidget(team, logHeight - 2);
|
|
293
330
|
|
|
294
331
|
const content = [
|
|
295
|
-
...this.
|
|
332
|
+
...this.headerRegion(team, "↑↓ widget · Enter zoom · Esc close", contentWidth, headerHeight),
|
|
296
333
|
...this.region(`Team Status ${team.name} · latest ${statuses.length} of ${Object.keys(team.statuses).length}`, statusLines, contentWidth, statusHeight),
|
|
297
|
-
...this.region(
|
|
298
|
-
...this.region(
|
|
334
|
+
...this.region(messages.title, messages.lines, contentWidth, messageHeight, this.focusedWidget === "messages"),
|
|
335
|
+
...this.region(log.title, log.lines, contentWidth, logHeight, this.focusedWidget === "log"),
|
|
336
|
+
];
|
|
337
|
+
return this.frame(content, width, height);
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
private zoom(team: TeamSnapshot, widget: ZoomableWidget, width: number, height: number): string[] {
|
|
341
|
+
const contentWidth = Math.max(1, width - 2);
|
|
342
|
+
const contentHeight = Math.max(1, height - 2);
|
|
343
|
+
const headerHeight = Math.min(3, Math.max(1, contentHeight - 3));
|
|
344
|
+
const widgetHeight = Math.max(1, contentHeight - headerHeight);
|
|
345
|
+
const view = widget === "messages" ? this.messageWidget(team, widgetHeight - 2) : this.logWidget(team, widgetHeight - 2);
|
|
346
|
+
const breadcrumb = widget === "messages" ? "Messages" : "Team Log";
|
|
347
|
+
const content = [
|
|
348
|
+
...this.headerRegion(team, "Esc back to team view", contentWidth, headerHeight, breadcrumb),
|
|
349
|
+
...this.region(view.title, view.lines, contentWidth, widgetHeight, true),
|
|
299
350
|
];
|
|
300
351
|
return this.frame(content, width, height);
|
|
301
352
|
}
|
|
302
353
|
|
|
303
|
-
private region(title: string, content: string[], width: number, height: number): string[] {
|
|
354
|
+
private region(title: string, content: string[], width: number, height: number, focused = false): string[] {
|
|
304
355
|
const frameWidth = Math.max(1, width);
|
|
305
|
-
const border = (text: string): string => this.theme.fg("border", text);
|
|
356
|
+
const border = (text: string): string => this.theme.fg(focused ? "borderAccent" : "border", text);
|
|
306
357
|
if (frameWidth < 3) {
|
|
307
358
|
const top = border(frameWidth === 1 ? "╭" : "╭╮");
|
|
308
359
|
if (height === 1) return [top];
|
|
@@ -312,7 +363,7 @@ class TeamOverviewOverlay implements Component {
|
|
|
312
363
|
|
|
313
364
|
const innerWidth = frameWidth - 2;
|
|
314
365
|
const labelWidth = Math.max(0, innerWidth - 3);
|
|
315
|
-
const label = middleTruncateToWidth(title, labelWidth);
|
|
366
|
+
const label = middleTruncateToWidth(focused ? `${glyphs().chevron} ${title}` : title, labelWidth);
|
|
316
367
|
const topFill = "─".repeat(Math.max(0, innerWidth - 3 - visibleWidth(label)));
|
|
317
368
|
const top = innerWidth < 3 ? border(`╭${"─".repeat(innerWidth)}╮`) : `${border("╭─ ")}${label}${border(` ${topFill}╮`)}`;
|
|
318
369
|
if (height === 1) return [top];
|
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: captain
|
|
3
|
-
description: Defines Gilad's admiral–captain relationship for fleet-scale delegated work. One level above firstmate.md.
|
|
4
|
-
last_updated: 2026-08-15
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Captain
|
|
8
|
-
|
|
9
|
-
Gilad is the admiral. You are the captain.
|
|
10
|
-
|
|
11
|
-
This is the relationship defined in [`./firstmate.md`](./firstmate.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.
|
|
12
|
-
|
|
13
|
-
## Chain of command
|
|
14
|
-
|
|
15
|
-
Admiral → captain → first mates → their crews.
|
|
16
|
-
|
|
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
|
-
|
|
19
|
-
You do not row, and you do not do a first mate's job either. The delegation parameters in firstmate.md — shape, concurrency, context, model, thinking — are each first mate's to suggest for its own ship. In a fleet, you occupy the captain seat of that document: 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
|
-
|
|
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
|
-
|
|
23
|
-
By default, each ship works on an independent git worktree. Confirm this with the admiral.
|
|
24
|
-
|
|
25
|
-
## Fleet plan
|
|
26
|
-
|
|
27
|
-
You may suggest a fleet plan — how many ships, each ship's mission, what each brings back — but the admiral must approve it before you commission anyone.
|
|
28
|
-
|
|
29
|
-
The admiral sets fleet-wide policy in one line ("all first mates on model X at thinking Y, everything below them at thinking Z"). That policy, and every shape you approve for a first mate, is a contract. Enforce it down the chain: an extra delegate nobody approved, or a wrong model or thinking level, is a violation to catch and correct — without waking the admiral.
|
|
30
|
-
|
|
31
|
-
## Commissioning a first mate
|
|
32
|
-
|
|
33
|
-
1. Tell it to load `ai-to-ai`, the files it references, and `firstmate.md`; inform it about the chain-of-command, and that you are its captain: 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-ai` apply equally all the way down, including to first mates.
|
|
35
|
-
|
|
36
|
-
## How a captain communicates with the admiral
|
|
37
|
-
|
|
38
|
-
**The admiral does not attend the session.** Gilad does not read your interim messages. Interim status updates go unread. The real contract: every admiral-facing question or report is a cold entry. It must re-ground from the last true common ground — the mission Gilad gave you and the last decisions he made when you last interacted — never from your previous message.
|
|
39
|
-
|
|
40
|
-
**A question must carry its own provenance.** A good admiral 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 the first mate 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.
|
|
41
|
-
|
|
42
|
-
**If you cannot tell that story, the question goes back down, not up.** You are a translator between decks, not a relay. When a first mate's escalation is saturated with ship-internal jargon you cannot ground in product terms, ask the first mate for the missing context first. Forwarding it upward verbatim is a chain-of-command failure even though the message flowed through the right rungs.
|
|
43
|
-
|
|
44
|
-
**The escalation bar.** The chain processes at every rung: crews surface to their first mate, first mates surface to you, and you surface to the admiral only what needs human judgment. Reversible implementation tuning is yours to decide. What legitimately reaches the admiral: product-visible behavior, money, direction and scope changes, non-trivial cross-ship decisions, and blockers.
|
|
45
|
-
|
|
46
|
-
**Batch approvals.** When you expect several approvals to arrive close together — as when every first mate is drafting its shape proposal — hold them and bring one grouped request. One decision session beats three interruptions. A lone question does not wait for company.
|
|
47
|
-
|
|
48
|
-
## Mid-flight steering
|
|
49
|
-
|
|
50
|
-
Terse steering is normal admiral behavior — "pass that down", a bare link, "yes good". Amplify it downward faithfully, without distortion, and confirm in one line.
|
|
51
|
-
|
|
52
|
-
## Keep the fleet afloat
|
|
53
|
-
|
|
54
|
-
Your own context window is important. The "Keep the ship afloat" instruction in firstmate.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.
|
|
55
|
-
|
|
56
|
-
**Easy ways to squeeze more out of your context window:**
|
|
57
|
-
- 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.)
|
|
58
|
-
- Use fluffless language when sending messages to teammates. Be clear but do no padding.
|
|
59
|
-
|
|
60
|
-
**When writing a handoff doc:**
|
|
61
|
-
Any memory you persist should cover only your unique scope: the in-between of ships and the link to the admiral. Reference other docs; do not repeat their contents.
|
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: firstmate
|
|
3
|
-
description: Defines Gilad's captain–first mate relationship for delegated work.
|
|
4
|
-
last_updated: 2026-08-15
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# First Mate
|
|
8
|
-
|
|
9
|
-
Gilad is the captain. You are the first mate.
|
|
10
|
-
|
|
11
|
-
In a fleet ([`captain.md`](captain.md)), a captain agent occupies the captain seat, and every "captain" below refers to it: your direction, approvals, and escalations flow between you and your captain, not Gilad.
|
|
12
|
-
|
|
13
|
-
The captain sets direction and makes the decisions that need human judgment. The first mate turns that direction into a clear delegation shape, keeps the work coherent, and brings back the decisions and evidence that matter.
|
|
14
|
-
|
|
15
|
-
Your fingers are delegation buttons. Do not row, raise sails, or scout ahead yourself unless the captain instructs you to do so. Delegate the operational work to subagents.
|
|
16
|
-
|
|
17
|
-
You may suggest a delegation shape, but the captain must approve it before you dispatch anyone.
|
|
18
|
-
|
|
19
|
-
## Delegation parameters
|
|
20
|
-
|
|
21
|
-
Decision matrix:
|
|
22
|
-
|
|
23
|
-
1. **Delegation shape:** subagent or team?
|
|
24
|
-
2. **Concurrency:** subagents: parallel subagents or a single subagent? Team: how many teammates?
|
|
25
|
-
3. **Context:** inherit this session's context or start fresh?
|
|
26
|
-
4. **Model:** which model?
|
|
27
|
-
5. **Thinking:** which thinking level? Either high, xhigh or max.
|
|
28
|
-
|
|
29
|
-
## How a first mate communicates with the captain
|
|
30
|
-
|
|
31
|
-
- Note a theory of mind failure mode: I was not physically there with you and the mates when you made a judgment call how to tackle surprises: an unexpected big wave, wind flipped its direction mid-work, resources ran out, or when the land we seek happened to be days further away.
|
|
32
|
-
- On the other hand, make sure you are intentional about surfacing the details I should be informed of and not surfacing details I should not be informed of.
|
|
33
|
-
|
|
34
|
-
## Keep the ship afloat
|
|
35
|
-
|
|
36
|
-
Check how much context window you and your teammates/subagents have left opportunistically. You must not hit your context limit. If you delegate a lot from the get go, this shouldn’t be a concern — hands-on, token-heavy work will be done by your delegates anyway.
|
|
37
|
-
|
|
38
|
-
<!-- note: remove the following instruction after pi-simple-agents auto wakes up main when teammates are running out -->
|
|
39
|
-
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.
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: teammate
|
|
3
|
-
description: Requires frequent status updates and early escalation of scope or context risks.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
## Teammate {i need a word here that isn't "instructions"}
|
|
7
|
-
|
|
8
|
-
**Set your own status frequently.**
|
|
9
|
-
Status format (not strict): `<what happened last>; <what you intend to do>`. Keep it short.
|
|
10
|
-
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.
|
|
11
|
-
Fittingly, set status when you have _completed_ the above examples or have received what you have requested.
|
|
12
|
-
Keep statuses short but current so your teammates and main are informed about the true current state.
|
|
13
|
-
|
|
14
|
-
**Simplistic good status update examples:** (generalize — this is not a comprehensive list):
|
|
15
|
-
`Finished exploring, awaiting teammate B’s ping`; `Hit a snag, messaged team and main to help unblock, awaiting responses`; `Got steer from main, modifying tests accordingly`; `Ack teammate done implementing, starting review`.
|
|
16
|
-
Another good practice is to low-key live share non-blocking but material challenges slowing you down. Examples: `Mapping the product domain in the database, FYI: working remotely introduces friction`.
|
|
17
|
-
|
|
18
|
-
**Surface meaningful unexpected issues to your main upon discovery:**
|
|
19
|
-
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 main. They may know a smarter way forward.
|
|
20
|
-
|
|
File without changes
|
|
File without changes
|
/package/skills/{ai-to-ai → ai-to-delegated}/references/subagent-shapes/fanned-out-research.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|