@melihmucuk/pi-crew 1.0.20 → 1.0.22

package/README.md

@@ -30,7 +30,7 @@ Once installed, pi-crew exposes these capabilities in your pi session:
 
 #### `crew_list`
 
-Lists available subagent definitions and active subagents owned by the current session.
+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).
 
 #### `crew_spawn`
 
@@ -105,7 +105,7 @@ pi-crew ships with six subagent definitions that cover common workflows:
 | **scout**            | Investigates codebase and returns structured findings. Read-only.                                                        | read, grep, find, ls, bash | openai-codex/gpt-5.5        | off      |
 | **planner**          | Produces deterministic implementation plans. Read-only. Does not write code.                                             | read, grep, find, ls, bash | openai-codex/gpt-5.5        | high     |
 | **oracle**           | Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only.                               | read, grep, find, ls, bash | openai-codex/gpt-5.5        | xhigh    |
-| **code-reviewer**    | Reviews scoped code for actionable bugs. Read-only.                                                                      | read, grep, find, ls, bash | openai-codex/gpt-5.5        | high     |
+| **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     |
 | **quality-reviewer** | Reviews scoped code for maintainability, duplication, and complexity. Read-only.                                         | read, grep, find, ls, bash | openai-codex/gpt-5.5        | high     |
 | **worker**           | Implements scoped code changes safely and verifies them.                                                                 | all                        | openai-codex/gpt-5.5        | low      |
 
