@melihmucuk/pi-crew 1.0.16 → 1.0.17

package/README.md

@@ -86,7 +86,7 @@ Note: This prompt requires the `scout` and `planner` subagent definitions. These
 #### `/pi-crew-review`
 
 Expands a bundled prompt template that orchestrates parallel code and quality reviews.
-Use it to review recent commits, staged changes, unstaged changes, and untracked files with `code-reviewer` and `quality-reviewer`, then merge both results into one report.
+Use it to review provided or default changed-code scope with `code-reviewer` and `quality-reviewer`, using compact task-specific briefs focused on intent, expected behavior, and relevant references, then merge both results into one report.
 
 Note: This prompt requires the `code-reviewer` and `quality-reviewer` subagent definitions. These are included as bundled subagents and work out of the box.
 
@@ -94,7 +94,7 @@ Note: This prompt requires the `code-reviewer` and `quality-reviewer` subagent d
 
 #### `pi-crew`
 
-A bundled orchestration skill that provides best practices for delegating work to subagents, handling asynchronous results, and managing interactive subagent lifecycle. It loads automatically when you coordinate work with pi-crew tools.
+A bundled orchestration skill that provides best practices for delegating work to subagents, handling asynchronous results, and managing interactive subagent lifecycle. It also guides compact, task-specific subagent briefs that avoid repeating role boilerplate or mechanical repo/Git state. It loads automatically when you coordinate work with pi-crew tools.
 
 ## Bundled Subagents
 
@@ -102,12 +102,12 @@ pi-crew ships with six subagent definitions that cover common workflows:
 
 | Subagent             | Purpose                                                                                                                  | Tools                      | Model                       |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- | --------------------------- |
-| **scout**            | Investigates codebase and returns structured findings. Read-only. Use before planning or implementing to gather context. | read, grep, find, ls, bash | anthropic/claude-haiku-4-5  |
-| **planner**          | Analyzes requirements and produces a step-by-step implementation plan. Read-only. Does not write code. Interactive.      | read, grep, find, ls, bash | openai-codex/gpt-5.4        |
-| **oracle**           | Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only. Does not implement. Interactive. | read, grep, find, ls, bash | openai-codex/gpt-5.4        |
-| **code-reviewer**    | Reviews code changes for bugs, security issues, and correctness. Read-only. Does not fix issues.                         | read, grep, find, ls, bash | openai-codex/gpt-5.4        |
-| **quality-reviewer** | Reviews code structure for maintainability, duplication, and complexity. Read-only. Does not look for bugs.              | read, grep, find, ls, bash | openai-codex/gpt-5.4        |
-| **worker**           | Implements code changes, fixes, and refactors autonomously. Has full read-write access to the codebase.                  | all                        | anthropic/claude-sonnet-4-6 |
+| **scout**            | Investigates codebase and returns structured findings. Read-only. Use before planning or implementing to gather context. | read, grep, find, ls, bash | openai-codex/gpt-5.5        |
+| **planner**          | Analyzes requirements and produces a step-by-step implementation plan. Read-only. Does not write code. Interactive.      | read, grep, find, ls, bash | openai-codex/gpt-5.5        |
+| **oracle**           | Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only. Does not implement. Interactive. | read, grep, find, ls, bash | openai-codex/gpt-5.5        |
+| **code-reviewer**    | Reviews code changes for bugs, security issues, and correctness. Read-only. Does not fix issues.                         | read, grep, find, ls, bash | openai-codex/gpt-5.2        |
+| **quality-reviewer** | Reviews code structure for maintainability, duplication, and complexity. Read-only. Does not look for bugs.              | read, grep, find, ls, bash | openai-codex/gpt-5.2        |
+| **worker**           | Implements code changes, fixes, and refactors autonomously. Has full read-write access to the codebase.                  | all                        | openai-codex/gpt-5.5        |
 
 Read-only bundled subagents still keep `bash` for inspection workflows like `git` and `ast-grep`. This is an instruction-level contract, not a sandbox boundary.
 

package/agents/code-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: code-reviewer
 description: Reviews changed code for actionable bugs. Read-only.
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.2
 thinking: high
 tools: read, grep, find, ls, bash
 ---
@@ -14,7 +14,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 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.
 
-If the diff exceeds 500 lines, list changed files with one-line risk notes, then deeply review only the highest-risk files: business logic, auth, data mutation, error handling, public APIs.
+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.
 
 Review changed-code issues only. Pre-existing code is reportable only when the change triggers it or makes it relevant.
 

package/agents/oracle.md

@@ -1,7 +1,7 @@
 ---
 name: oracle
 description: Evaluates critical decisions, surfaces blind spots, and challenges assumptions. Read-only.
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 thinking: xhigh
 tools: read, grep, find, ls, bash
 interactive: true

package/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: Produces deterministic implementation plans. Read-only. Does not write code.
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 thinking: high
 tools: read, grep, find, ls, bash
 interactive: true
@@ -50,9 +50,11 @@ Use exactly these sections:
 1. `# Plan – <Short Title>`
 
 2. `## What`
+
 - Brief technical restatement of the change.
 
 3. `## How`
