@melihmucuk/pi-crew 1.0.19 → 1.0.21
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 +10 -10
- package/agents/code-reviewer.md +20 -25
- package/agents/quality-reviewer.md +20 -25
- package/extension/crew.ts +17 -4
- package/extension/subagent-session.ts +11 -0
- package/extension/tools.ts +42 -38
- package/extension/ui.ts +8 -2
- package/package.json +9 -9
- package/prompts/pi-crew-plan.md +2 -2
- package/prompts/pi-crew-review.md +23 -44
- package/skills/pi-crew/SKILL.md +72 -16
- package/skills/pi-crew/REFERENCE.md +0 -82
package/README.md
CHANGED
|
@@ -30,11 +30,11 @@ Once installed, pi-crew exposes these capabilities in your pi session:
|
|
|
30
30
|
|
|
31
31
|
#### `crew_list`
|
|
32
32
|
|
|
33
|
-
Lists available subagent definitions and active subagents owned by the current session.
|
|
33
|
+
Lists available subagent definitions and active subagents owned by the current session. For each definition it shows the `name`, `description`, `interactive` flag, and the resolved `tools` and `skills` (`all built-in`, `none`, or an explicit list).
|
|
34
34
|
|
|
35
35
|
#### `crew_spawn`
|
|
36
36
|
|
|
37
|
-
Spawns a subagent in an isolated session. The subagent runs in the background with its own context window, tools, and skills. When it finishes, the result is delivered to the session that spawned it as a steering message that triggers a new turn. If that session is not active, the result is queued until you switch back to it.
|
|
37
|
+
Spawns a subagent in an isolated session. Each spawn includes a concise `brief` label for session lists and a full self-contained `task`. The subagent runs in the background with its own context window, tools, and skills. When it finishes, the result is delivered to the session that spawned it as a steering message that triggers a new turn. If that session is not active, the result is queued until you switch back to it.
|
|
38
38
|
|
|
39
39
|
```
|
|
40
40
|
"spawn scout and find all API endpoints and their authentication methods"
|
|
@@ -100,14 +100,14 @@ A bundled orchestration skill that provides best practices for delegating work t
|
|
|
100
100
|
|
|
101
101
|
pi-crew ships with six subagent definitions that cover common workflows:
|
|
102
102
|
|
|
103
|
-
| Subagent | Purpose | Tools | Model |
|
|
104
|
-
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- | --------------------------- |
|
|
105
|
-
| **scout** | Investigates codebase and returns structured findings. Read-only.
|
|
106
|
-
| **planner** |
|
|
107
|
-
| **oracle** | Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only.
|
|
108
|
-
| **code-reviewer** | Reviews code
|
|
109
|
-
| **quality-reviewer** | Reviews code
|
|
110
|
-
| **worker** | Implements code changes
|
|
103
|
+
| Subagent | Purpose | Tools | Model | Thinking |
|
|
104
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- | --------------------------- | -------- |
|
|
105
|
+
| **scout** | Investigates codebase and returns structured findings. Read-only. | read, grep, find, ls, bash | openai-codex/gpt-5.5 | off |
|
|
106
|
+
| **planner** | Produces deterministic implementation plans. Read-only. Does not write code. | read, grep, find, ls, bash | openai-codex/gpt-5.5 | high |
|
|
107
|
+
| **oracle** | Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only. | read, grep, find, ls, bash | openai-codex/gpt-5.5 | xhigh |
|
|
108
|
+
| **code-reviewer** | Reviews scoped code for actionable bugs. Does not modify files; may run typecheck and tests. | read, grep, find, ls, bash | openai-codex/gpt-5.5 | high |
|
|
109
|
+
| **quality-reviewer** | Reviews scoped code for maintainability, duplication, and complexity. Read-only. | read, grep, find, ls, bash | openai-codex/gpt-5.5 | high |
|
|
110
|
+
| **worker** | Implements scoped code changes safely and verifies them. | all | openai-codex/gpt-5.5 | low |
|
|
111
111
|
|
|
112
112
|
Read-only bundled subagents still keep `bash` for inspection workflows like `git` and `ast-grep`. This is an instruction-level contract, not a sandbox boundary.
|
|
113
113
|
|
package/agents/code-reviewer.md
CHANGED
|
@@ -1,60 +1,55 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: code-reviewer
|
|
3
|
-
description: Reviews scoped code for actionable bugs.
|
|
4
|
-
model: openai-codex/gpt-5.
|
|
3
|
+
description: Reviews scoped code for actionable bugs. Does not modify files; may run typecheck and tests.
|
|
4
|
+
model: openai-codex/gpt-5.5
|
|
5
5
|
thinking: high
|
|
6
6
|
tools: read, grep, find, ls, bash
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are a
|
|
9
|
+
You are a code reviewer. Decide whether the reviewed scope contains realistic, actionable bugs — finding nothing is a valid outcome. Reply in the user's language.
|
|
10
10
|
|
|
11
|
-
Do not modify files.
|
|
11
|
+
Do not modify files. Verify with typecheck and relevant tests. Do not run builds, formatters, or install commands.
|
|
12
12
|
|
|
13
13
|
## Scope
|
|
14
14
|
|
|
15
|
-
Review the provided scope.
|
|
15
|
+
Review the provided scope; default to uncommitted changes. "latest" = last 5 commits unless a count is given.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Full/codebase reviews are bounded, not exhaustive: map highest-risk areas, deeply inspect selected files, state what was skipped.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
For large scopes, prioritize: business logic, auth/security, data mutation, persistence, external integrations, concurrency/async, error handling, public APIs.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
For changed-code scopes, report pre-existing issues only when the change triggers or makes them relevant. For full-codebase scopes, report existing issues only when directly evidenced, realistically triggerable, and worth acting on now.
|
|
21
|
+
Report pre-existing issues only when the change triggers them (changed-code) or when directly evidenced and realistically triggerable (full-codebase).
|
|
24
22
|
|
|
25
23
|
## Method
|
|
26
24
|
|
|
27
|
-
|
|
25
|
+
Read the full file, not just diffs, before reporting. Trace direct callers/callees only when needed; stop when further context adds no evidence.
|
|
28
26
|
|
|
29
|
-
For full-codebase
|
|
27
|
+
For full-codebase: report only from files you directly inspected. Verify any caller, route, config, or runtime assumption a finding depends on.
|
|
30
28
|
|
|
31
|
-
Do not report
|
|
29
|
+
Do not report from skipped files — mention them only as skipped, not as evidence.
|
|
32
30
|
|
|
33
31
|
## Finding Bar
|
|
34
32
|
|
|
35
|
-
Default to no finding
|
|
36
|
-
|
|
37
|
-
- the trigger is realistic in this project's real operating context;
|
|
33
|
+
Default to no finding. Report only when:
|
|
34
|
+
- the trigger is realistic in the project's operating context;
|
|
38
35
|
- the impact is worth acting on now;
|
|
39
36
|
- the failing path is concrete and evidence-backed.
|
|
40
37
|
|
|
41
|
-
Omit
|
|
38
|
+
Omit: operationally unlikely edge cases, unsupported usage, speculative misconfiguration, style/refactor/naming/docs/TODO comments, low-confidence findings.
|
|
42
39
|
|
|
43
40
|
Missing tests are findings only when a high-risk behavior change lacks meaningful coverage.
|
|
44
41
|
|
|
45
|
-
Report the same
|
|
42
|
+
Report the same pattern at most twice, then list remaining locations.
|
|
46
43
|
|
|
47
44
|
## Severity
|
|
48
45
|
|
|
49
|
-
- Critical
|
|
50
|
-
- Major
|
|
51
|
-
- Minor
|
|
46
|
+
- **Critical**: severe user, data, security, operational, or near-term development breakage.
|
|
47
|
+
- **Major**: likely to affect users, developers, operations, or maintainability enough to act on soon.
|
|
48
|
+
- **Minor**: real but non-blocking, localized friction, or high-risk coverage gap.
|
|
52
49
|
|
|
53
50
|
## Output
|
|
54
51
|
|
|
55
|
-
If no findings:
|
|
56
|
-
|
|
57
|
-
**No issues found.**
|
|
52
|
+
If no findings: **No issues found.**
|
|
58
53
|
|
|
59
54
|
For each finding:
|
|
60
55
|
|
|
@@ -65,4 +60,4 @@ Evidence: what you verified
|
|
|
65
60
|
Impact: concrete consequence
|
|
66
61
|
Fix: suggested correction
|
|
67
62
|
|
|
68
|
-
Be direct
|
|
63
|
+
Be direct and concise.
|
|
@@ -1,62 +1,57 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: quality-reviewer
|
|
3
3
|
description: Reviews scoped code for maintainability, duplication, and complexity. Read-only.
|
|
4
|
-
model: openai-codex/gpt-5.
|
|
4
|
+
model: openai-codex/gpt-5.5
|
|
5
5
|
thinking: high
|
|
6
6
|
tools: read, grep, find, ls, bash
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are a read-only maintainability reviewer.
|
|
9
|
+
You are a read-only maintainability reviewer. Decide whether the code has evidence-backed structural problems that create real maintenance cost — finding nothing is a valid outcome. If a correctness risk is inseparable from a structural issue, mention it briefly but keep the finding about maintainability. Reply in the user's language.
|
|
10
10
|
|
|
11
|
-
Do not
|
|
12
|
-
|
|
13
|
-
Do not modify files. Use bash only for read-only inspection. Do not run builds, tests, typechecks, formatters, installers, or commands that may change project state.
|
|
11
|
+
Do not modify files. Use bash only for read-only inspection — no builds, tests, typechecks, formatters, or install commands.
|
|
14
12
|
|
|
15
13
|
## Scope
|
|
16
14
|
|
|
17
|
-
Review the provided scope
|
|
15
|
+
Review the provided scope; default to uncommitted changes. "latest" = last 5 commits unless a count is given.
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
Full/codebase reviews are bounded, not exhaustive. First produce a structural risk map, then deeply review only the highest-risk areas. State what was skipped.
|
|
20
18
|
|
|
21
|
-
For large
|
|
19
|
+
For large scopes, prioritize: large files, dependency-heavy files, widely imported files, or files crossing module boundaries.
|
|
22
20
|
|
|
23
21
|
## Method
|
|
24
22
|
|
|
25
|
-
Maintainability is project-relative
|
|
23
|
+
Maintainability is project-relative. Read the full file before reporting. Check nearby patterns, AGENTS.md/conventions, direct callers/imports, and representative clean files only when needed. Stop when further context adds no structural insight.
|
|
26
24
|
|
|
27
|
-
Do not report
|
|
25
|
+
Do not report from skipped files — mention them only as skipped, not as evidence.
|
|
28
26
|
|
|
29
27
|
## Finding Bar
|
|
30
28
|
|
|
31
|
-
Default to no finding
|
|
32
|
-
|
|
29
|
+
Default to no finding. Report only when:
|
|
33
30
|
- the problem is visible now, not speculative;
|
|
34
31
|
- the structure creates real near-term maintenance cost;
|
|
35
32
|
- a concrete future change, extension, or debugging task becomes harder;
|
|
36
|
-
- the fix clearly reduces complexity, duplication, or coupling rather than moving code
|
|
33
|
+
- the fix clearly reduces complexity, duplication, or coupling rather than moving code.
|
|
37
34
|
|
|
38
|
-
Omit taste-based refactors, abstractions without present-day need, length alone, naming/style preferences without local convention impact, missing docs/comments, one-off scripts/migrations, test gaps,
|
|
35
|
+
Omit: taste-based refactors, abstractions without present-day need, length alone, naming/style preferences without local convention impact, missing docs/comments, one-off scripts/migrations, test gaps, low-confidence findings.
|
|
39
36
|
|
|
40
37
|
## Look For
|
|
41
38
|
|
|
42
|
-
- Complexity
|
|
43
|
-
- Duplication
|
|
44
|
-
- Dead/redundant code
|
|
45
|
-
- Boundaries/coupling
|
|
39
|
+
- **Complexity**: mixed responsibilities, deep branching, unrelated code in one file, over-fragmentation.
|
|
40
|
+
- **Duplication**: copy-paste or near-identical logic that makes future changes error-prone.
|
|
41
|
+
- **Dead/redundant code**: unused or unreachable code, redundant checks; verify dynamic/public usage first.
|
|
42
|
+
- **Boundaries/coupling**: convention drift, leaked internals, unclear public APIs, one-implementation wrappers.
|
|
46
43
|
|
|
47
44
|
Default stance: no new abstraction unless it reduces present-day duplication or coupling.
|
|
48
45
|
|
|
49
46
|
## Severity
|
|
50
47
|
|
|
51
|
-
- Critical
|
|
52
|
-
- Major
|
|
53
|
-
- Minor
|
|
48
|
+
- **Critical**: severe user, data, security, operational, or near-term development breakage.
|
|
49
|
+
- **Major**: likely to affect users, developers, operations, or maintainability enough to act on soon.
|
|
50
|
+
- **Minor**: real but non-blocking, localized friction, or high-risk coverage gap.
|
|
54
51
|
|
|
55
52
|
## Output
|
|
56
53
|
|
|
57
|
-
If no findings:
|
|
58
|
-
|
|
59
|
-
**No issues found.**
|
|
54
|
+
If no findings: **No issues found.**
|
|
60
55
|
|
|
61
56
|
For each finding:
|
|
62
57
|
|
|
@@ -67,4 +62,4 @@ Evidence: what you verified
|
|
|
67
62
|
Impact: concrete consequence
|
|
68
63
|
Fix: suggested correction
|
|
69
64
|
|
|
70
|
-
Be direct
|
|
65
|
+
Be direct and concise.
|
package/extension/crew.ts
CHANGED
|
@@ -27,6 +27,7 @@ export interface SubagentState {
|
|
|
27
27
|
id: string;
|
|
28
28
|
agentConfig: AgentConfig;
|
|
29
29
|
task: string;
|
|
30
|
+
brief: string;
|
|
30
31
|
status: SubagentStatus;
|
|
31
32
|
ownerSessionId: string;
|
|
32
33
|
session: AgentSession | null;
|
|
@@ -63,6 +64,7 @@ export interface SpawnContext {
|
|
|
63
64
|
agentDir: string;
|
|
64
65
|
parentSessionFile?: string;
|
|
65
66
|
onWarning?: (message: string) => void;
|
|
67
|
+
brief?: string;
|
|
66
68
|
}
|
|
67
69
|
|
|
68
70
|
type SettledSubagentStatus = Extract<SubagentStatus, "done" | "waiting" | "error" | "aborted">;
|
|
@@ -149,7 +151,7 @@ export class CrewRuntime {
|
|
|
149
151
|
ctx: SpawnContext,
|
|
150
152
|
extensionResolvedPath: string,
|
|
151
153
|
): string {
|
|
152
|
-
const state = this.createAgent(agentConfig, task, ownerSessionId);
|
|
154
|
+
const state = this.createAgent(agentConfig, task, ctx.brief ?? "", ownerSessionId);
|
|
153
155
|
this.refreshWidgetFor(ownerSessionId);
|
|
154
156
|
this.runner.start(state, {
|
|
155
157
|
cwd,
|
|
@@ -226,12 +228,13 @@ export class CrewRuntime {
|
|
|
226
228
|
.map(buildActiveAgentSummary);
|
|
227
229
|
}
|
|
228
230
|
|
|
229
|
-
private createAgent(agentConfig: AgentConfig, task: string, ownerSessionId: string): SubagentState {
|
|
231
|
+
private createAgent(agentConfig: AgentConfig, task: string, brief: string, ownerSessionId: string): SubagentState {
|
|
230
232
|
const id = generateId(agentConfig.name, new Set(this.agents.keys()));
|
|
231
233
|
const state: SubagentState = {
|
|
232
234
|
id,
|
|
233
235
|
agentConfig,
|
|
234
236
|
task,
|
|
237
|
+
brief,
|
|
235
238
|
status: "running",
|
|
236
239
|
ownerSessionId,
|
|
237
240
|
session: null,
|
|
@@ -371,7 +374,17 @@ export class CrewRuntime {
|
|
|
371
374
|
}
|
|
372
375
|
}
|
|
373
376
|
|
|
377
|
+
const CREW_RUNTIME_VERSION = 2;
|
|
374
378
|
const crewRuntimeKey = Symbol.for("pi-crew.runtime");
|
|
375
|
-
const globalWithCrewRuntime = globalThis as typeof globalThis & Record<symbol, CrewRuntime | undefined>;
|
|
379
|
+
const globalWithCrewRuntime = globalThis as typeof globalThis & Record<symbol, (CrewRuntime & { __piCrewRuntimeVersion?: number }) | undefined>;
|
|
376
380
|
|
|
377
|
-
|
|
381
|
+
function createCrewRuntime(): CrewRuntime & { __piCrewRuntimeVersion?: number } {
|
|
382
|
+
const runtime = new CrewRuntime() as CrewRuntime & { __piCrewRuntimeVersion?: number };
|
|
383
|
+
runtime.__piCrewRuntimeVersion = CREW_RUNTIME_VERSION;
|
|
384
|
+
return runtime;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
const existingRuntime = globalWithCrewRuntime[crewRuntimeKey];
|
|
388
|
+
export const crewRuntime = existingRuntime?.__piCrewRuntimeVersion === CREW_RUNTIME_VERSION
|
|
389
|
+
? existingRuntime
|
|
390
|
+
: (globalWithCrewRuntime[crewRuntimeKey] = createCrewRuntime());
|
|
@@ -175,6 +175,16 @@ function isAborted(state: SubagentState): boolean {
|
|
|
175
175
|
return state.status === "aborted";
|
|
176
176
|
}
|
|
177
177
|
|
|
178
|
+
function normalizeSessionNamePart(value: string): string {
|
|
179
|
+
return value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function formatSubagentSessionName(state: Pick<SubagentState, "agentConfig" | "brief" | "id">): string {
|
|
183
|
+
const agentName = normalizeSessionNamePart(state.agentConfig.name) || "subagent";
|
|
184
|
+
const brief = normalizeSessionNamePart(state.brief) || state.id;
|
|
185
|
+
return `crew: ${agentName} · ${brief}`;
|
|
186
|
+
}
|
|
187
|
+
|
|
178
188
|
export class SubagentSessionRunner implements SubagentRunner {
|
|
179
189
|
constructor(private readonly callbacks: SubagentRunnerCallbacks) {}
|
|
180
190
|
|
|
@@ -211,6 +221,7 @@ export class SubagentSessionRunner implements SubagentRunner {
|
|
|
211
221
|
return false;
|
|
212
222
|
}
|
|
213
223
|
state.session = session;
|
|
224
|
+
session.setSessionName(formatSubagentSessionName(state));
|
|
214
225
|
return true;
|
|
215
226
|
}
|
|
216
227
|
|
package/extension/tools.ts
CHANGED
|
@@ -55,12 +55,18 @@ function formatAvailableAgents(agents: AgentConfig[]): string[] {
|
|
|
55
55
|
return ["No valid subagent definitions found. Add `.md` files to `<cwd>/.pi/agents/` or `~/.pi/agent/agents/`."];
|
|
56
56
|
}
|
|
57
57
|
|
|
58
|
-
return agents.flatMap((agent) =>
|
|
59
|
-
"",
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
return agents.flatMap((agent) => {
|
|
59
|
+
const tools = agent.tools === undefined ? "all built-in" : agent.tools.length === 0 ? "none" : agent.tools.join(", ");
|
|
60
|
+
const skills = agent.skills === undefined ? "all built-in" : agent.skills.length === 0 ? "none" : agent.skills.join(", ");
|
|
61
|
+
return [
|
|
62
|
+
"",
|
|
63
|
+
`name: ${agent.name}`,
|
|
64
|
+
`description: ${agent.description}`,
|
|
65
|
+
`interactive: ${agent.interactive ? "true" : "false"}`,
|
|
66
|
+
`tools: ${tools}`,
|
|
67
|
+
`skills: ${skills}`,
|
|
68
|
+
];
|
|
69
|
+
});
|
|
64
70
|
}
|
|
65
71
|
|
|
66
72
|
function formatWarnings(warnings: AgentDiscoveryWarning[]): string[] {
|
|
@@ -141,14 +147,12 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
141
147
|
pi.registerTool({
|
|
142
148
|
name: "crew_list",
|
|
143
149
|
label: "List Crew",
|
|
144
|
-
description:
|
|
145
|
-
"List available subagent definitions and currently running subagents with their status. Use only to discover which subagents exist or to get a one-time status snapshot. Do NOT call this repeatedly to check if a subagent has finished — results are delivered automatically as steering messages.",
|
|
150
|
+
description: "List subagent definitions and active subagents.",
|
|
146
151
|
parameters: Type.Object({}),
|
|
147
|
-
promptSnippet: "List
|
|
152
|
+
promptSnippet: "List available subagents and active subagents.",
|
|
148
153
|
promptGuidelines: [
|
|
149
|
-
"crew_list:
|
|
150
|
-
"crew_list:
|
|
151
|
-
"crew_list: Use only for discovery or a requested status snapshot; do not poll for completion.",
|
|
154
|
+
"crew_list: Use for discovery or a requested one-time status snapshot.",
|
|
155
|
+
"crew_list: Call before crew_spawn; never poll for completion.",
|
|
152
156
|
],
|
|
153
157
|
async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
|
|
154
158
|
const toolCtx = getToolContext(ctx);
|
|
@@ -175,24 +179,25 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
175
179
|
},
|
|
176
180
|
});
|
|
177
181
|
|
|
178
|
-
registerActionTool<{ subagent: string; task: string }>(pi, {
|
|
182
|
+
registerActionTool<{ subagent: string; brief: string; task: string }>(pi, {
|
|
179
183
|
name: "crew_spawn",
|
|
180
184
|
label: "Spawn Crew",
|
|
181
|
-
description:
|
|
182
|
-
"Spawn a non-blocking subagent that runs in an isolated session. The subagent works independently while your session stays interactive. Results are delivered back to your session as steering messages.",
|
|
185
|
+
description: "Spawn a non-blocking subagent in an isolated session. Returns immediately without the result; the result is delivered separately as a steering message.",
|
|
183
186
|
parameters: Type.Object({
|
|
184
187
|
subagent: Type.String({ description: "Subagent name from crew_list" }),
|
|
185
|
-
|
|
188
|
+
brief: Type.String({ description: "Concise task label for session lists, ideally under 80 characters. This is not the full task." }),
|
|
189
|
+
task: Type.String({ description: "Full self-contained task to delegate to the subagent" }),
|
|
186
190
|
}),
|
|
187
|
-
promptSnippet: "Spawn a
|
|
191
|
+
promptSnippet: "Spawn a discovered subagent for delegated work.",
|
|
188
192
|
promptGuidelines: [
|
|
189
|
-
"crew_spawn:
|
|
190
|
-
"crew_spawn:
|
|
191
|
-
"crew_spawn:
|
|
192
|
-
"crew_spawn: Results arrive as steering messages; do not poll crew_list or fabricate results.",
|
|
193
|
-
"crew_spawn: Use the bundled pi-crew skill for detailed delegation patterns.",
|
|
193
|
+
"crew_spawn: Use only after crew_list, for one bounded self-contained task.",
|
|
194
|
+
"crew_spawn: Keep brief short; put necessary context and criteria in task.",
|
|
195
|
+
"crew_spawn: Do not duplicate delegated work; wait for steering results.",
|
|
194
196
|
],
|
|
195
197
|
action: (params, ctx) => {
|
|
198
|
+
const brief = params.brief.trim();
|
|
199
|
+
if (!brief) return toolError("brief is required and must not be empty.");
|
|
200
|
+
|
|
196
201
|
const toolCtx = getToolContext(ctx);
|
|
197
202
|
const { agents, warnings } = discoverAgents(toolCtx.cwd);
|
|
198
203
|
notifyDiscoveryWarnings(ctx, shownDiscoveryWarnings, warnings);
|
|
@@ -208,6 +213,7 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
208
213
|
toolCtx.cwd,
|
|
209
214
|
toolCtx.callerSessionId,
|
|
210
215
|
{
|
|
216
|
+
brief,
|
|
211
217
|
model: ctx.model,
|
|
212
218
|
modelRegistry: ctx.modelRegistry,
|
|
213
219
|
agentDir: getAgentDir(),
|
|
@@ -218,28 +224,28 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
218
224
|
);
|
|
219
225
|
return toolSuccess(
|
|
220
226
|
`Subagent '${subagent.name}' spawned as ${id}. Result will be delivered as a steering message when done.`,
|
|
221
|
-
{ id, agentName: subagent.name, task: params.task },
|
|
227
|
+
{ id, agentName: subagent.name, brief, task: params.task },
|
|
222
228
|
);
|
|
223
229
|
},
|
|
224
230
|
renderCall(args, theme, _context) {
|
|
225
|
-
|
|
231
|
+
const subagent = args.subagent || "...";
|
|
232
|
+
const title = args.brief ? `${subagent} · ${args.brief}` : subagent;
|
|
233
|
+
return renderCrewCall(theme, "crew_spawn", title, args.task);
|
|
226
234
|
},
|
|
227
235
|
});
|
|
228
236
|
|
|
229
237
|
registerActionTool<{ subagent_id?: string; subagent_ids?: string[]; all?: boolean }>(pi, {
|
|
230
238
|
name: "crew_abort",
|
|
231
239
|
label: "Abort Crew",
|
|
232
|
-
description: "Abort
|
|
240
|
+
description: "Abort active subagents owned by this session.",
|
|
233
241
|
parameters: Type.Object({
|
|
234
242
|
subagent_id: Type.Optional(Type.String({ description: "Single subagent ID to abort" })),
|
|
235
243
|
subagent_ids: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Multiple subagent IDs to abort" })),
|
|
236
244
|
all: Type.Optional(Type.Boolean({ description: "Abort all active subagents owned by the current session" })),
|
|
237
245
|
}),
|
|
238
|
-
promptSnippet: "Abort
|
|
246
|
+
promptSnippet: "Abort active subagents.",
|
|
239
247
|
promptGuidelines: [
|
|
240
|
-
"crew_abort:
|
|
241
|
-
"crew_abort: Provide exactly one mode: subagent_id, subagent_ids, or all=true.",
|
|
242
|
-
"crew_abort: Use only when delegated work is obsolete, wrong, or explicitly cancelled.",
|
|
248
|
+
"crew_abort: Use one mode only: subagent_id, subagent_ids, or all=true.",
|
|
243
249
|
],
|
|
244
250
|
action: (params, ctx) => {
|
|
245
251
|
const { callerSessionId } = getToolContext(ctx);
|
|
@@ -273,16 +279,15 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
273
279
|
registerActionTool<{ subagent_id: string; message: string }>(pi, {
|
|
274
280
|
name: "crew_respond",
|
|
275
281
|
label: "Respond to Crew",
|
|
276
|
-
description: "Send a follow-up message to
|
|
282
|
+
description: "Send a follow-up message to a waiting interactive subagent. Returns immediately; the response is delivered as a steering message that starts a new turn.",
|
|
277
283
|
parameters: Type.Object({
|
|
278
284
|
subagent_id: Type.String({ description: "ID of the waiting subagent (from crew_list or crew_spawn result)" }),
|
|
279
285
|
message: Type.String({ description: "Message to send to the subagent" }),
|
|
280
286
|
}),
|
|
281
|
-
promptSnippet: "
|
|
287
|
+
promptSnippet: "Respond to a waiting interactive subagent.",
|
|
282
288
|
promptGuidelines: [
|
|
283
|
-
"crew_respond: Send a complete follow-up
|
|
284
|
-
"crew_respond:
|
|
285
|
-
"crew_respond: The response arrives as a steering message; do not poll crew_list.",
|
|
289
|
+
"crew_respond: Send a complete follow-up only to a waiting interactive subagent.",
|
|
290
|
+
"crew_respond: Returns immediately; wait for the next steering result and do not poll.",
|
|
286
291
|
],
|
|
287
292
|
action: (params, ctx) => {
|
|
288
293
|
const { callerSessionId } = getToolContext(ctx);
|
|
@@ -301,14 +306,13 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
|
|
|
301
306
|
registerActionTool<{ subagent_id: string }>(pi, {
|
|
302
307
|
name: "crew_done",
|
|
303
308
|
label: "Done with Crew",
|
|
304
|
-
description: "Close
|
|
309
|
+
description: "Close a waiting interactive subagent.",
|
|
305
310
|
parameters: Type.Object({
|
|
306
311
|
subagent_id: Type.String({ description: "ID of the subagent to close" }),
|
|
307
312
|
}),
|
|
308
|
-
promptSnippet: "Close
|
|
313
|
+
promptSnippet: "Close a waiting interactive subagent.",
|
|
309
314
|
promptGuidelines: [
|
|
310
|
-
"crew_done:
|
|
311
|
-
"crew_done: Use only when no further follow-up is needed; otherwise use crew_respond.",
|
|
315
|
+
"crew_done: Use only when no further follow-up is needed.",
|
|
312
316
|
],
|
|
313
317
|
action: (params, ctx) => {
|
|
314
318
|
const { callerSessionId } = getToolContext(ctx);
|
package/extension/ui.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { pathToFileURL } from "node:url";
|
|
1
2
|
import type { AgentToolResult } from "@earendil-works/pi-agent-core";
|
|
2
3
|
import {
|
|
3
4
|
type ExtensionAPI,
|
|
@@ -144,6 +145,11 @@ function renderWarningMessage(content: unknown, theme: MessageRendererTheme): Bo
|
|
|
144
145
|
return box;
|
|
145
146
|
}
|
|
146
147
|
|
|
148
|
+
function linkFilePath(filePath: string): string {
|
|
149
|
+
const url = pathToFileURL(filePath).href;
|
|
150
|
+
return `\x1b]8;;${url}\x07${filePath}\x1b]8;;\x07`;
|
|
151
|
+
}
|
|
152
|
+
|
|
147
153
|
export function registerCrewMessageRenderers(pi: ExtensionAPI): void {
|
|
148
154
|
pi.registerMessageRenderer("crew-result", (message, { expanded }, theme) => {
|
|
149
155
|
const details = message.details as CrewResultMessageDetails | undefined;
|
|
@@ -158,7 +164,7 @@ export function registerCrewMessageRenderers(pi: ExtensionAPI): void {
|
|
|
158
164
|
box.addChild(new Text(header, 0, 0));
|
|
159
165
|
|
|
160
166
|
if (details?.sessionFile) {
|
|
161
|
-
box.addChild(new Text(theme.fg("muted", `📁 ${details.sessionFile}`), 0, 0));
|
|
167
|
+
box.addChild(new Text(theme.fg("muted", `📁 ${linkFilePath(details.sessionFile)}`), 0, 0));
|
|
162
168
|
}
|
|
163
169
|
|
|
164
170
|
if (body) {
|
|
@@ -242,7 +248,7 @@ function syncWidgetText(state: WidgetState, agents: ActiveAgentSummary[]): void
|
|
|
242
248
|
}
|
|
243
249
|
|
|
244
250
|
export function updateWidget(ctx: ExtensionContext, crew: CrewRuntime): void {
|
|
245
|
-
if (
|
|
251
|
+
if (ctx.mode !== "tui") {
|
|
246
252
|
clearWidget();
|
|
247
253
|
return;
|
|
248
254
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@melihmucuk/pi-crew",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.21",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Non-blocking subagent orchestration for pi coding agent",
|
|
6
6
|
"files": [
|
|
@@ -43,13 +43,13 @@
|
|
|
43
43
|
"typebox": "*"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
|
-
"@earendil-works/pi-agent-core": "^0.
|
|
47
|
-
"@earendil-works/pi-ai": "^0.
|
|
48
|
-
"@earendil-works/pi-coding-agent": "^0.
|
|
49
|
-
"@earendil-works/pi-tui": "^0.
|
|
50
|
-
"@types/node": "^
|
|
51
|
-
"tsx": "^4.22.
|
|
52
|
-
"typebox": "^1.
|
|
53
|
-
"typescript": "^
|
|
46
|
+
"@earendil-works/pi-agent-core": "^0.79.6",
|
|
47
|
+
"@earendil-works/pi-ai": "^0.79.6",
|
|
48
|
+
"@earendil-works/pi-coding-agent": "^0.79.6",
|
|
49
|
+
"@earendil-works/pi-tui": "^0.79.6",
|
|
50
|
+
"@types/node": "^25.9.3",
|
|
51
|
+
"tsx": "^4.22.4",
|
|
52
|
+
"typebox": "^1.2.16",
|
|
53
|
+
"typescript": "^6.0.3"
|
|
54
54
|
}
|
|
55
55
|
}
|
package/prompts/pi-crew-plan.md
CHANGED
|
@@ -21,11 +21,11 @@ Build compact shared context for subagents. Include only information that helps
|
|
|
21
21
|
- minimal orientation already gathered, only when it clarifies where to look;
|
|
22
22
|
- exact errors/output or verification context, when relevant.
|
|
23
23
|
|
|
24
|
-
Do not copy full reference contents. Do not include project root/cwd, generic repo conventions, default scope, edit permissions, output format, or role boilerplate. Subagents run in the same repo cwd and can inspect repo guidance themselves.
|
|
24
|
+
Do not copy full reference contents. Do not include project root/cwd, generic repo conventions, default scope, edit permissions, output format, or role boilerplate. Subagents run in the same repo cwd and can inspect repo guidance and any file themselves; they cannot see this session's conversation or decisions, so include any session-only decision a scout or the planner needs and state the findings or plan output you expect back.
|
|
25
25
|
|
|
26
26
|
If the user provides a plan, spec, issue, doc, design, URL, or file as the source of intent, read it when practical and summarize the relevant intent instead of merely passing the path.
|
|
27
27
|
|
|
28
|
-
Gather only enough orientation to assign scout scopes or
|
|
28
|
+
Gather only enough orientation to assign scout scopes or instruct the planner: targeted searches, likely entry points, and small config or structure checks when they materially affect delegation. Do not read full implementation files, trace call chains, or analyze implementations. Do not read README/AGENTS just to repeat generic repo guidance.
|
|
29
29
|
|
|
30
30
|
## Scouts
|
|
31
31
|
|
|
@@ -6,52 +6,42 @@ description: Orchestrate parallel code and quality reviews with reviewer subagen
|
|
|
6
6
|
|
|
7
7
|
Additional instructions: `$ARGUMENTS`
|
|
8
8
|
|
|
9
|
-
You are a review orchestrator, not a reviewer. Resolve
|
|
9
|
+
You are a review orchestrator, not a reviewer. Resolve scope, gather minimal context, spawn reviewers, then filter and merge their results. Do not perform an independent review — spot-check only for ambiguous or high-impact findings.
|
|
10
10
|
|
|
11
11
|
## Scope
|
|
12
12
|
|
|
13
|
-
Use the user's scope when provided
|
|
13
|
+
Use the user's scope when provided; otherwise rely on each reviewer's default. "latest" = last 5 commits unless a count is given. "full"/"codebase" is an explicit non-default scope.
|
|
14
14
|
|
|
15
|
-
Gather
|
|
15
|
+
Gather why the changes were made, expected outcome, intent, notable fixes since prior review, verification already run, and review-specific user instructions.
|
|
16
16
|
|
|
17
|
-
If the user provides a plan, spec, issue,
|
|
17
|
+
If the user provides a plan, spec, issue, or doc as the intent source, read it and summarize the relevant behavior. This is context gathering, not independent review.
|
|
18
18
|
|
|
19
|
-
Keep the
|
|
19
|
+
Keep the task focused on intent and outcome, not repository mechanics. Do not paste file inventories, branch/cwd details, or project constraints. Reviewers run in the same repo and can inspect Git state, repo guidance, and any file themselves. Include session-only intent they cannot discover. Mention file paths only when they define scope or prevent ambiguity.
|
|
20
20
|
|
|
21
21
|
## Subagents
|
|
22
22
|
|
|
23
|
-
Call `crew_list` first and check for `code-reviewer` and `quality-reviewer`. Spawn available reviewers in parallel.
|
|
23
|
+
Call `crew_list` first and check for `code-reviewer` and `quality-reviewer`. Spawn available reviewers in parallel. Report any that fail, error, or abort; continue with completed results.
|
|
24
24
|
|
|
25
|
-
Send each reviewer a compact,
|
|
26
|
-
-
|
|
27
|
-
- why the changes were made and
|
|
28
|
-
- notable prior-review fixes and verification
|
|
29
|
-
- non-default scope, commit range,
|
|
30
|
-
- additional user instructions
|
|
25
|
+
Send each reviewer a compact, self-contained task with only non-obvious information:
|
|
26
|
+
- intent source (plan/spec/doc) + concise summary after reading it;
|
|
27
|
+
- why the changes were made and expected outcome;
|
|
28
|
+
- notable prior-review fixes and verification run;
|
|
29
|
+
- non-default scope, commit range, or entry-point hints only when they clarify scope;
|
|
30
|
+
- additional user instructions specific to this review.
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
Do not restate reviewer-role boilerplate, default scope, acceptance criteria, output format, edit permissions, or severity rules unless the user overrides them.
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
For full/codebase requests, state that the requested scope is a bounded full-codebase review.
|
|
37
|
-
|
|
38
|
-
Do not echo the raw user instruction if it is already represented in the intent summary; quote it only when exact wording matters.
|
|
39
|
-
|
|
40
|
-
Do not restate reviewer-role boilerplate implied by the selected reviewer, such as telling `code-reviewer` to find actionable bugs or telling `quality-reviewer` to review maintainability. Do not include default scope, generic non-goals, acceptance criteria, output format, edit permissions, or severity rules unless the user explicitly overrides them.
|
|
41
|
-
|
|
42
|
-
Do not poll. Wait for all successfully spawned reviewers to return terminal results before the final report. Never fabricate subagent output.
|
|
34
|
+
Do not poll. Wait for all spawned reviewers to finish before the final report. Never fabricate subagent output.
|
|
43
35
|
|
|
44
36
|
## Acceptance Gate
|
|
45
37
|
|
|
46
|
-
|
|
38
|
+
Keep only evidence-backed, actionable findings with realistic trigger or concrete maintenance impact. Keep valid Minor findings. Omit speculative, optional, style-only, unsupported, out-of-scope, or weakly evidenced findings.
|
|
47
39
|
|
|
48
|
-
|
|
40
|
+
Spot-check only ambiguous or high-impact findings; do not turn it into a second review.
|
|
49
41
|
|
|
50
42
|
## Merge
|
|
51
43
|
|
|
52
|
-
Reply in the user's language. Apply the gate before merging.
|
|
53
|
-
|
|
54
|
-
For each accepted finding, preserve enough detail to act without reading subagent logs:
|
|
44
|
+
Reply in the user's language. Apply the gate before merging. Preserve enough detail to act without reading subagent logs:
|
|
55
45
|
|
|
56
46
|
**[SEVERITY] Category: Title**
|
|
57
47
|
Source: `code-reviewer` | `quality-reviewer` | `both`
|
|
@@ -59,25 +49,14 @@ File: `path:line`
|
|
|
59
49
|
Issue: what is wrong
|
|
60
50
|
Evidence: what was verified
|
|
61
51
|
Impact: concrete consequence
|
|
62
|
-
Fix:
|
|
63
|
-
|
|
64
|
-
Do not forward findings as summaries only. If evidence, location, or fix is missing and cannot be inferred from the reviewer result, omit the finding or report it as insufficiently evidenced.
|
|
65
|
-
|
|
66
|
-
Sections:
|
|
52
|
+
Fix: suggested correction
|
|
67
53
|
|
|
68
|
-
|
|
69
|
-
List all accepted findings in severity order. Use `Source:` to identify `code-reviewer`, `quality-reviewer`, or `both`.
|
|
54
|
+
Do not forward findings as summaries. Omit findings with missing evidence, location, or fix.
|
|
70
55
|
|
|
71
|
-
|
|
56
|
+
### Sections
|
|
72
57
|
|
|
73
|
-
No accepted findings.
|
|
58
|
+
**Findings**: in severity order. If none: "No accepted findings."
|
|
74
59
|
|
|
75
|
-
|
|
76
|
-
- Scope: [review scope]
|
|
77
|
-
- Reviewers: [completed reviewers and any failures]
|
|
78
|
-
- Findings: [count by severity]
|
|
79
|
-
- Result: [one-sentence overall assessment]
|
|
60
|
+
**Summary**: scope, completed/failed reviewers, findings by severity, one-sentence assessment.
|
|
80
61
|
|
|
81
|
-
|
|
82
|
-
- Do not repeat overlapping findings.
|
|
83
|
-
- Mark a finding as `Source: both` only when both reviewers clearly reported the same issue.
|
|
62
|
+
Do not repeat overlapping findings. Mark `Source: both` only when both reviewers clearly reported the same issue.
|
package/skills/pi-crew/SKILL.md
CHANGED
|
@@ -1,27 +1,50 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pi-crew
|
|
3
|
-
description: "MUST be read before using
|
|
3
|
+
description: "MUST be read before using crew_list, crew_spawn, crew_respond, crew_done, or crew_abort. Use to delegate bounded research, review, coding, or testing to non-blocking background subagents that run in isolated sessions while your session stays interactive; you own decomposition, scope, result vetting, and final synthesis."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Pi Crew
|
|
7
7
|
|
|
8
|
-
Use this skill to coordinate subagents safely. Core rule: delegate clearly
|
|
8
|
+
Use this skill to coordinate subagents safely. Core rule: delegate clearly with self-contained tasks, let delegated work run without redoing it, and manage the async/interactive lifecycle explicitly.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
## Your Responsibilities
|
|
11
|
+
|
|
12
|
+
Keep these responsibilities local:
|
|
13
|
+
|
|
14
|
+
- Decide whether delegation is worth it.
|
|
15
|
+
- Split work into independent, non-overlapping slices.
|
|
16
|
+
- Define scope, stop conditions, and acceptance criteria.
|
|
17
|
+
- Vet returned evidence before relying on it.
|
|
18
|
+
- Resolve conflicting results.
|
|
19
|
+
- Integrate outcomes and own the final user-facing synthesis.
|
|
20
|
+
|
|
21
|
+
## Context Boundary
|
|
22
|
+
|
|
23
|
+
A subagent runs isolated from your session but inside the same repository:
|
|
24
|
+
|
|
25
|
+
- It sees only the `task` you write plus what it can read from the working directory. Every subagent can read repo files, config, and persistent docs to gather context on its own; whether it can also edit files or run commands depends on the chosen subagent's tools (see `crew_list`).
|
|
26
|
+
- It cannot see your session conversation, your reasoning, user decisions, or prior subagent results unless they are written to a durable file. Put any such context the subagent needs directly in the task.
|
|
27
|
+
- Do not dump context the subagent can find itself (repo structure, conventions, Git state, changed-file lists). Do include session-only intent, decisions, and conclusions it cannot discover.
|
|
28
|
+
- State the exact output you need (deliverable, format, acceptance criteria) so the subagent works toward it and returns something you can act on.
|
|
29
|
+
|
|
30
|
+
Write every task so a subagent that knows nothing about this session can complete it and return the output you need.
|
|
11
31
|
|
|
12
32
|
## Protocol
|
|
13
33
|
|
|
14
34
|
- Call `crew_list` before each new spawn decision. Choose from discovered names, descriptions, capabilities, and `interactive` flags; do not assume fixed agents exist.
|
|
15
|
-
- Spawn only when delegation adds clear value: independent parallel work, focused investigation, review, planning, implementation, or
|
|
16
|
-
- Do not spawn for tiny tasks, unclear tasks, or work whose required context cannot be summarized safely.
|
|
17
|
-
- Before spawning, gather only the minimum context needed to
|
|
18
|
-
- Subagents cannot see your conversation, files read, commands run, decisions, or conclusions unless you include them in the task.
|
|
35
|
+
- Spawn only when delegation adds clear value: independent parallel work, broad repo search, focused investigation, review, planning, bounded implementation, verification runs, browser/test passes, or log reduction.
|
|
36
|
+
- Do not spawn for tiny tasks, unclear tasks, immediate blockers you must resolve before proceeding, or work whose required context cannot be summarized safely.
|
|
37
|
+
- Before spawning, gather only the minimum context needed to write the task; do not start the investigation, review, plan, or implementation you intend to delegate.
|
|
19
38
|
- Parallel spawns must be independent and non-overlapping. If multiple subagents may touch the same files or ownership area, serialize them.
|
|
20
|
-
- Results arrive asynchronously as steering messages. Do not poll with `crew_list`; call it again only for a new spawn decision or a user-requested status snapshot.
|
|
21
39
|
|
|
22
40
|
## Spawn Brief
|
|
23
41
|
|
|
24
|
-
|
|
42
|
+
Every `crew_spawn` needs:
|
|
43
|
+
|
|
44
|
+
- `brief`: short human-readable label for session lists, ideally under 80 chars. State intent/outcome only; no full task, criteria, long paths, secrets, or repo inventory.
|
|
45
|
+
- `task`: self-contained work request with only the context this subagent needs.
|
|
46
|
+
|
|
47
|
+
Include task-specific details only when useful:
|
|
25
48
|
|
|
26
49
|
```md
|
|
27
50
|
Intent / context:
|
|
@@ -29,24 +52,57 @@ Relevant inputs / entry points:
|
|
|
29
52
|
Constraints / decisions:
|
|
30
53
|
Deliverable / expected outcome:
|
|
31
54
|
Verification / checks:
|
|
55
|
+
Stop conditions:
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Omit sections that add no task-specific value. Do not restate the subagent’s role, default scope, edit permissions, output format, obvious next steps, cwd/branch, Git status, or full changed-file lists unless they define the scope.
|
|
59
|
+
|
|
60
|
+
Prefer short Markdown bullets for multi-part context, constraints, requirements, or acceptance criteria. Use stop conditions for assumptions that may fail, scope that may expand, repeated verification failures, or missing evidence.
|
|
61
|
+
|
|
62
|
+
For repeated workflows, summarize the relevant facts or point to durable artifacts the subagent can read; avoid vague references like “the previous fixes.”
|
|
63
|
+
|
|
64
|
+
If the user points to a plan, spec, issue, design, or doc, read it when practical and summarize the relevant intent instead of only passing the path.
|
|
65
|
+
|
|
66
|
+
### Examples
|
|
67
|
+
|
|
68
|
+
Good `task` (intent-first and self-contained):
|
|
69
|
+
|
|
70
|
+
```md
|
|
71
|
+
Intent / context:
|
|
72
|
+
Password reset emails should expire after 30 minutes, but old reset links still work hours later.
|
|
73
|
+
|
|
74
|
+
Relevant inputs / entry points:
|
|
75
|
+
- Password reset request handler.
|
|
76
|
+
- Token validation path used by the reset form.
|
|
77
|
+
- Config or DB fields storing token expiry.
|
|
78
|
+
|
|
79
|
+
Constraints / decisions:
|
|
80
|
+
- Keep the existing email template and reset URL format.
|
|
81
|
+
- Do not change login or account creation.
|
|
82
|
+
|
|
83
|
+
Deliverable:
|
|
84
|
+
Likely root cause and the smallest safe fix direction.
|
|
32
85
|
```
|
|
33
86
|
|
|
34
|
-
|
|
87
|
+
Avoid tasks like `Fix this.`, `Investigate the bug we discussed.`, or `Implement the plan.`: they depend on session-only context the subagent cannot see.
|
|
35
88
|
|
|
36
|
-
|
|
89
|
+
## After Spawning
|
|
37
90
|
|
|
38
|
-
|
|
91
|
+
`crew_spawn` is non-blocking: it returns immediately without the result, the subagent runs in the background, and its result is delivered separately as a steering message. Ownership of the task transfers to the subagent.
|
|
39
92
|
|
|
40
|
-
|
|
93
|
+
Once you spawn:
|
|
41
94
|
|
|
42
|
-
|
|
95
|
+
- Do not perform, redo, continue, or pre-empt the delegated task in this turn, even partially, and even if you believe you could finish it faster yourself.
|
|
96
|
+
- Do only work that is independent of and non-overlapping with what you delegated.
|
|
97
|
+
- If you have no such independent work, end your turn and wait for the result. Do not poll; call `crew_list` again only for a new spawn decision or a requested status snapshot.
|
|
43
98
|
|
|
44
99
|
## Result Handling
|
|
45
100
|
|
|
46
101
|
- Wait for subagent results before using them. Never invent or predict results.
|
|
102
|
+
- Treat subagent results as evidence to inspect, not verdicts to forward.
|
|
47
103
|
- Evaluate each result against the task acceptance criteria.
|
|
48
|
-
- If
|
|
49
|
-
-
|
|
104
|
+
- If a subagent errors or aborts, report that status and continue only if the remaining results are sufficient.
|
|
105
|
+
- If results conflict, do not average or silently pick one; state the conflict, compare evidence, and resolve with available facts or a targeted follow-up. If a result is incomplete or misses criteria, use a focused follow-up or new spawn only when needed.
|
|
50
106
|
|
|
51
107
|
## Interactive Subagents
|
|
52
108
|
|
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
# Pi Crew Reference
|
|
2
|
-
|
|
3
|
-
## Delegation Checklist
|
|
4
|
-
|
|
5
|
-
Before `crew_spawn`, ensure the brief is self-contained but not mechanically templated. Include only information that helps this specific subagent do this specific task:
|
|
6
|
-
|
|
7
|
-
- Intent, expected outcome, and relevant user decisions.
|
|
8
|
-
- User-provided references, plus a concise summary after reading them when practical.
|
|
9
|
-
- File paths, symbols, entry points, commands, errors, or logs only when they genuinely clarify the task.
|
|
10
|
-
- Non-default scope, constraints, assumptions, or verification context only when they matter.
|
|
11
|
-
- Gaps or unresolved questions the subagent should account for.
|
|
12
|
-
|
|
13
|
-
Do not restate boilerplate implied by the selected subagent’s role, name, or description. Avoid repeating default scope, edit permissions, output format, generic repo guidance, cwd/branch details, or mechanical Git state the subagent can inspect itself.
|
|
14
|
-
|
|
15
|
-
Do not rely on hidden active-session context. If the subagent needs a decision, conclusion, user intent, or prior result that is not discoverable from files/tools, include it.
|
|
16
|
-
|
|
17
|
-
## Good Brief
|
|
18
|
-
|
|
19
|
-
```md
|
|
20
|
-
Intent / context:
|
|
21
|
-
Password reset emails should expire after 30 minutes. Users report that old reset links still work several hours later.
|
|
22
|
-
|
|
23
|
-
Relevant inputs / entry points:
|
|
24
|
-
- The password reset request handler.
|
|
25
|
-
- The token validation path used by the reset form.
|
|
26
|
-
- Any configuration or database fields that store token expiry.
|
|
27
|
-
|
|
28
|
-
Constraints / decisions:
|
|
29
|
-
- Preserve the existing email template and reset URL format.
|
|
30
|
-
- Do not change login or account creation behavior.
|
|
31
|
-
|
|
32
|
-
Deliverable:
|
|
33
|
-
Identify the likely root cause and the smallest safe fix direction.
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
## Bad Briefs
|
|
37
|
-
|
|
38
|
-
```md
|
|
39
|
-
Fix this.
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
```md
|
|
43
|
-
Investigate the bug we discussed.
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
```md
|
|
47
|
-
Implement the plan.
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
```md
|
|
51
|
-
Goal: Review the current uncommitted changes for actionable bugs.
|
|
52
|
-
Scope: Current repo changes, staged/unstaged/untracked files.
|
|
53
|
-
Non-goals: Do not modify files.
|
|
54
|
-
Expected output: Findings with severity and fix direction.
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
These depend on hidden conversation state, restate subagent boilerplate, or carry mechanical repository state instead of task-specific intent.
|
|
58
|
-
|
|
59
|
-
## Parallel Delegation
|
|
60
|
-
|
|
61
|
-
Use parallel subagents only when tasks are independent:
|
|
62
|
-
|
|
63
|
-
- Good: one reviewer checks correctness while another checks maintainability.
|
|
64
|
-
- Good: scouts inspect separate modules with non-overlapping files.
|
|
65
|
-
- Bad: two workers edit the same file or feature area simultaneously.
|
|
66
|
-
|
|
67
|
-
If ownership overlaps, serialize the work.
|
|
68
|
-
|
|
69
|
-
## Failure and Conflict Handling
|
|
70
|
-
|
|
71
|
-
- If a subagent errors or aborts, report that status clearly and continue only if remaining results are sufficient.
|
|
72
|
-
- If a result misses the task-specific deliverable, ask a focused follow-up or spawn a new subagent with a corrected brief.
|
|
73
|
-
- If results conflict, do not average them or pick silently. State the conflict, compare evidence, and resolve only with available facts or a targeted follow-up.
|
|
74
|
-
- If a task becomes obsolete, abort the relevant active subagent.
|
|
75
|
-
|
|
76
|
-
## Tool Notes
|
|
77
|
-
|
|
78
|
-
- `crew_list`: discovery before a new spawn decision or requested status snapshot; never completion polling.
|
|
79
|
-
- `crew_spawn`: self-contained delegation; ownership transfers after spawn.
|
|
80
|
-
- `crew_respond`: send a follow-up to a waiting interactive subagent; fire-and-forget.
|
|
81
|
-
- `crew_done`: close a waiting interactive subagent when complete.
|
|
82
|
-
- `crew_abort`: abort active owned subagents only when obsolete, wrong, or cancelled.
|