pi-crew 0.1.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "pi-crew",
+  "version": "0.1.0",
+  "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
+  "author": "baphuongna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baphuongna/pi-crew.git"
+  },
+  "homepage": "https://github.com/baphuongna/pi-crew#readme",
+  "bugs": {
+    "url": "https://github.com/baphuongna/pi-crew/issues"
+  },
+  "type": "module",
+  "bin": {
+    "pi-crew": "install.mjs"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "teams",
+    "agents",
+    "multi-agent",
+    "orchestration"
+  ],
+  "files": [
+    "*.ts",
+    "*.mjs",
+    "src/**/*.ts",
+    "agents/",
+    "teams/",
+    "workflows/",
+    "skills/**/*",
+    "README.md",
+    "AGENTS.md",
+    "docs/",
+    "tsconfig.json",
+    "schema.json",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "check": "npm run ci",
+    "ci": "npm run typecheck && npm test && npm pack --dry-run",
+    "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
+    "test": "npm run test:unit",
+    "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
+    "smoke:pi": "pi install ."
+  },
+  "exports": {
+    "./schema.json": "./schema.json"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-agent-core": "^0.65.0",
+    "@mariozechner/pi-ai": "^0.65.0",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
+    "typescript": "^5.9.3"
+  }
+}

package/schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.invalid/pi-crew.schema.json",
+  "title": "pi-crew config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "asyncByDefault": {
+      "type": "boolean",
+      "description": "Run team workflows in detached async mode by default when the tool call omits async."
+    },
+    "executeWorkers": {
+      "type": "boolean",
+      "description": "Allow real child Pi workers without setting PI_TEAMS_EXECUTE_WORKERS=1."
+    },
+    "notifierIntervalMs": {
+      "type": "number",
+      "minimum": 1000,
+      "description": "Polling interval for async completion notifications."
+    },
+    "requireCleanWorktreeLeader": {
+      "type": "boolean",
+      "description": "Require a clean leader git repository before provisioning worktrees."
+    },
+    "autonomous": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Autonomous team routing policy injected into the agent system prompt.",
+      "properties": {
+        "profile": { "type": "string", "enum": ["manual", "suggested", "assisted", "aggressive"] },
+        "enabled": { "type": "boolean" },
+        "injectPolicy": { "type": "boolean" },
+        "preferAsyncForLongTasks": { "type": "boolean" },
+        "allowWorktreeSuggestion": { "type": "boolean" },
+        "magicKeywords": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/src/agents/agent-config.ts

@@ -0,0 +1,27 @@
+export type ResourceSource = "builtin" | "user" | "project";
+
+export interface RoutingMetadata {
+	triggers?: string[];
+	useWhen?: string[];
+	avoidWhen?: string[];
+	cost?: "free" | "cheap" | "expensive";
+	category?: string;
+}
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	source: ResourceSource;
+	filePath: string;
+	systemPrompt: string;
+	model?: string;
+	fallbackModels?: string[];
+	thinking?: string;
+	tools?: string[];
+	extensions?: string[];
+	skills?: string[];
+	systemPromptMode?: "replace" | "append";
+	inheritProjectContext?: boolean;
+	inheritSkills?: boolean;
+	routing?: RoutingMetadata;
+}

package/src/agents/agent-serializer.ts

@@ -0,0 +1,34 @@
+import type { AgentConfig } from "./agent-config.ts";
+
+function line(key: string, value: string | boolean | string[] | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+	return `${key}: ${String(value)}`;
+}
+
+export function serializeAgent(agent: AgentConfig): string {
+	const lines = [
+		"---",
+		`name: ${agent.name}`,
+		`description: ${agent.description}`,
+		line("model", agent.model),
+		line("fallbackModels", agent.fallbackModels),
+		line("thinking", agent.thinking),
+		line("tools", agent.tools),
+		agent.extensions !== undefined ? line("extensions", agent.extensions) ?? "extensions:" : undefined,
+		line("skills", agent.skills),
+		line("systemPromptMode", agent.systemPromptMode),
+		line("inheritProjectContext", agent.inheritProjectContext),
+		line("inheritSkills", agent.inheritSkills),
+		line("triggers", agent.routing?.triggers),
+		line("useWhen", agent.routing?.useWhen),
+		line("avoidWhen", agent.routing?.avoidWhen),
+		line("cost", agent.routing?.cost),
+		line("category", agent.routing?.category),
+		"---",
+		"",
+		agent.systemPrompt.trim(),
+		"",
+	].filter((entry): entry is string => entry !== undefined);
+	return lines.join("\n");
+}

