@melihmucuk/pi-crew 1.0.17 → 1.0.19

package/agents/code-reviewer.md

@@ -1,26 +1,32 @@
 ---
 name: code-reviewer
-description: Reviews changed code for actionable bugs. Read-only.
+description: Reviews scoped code for actionable bugs. Read-only.
 model: openai-codex/gpt-5.2
 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 changed code contains realistic, actionable bugs. An empty review is a valid successful outcome. Reply in the user's language.
+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.
 
 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.
 
 ## Scope
 
-Review the provided scope. If none is provided, review uncommitted changes. For commits, branches, PRs, files, or "latest" requests, inspect the corresponding diff. If "latest" is requested, review the last 5 commits unless a count is given.
+Review the provided scope. If none is provided, review uncommitted changes.
 
-For large or broad diffs, summarize coverage by area with brief risk notes, then deeply review only the highest-risk changed files: business logic, auth, data mutation, error handling, and public APIs. Avoid exhaustive file inventories.
+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.
 
-Review changed-code issues only. Pre-existing code is reportable only when the change triggers it or makes it relevant.
+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 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.
 
 ## Method
 
-Diffs are not enough. Before reporting a finding, read the full changed 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.
+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.
+
+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.
 
 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.
 
@@ -40,17 +46,15 @@ Report the same finding pattern at most twice, then list other affected location
 
 ## Severity
 
-- Critical: proven realistic security, data loss, or severe breakage.
-- Major: realistic bug likely to affect users, developers, or operations.
-- Minor: real non-blocking bug or high-risk coverage gap.
+- 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.
 
 ## Output
 
 If no findings:
 
 **No issues found.**
-Reviewed: [files]
-Overall confidence: [high/medium]
 
 For each finding:
 
@@ -58,6 +62,7 @@ For each finding:
 File: `path:line`
 Issue: what is wrong
 Evidence: what you verified
+Impact: concrete consequence
 Fix: suggested correction
 
 Be direct, concise, and unpadded.

package/agents/quality-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: quality-reviewer
-description: Reviews changed code for maintainability, duplication, and complexity. Read-only.
+description: Reviews scoped code for maintainability, duplication, and complexity. Read-only.
 model: openai-codex/gpt-5.2
 thinking: high
 tools: read, grep, find, ls, bash
@@ -16,7 +16,7 @@ Do not modify files. Use bash only for read-only inspection. Do not run builds,
 
 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.
 
-If "full" or "codebase" is requested, first produce a structural risk map, then deeply review only the highest-risk areas.
+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.
 
 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.
 
@@ -48,32 +48,23 @@ Default stance: no new abstraction unless it reduces present-day duplication or
 
 ## Severity
 
-- High: structure will materially hinder near-term changes or debugging.
-- Medium: noticeable maintenance friction with concrete evidence.
-- Minor: small structural friction on a realistic future change/debug path.
+- 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.
 
 ## Output
 
 If no findings:
 
 **No issues found.**
-Reviewed: [files]
-Overall health: [brief assessment]
 
 For each finding:
 
 **[SEVERITY] Category: Title**
 File: `path:line`
-Issue: structural problem
-Impact: concrete future change/debug task made harder
+Issue: what is wrong
 Evidence: what you verified
-Fix: specific refactoring approach
-
-End with:
-
-**Quality Review Summary**
-Files reviewed: [count]
-Findings: [count by severity]
-Overall health: [one sentence]
+Impact: concrete consequence
+Fix: suggested correction
 
 Be direct, concise, and unpadded.

package/extension/catalog.ts