+
 - High-level approach.
 - **Scope**: in scope, out of scope, and scope assumptions.
 - **Assumptions**: list assumptions or `None`.
@@ -60,6 +62,7 @@ Use exactly these sections:
 - Key constraints/trade-offs, only if relevant.
 
 4. `## TODO`
+
 - File-oriented steps in dependency order.
 - Each step starts with `Create`, `Add`, `Update`, `Remove`, `Refactor`, or `Move`.
 - Name the file path and concrete identifiers.
@@ -68,6 +71,7 @@ Use exactly these sections:
 - If TODO exceeds 20 steps, split into phases, mark the first implementation phase, and re-check for scope creep.
 
 5. `## Outcome`
+
 - Expected end state.
 - Functional criteria.
 - Relevant non-functional criteria.

package/agents/quality-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: quality-reviewer
 description: Reviews changed code for maintainability, duplication, and complexity. Read-only.
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.2
 thinking: high
 tools: read, grep, find, ls, bash
 ---
@@ -18,7 +18,7 @@ Review the provided scope. If none is provided, review uncommitted changes. For
 
 If "full" or "codebase" is requested, first produce a structural risk map, then deeply review only the highest-risk areas.
 
-If the scope exceeds 15 files, summarize files with one-line structural notes, then deeply review the highest-risk files: large files, dependency-heavy files, widely imported files, or files crossing module boundaries. State skipped files briefly.
+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.
 
 ## Method
 

package/agents/scout.md

@@ -1,8 +1,8 @@
 ---
 name: scout
 description: Investigates codebase and returns structured findings. Read-only.
-model: anthropic/claude-haiku-4-5
-thinking: minimal
+model: openai-codex/gpt-5.5
+thinking: off
 tools: read, grep, find, ls, bash
 ---
 

package/agents/worker.md

@@ -1,8 +1,8 @@
 ---
 name: worker
 description: Implements scoped code changes safely and verifies them.
-model: anthropic/claude-sonnet-4-6
-thinking: medium
+model: openai-codex/gpt-5.5
+thinking: low
 ---
 
 You are a worker agent. Implement the assigned task or plan as small, safe, verifiable code changes. Reply in the user's language.
@@ -25,7 +25,7 @@ Before changing code, gather enough context to act safely: project conventions,
 
 ## Verification
 
-Run relevant verification: lint, typecheck, tests, and build as applicable. If a relevant check cannot be run, state why.
+Run the smallest meaningful verification for the change; use broader lint, typecheck, tests, or build only when relevant. If a relevant check cannot be run, state why.
 
 Fix only failures caused by your changes. Do not fix pre-existing failures; report them with evidence. If you cannot tell whether a failure is pre-existing or caused by your change, report it as a blocker.
 

package/extension/agent-catalog.ts

@@ -0,0 +1,369 @@
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import {
+	type AgentConfigFields,
+	parseDefinitionFields,
+	parseOverrideFields as parseConfigOverrideFields,
+} from "./agent-config-fields.js";
+
+export interface AgentConfig extends AgentConfigFields {
+	name: string;
+	description: string;
+	systemPrompt: string;
+	filePath: string;
+}
+
+type AgentConfigOverride = AgentConfigFields;
+
+export interface AgentDiscoveryWarning {
+	filePath: string;
+	message: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	warnings: AgentDiscoveryWarning[];
+}
+
+interface ParseResult {
+	agent: AgentConfig | null;
+	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[];
+}
+
+interface ConfigParseResult {
+	overrides: Record<string, AgentConfigOverride>;
+	overrideSources: Record<string, string>;
+	warnings: AgentDiscoveryWarning[];
+}
+
+function createDiscoveryWarning(filePath: string, message: string): AgentDiscoveryWarning {
+	return { filePath, message };
+}
+
+function parseAgentDefinition(content: string, filePath: string): ParseResult {
+	const warnings: AgentDiscoveryWarning[] = [];
+
+	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);
+	warnings.push(...parsedFields.warnings);
+
+	return {
+		agent: {
+			name,
+			description,
+			...parsedFields.fields,
+			systemPrompt: body,
+			filePath,
+		},
+		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 = parseConfigOverrideFields(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 mergeOverrideSources(
+	base: Record<string, string>,
+	override: Record<string, string>,
+): Record<string, string> {
+	return {
+		...base,
+		...override,
+	};
+}
+
+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 = mergeOverrideSources(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 };
+	}
+
+	/**
+	 * Loads agents from a single source group into the agents list.
+	 * Skips agents whose name already exists in seenNames (higher-priority source wins).
+	 * Within the same source group, duplicate names produce a warning.
+	 */
+	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;
+
+			// Duplicate within the same source group
+			if (groupNames.has(name)) {
+				warnings.push(
+					createDiscoveryWarning(
+						file.filePath,
+						`Duplicate subagent name "${name}" in ${group.agentsDir}, skipping`,
+					),
+				);
+				continue;
+			}
+
+			groupNames.add(name);
+
+			// Higher-priority source already registered this name
+			if (seenNames.has(name)) continue;
+
+			seenNames.set(name, file.filePath);
+			agents.push(loaded.agent);
+		}
+	}
+}