package/src/agents/discover-agents.ts

@@ -0,0 +1,73 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentConfig, ResourceSource } from "./agent-config.ts";
+import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
+import { packageRoot, projectPiRoot, userPiRoot } from "../utils/paths.ts";
+
+export interface AgentDiscoveryResult {
+	builtin: AgentConfig[];
+	user: AgentConfig[];
+	project: AgentConfig[];
+}
+
+function parseCost(value: string | undefined): "free" | "cheap" | "expensive" | undefined {
+	return value === "free" || value === "cheap" || value === "expensive" ? value : undefined;
+}
+
+function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig | undefined {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		const { frontmatter, body } = parseFrontmatter(content);
+		const name = frontmatter.name?.trim() || path.basename(filePath, path.extname(filePath));
+		const description = frontmatter.description?.trim() || "No description provided.";
+		const triggers = parseCsv(frontmatter.triggers ?? frontmatter.trigger);
+		const useWhen = parseCsv(frontmatter.useWhen);
+		const avoidWhen = parseCsv(frontmatter.avoidWhen);
+		const cost = parseCost(frontmatter.cost);
+		const category = frontmatter.category?.trim() || undefined;
+		return {
+			name,
+			description,
+			source,
+			filePath,
+			systemPrompt: body.trim(),
+			model: frontmatter.model || undefined,
+			fallbackModels: parseCsv(frontmatter.fallbackModels),
+			thinking: frontmatter.thinking || undefined,
+			tools: parseCsv(frontmatter.tools),
+			extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
+			skills: parseCsv(frontmatter.skills ?? frontmatter.skill),
+			systemPromptMode: frontmatter.systemPromptMode === "append" ? "append" : "replace",
+			inheritProjectContext: frontmatter.inheritProjectContext === "true",
+			inheritSkills: frontmatter.inheritSkills === "true",
+			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((entry) => entry.endsWith(".md") && !entry.endsWith(".team.md") && !entry.endsWith(".workflow.md"))
+		.map((entry) => parseAgentFile(path.join(dir, entry), source))
+		.filter((agent): agent is AgentConfig => agent !== undefined)
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function discoverAgents(cwd: string): AgentDiscoveryResult {
+	return {
+		builtin: readAgentDir(path.join(packageRoot(), "agents"), "builtin"),
+		user: readAgentDir(path.join(userPiRoot(), "agents"), "user"),
+		project: readAgentDir(path.join(projectPiRoot(cwd), "agents"), "project"),
+	};
+}
+
+export function allAgents(discovery: AgentDiscoveryResult): AgentConfig[] {
+	const byName = new Map<string, AgentConfig>();
+	for (const agent of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
+		byName.set(agent.name, agent);
+	}
+	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/config/config.ts

@@ -0,0 +1,193 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type PiTeamsAutonomyProfile = "manual" | "suggested" | "assisted" | "aggressive";
+
+export interface PiTeamsAutonomousConfig {
+	profile?: PiTeamsAutonomyProfile;
+	enabled?: boolean;
+	injectPolicy?: boolean;
+	preferAsyncForLongTasks?: boolean;
+	allowWorktreeSuggestion?: boolean;
+	magicKeywords?: Record<string, string[]>;
+}
+
+export interface PiTeamsConfig {
+	asyncByDefault?: boolean;
+	executeWorkers?: boolean;
+	notifierIntervalMs?: number;
+	requireCleanWorktreeLeader?: boolean;
+	autonomous?: PiTeamsAutonomousConfig;
+}
+
+export interface LoadedPiTeamsConfig {
+	config: PiTeamsConfig;
+	path: string;
+	paths: string[];
+	error?: string;
+}
+
+export interface SavedPiTeamsConfig {
+	config: PiTeamsConfig;
+	path: string;
+}
+
+export interface UpdateConfigOptions {
+	cwd?: string;
+	scope?: "user" | "project";
+	unsetPaths?: string[];
+}
+
+export function configPath(): string {
+	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
+	return path.join(home, ".pi", "agent", "extensions", "pi-crew", "config.json");
+}
+
+export function projectConfigPath(cwd: string): string {
+	return path.join(cwd, ".pi", "teams", "config.json");
+}
+
+function withoutUndefined<T extends Record<string, unknown>>(value: T): Partial<T> {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as Partial<T>;
+}
+
+function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfig {
+	const merged: PiTeamsConfig = { ...base, ...withoutUndefined(override as Record<string, unknown>) };
+	if (base.autonomous || override.autonomous) {
+		merged.autonomous = {
+			...(base.autonomous ?? {}),
+			...withoutUndefined((override.autonomous ?? {}) as Record<string, unknown>),
+		};
+	}
+	return merged;
+}
+
+function parseAutonomyProfile(value: unknown): PiTeamsAutonomyProfile | undefined {
+	return value === "manual" || value === "suggested" || value === "assisted" || value === "aggressive" ? value : undefined;
+}
+
+export function effectiveAutonomousConfig(config: PiTeamsAutonomousConfig | undefined): Required<Pick<PiTeamsAutonomousConfig, "profile" | "enabled" | "injectPolicy" | "preferAsyncForLongTasks" | "allowWorktreeSuggestion">> & Pick<PiTeamsAutonomousConfig, "magicKeywords"> {
+	const profile = config?.enabled === false ? "manual" : (config?.profile ?? "suggested");
+	const profileDefaults: Record<PiTeamsAutonomyProfile, { enabled: boolean; injectPolicy: boolean; preferAsyncForLongTasks: boolean; allowWorktreeSuggestion: boolean }> = {
+		manual: { enabled: false, injectPolicy: false, preferAsyncForLongTasks: false, allowWorktreeSuggestion: false },
+		suggested: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: false, allowWorktreeSuggestion: true },
+		assisted: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: true, allowWorktreeSuggestion: true },
+		aggressive: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: true, allowWorktreeSuggestion: true },
+	};
+	const defaults = profileDefaults[profile];
+	return {
+		profile,
+		enabled: config?.enabled ?? defaults.enabled,
+		injectPolicy: config?.injectPolicy ?? defaults.injectPolicy,
+		preferAsyncForLongTasks: config?.preferAsyncForLongTasks ?? defaults.preferAsyncForLongTasks,
+		allowWorktreeSuggestion: config?.allowWorktreeSuggestion ?? defaults.allowWorktreeSuggestion,
+		magicKeywords: config?.magicKeywords,
+	};
+}
+
+function parseStringArrayRecord(value: unknown): Record<string, string[]> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const result: Record<string, string[]> = {};
+	for (const [key, rawValues] of Object.entries(value)) {
+		if (!Array.isArray(rawValues)) continue;
+		const values = rawValues.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim());
+		if (values.length > 0) result[key] = values;
+	}
+	return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function parseAutonomousConfig(value: unknown): PiTeamsAutonomousConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	return {
+		profile: parseAutonomyProfile(obj.profile),
+		enabled: typeof obj.enabled === "boolean" ? obj.enabled : undefined,
+		injectPolicy: typeof obj.injectPolicy === "boolean" ? obj.injectPolicy : undefined,
+		preferAsyncForLongTasks: typeof obj.preferAsyncForLongTasks === "boolean" ? obj.preferAsyncForLongTasks : undefined,
+		allowWorktreeSuggestion: typeof obj.allowWorktreeSuggestion === "boolean" ? obj.allowWorktreeSuggestion : undefined,
+		magicKeywords: parseStringArrayRecord(obj.magicKeywords),
+	};
+}
+
+function parseConfig(raw: unknown): PiTeamsConfig {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const obj = raw as Record<string, unknown>;
+	return {
+		asyncByDefault: typeof obj.asyncByDefault === "boolean" ? obj.asyncByDefault : undefined,
+		executeWorkers: typeof obj.executeWorkers === "boolean" ? obj.executeWorkers : undefined,
+		notifierIntervalMs: typeof obj.notifierIntervalMs === "number" && Number.isFinite(obj.notifierIntervalMs) && obj.notifierIntervalMs >= 1000 ? obj.notifierIntervalMs : undefined,
+		requireCleanWorktreeLeader: typeof obj.requireCleanWorktreeLeader === "boolean" ? obj.requireCleanWorktreeLeader : undefined,
+		autonomous: parseAutonomousConfig(obj.autonomous),
+	};
+}
+
+function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
+	const parts = dottedPath.split(".").filter(Boolean);
+	if (parts.length === 0) return;
+	let target: Record<string, unknown> = record;
+	for (const part of parts.slice(0, -1)) {
+		const current = target[part];
+		if (!current || typeof current !== "object" || Array.isArray(current)) return;
+		target = current as Record<string, unknown>;
+	}
+	delete target[parts[parts.length - 1]!];
+}
+
+function readConfigRecord(filePath: string): Record<string, unknown> {
+	if (!fs.existsSync(filePath)) return {};
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw as Record<string, unknown>;
+}
+
+export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
+	const filePath = configPath();
+	const paths = cwd ? [filePath, projectConfigPath(cwd)] : [filePath];
+	try {
+		let config = parseConfig(readConfigRecord(filePath));
+		if (cwd) config = mergeConfig(config, parseConfig(readConfigRecord(projectConfigPath(cwd))));
+		return { path: filePath, paths, config };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { path: filePath, paths, config: {}, error: message };
+	}
+}
+
+export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions = {}): SavedPiTeamsConfig {
+	const filePath = options.scope === "project" && options.cwd ? projectConfigPath(options.cwd) : configPath();
+	let current: Record<string, unknown>;
+	try {
+		current = readConfigRecord(filePath);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not update pi-crew config: ${message}`);
+	}
+	let merged = mergeConfig(parseConfig(current), patch);
+	if (options.unsetPaths?.length) {
+		const raw = JSON.parse(JSON.stringify(merged)) as Record<string, unknown>;
+		for (const unset of options.unsetPaths) unsetPath(raw, unset);
+		merged = parseConfig(raw);
+	}
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+	return { path: filePath, config: merged };
+}
+
+export function updateAutonomousConfig(patch: PiTeamsAutonomousConfig): SavedPiTeamsConfig {
+	const filePath = configPath();
+	let current: Record<string, unknown>;
+	try {
+		current = readConfigRecord(filePath);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not update pi-crew config: ${message}`);
+	}
+	const currentAutonomous = current.autonomous && typeof current.autonomous === "object" && !Array.isArray(current.autonomous)
+		? current.autonomous as Record<string, unknown>
+		: {};
+	current.autonomous = { ...currentAutonomous, ...patch };
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, `${JSON.stringify(current, null, 2)}\n`, "utf-8");
+	return { path: filePath, config: parseConfig(current) };
+}