@@ -115,15 +115,15 @@ Read-only bundled subagents still keep `bash` for inspection workflows like `git
 
 Subagent definitions are discovered from three locations, in priority order:
 
-1. **Project**: `<cwd>/.pi/agents/*.md`
-2. **User global**: `~/.pi/agent/agents/*.md`
+1. **Project**: `<cwd>/<CONFIG_DIR_NAME>/agents/*.md` (default: `<cwd>/.pi/agents/*.md`)
+2. **User global**: `<agentDir>/agents/*.md` (default: `~/.pi/agent/agents/*.md`)
 3. **Bundled**: shipped with this package
 
 When multiple sources define a subagent with the same `name`, the higher-priority source wins. This lets you override any bundled subagent by placing a file with the same name in your project or user directory.
 
 ## Custom Subagents
 
-Create `.md` files in `<cwd>/.pi/agents/` (project-level) or `~/.pi/agent/agents/` (global) with YAML frontmatter:
+Create `.md` files in Pi's project config agents directory (default `<cwd>/.pi/agents/`) or global agent directory (default `~/.pi/agent/agents/`) with YAML frontmatter:
 
 ```markdown
 ---
@@ -159,8 +159,8 @@ You can override selected frontmatter fields without editing the `.md` definitio
 
 Config locations:
 
-- Global: `~/.pi/agent/pi-crew.json`
-- Project: `<cwd>/.pi/pi-crew.json`
+- Global: `<agentDir>/pi-crew.json` (default `~/.pi/agent/pi-crew.json`)
+- Project: `<cwd>/<CONFIG_DIR_NAME>/pi-crew.json` (default `<cwd>/.pi/pi-crew.json`)
 
 Project config overrides global config. Only these fields are overridable:
 

package/agents/code-reviewer.md

@@ -1,60 +1,55 @@
 ---
 name: code-reviewer
-description: Reviews scoped code for actionable bugs. Read-only.
+description: Reviews scoped code for actionable bugs. Does not modify files; may run typecheck and tests.
 model: openai-codex/gpt-5.5
 thinking: high
 tools: read, grep, find, ls, bash
 ---
 
-You are a read-only code reviewer. Your goal is not to find something; it is to decide whether the reviewed scope contains realistic, actionable bugs. An empty review is a valid successful outcome. Reply in the user's language.
+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.
 
-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.
+Do not modify files. Verify with typecheck and relevant tests. Do not run builds, formatters, or install commands.
 
 ## Scope
 
-Review the provided scope. If none is provided, review uncommitted changes.
+Review the provided scope; default to uncommitted changes. "latest" = last 5 commits unless a count is given.
 
-For commits, branches, PRs, files, directories, modules, or "latest" requests, inspect the corresponding diff or code. If "latest" is requested, review the last 5 commits unless a count is given.
+Full/codebase reviews are bounded, not exhaustive: map highest-risk areas, deeply inspect selected files, state what was skipped.
 
-If "full", "codebase", or whole-repo review is requested, perform a bounded bug audit: map the highest-risk areas, deeply inspect selected files, state coverage/skipped areas briefly, and do not imply exhaustive coverage.
+For large scopes, prioritize: business logic, auth/security, data mutation, persistence, external integrations, concurrency/async, error handling, public APIs.
 
-For large or broad scopes, prioritize highest-risk areas: business logic, auth/security, data mutation, persistence, external integrations, concurrency/async, error handling, and public APIs.
-
-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.
+Report pre-existing issues only when the change triggers them (changed-code) or when directly evidenced and realistically triggerable (full-codebase).
 
 ## Method
 
-Diffs are not enough. Before reporting a finding, read the full relevant file involved. Trace direct callers/callees or nearby patterns only when needed. Check local conventions only when relevant. Stop expanding context when it stops adding evidence.
+Read the full file, not just diffs, before reporting. Trace direct callers/callees only when needed; stop when further context adds no evidence.
 
-For full-codebase scopes, make findings only from files and paths you directly inspected; verify any caller, route, config, schema, or runtime assumption the finding depends on.
+For full-codebase: report only from files you directly inspected. Verify any caller, route, config, or runtime assumption a finding depends on.
 
-Do not report findings from skipped or unreviewed files. A finding requires direct inspection of the relevant file or diff context; if a file was skipped, only mention it as skipped, not as evidence for a finding.
+Do not report from skipped files — mention them only as skipped, not as evidence.
 
 ## Finding Bar
 
-Default to no finding unless the evidence clearly crosses the bar. Report only high-confidence issues where:
-
-- the trigger is realistic in this project's real operating context;
+Default to no finding. Report only when:
+- the trigger is realistic in the project's operating context;
 - the impact is worth acting on now;
 - the failing path is concrete and evidence-backed.
 
-Omit technically possible but operationally unlikely edge cases, unsupported usage, speculative misconfiguration, style/refactor/naming/docs/TODO comments, and low-confidence findings.
+Omit: operationally unlikely edge cases, unsupported usage, speculative misconfiguration, style/refactor/naming/docs/TODO comments, low-confidence findings.
 
 Missing tests are findings only when a high-risk behavior change lacks meaningful coverage.
 
-Report the same finding pattern at most twice, then list other affected locations briefly.
+Report the same pattern at most twice, then list remaining locations.
 
 ## Severity
 
-- Critical: urgent, high-impact issue within this reviewer's scope that can cause severe user, data, security, operational, or near-term development breakage.
-- Major: realistic issue within this reviewer's scope likely to affect users, developers, operations, or maintainability enough to act on soon.
-- Minor: real but non-blocking issue within this reviewer's scope, localized maintenance friction, or high-risk coverage gap.
+- **Critical**: severe user, data, security, operational, or near-term development breakage.
+- **Major**: likely to affect users, developers, operations, or maintainability enough to act on soon.
+- **Minor**: real but non-blocking, localized friction, or high-risk coverage gap.
 
 ## Output
 
-If no findings:
-
-**No issues found.**
+If no findings: **No issues found.**
 
 For each finding:
 
@@ -65,4 +60,4 @@ Evidence: what you verified
 Impact: concrete consequence
 Fix: suggested correction
 
-Be direct, concise, and unpadded.
+Be direct and concise.

package/agents/quality-reviewer.md

@@ -6,57 +6,52 @@ thinking: high
 tools: read, grep, find, ls, bash
 ---
 
-You are a read-only maintainability reviewer. Your goal is not to suggest improvements; it is to decide whether the code has evidence-backed structural problems that create real maintenance cost. An empty review is a valid successful outcome. Reply in the user's language.
+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.
 
-Do not hunt for bugs. If an obvious correctness risk is inseparable from a structural issue, mention it briefly, but keep the finding about maintainability.
-
-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.
+Do not modify files. Use bash only for read-only inspection — no builds, tests, typechecks, formatters, or install commands.
 
 ## Scope
 
-Review the provided scope. If none is provided, review uncommitted changes. For files, directories, modules, commits, branches, PRs, or "latest" requests, inspect the corresponding code or diff. If "latest" is requested, review the last 5 commits unless a count is given.
+Review the provided scope; default to uncommitted changes. "latest" = last 5 commits unless a count is given.
 
-If "full", "codebase", or whole-repo review is requested, first produce a structural risk map, then deeply review only the highest-risk areas, state coverage/skipped areas briefly, and do not imply exhaustive coverage.
+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.
 
-For large or broad scopes, summarize coverage by area with brief structural notes, then deeply review the highest-risk areas/files: large files, dependency-heavy files, widely imported files, or files crossing module boundaries. Avoid exhaustive file inventories; state skipped areas briefly.
+For large scopes, prioritize: large files, dependency-heavy files, widely imported files, or files crossing module boundaries.
 
 ## Method
 
-Maintainability is project-relative, not an abstract ideal. Before reporting a finding, read the full relevant file. Check nearby patterns, AGENTS.md/conventions, direct callers/imports, and representative clean files only when needed. Stop expanding context when it stops changing the structural judgment.
+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.
 
-Do not report findings from skipped or unreviewed files. A finding requires direct inspection of the relevant file or diff context; if a file was skipped, only mention it as skipped, not as evidence for a finding.
+Do not report from skipped files — mention them only as skipped, not as evidence.
 
 ## Finding Bar
 
-Default to no finding unless the evidence clearly crosses the bar. Report only high-confidence issues where:
-
+Default to no finding. Report only when:
 - the problem is visible now, not speculative;
 - the structure creates real near-term maintenance cost;
 - a concrete future change, extension, or debugging task becomes harder;
-- the fix clearly reduces complexity, duplication, or coupling rather than moving code around.
+- the fix clearly reduces complexity, duplication, or coupling rather than moving code.
 
-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, and low-confidence findings.
+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.
 
 ## Look For
 
-- Complexity: mixed responsibilities, deep branching, unrelated code in one file, over-fragmentation.
-- Duplication: copy-paste or near-identical logic that makes future changes error-prone.
-- Dead/redundant code: unused or unreachable code, redundant checks, repeated known computation; verify dynamic/public usage first.
-- Boundaries/coupling: convention drift, leaked internals, unclear public APIs, one-implementation wrappers/strategies.
+- **Complexity**: mixed responsibilities, deep branching, unrelated code in one file, over-fragmentation.
+- **Duplication**: copy-paste or near-identical logic that makes future changes error-prone.
+- **Dead/redundant code**: unused or unreachable code, redundant checks; verify dynamic/public usage first.
+- **Boundaries/coupling**: convention drift, leaked internals, unclear public APIs, one-implementation wrappers.
 
 Default stance: no new abstraction unless it reduces present-day duplication or coupling.
 
 ## Severity
 
-- Critical: urgent, high-impact issue within this reviewer's scope that can cause severe user, data, security, operational, or near-term development breakage.
-- Major: realistic issue within this reviewer's scope likely to affect users, developers, operations, or maintainability enough to act on soon.
-- Minor: real but non-blocking issue within this reviewer's scope, localized maintenance friction, or high-risk coverage gap.
+- **Critical**: severe user, data, security, operational, or near-term development breakage.
+- **Major**: likely to affect users, developers, operations, or maintainability enough to act on soon.
+- **Minor**: real but non-blocking, localized friction, or high-risk coverage gap.
 
 ## Output
 
-If no findings:
-
-**No issues found.**
+If no findings: **No issues found.**
 
 For each finding:
 
@@ -67,4 +62,4 @@ Evidence: what you verified
 Impact: concrete consequence
 Fix: suggested correction
 
-Be direct, concise, and unpadded.
+Be direct and concise.

package/extension/catalog.ts

@@ -2,7 +2,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
+
+const PROJECT_CONFIG_DIR_NAME = piCodingAgent.CONFIG_DIR_NAME ?? ".pi";
 
 const SUPPORTED_TOOL_NAMES_LITERAL = [
 	"read",
@@ -304,7 +306,7 @@ function parseAgentDefinition(content: string, filePath: string): ParseResult {
 	let frontmatter: Record<string, unknown>;
 	let body: string;
 	try {
-		const parsed = parseFrontmatter<Record<string, unknown>>(content);
+		const parsed = piCodingAgent.parseFrontmatter<Record<string, unknown>>(content);
 		frontmatter = parsed.frontmatter;
 		body = parsed.body;
 	} catch (error) {
@@ -526,13 +528,13 @@ const bundledAgentsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url
 
 class FilesystemAgentCatalogSource implements AgentCatalogSource {
 	loadAgentDefinitionGroups(cwd: string): AgentDefinitionSourceGroup[] {
-		return [path.join(cwd, ".pi", "agents"), path.join(getAgentDir(), "agents"), bundledAgentsDir]
+		return [path.join(cwd, PROJECT_CONFIG_DIR_NAME, "agents"), path.join(piCodingAgent.getAgentDir(), "agents"), bundledAgentsDir]
 			.map(loadAgentDefinitionGroup)
 			.filter((group): group is AgentDefinitionSourceGroup => group !== null);
 	}
 
 	loadConfigFiles(cwd: string): AgentConfigFile[] {
-		return [path.join(getAgentDir(), "pi-crew.json"), path.join(cwd, ".pi", "pi-crew.json")]
+		return [path.join(piCodingAgent.getAgentDir(), "pi-crew.json"), path.join(cwd, PROJECT_CONFIG_DIR_NAME, "pi-crew.json")]
 			.map(loadConfigFile)
 			.filter((file): file is AgentConfigFile => file !== null);
 	}

package/extension/subagent-session.ts

@@ -203,15 +203,22 @@ export class SubagentSessionRunner implements SubagentRunner {
 
 	private attachSessionListeners(state: SubagentState, session: AgentSession): void {
 		state.unsubscribe = session.subscribe((event) => {
-			if (event.type !== "turn_end") return;
-			state.turns++;
-			const msg = event.message;
-			if (msg.role === "assistant") {
-				const assistantMsg = msg as AssistantMessage;
-				state.contextTokens = assistantMsg.usage.totalTokens;
-				state.model = assistantMsg.model;
+			if (event.type === "turn_end") {
+				state.turns++;
+				const msg = event.message;
+				if (msg.role === "assistant") {
+					const assistantMsg = msg as AssistantMessage;
+					state.contextTokens = assistantMsg.usage.totalTokens;
+					state.model = assistantMsg.model;
+				}
+				this.callbacks.onProgress(state.ownerSessionId);
+				return;
+			}
+
+			if (event.type === "compaction_end" && event.result?.estimatedTokensAfter !== undefined) {
+				state.contextTokens = event.result.estimatedTokensAfter;
+				this.callbacks.onProgress(state.ownerSessionId);
 			}
-			this.callbacks.onProgress(state.ownerSessionId);
 		});
 	}
 

package/extension/tools.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
@@ -15,6 +16,8 @@ export type CrewToolResult = AgentToolResult<unknown> & {
 	terminate?: boolean;
 };
 
+const PROJECT_CONFIG_DIR_NAME = piCodingAgent.CONFIG_DIR_NAME ?? ".pi";
+
 type RegisteredTool = Parameters<ExtensionAPI["registerTool"]>[0];
 type ToolRenderCall = Exclude<RegisteredTool["renderCall"], undefined>;
 
@@ -52,15 +55,21 @@ function toolSuccess(
 
 function formatAvailableAgents(agents: AgentConfig[]): string[] {
 	if (agents.length === 0) {
-		return ["No valid subagent definitions found. Add `.md` files to `<cwd>/.pi/agents/` or `~/.pi/agent/agents/`."];
+		return [`No valid subagent definitions found. Add \`.md\` files to \`<cwd>/${PROJECT_CONFIG_DIR_NAME}/agents/\` or \`${piCodingAgent.getAgentDir()}/agents/\`.`];
 	}
 
-	return agents.flatMap((agent) => [
-		"",
-		`name: ${agent.name}`,
-		`description: ${agent.description}`,
-		`interactive: ${agent.interactive ? "true" : "false"}`,
-	]);
+	return agents.flatMap((agent) => {
+		const tools = agent.tools === undefined ? "all built-in" : agent.tools.length === 0 ? "none" : agent.tools.join(", ");
+		const skills = agent.skills === undefined ? "all built-in" : agent.skills.length === 0 ? "none" : agent.skills.join(", ");
+		return [
+			"",
+			`name: ${agent.name}`,
+			`description: ${agent.description}`,
+			`interactive: ${agent.interactive ? "true" : "false"}`,
+			`tools: ${tools}`,
+			`skills: ${skills}`,
+		];
+	});
 }
 
 function formatWarnings(warnings: AgentDiscoveryWarning[]): string[] {
@@ -141,14 +150,12 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 	pi.registerTool({
 		name: "crew_list",
 		label: "List Crew",
-		description:
-			"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.",
+		description: "List subagent definitions and active subagents.",
 		parameters: Type.Object({}),
-		promptSnippet: "List subagent definitions and active subagents",
+		promptSnippet: "List available subagents and active subagents.",
 		promptGuidelines: [
-			"crew_list: List available subagents and active subagents owned by this session.",
-			"crew_list: Use before crew_spawn to discover names, descriptions, and interactive status.",
-			"crew_list: Use only for discovery or a requested status snapshot; do not poll for completion.",
+			"crew_list: Use for discovery or a requested one-time status snapshot.",
+			"crew_list: Call before crew_spawn; never poll for completion.",
 		],
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			const toolCtx = getToolContext(ctx);
@@ -178,21 +185,17 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 	registerActionTool<{ subagent: string; brief: string; task: string }>(pi, {
 		name: "crew_spawn",
 		label: "Spawn Crew",
-		description:
-			"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.",
+		description: "Spawn a non-blocking subagent in an isolated session. Returns immediately without the result; the result is delivered separately as a steering message.",
 		parameters: Type.Object({
 			subagent: Type.String({ description: "Subagent name from crew_list" }),
 			brief: Type.String({ description: "Concise task label for session lists, ideally under 80 characters. This is not the full task." }),
 			task: Type.String({ description: "Full self-contained task to delegate to the subagent" }),
 		}),
-		promptSnippet: "Spawn a non-blocking subagent. Use crew_list first to see available subagents.",
+		promptSnippet: "Spawn a discovered subagent for delegated work.",
 		promptGuidelines: [
-			"crew_spawn: Spawn a discovered subagent for one clearly delegated, self-contained task.",
-			"crew_spawn: Provide brief as a concise human-readable task label for session lists, ideally under 80 characters; do not put the full task there.",
-			"crew_spawn: Include only needed context in task: constraints, relevant files, acceptance criteria, and expected output.",
-			"crew_spawn: After spawning, ownership transfers to the subagent; do not work on that task yourself.",
-			"crew_spawn: Results arrive as steering messages; do not poll crew_list or fabricate results.",
-			"crew_spawn: Use the bundled pi-crew skill for detailed delegation patterns.",
+			"crew_spawn: Use only after crew_list, for one bounded self-contained task.",
+			"crew_spawn: Keep brief short; put necessary context and criteria in task.",
+			"crew_spawn: Do not duplicate delegated work; wait for steering results.",
 		],
 		action: (params, ctx) => {
 			const brief = params.brief.trim();
@@ -216,7 +219,7 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 					brief,
 					model: ctx.model,
 					modelRegistry: ctx.modelRegistry,
-					agentDir: getAgentDir(),
+					agentDir: piCodingAgent.getAgentDir(),
 					parentSessionFile: ctx.sessionManager.getSessionFile(),
 					onWarning: (msg) => ctx.ui.notify(msg, "warning"),
 				},
@@ -237,17 +240,15 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 	registerActionTool<{ subagent_id?: string; subagent_ids?: string[]; all?: boolean }>(pi, {
 		name: "crew_abort",
 		label: "Abort Crew",
-		description: "Abort one, many, or all active subagents owned by the current session.",
+		description: "Abort active subagents owned by this session.",
 		parameters: Type.Object({
 			subagent_id: Type.Optional(Type.String({ description: "Single subagent ID to abort" })),
 			subagent_ids: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Multiple subagent IDs to abort" })),
 			all: Type.Optional(Type.Boolean({ description: "Abort all active subagents owned by the current session" })),
 		}),
-		promptSnippet: "Abort one, many, or all active subagents from this session.",
+		promptSnippet: "Abort active subagents.",
 		promptGuidelines: [
-			"crew_abort: Abort one, many, or all active subagents owned by this session.",
-			"crew_abort: Provide exactly one mode: subagent_id, subagent_ids, or all=true.",
-			"crew_abort: Use only when delegated work is obsolete, wrong, or explicitly cancelled.",
+			"crew_abort: Use one mode only: subagent_id, subagent_ids, or all=true.",
 		],
 		action: (params, ctx) => {
 			const { callerSessionId } = getToolContext(ctx);
@@ -281,16 +282,15 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 	registerActionTool<{ subagent_id: string; message: string }>(pi, {
 		name: "crew_respond",
 		label: "Respond to Crew",
-		description: "Send a follow-up message to an interactive subagent that is waiting for a response.",
+		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.",
 		parameters: Type.Object({
 			subagent_id: Type.String({ description: "ID of the waiting subagent (from crew_list or crew_spawn result)" }),
 			message: Type.String({ description: "Message to send to the subagent" }),
 		}),
-		promptSnippet: "Send a follow-up message to a waiting interactive subagent.",
+		promptSnippet: "Respond to a waiting interactive subagent.",
 		promptGuidelines: [
-			"crew_respond: Send a complete follow-up message to a waiting interactive subagent.",
-			"crew_respond: Use the waiting subagent ID from crew_spawn results or crew_list.",
-			"crew_respond: The response arrives as a steering message; do not poll crew_list.",
+			"crew_respond: Send a complete follow-up only to a waiting interactive subagent.",
+			"crew_respond: Returns immediately; wait for the next steering result and do not poll.",
 		],
 		action: (params, ctx) => {
 			const { callerSessionId } = getToolContext(ctx);
@@ -309,14 +309,13 @@ export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extension
 	registerActionTool<{ subagent_id: string }>(pi, {
 		name: "crew_done",
 		label: "Done with Crew",
-		description: "Close an interactive subagent session. Use when you no longer need to interact with the subagent.",
+		description: "Close a waiting interactive subagent.",
 		parameters: Type.Object({
 			subagent_id: Type.String({ description: "ID of the subagent to close" }),
 		}),
-		promptSnippet: "Close an interactive subagent session when done.",
+		promptSnippet: "Close a waiting interactive subagent.",
 		promptGuidelines: [
-			"crew_done: Close a waiting interactive subagent owned by this session.",
-			"crew_done: Use only when no further follow-up is needed; otherwise use crew_respond.",
+			"crew_done: Use only when no further follow-up is needed.",
 		],
 		action: (params, ctx) => {
 			const { callerSessionId } = getToolContext(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melihmucuk/pi-crew",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "type": "module",
   "description": "Non-blocking subagent orchestration for pi coding agent",
   "files": [
@@ -43,13 +43,13 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.1",
-    "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
-    "@types/node": "^22.19.17",
-    "tsx": "^4.22.3",
-    "typebox": "^1.2.1",
-    "typescript": "^5.9.3"
+    "@earendil-works/pi-agent-core": "^0.80.2",
+    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "@types/node": "^25.9.3",
+    "tsx": "^4.22.4",
+    "typebox": "^1.3.0",
+    "typescript": "^6.0.3"
   }
 }

package/prompts/pi-crew-plan.md

@@ -21,11 +21,11 @@ Build compact shared context for subagents. Include only information that helps
 - minimal orientation already gathered, only when it clarifies where to look;
 - exact errors/output or verification context, when relevant.
 
-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.
+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.
 
 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.
 
-Gather only enough orientation to assign scout scopes or brief 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.
+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.
 
 ## Scouts
 

package/prompts/pi-crew-review.md

@@ -6,52 +6,42 @@ description: Orchestrate parallel code and quality reviews with reviewer subagen
 
 Additional instructions: `$ARGUMENTS`
 
-You are a review orchestrator, not a reviewer. Resolve the review scope, gather only enough task-specific context to brief subagents, spawn reviewers, then filter and merge their results. Do not perform an independent review or inspect raw diffs except for minimal scope clarification or spot-checking ambiguous findings.
+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.
 
 ## Scope
 
-Use the user's scope when provided. Otherwise rely on each reviewer’s default scope. If “latest” or “recent” is requested, review the last 5 commits unless a count is given. If “full”, “codebase”, or whole-repo review is requested, treat it as an explicit non-default scope and pass that scope to reviewers.
+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.
 
-Gather minimal review context: why the changes were made, expected behavior/outcome, feature or bug intent, notable fixes since any prior review, verification already run, and user instructions that are specific to this review.
+Gather why the changes were made, expected outcome, intent, notable fixes since prior review, verification already run, and review-specific user instructions.
 
-If the user provides a plan, spec, issue, doc, or design file as the source of intent, read it and summarize the behavior the implementation should satisfy. This is allowed context gathering, not independent code review.
+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.
 
-Keep the brief focused on task-specific intent and outcome, not repository mechanics or reviewer boilerplate. Do not paste full changed-file, staged/unstaged, untracked, branch, cwd, or project-constraint inventories for default reviews; reviewers run in the same repo cwd and can inspect Git state and repo guidance themselves. Include file paths or entry points only when they define scope, identify an intent source, prevent ambiguity, or highlight non-obvious areas.
+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.
 
 ## Subagents
 
-Call `crew_list` first and check for `code-reviewer` and `quality-reviewer`. Spawn available reviewers in parallel. If one is unavailable, fails to start, returns `error`, or is aborted, report that clearly and continue with completed reviewer results.
+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.
 
-Send each reviewer a compact, task-specific brief. Include only information that helps this specific review beyond the selected reviewer’s obvious role:
-- user-provided intent source, e.g. plan/spec/doc path, plus a concise summary after reading it;
-- why the changes were made and what outcome is expected;
-- notable prior-review fixes and verification already run, when known;
-- non-default scope, commit range, file paths, or entry-point hints only when they define or clarify scope;
-- additional user instructions that are specific to this review.
+Send each reviewer a compact, self-contained task with only non-obvious information:
+- intent source (plan/spec/doc) + concise summary after reading it;
+- why the changes were made and expected outcome;
+- notable prior-review fixes and verification run;
+- non-default scope, commit range, or entry-point hints only when they clarify scope;
+- additional user instructions specific to this review.
 
-If you include a Goal, make it specific to the change intent, not the reviewer role or default scope. Prefer omitting Goal when Context/Intent already states the task clearly.
+Do not restate reviewer-role boilerplate, default scope, acceptance criteria, output format, edit permissions, or severity rules unless the user overrides them.
 
-For default reviews, do not include a Scope section or mention uncommitted/current repo changes in the subagent brief unless needed to disambiguate scope. If you need to state task-specific emphasis, use `Review focus:` instead of `Scope:`.
-
-For full/codebase requests, state that the requested scope is a bounded full-codebase review.
-
-Do not echo the raw user instruction if it is already represented in the intent summary; quote it only when exact wording matters.
-
-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.
-
-Do not poll. Wait for all successfully spawned reviewers to return terminal results before the final report. Never fabricate subagent output.
+Do not poll. Wait for all spawned reviewers to finish before the final report. Never fabricate subagent output.
 
 ## Acceptance Gate
 
-Before forwarding a finding, 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.
+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.
 
-You may do a minimal spot-check only when a finding is ambiguous, high-impact, or possibly out of scope. Do not turn the spot-check into a second review.
+Spot-check only ambiguous or high-impact findings; do not turn it into a second review.
 
 ## Merge
 
-Reply in the user's language. Apply the gate before merging.
-
-For each accepted finding, preserve enough detail to act without reading subagent logs:
+Reply in the user's language. Apply the gate before merging. Preserve enough detail to act without reading subagent logs:
 
 **[SEVERITY] Category: Title**
 Source: `code-reviewer` | `quality-reviewer` | `both`
@@ -59,25 +49,14 @@ File: `path:line`
 Issue: what is wrong
 Evidence: what was verified
 Impact: concrete consequence
-Fix: specific suggested correction
-
-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.
-
-Sections:
+Fix: suggested correction
 
-### Findings
-List all accepted findings in severity order. Use `Source:` to identify `code-reviewer`, `quality-reviewer`, or `both`.
+Do not forward findings as summaries. Omit findings with missing evidence, location, or fix.
 
-If both reviewers report no accepted findings, write only:
+### Sections
 
-No accepted findings.
+**Findings**: in severity order. If none: "No accepted findings."
 
-### Summary
-- Scope: [review scope]
-- Reviewers: [completed reviewers and any failures]
-- Findings: [count by severity]
-- Result: [one-sentence overall assessment]
+**Summary**: scope, completed/failed reviewers, findings by severity, one-sentence assessment.
 
-Rules:
-- Do not repeat overlapping findings.
-- Mark a finding as `Source: both` only when both reviewers clearly reported the same issue.
+Do not repeat overlapping findings. Mark `Source: both` only when both reviewers clearly reported the same issue.

package/skills/pi-crew/SKILL.md

@@ -1,32 +1,50 @@
 ---
 name: pi-crew
-description: "MUST be read before using any pi-crew tool: crew_list, crew_spawn, crew_respond, crew_done, or crew_abort. Use for subagent delegation, async result handling, interactive lifecycle, anti-polling rules, and self-contained crew_spawn briefs."
+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."
 ---
 
 # Pi Crew
 
-Use this skill to coordinate subagents safely. Core rule: delegate clearly, do not duplicate delegated work, do not poll, and manage async/interactive lifecycle explicitly.
+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.
 
-See [REFERENCE.md](REFERENCE.md) for examples and detailed handling patterns.
+## Your Responsibilities
+
+Keep these responsibilities local:
+
+- Decide whether delegation is worth it.
+- Split work into independent, non-overlapping slices.
+- Define scope, stop conditions, and acceptance criteria.
+- Vet returned evidence before relying on it.
+- Resolve conflicting results.
+- Integrate outcomes and own the final user-facing synthesis.
+
+## Context Boundary
+
+A subagent runs isolated from your session but inside the same repository:
+
+- 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`).
+- 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.
+- 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.
+- State the exact output you need (deliverable, format, acceptance criteria) so the subagent works toward it and returns something you can act on.
+
+Write every task so a subagent that knows nothing about this session can complete it and return the output you need.
 
 ## Protocol
 
 - Call `crew_list` before each new spawn decision. Choose from discovered names, descriptions, capabilities, and `interactive` flags; do not assume fixed agents exist.
-- Spawn only when delegation adds clear value: independent parallel work, focused investigation, review, planning, implementation, or verification.
-- Do not spawn for tiny tasks, unclear tasks, or work whose required context cannot be summarized safely.
-- Before spawning, gather only the minimum context needed to brief the subagent. Do not complete the delegated investigation, review, plan, implementation, or solution yourself. After spawning, ownership transfers to the subagent.
-- Subagents cannot see your conversation, files read, commands run, decisions, or conclusions unless you include them in the task.
+- 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.
+- Do not spawn for tiny tasks, unclear tasks, immediate blockers you must resolve before proceeding, or work whose required context cannot be summarized safely.
+- 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.
 - Parallel spawns must be independent and non-overlapping. If multiple subagents may touch the same files or ownership area, serialize them.
-- 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.
 
 ## Spawn Brief
 
-Every `crew_spawn` requires both `brief` and `task`:
+Every `crew_spawn` needs:
 
-- `brief`: concise human-readable task label for session lists, ideally under 80 characters. Write the intent/outcome in a few words; do not include the full task, acceptance criteria, long paths, secrets, or mechanical repo state.
-- `task`: self-contained delegated work body with the context the subagent needs.
+- `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.
+- `task`: self-contained work request with only the context this subagent needs.
 
-Send a self-contained task, but do not fill a template mechanically. Use only sections that add task-specific value, for example:
+Include task-specific details only when useful:
 
 ```md
 Intent / context:
@@ -34,24 +52,57 @@ Relevant inputs / entry points:
 Constraints / decisions:
 Deliverable / expected outcome:
 Verification / checks:
+Stop conditions:
+```
+
+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.
+
+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.
+
+For repeated workflows, summarize the relevant facts or point to durable artifacts the subagent can read; avoid vague references like “the previous fixes.”
+
+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.
+
+### Examples
+
+Good `task` (intent-first and self-contained):
+
+```md
+Intent / context:
+Password reset emails should expire after 30 minutes, but old reset links still work hours later.
+
+Relevant inputs / entry points:
+- Password reset request handler.
+- Token validation path used by the reset form.
+- Config or DB fields storing token expiry.
+
+Constraints / decisions:
+- Keep the existing email template and reset URL format.
+- Do not change login or account creation.
+
+Deliverable:
+Likely root cause and the smallest safe fix direction.
 ```
 
-Omit sections that would only restate the selected subagent’s role, default scope, edit permissions, output format, or obvious next steps.
+Avoid tasks like `Fix this.`, `Investigate the bug we discussed.`, or `Implement the plan.`: they depend on session-only context the subagent cannot see.
 
-Include only information that helps this specific subagent do this specific task: intent, expected outcome, relevant decisions, exact errors/output, unusual constraints, and file paths or entry points that genuinely clarify the task. Use short Markdown sections and bullets when they improve scanability, especially for multi-part intent, constraints, observations, requirements, or acceptance criteria; avoid dense paragraphs.
+## After Spawning
 
-For repeated workflows, make each task independent. Do not assume a new subagent knows earlier loop results, owner-session discussion, or what another subagent saw. If prior findings, fixes, decisions, or verification matter, summarize the concrete facts or point to durable artifacts the subagent can inspect. Avoid vague references like “we fixed the first review findings” unless you also state what those findings/fixes were or define the current review target without relying on that history.
+`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.
 
-Do not restate boilerplate implied by the selected subagent’s role, name, or description. Avoid repeating default scope, output format, edit permissions, or repo guidance. Subagents run in the same cwd as the orchestrator, so do not include mechanical Git state they can inspect themselves, such as full changed-file lists, staged/unstaged/untracked inventories, branch/cwd details, or generic project constraints, unless those details define a non-default scope or prevent ambiguity.
+Once you spawn:
 
-If the user points to a plan, spec, issue, design, or doc as task intent, read it when practical and summarize the relevant intent instead of merely passing the path. Prefer explaining why the work matters and what outcome is expected over restating repository state.
+- 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.
+- Do only work that is independent of and non-overlapping with what you delegated.
+- 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.
 
 ## Result Handling
 
 - Wait for subagent results before using them. Never invent or predict results.
+- Treat subagent results as evidence to inspect, not verdicts to forward.
 - Evaluate each result against the task acceptance criteria.
-- If results conflict, are incomplete, or miss criteria, state that clearly and use a follow-up or new spawn only when needed.
-- After spawning, do not work on the delegated task; wait for results, continue only with unrelated work, or end the turn.
+- If a subagent errors or aborts, report that status and continue only if the remaining results are sufficient.
+- 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.
 
 ## Interactive Subagents
 

package/skills/pi-crew/REFERENCE.md

@@ -1,87 +0,0 @@
-# Pi Crew Reference
-
-## Delegation Checklist
-
-Before `crew_spawn`, provide:
-
-- `brief`: a concise human-readable task label for session lists, ideally under 80 characters. Use a few words for intent/outcome; do not include the full task, acceptance criteria, long paths, secrets, or mechanical repo state.
-- `task`: a self-contained delegated task body, not mechanically templated.
-
-In `task`, include only information that helps this specific subagent do this specific task:
-
-- Intent, expected outcome, and relevant user decisions.
-- User-provided references, plus a concise summary after reading them when practical.
-- File paths, symbols, entry points, commands, errors, or logs only when they genuinely clarify the task.
-- Non-default scope, constraints, assumptions, or verification context only when they matter.
-- Gaps or unresolved questions the subagent should account for.
-
-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.
-
-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.
-
-## Good Brief
-
-```md
-Intent / context:
-Password reset emails should expire after 30 minutes. Users report that old reset links still work several hours later.
-
-Relevant inputs / entry points:
-- The password reset request handler.
-- The token validation path used by the reset form.
-- Any configuration or database fields that store token expiry.
-
-Constraints / decisions:
-- Preserve the existing email template and reset URL format.
-- Do not change login or account creation behavior.
-
-Deliverable:
-Identify the likely root cause and the smallest safe fix direction.
-```
-
-## Bad Briefs
-
-```md
-Fix this.
-```
-
-```md
-Investigate the bug we discussed.
-```
-
-```md
-Implement the plan.
-```
-
-```md
-Goal: Review the current uncommitted changes for actionable bugs.
-Scope: Current repo changes, staged/unstaged/untracked files.
-Non-goals: Do not modify files.
-Expected output: Findings with severity and fix direction.
-```
-
-These depend on hidden conversation state, restate subagent boilerplate, or carry mechanical repository state instead of task-specific intent.
-
-## Parallel Delegation
-
-Use parallel subagents only when tasks are independent:
-
-- Good: one reviewer checks correctness while another checks maintainability.
-- Good: scouts inspect separate modules with non-overlapping files.
-- Bad: two workers edit the same file or feature area simultaneously.
-
-If ownership overlaps, serialize the work.
-
-## Failure and Conflict Handling
-
-- If a subagent errors or aborts, report that status clearly and continue only if remaining results are sufficient.
-- If a result misses the task-specific deliverable, ask a focused follow-up or spawn a new subagent with a corrected brief.
-- 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.
-- If a task becomes obsolete, abort the relevant active subagent.
-
-## Tool Notes
-
-- `crew_list`: discovery before a new spawn decision or requested status snapshot; never completion polling.
-- `crew_spawn`: provide `brief` plus a self-contained `task`; ownership transfers after spawn.
-- `crew_respond`: send a follow-up to a waiting interactive subagent; fire-and-forget.
-- `crew_done`: close a waiting interactive subagent when complete.
-- `crew_abort`: abort active owned subagents only when obsolete, wrong, or cancelled.