@@ -0,0 +1,543 @@
+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";
+
+const SUPPORTED_TOOL_NAMES_LITERAL = [
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls",
+] as const;
+
+export type SupportedToolName = (typeof SUPPORTED_TOOL_NAMES_LITERAL)[number];
+export const SUPPORTED_TOOL_NAMES = Object.freeze([...SUPPORTED_TOOL_NAMES_LITERAL] as SupportedToolName[]);
+
+function isSupportedToolName(name: string): name is SupportedToolName {
+	return SUPPORTED_TOOL_NAMES.includes(name as SupportedToolName);
+}
+
+export interface ParsedModel {
+	provider: string;
+	modelId: string;
+}
+
+interface AgentConfigFields {
+	model?: string;
+	parsedModel?: ParsedModel;
+	thinking?: ThinkingLevel;
+	tools?: SupportedToolName[];
+	skills?: string[];
+	compaction?: boolean;
+	interactive?: boolean;
+}
+
+export interface AgentConfig extends AgentConfigFields {
+	name: string;
+	description: string;
+	systemPrompt: string;
+	filePath: string;
+}
+
+export interface AgentDiscoveryWarning {
+	filePath: string;
+	message: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	warnings: AgentDiscoveryWarning[];
+}
+
+export interface AgentDefinitionFile {
+	filePath: string;
+	content: string | null;
+	warnings?: AgentDiscoveryWarning[];
+}
+
+export interface AgentDefinitionSourceGroup {
+	agentsDir: string;
+	files: AgentDefinitionFile[];
+	warnings?: AgentDiscoveryWarning[];
+}
+
+export interface AgentConfigFile {
+	filePath: string;
+	content: string | null;
+	warnings?: AgentDiscoveryWarning[];
+}
+
+export interface AgentCatalogSource {
+	loadAgentDefinitionGroups(cwd: string): AgentDefinitionSourceGroup[];
+	loadConfigFiles(cwd: string): AgentConfigFile[];
+}
+
+type AgentConfigOverride = AgentConfigFields;
+type ParsedFieldName = "model" | "thinking" | "tools" | "skills" | "compaction" | "interactive";
+type ParsedListFieldName = "tools" | "skills";
+type ParsedBooleanFieldName = "compaction" | "interactive";
+type WarningSubject = "subagent" | "subagent override";
+
+type ParsedFieldWarning =
+	| { code: "invalid-list-format"; fieldName: ParsedListFieldName }
+	| { code: "invalid-type"; fieldName: ParsedFieldName; expected: "string" | "boolean" }
+	| { code: "invalid-model-format"; model: string }
+	| { code: "invalid-thinking-level"; thinking: string }
+	| { code: "unknown-tools"; tools: string[] };
+
+interface ParsedFieldSet extends AgentConfigFields {
+	warnings: ParsedFieldWarning[];
+}
+
+interface ParseFieldOptions {
+	warnOnInvalidType: boolean;
+	setValueOnInvalidType: boolean;
+}
+
+interface ParseResult {
+	agent: AgentConfig | null;
+	warnings: AgentDiscoveryWarning[];
+}
+
+interface ConfigParseResult {
+	overrides: Record<string, AgentConfigOverride>;
+	overrideSources: Record<string, string>;
+	warnings: AgentDiscoveryWarning[];
+}
+
+const VALID_THINKING_LEVELS: readonly string[] = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+];
+
+const ALLOWED_OVERRIDE_FIELDS = new Set([
+	"model",
+	"thinking",
+	"tools",
+	"skills",
+	"compaction",
+	"interactive",
+]);
+
+function createDiscoveryWarning(filePath: string, message: string): AgentDiscoveryWarning {
+	return { filePath, message };
+}
+
+function parseCommaSeparated(value: unknown): string[] | undefined {
+	if (value == null) return undefined;
+	if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+	if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
+	return undefined;
+}
+
+function formatFieldWarning(subject: WarningSubject, name: string, warning: ParsedFieldWarning): string {
+	const prefix = `${subject === "subagent" ? "Subagent" : "Subagent override"} "${name}"`;
+
+	switch (warning.code) {
+		case "invalid-list-format":
+			return `${prefix}: invalid ${warning.fieldName} field, expected a comma-separated string or YAML array`;
+		case "invalid-type":
+			return `${prefix}: field "${warning.fieldName}" must be a ${warning.expected}, ignoring`;
+		case "invalid-model-format":
+			return `${prefix}: invalid model format "${warning.model}" (expected "provider/model-id"), ignoring model field`;
+		case "invalid-thinking-level":
+			return `${prefix}: invalid thinking level "${warning.thinking}", ignoring`;
+		case "unknown-tools":
+			return `${prefix}: unknown tools ${warning.tools.map((toolName) => `"${toolName}"`).join(", ")}, ignoring`;
+	}
+}
+
+function toParseWarnings(
+	filePath: string,
+	subject: WarningSubject,
+	name: string,
+	warnings: ParsedFieldWarning[],
+): AgentDiscoveryWarning[] {
+	return warnings.map((warning) => createDiscoveryWarning(filePath, formatFieldWarning(subject, name, warning)));
+}
+
+function parseListField(value: unknown, fieldName: ParsedListFieldName): { values: string[]; warnings: ParsedFieldWarning[] } {
+	if (value == null) return { values: [], warnings: [] };
+	const parsed = parseCommaSeparated(value);
+	if (parsed !== undefined) return { values: parsed, warnings: [] };
+	return { values: [], warnings: [{ code: "invalid-list-format", fieldName }] };
+}
+
+function parseModel(value: unknown): ParsedModel | null {
+	if (typeof value !== "string" || !value.includes("/")) return null;
+	const slashIndex = value.indexOf("/");
+	const provider = value.slice(0, slashIndex).trim();
+	const modelId = value.slice(slashIndex + 1).trim();
+	return provider && modelId ? { provider, modelId } : null;
+}
+
+function validateThinkingLevel(value: string | undefined): ThinkingLevel | undefined {
+	if (!value) return undefined;
+	return VALID_THINKING_LEVELS.includes(value) ? value as ThinkingLevel : undefined;
+}
+
+function parseModelField(value: unknown, options: ParseFieldOptions): Pick<ParsedFieldSet, "model" | "parsedModel" | "warnings"> {
+	if (typeof value === "string") {
+		const parsedModel = parseModel(value);
+		if (!parsedModel) {
+			return {
+				...(options.setValueOnInvalidType ? { model: value } : {}),
+				warnings: [{ code: "invalid-model-format", model: value }],
+			};
+		}
+		return { model: value, parsedModel, warnings: [] };
+	}
+	if (value !== undefined && options.warnOnInvalidType) {
+		return { warnings: [{ code: "invalid-type", fieldName: "model", expected: "string" }] };
+	}
+	return { warnings: [] };
+}
+
+function parseThinkingField(value: unknown, options: ParseFieldOptions): Pick<ParsedFieldSet, "thinking" | "warnings"> {
+	if (typeof value === "string") {
+		const thinking = validateThinkingLevel(value);
+		return thinking ? { thinking, warnings: [] } : { warnings: [{ code: "invalid-thinking-level", thinking: value }] };
+	}
+	if (value !== undefined && options.warnOnInvalidType) {
+		return { warnings: [{ code: "invalid-type", fieldName: "thinking", expected: "string" }] };
+	}
+	return { warnings: [] };
+}
+
+function parseToolsField(value: unknown, options: ParseFieldOptions): Pick<ParsedFieldSet, "tools" | "warnings"> {
+	const parsedTools = parseListField(value, "tools");
+	const validTools = parsedTools.values.filter(isSupportedToolName);
+	const invalidTools = parsedTools.values.filter((toolName) => !isSupportedToolName(toolName));
+	const warnings: ParsedFieldWarning[] = [...parsedTools.warnings];
+	if (invalidTools.length > 0) warnings.push({ code: "unknown-tools", tools: invalidTools });
+	if (invalidTools.length > 0 && validTools.length === 0 && !options.setValueOnInvalidType) return { warnings };
+	if (parsedTools.warnings.length > 0 && !options.setValueOnInvalidType) return { warnings };
+	return { tools: validTools, warnings };
+}
+
+function parseSkillsField(value: unknown, options: ParseFieldOptions): Pick<ParsedFieldSet, "skills" | "warnings"> {
+	const parsedSkills = parseListField(value, "skills");
+	if (parsedSkills.warnings.length > 0 && !options.setValueOnInvalidType) return { warnings: parsedSkills.warnings };
+	return { skills: parsedSkills.values, warnings: parsedSkills.warnings };
+}
+
+function parseBooleanField(
+	fieldName: ParsedBooleanFieldName,
+	value: unknown,
+	options: ParseFieldOptions,
+): Pick<ParsedFieldSet, ParsedBooleanFieldName | "warnings"> {
+	if (typeof value === "boolean") return { [fieldName]: value, warnings: [] };
+	if (value !== undefined && options.warnOnInvalidType) {
+		return { warnings: [{ code: "invalid-type", fieldName, expected: "boolean" }] };
+	}
+	return { warnings: [] };
+}
+
+function parseSharedFields(record: Record<string, unknown>, options: ParseFieldOptions): ParsedFieldSet {
+	const model = parseModelField(record.model, options);
+	const thinking = parseThinkingField(record.thinking, options);
+	const tools = Object.prototype.hasOwnProperty.call(record, "tools") ? parseToolsField(record.tools, options) : { warnings: [] };
+	const skills = Object.prototype.hasOwnProperty.call(record, "skills") ? parseSkillsField(record.skills, options) : { warnings: [] };
+	const compaction = parseBooleanField("compaction", record.compaction, options);
+	const interactive = parseBooleanField("interactive", record.interactive, options);
+
+	return {
+		...("model" in model ? { model: model.model } : {}),
+		...("parsedModel" in model ? { parsedModel: model.parsedModel } : {}),
+		...(thinking.thinking !== undefined ? { thinking: thinking.thinking } : {}),
+		...(tools.tools !== undefined ? { tools: tools.tools } : {}),
+		...(skills.skills !== undefined ? { skills: skills.skills } : {}),
+		...(compaction.compaction !== undefined ? { compaction: compaction.compaction } : {}),
+		...(interactive.interactive !== undefined ? { interactive: interactive.interactive } : {}),
+		warnings: [
+			...model.warnings,
+			...thinking.warnings,
+			...tools.warnings,
+			...skills.warnings,
+			...compaction.warnings,
+			...interactive.warnings,
+		],
+	};
+}
+
+function parseDefinitionFields(
+	record: Record<string, unknown>,
+	filePath: string,
+	agentName: string,
+): { fields: AgentConfigFields; warnings: AgentDiscoveryWarning[] } {
+	const parsed = parseSharedFields(record, { warnOnInvalidType: false, setValueOnInvalidType: true });
+	const { warnings, ...fields } = parsed;
+	return { fields, warnings: toParseWarnings(filePath, "subagent", agentName, warnings) };
+}
+
+function parseOverrideFields(
+	record: Record<string, unknown>,
+	filePath: string,
+	agentName: string,
+): { fields: AgentConfigFields; warnings: AgentDiscoveryWarning[] } {
+	const warnings: AgentDiscoveryWarning[] = [];
+	for (const fieldName of Object.keys(record)) {
+		if (fieldName === "name" || fieldName === "description") {
+			warnings.push(createDiscoveryWarning(filePath, `Subagent override "${agentName}": field "${fieldName}" is not overridable, ignoring`));
+			continue;
+		}
+		if (!ALLOWED_OVERRIDE_FIELDS.has(fieldName)) {
+			warnings.push(createDiscoveryWarning(filePath, `Subagent override "${agentName}": unknown field "${fieldName}", ignoring`));
+		}
+	}
+
+	const parsed = parseSharedFields(record, { warnOnInvalidType: true, setValueOnInvalidType: false });
+	const { warnings: fieldWarnings, ...fields } = parsed;
+	warnings.push(...toParseWarnings(filePath, "subagent override", agentName, fieldWarnings));
+	return { fields, warnings };
+}
+
+function parseAgentDefinition(content: string, filePath: string): ParseResult {
+	let frontmatter: Record<string, unknown>;
+	let body: string;
+	try {
+		const parsed = parseFrontmatter<Record<string, unknown>>(content);
+		frontmatter = parsed.frontmatter;
+		body = parsed.body;
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return { agent: null, warnings: [createDiscoveryWarning(filePath, `Ignored invalid subagent definition. Frontmatter could not be parsed: ${reason}`)] };
+	}
+
+	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : undefined;
+	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : undefined;
+	if (!name || !description) {
+		return { agent: null, warnings: [createDiscoveryWarning(filePath, 'Ignored invalid subagent definition. Required frontmatter fields "name" and "description" must be non-empty strings.')] };
+	}
+	if (/\s/.test(name)) {
+		return { agent: null, warnings: [createDiscoveryWarning(filePath, `Ignored subagent definition "${name}". Subagent names cannot contain whitespace. Use "-" instead.`)] };
+	}
+
+	const parsedFields = parseDefinitionFields(frontmatter, filePath, name);
+	return {
+		agent: { name, description, ...parsedFields.fields, systemPrompt: body, filePath },
+		warnings: parsedFields.warnings,
+	};
+}
+
+function parseAgentOverride(
+	agentName: string,
+	value: unknown,
+	filePath: string,
+): { override: AgentConfigOverride | null; warnings: AgentDiscoveryWarning[] } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return { override: null, warnings: [createDiscoveryWarning(filePath, `Subagent override "${agentName}" must be a JSON object, ignoring`)] };
+	}
+	const parsedFields = parseOverrideFields(value as Record<string, unknown>, filePath, agentName);
+	return { override: parsedFields.fields, warnings: parsedFields.warnings };
+}
+
+function parseConfigFile(content: string, filePath: string): ConfigParseResult {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return { overrides: {}, overrideSources: {}, warnings: [createDiscoveryWarning(filePath, `Ignored pi-crew config. JSON could not be parsed: ${reason}`)] };
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { overrides: {}, overrideSources: {}, warnings: [createDiscoveryWarning(filePath, "Ignored pi-crew config. Root value must be a JSON object.")] };
+	}
+
+	const root = parsed as Record<string, unknown>;
+	if (root.agents === undefined) return { overrides: {}, overrideSources: {}, warnings: [] };
+	if (!root.agents || typeof root.agents !== "object" || Array.isArray(root.agents)) {
+		return { overrides: {}, overrideSources: {}, warnings: [createDiscoveryWarning(filePath, 'Ignored pi-crew config. Field "agents" must be a JSON object.')] };
+	}
+
+	const overrides: Record<string, AgentConfigOverride> = {};
+	const overrideSources: Record<string, string> = {};
+	const warnings: AgentDiscoveryWarning[] = [];
+	for (const [agentName, value] of Object.entries(root.agents)) {
+		if (!agentName.trim()) {
+			warnings.push(createDiscoveryWarning(filePath, "Ignored pi-crew config entry with empty subagent name."));
+			continue;
+		}
+		const parsedOverride = parseAgentOverride(agentName, value, filePath);
+		warnings.push(...parsedOverride.warnings);
+		if (parsedOverride.override) {
+			overrides[agentName] = parsedOverride.override;
+			overrideSources[agentName] = filePath;
+		}
+	}
+	return { overrides, overrideSources, warnings };
+}
+
+function mergeConfigOverrides(
+	base: Record<string, AgentConfigOverride>,
+	override: Record<string, AgentConfigOverride>,
+): Record<string, AgentConfigOverride> {
+	const merged: Record<string, AgentConfigOverride> = { ...base };
+	for (const [agentName, agentOverride] of Object.entries(override)) {
+		merged[agentName] = { ...(merged[agentName] ?? {}), ...agentOverride };
+	}
+	return merged;
+}
+
+function applyAgentOverride(agent: AgentConfig, override: AgentConfigOverride): AgentConfig {
+	return {
+		...agent,
+		...(override.model !== undefined ? { model: override.model, parsedModel: override.parsedModel } : {}),
+		...(override.thinking !== undefined ? { thinking: override.thinking } : {}),
+		...(override.tools !== undefined ? { tools: override.tools } : {}),
+		...(override.skills !== undefined ? { skills: override.skills } : {}),
+		...(override.compaction !== undefined ? { compaction: override.compaction } : {}),
+		...(override.interactive !== undefined ? { interactive: override.interactive } : {}),
+	};
+}
+
+function loadAgentDefinitionFromFile(file: AgentDefinitionFile): ParseResult {
+	if (!file.content) return { agent: null, warnings: file.warnings ?? [] };
+	const parsed = parseAgentDefinition(file.content, file.filePath);
+	return { agent: parsed.agent, warnings: [...(file.warnings ?? []), ...parsed.warnings] };
+}
+
+function mergeConfigFiles(configFiles: AgentConfigFile[]): ConfigParseResult {
+	let overrides: Record<string, AgentConfigOverride> = {};
+	let overrideSources: Record<string, string> = {};
+	const warnings: AgentDiscoveryWarning[] = [];
+
+	for (const configFile of configFiles) {
+		warnings.push(...(configFile.warnings ?? []));
+		if (!configFile.content) continue;
+		const parsed = parseConfigFile(configFile.content, configFile.filePath);
+		overrides = mergeConfigOverrides(overrides, parsed.overrides);
+		overrideSources = { ...overrideSources, ...parsed.overrideSources };
+		warnings.push(...parsed.warnings);
+	}
+
+	return { overrides, overrideSources, warnings };
+}
+
+export class AgentCatalog {
+	constructor(private readonly source: AgentCatalogSource) {}
+
+	discover(cwd: string = process.cwd()): AgentDiscoveryResult {
+		const agents: AgentConfig[] = [];
+		const warnings: AgentDiscoveryWarning[] = [];
+		const seenNames = new Map<string, string>();
+
+		for (const group of this.source.loadAgentDefinitionGroups(cwd)) {
+			this.loadAgentsFromGroup(group, seenNames, agents, warnings);
+		}
+
+		const configOverrides = mergeConfigFiles(this.source.loadConfigFiles(cwd));
+		warnings.push(...configOverrides.warnings);
+
+		const finalAgents = agents.map((agent) => {
+			const override = configOverrides.overrides[agent.name];
+			return override ? applyAgentOverride(agent, override) : agent;
+		});
+
+		for (const agentName of Object.keys(configOverrides.overrides)) {
+			if (!seenNames.has(agentName)) {
+				warnings.push(createDiscoveryWarning(
+					configOverrides.overrideSources[agentName] ?? "pi-crew.json",
+					`Subagent override "${agentName}" does not match any discovered subagent, ignoring`,
+				));
+			}
+		}
+
+		return { agents: finalAgents, warnings };
+	}
+
+	private loadAgentsFromGroup(
+		group: AgentDefinitionSourceGroup,
+		seenNames: Map<string, string>,
+		agents: AgentConfig[],
+		warnings: AgentDiscoveryWarning[],
+	): void {
+		warnings.push(...(group.warnings ?? []));
+		const groupNames = new Set<string>();
+
+		for (const file of group.files) {
+			const loaded = loadAgentDefinitionFromFile(file);
+			warnings.push(...loaded.warnings);
+			if (!loaded.agent) continue;
+
+			const { name } = loaded.agent;
+			if (groupNames.has(name)) {
+				warnings.push(createDiscoveryWarning(file.filePath, `Duplicate subagent name "${name}" in ${group.agentsDir}, skipping`));
+				continue;
+			}
+			groupNames.add(name);
+			if (seenNames.has(name)) continue;
+			seenNames.set(name, file.filePath);
+			agents.push(loaded.agent);
+		}
+	}
+}
+
+function loadAgentFile(filePath: string): AgentDefinitionFile {
+	try {
+		return { filePath, content: fs.readFileSync(filePath, "utf-8") };
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			filePath,
+			content: null,
+			warnings: [createDiscoveryWarning(filePath, `Ignored subagent definition. File could not be read: ${reason}`)],
+		};
+	}
+}
+
+function loadAgentDefinitionGroup(agentsDir: string): AgentDefinitionSourceGroup | null {
+	if (!fs.existsSync(agentsDir)) return null;
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return { agentsDir, files: [], warnings: [createDiscoveryWarning(agentsDir, `Subagent directory could not be read: ${reason}`)] };
+	}
+	return {
+		agentsDir,
+		files: entries
+			.filter((entry) => entry.name.endsWith(".md"))
+			.filter((entry) => entry.isFile() || entry.isSymbolicLink())
+			.map((entry) => loadAgentFile(path.join(agentsDir, entry.name))),
+	};
+}
+
+function loadConfigFile(filePath: string): AgentConfigFile | null {
+	if (!fs.existsSync(filePath)) return null;
+	try {
+		return { filePath, content: fs.readFileSync(filePath, "utf-8") };
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return { filePath, content: null, warnings: [createDiscoveryWarning(filePath, `Ignored pi-crew config. File could not be read: ${reason}`)] };
+	}
+}
+
+const bundledAgentsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
+
+class FilesystemAgentCatalogSource implements AgentCatalogSource {
+	loadAgentDefinitionGroups(cwd: string): AgentDefinitionSourceGroup[] {
+		return [path.join(cwd, ".pi", "agents"), path.join(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")]
+			.map(loadConfigFile)
+			.filter((file): file is AgentConfigFile => file !== null);
+	}
+}
+
+export function discoverAgents(cwd: string = process.cwd()): AgentDiscoveryResult {
+	return new AgentCatalog(new FilesystemAgentCatalogSource()).discover(cwd);
+}