package/src/extension/async-notifier.ts

@@ -0,0 +1,36 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { listRuns } from "./run-index.ts";
+
+export interface AsyncNotifierState {
+	seenFinishedRunIds: Set<string>;
+	interval?: ReturnType<typeof setInterval>;
+}
+
+function isFinished(status: string): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled" || status === "blocked";
+}
+
+export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifierState, intervalMs = 5000): void {
+	if (state.interval) clearInterval(state.interval);
+	for (const run of listRuns(ctx.cwd)) {
+		if (isFinished(run.status)) state.seenFinishedRunIds.add(run.runId);
+	}
+	state.interval = setInterval(() => {
+		try {
+			for (const run of listRuns(ctx.cwd).slice(0, 20)) {
+				if (!isFinished(run.status) || state.seenFinishedRunIds.has(run.runId)) continue;
+				state.seenFinishedRunIds.add(run.runId);
+				const level = run.status === "completed" ? "info" : run.status === "cancelled" ? "warning" : "error";
+				ctx.ui.notify(`pi-crew run ${run.status}: ${run.runId} (${run.team}/${run.workflow ?? "none"})`, level);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(`[pi-crew] async notifier error: ${message}`);
+		}
+	}, intervalMs);
+}
+
+export function stopAsyncRunNotifier(state: AsyncNotifierState): void {
+	if (state.interval) clearInterval(state.interval);
+	state.interval = undefined;
+}

package/src/extension/autonomous-policy.ts

@@ -0,0 +1,122 @@
+import type { BeforeAgentStartEvent, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { effectiveAutonomousConfig, loadConfig, type PiTeamsAutonomousConfig } from "../config/config.ts";
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+
+const DEFAULT_MAGIC_KEYWORDS: Record<string, string[]> = {
+	implementation: ["autoteam", "team:", "implementation-team"],
+	review: ["review-team", "security review", "code review"],
+	fastFix: ["fast-fix", "quick fix"],
+	research: ["research-team", "deep research"],
+};
+
+function mergeMagicKeywords(configured: Record<string, string[]> | undefined): Record<string, string[]> {
+	return { ...DEFAULT_MAGIC_KEYWORDS, ...(configured ?? {}) };
+}
+
+export function detectTeamIntent(prompt: string, config: PiTeamsAutonomousConfig = {}): string[] {
+	const lower = prompt.toLowerCase();
+	const matches: string[] = [];
+	for (const [intent, keywords] of Object.entries(mergeMagicKeywords(config.magicKeywords))) {
+		if (keywords.some((keyword) => lower.includes(keyword.toLowerCase()))) matches.push(intent);
+	}
+	return matches;
+}
+
+export function buildAutonomousPolicy(prompt: string, config: PiTeamsAutonomousConfig = {}): string {
+	const effective = effectiveAutonomousConfig(config);
+	const intents = detectTeamIntent(prompt, config);
+	const asyncGuidance = effective.preferAsyncForLongTasks
+		? "For long-running team runs, prefer async: true unless the user needs immediate foreground progress."
+		: "Use async: true only when the task is clearly long-running or the user asks for background execution.";
+	const worktreeGuidance = effective.allowWorktreeSuggestion === false
+		? "Do not suggest worktree mode unless the user explicitly asks for it."
+		: "Consider workspaceMode: 'worktree' for parallel or risky code-changing work in clean git repositories.";
+	return [
+		"# pi-crew Autonomous Delegation Policy",
+		"",
+		`Autonomy profile: ${effective.profile}.`,
+		"You have access to the `team` tool for coordinated multi-agent work. Use it proactively when the task benefits from specialized roles, planning, review, verification, durable artifacts, async execution, or worktree isolation.",
+		"",
+		"Use `team` automatically when:",
+		"- The task spans multiple files, subsystems, or unclear code areas.",
+		"- The task requires planning before implementation.",
+		"- The task asks for implementation plus tests, review, verification, migration, architecture, security review, or debugging.",
+		"- The task would benefit from explorer/planner/executor/reviewer/verifier roles.",
+		"",
+		"Do not use `team` when:",
+		"- The user asks a simple factual question or tiny single-file edit.",
+		"- The user explicitly asks you to work directly without delegation.",
+		"- The action is destructive (`delete`, `forget`, `prune`, forced cleanup) and the user has not explicitly confirmed it.",
+		"",
+		"Recommended mappings:",
+		"- Complex feature/refactor/migration -> action='run', team='implementation'.",
+		"- Small bug fix -> action='run', team='fast-fix'.",
+		"- Code/security review -> action='run', team='review'.",
+		"- Research or documentation synthesis -> action='run', team='research'.",
+		"- Unsure which team/workflow to use -> call the `team` tool with action='recommend' and the user's goal, then follow the suggested plan/run call if appropriate.",
+		"- After delegating exploration/research/review, do not duplicate the same search manually. Continue only with non-overlapping work.",
+		"- Before claiming delegated work is complete, inspect the run with action='status' or action='summary'.",
+		"- Unsure or risky work -> action='plan' first, then run the selected team.",
+		"",
+		asyncGuidance,
+		worktreeGuidance,
+		intents.length > 0 ? `Detected pi-crew routing keywords/intents in the user prompt: ${intents.join(", ")}. Consider the matching team workflow if appropriate.` : "No explicit pi-crew magic keyword was detected; decide based on task complexity and risk.",
+	].join("\n");
+}
+
+function sourcePriority(source: string): number {
+	if (source === "project") return 0;
+	if (source === "user") return 1;
+	return 2;
+}
+
+function capLines(lines: string[], maxChars: number): string[] {
+	const kept: string[] = [];
+	let used = 0;
+	for (const line of lines) {
+		const next = used + line.length + 1;
+		if (next > maxChars) {
+			kept.push("- ...resource guidance truncated to stay within prompt budget");
+			break;
+		}
+		kept.push(line);
+		used = next;
+	}
+	return kept;
+}
+
+export function buildResourceRoutingGuidance(cwd: string, maxChars = 5000): string {
+	const teams = allTeams(discoverTeams(cwd)).sort((a, b) => sourcePriority(a.source) - sourcePriority(b.source)).slice(0, 12);
+	const workflows = allWorkflows(discoverWorkflows(cwd)).sort((a, b) => sourcePriority(a.source) - sourcePriority(b.source)).slice(0, 12);
+	const agents = allAgents(discoverAgents(cwd)).sort((a, b) => sourcePriority(a.source) - sourcePriority(b.source)).slice(0, 16);
+	const lines = [
+		"# pi-crew Available Resources",
+		"Use project-scoped resources over user/builtin resources when names overlap.",
+		"Teams:",
+		...(teams.length ? teams.map((team) => `- ${team.name} (${team.source}): ${team.description}; defaultWorkflow=${team.defaultWorkflow ?? "default"}; roles=${team.roles.map((role) => `${role.name}->${role.agent}`).join(", ") || "none"}${team.routing?.triggers?.length ? `; triggers=${team.routing.triggers.join(",")}` : ""}${team.routing?.useWhen?.length ? `; useWhen=${team.routing.useWhen.join(";")}` : ""}`) : ["- (none)"]),
+		"Workflows:",
+		...(workflows.length ? workflows.map((workflow) => `- ${workflow.name} (${workflow.source}): ${workflow.description}; steps=${workflow.steps.map((step) => `${step.id}:${step.role}`).join(", ") || "none"}`) : ["- (none)"]),
+		"Agents:",
+		...(agents.length ? agents.map((agent) => `- ${agent.name} (${agent.source}): ${agent.description}${agent.routing?.triggers?.length ? `; triggers=${agent.routing.triggers.join(",")}` : ""}${agent.routing?.useWhen?.length ? `; useWhen=${agent.routing.useWhen.join(";")}` : ""}${agent.routing?.avoidWhen?.length ? `; avoidWhen=${agent.routing.avoidWhen.join(";")}` : ""}${agent.routing?.cost ? `; cost=${agent.routing.cost}` : ""}${agent.routing?.category ? `; category=${agent.routing.category}` : ""}`) : ["- (none)"]),
+	];
+	return capLines(lines, maxChars).join("\n");
+}
+
+export function appendAutonomousPolicy(systemPrompt: string, userPrompt: string, config: PiTeamsAutonomousConfig = {}, cwd?: string): string {
+	const resourceGuidance = cwd ? `\n\n${buildResourceRoutingGuidance(cwd)}` : "";
+	return `${systemPrompt}\n\n${buildAutonomousPolicy(userPrompt, config)}${resourceGuidance}`;
+}
+
+export function registerAutonomousPolicy(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+		const options = (event as BeforeAgentStartEvent & { systemPromptOptions?: { cwd?: unknown } }).systemPromptOptions ?? {};
+		const cwd = typeof options.cwd === "string" ? options.cwd : undefined;
+		const loaded = loadConfig(cwd);
+		const autonomous = effectiveAutonomousConfig(loaded.config.autonomous);
+		if (!autonomous.enabled) return undefined;
+		if (!autonomous.injectPolicy) return undefined;
+		return { systemPrompt: appendAutonomousPolicy(event.systemPrompt, event.prompt, autonomous, cwd) };
+	});
+}

package/src/extension/help.ts

@@ -0,0 +1,43 @@
+export function piTeamsHelp(): string {
+	return [
+		"pi-crew commands:",
+		"",
+		"Core:",
+		"- Agent can use the `team` tool autonomously; slash commands are manual controls.",
+		"- Tool action `recommend` suggests the best team/workflow for a goal.",
+		"- /teams — list teams, workflows, agents, recent runs",
+		"- /team-run [--team=name] [--workflow=name] [--async] [--worktree] <goal>",
+		"- /team-status <runId>",
+		"- /team-summary <runId>",
+		"- /team-resume <runId>",
+		"- /team-cancel <runId>",
+		"",
+		"Inspection:",
+		"- /team-events <runId>",
+		"- /team-artifacts <runId>",
+		"- /team-worktrees <runId>",
+		"- /team-api <runId> <operation> [taskId=<taskId>] [body=<message>]",
+		"- /team-dashboard",
+		"- /team-manager",
+		"",
+		"Maintenance:",
+		"- /team-cleanup <runId> [--force]",
+		"- /team-forget <runId> --confirm [--force]",
+		"- /team-prune --keep=20 --confirm",
+		"",
+		"Portability:",
+		"- /team-export <runId>",
+		"- /team-import <path-to-run-export.json> [--user]",
+		"- /team-imports",
+		"",
+		"Diagnostics:",
+		"- /team-doctor",
+		"- /team-init [--copy-builtins] [--overwrite]",
+		"- /team-config [key=value] [--unset=key.path] [--project]",
+		"- /team-autonomy [status|on|off|manual|suggested|assisted|aggressive] [--prefer-async] [--no-worktree-suggest]",
+		"- /team-validate",
+		"- /team-help",
+		"",
+		"Real child workers are disabled by default. Enable with PI_TEAMS_EXECUTE_WORKERS=1 or config executeWorkers=true.",
+	].join("\n");
+}