@melihmucuk/pi-crew 1.0.0

package/agents/scout.md

@@ -0,0 +1,58 @@
+---
+name: scout
+description: Investigates codebase and returns structured findings. Read-only. Use before planning or implementing to gather context.
+model: anthropic/claude-haiku-4-5
+thinking: minimal
+tools: read, grep, find, ls, bash
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything. Your output will be passed to an agent who has NOT seen the files you explored. Deliver your output in the same language as the user's request.
+
+Do NOT modify any files. Bash is for read-only commands only. Do not run builds, tests, or any command that mutates state.
+
+---
+
+## Gathering Context
+
+Before diving into the task:
+
+- Check for project conventions files (CONVENTIONS.md, .editorconfig, etc.)
+- Look at the overall project structure to understand patterns
+- Note the language, framework, and key dependencies
+
+---
+
+## Strategy
+
+1. Search the codebase to locate relevant code
+2. Read the files you need to understand the problem
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+5. Stop as soon as you have enough context for the requesting agent to act
+
+---
+
+## Output Format
+
+## Files Retrieved
+
+List with exact line ranges:
+
+1. `path/to/file` (lines 10-50) - Description of what's here
+2. `path/to/other` (lines 100-150) - Description
+
+## Key Code
+
+Critical types, interfaces, or functions (actual code from the files):
+
+```
+// paste relevant code here
+```
+
+## Architecture
+
+Brief explanation of how the pieces connect.
+
+## Start Here
+
+Which file to look at first and why.

package/agents/worker.md

@@ -0,0 +1,81 @@
+---
+name: worker
+description: Implements code changes, fixes, and refactors autonomously. Has full read-write access to the codebase.
+model: anthropic/claude-sonnet-4-6
+thinking: medium
+---
+
+You are a worker agent. You operate in an isolated context window to handle delegated tasks autonomously. Deliver your output in the same language as the user's request.
+
+---
+
+## Gathering Context
+
+Before making any changes:
+
+- Check for project conventions files (CONVENTIONS.md, .editorconfig, etc.) and follow them
+- Look at existing code in the same area to understand patterns, style, and abstractions
+- Identify existing utilities, helpers, and shared code that can be reused
+
+---
+
+## Reuse Mandate
+
+Before writing new code, search the codebase for existing functions, classes, or helpers that already solve the problem. If something similar exists, extend or reuse it. Do not duplicate logic. In common locations like `utils/`, `helpers/`, `lib/`, `shared/`, `common/`, `hooks/`, check first.
+
+---
+
+## How to Work
+
+- Work in small, verifiable steps. Do not make large sweeping changes in one go.
+- Stay within the scope of the assigned task. Do not fix unrelated issues, refactor adjacent code, or add features that weren't requested.
+- Do not perform destructive or irreversible operations (migrations, schema changes, API signature changes, public method removal) unless the task explicitly requires it.
+- After making changes, clean up: remove unused imports, dead variables, debug logs, and leftover code from old approaches.
+
+---
+
+## Verification
+
+After completing the task, run the relevant verification commands:
+
+- **Lint**: If the project has a linter configured, run it on changed files.
+- **Typecheck**: If the project uses static typing, run the type checker.
+- **Tests**: Run tests related to the changed code. If existing tests break, fix them.
+- **Build**: If the change could affect the build, verify it still succeeds.
+
+Only fix errors caused by your own changes. Do not fix pre-existing issues.
+
+---
+
+## When Stuck
+
+If you hit a blocker (ambiguous requirement, conflicting patterns in the codebase, missing context), stop and report it clearly in your output. Do not guess and continue. State what you know, what's unclear, and what decision is needed.
+
+---
+
+## What NOT to Do
+
+- Do not commit, push, or perform any git operations unless the task explicitly asks for it.
+- Do not modify files outside the task scope.
+- Do not add placeholder or TODO comments instead of implementing.
+- Do not over-abstract. Write simple, readable code. If there's only one use case, don't create a factory/strategy/wrapper for it.
+
+---
+
+## Output Format
+
+## Completed
+
+What was done, concisely.
+
+## Files Changed
+
+- `path/to/file` - what changed
+
+## Verification
+
+Which checks were run and their results (pass/fail).
+
+## Blockers (if any)
+
+What couldn't be completed and why. What decision is needed.

package/dist/agent-discovery.d.ts

@@ -0,0 +1,34 @@
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import { type SupportedToolName } from "./tool-registry.js";
+interface ParsedModel {
+    provider: string;
+    modelId: string;
+}
+export interface AgentConfig {
+    name: string;
+    description: string;
+    model?: string;
+    parsedModel?: ParsedModel;
+    thinking?: ThinkingLevel;
+    tools?: SupportedToolName[];
+    skills?: string[];
+    compaction?: boolean;
+    interactive?: boolean;
+    systemPrompt: string;
+    filePath: string;
+}
+export interface AgentDiscoveryWarning {
+    filePath: string;
+    message: string;
+}
+interface AgentDiscoveryResult {
+    agents: AgentConfig[];
+    warnings: AgentDiscoveryWarning[];
+}
+interface ParseResult {
+    agent: AgentConfig | null;
+    warnings: AgentDiscoveryWarning[];
+}
+export declare function parseAgentDefinition(content: string, filePath: string): ParseResult;
+export declare function discoverAgents(cwd?: string): AgentDiscoveryResult;
+export {};

package/dist/agent-discovery.js

@@ -0,0 +1,527 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { isSupportedToolName } from "./tool-registry.js";
+const VALID_THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+const ALLOWED_OVERRIDE_FIELDS = new Set([
+    "model",
+    "thinking",
+    "tools",
+    "skills",
+    "compaction",
+    "interactive",
+]);
+function createDiscoveryWarning(filePath, message) {
+    return { filePath, message };
+}
+/**
+ * Converts a comma-separated string or YAML array to string[].
+ * Returns undefined for null/undefined input.
+ */
+function parseCommaSeparated(value) {
+    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, name, warning) {
+    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 toDiscoveryWarnings(filePath, subject, name, warnings) {
+    return warnings.map((warning) => createDiscoveryWarning(filePath, formatFieldWarning(subject, name, warning)));
+}
+function parseListField(value, fieldName) {
+    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 }],
+    };
+}
+/**
+ * Parses "provider/model-id" format.
+ * Returns null if "/" is missing.
+ */
+function parseModel(value) {
+    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();
+    if (!provider || !modelId)
+        return null;
+    return { provider, modelId };
+}
+function validateThinkingLevel(value) {
+    if (!value)
+        return undefined;
+    if (VALID_THINKING_LEVELS.includes(value))
+        return value;
+    return undefined;
+}
+function parseModelField(value, options) {
+    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, options) {
+    if (typeof value === "string") {
+        const thinking = validateThinkingLevel(value);
+        if (!thinking) {
+            return {
+                warnings: [{ code: "invalid-thinking-level", thinking: value }],
+            };
+        }
+        return { thinking, warnings: [] };
+    }
+    if (value !== undefined && options.warnOnInvalidType) {
+        return {
+            warnings: [{ code: "invalid-type", fieldName: "thinking", expected: "string" }],
+        };
+    }
+    return { warnings: [] };
+}
+function parseToolsField(value, options) {
+    const parsedTools = parseListField(value, "tools");
+    const validTools = parsedTools.values.filter(isSupportedToolName);
+    const invalidTools = parsedTools.values.filter((toolName) => !isSupportedToolName(toolName));
+    const warnings = [...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, options) {
+    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, value, options) {
+    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, options) {
+    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,
+        ],
+    };
+}
+export function parseAgentDefinition(content, filePath) {
+    const warnings = [];
+    let frontmatter;
+    let body;
+    try {
+        const parsed = parseFrontmatter(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 = parseSharedFields(frontmatter, {
+        warnOnInvalidType: false,
+        setValueOnInvalidType: true,
+    });
+    warnings.push(...toDiscoveryWarnings(filePath, "subagent", name, parsedFields.warnings));
+    const { model, parsedModel, thinking, tools, skills, compaction, interactive } = parsedFields;
+    return {
+        agent: {
+            name,
+            description,
+            model,
+            parsedModel: parsedModel ?? undefined,
+            thinking,
+            tools,
+            skills,
+            compaction,
+            interactive,
+            systemPrompt: body,
+            filePath,
+        },
+        warnings,
+    };
+}
+function loadAgentFile(filePath) {
+    try {
+        return {
+            content: fs.readFileSync(filePath, "utf-8"),
+            warnings: [],
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            content: null,
+            warnings: [
+                createDiscoveryWarning(filePath, `Ignored subagent definition. File could not be read: ${reason}`),
+            ],
+        };
+    }
+}
+function loadAgentDefinitionFromFile(filePath) {
+    const file = loadAgentFile(filePath);
+    if (!file.content) {
+        return { agent: null, warnings: file.warnings };
+    }
+    const parsed = parseAgentDefinition(file.content, filePath);
+    return {
+        agent: parsed.agent,
+        warnings: [...file.warnings, ...parsed.warnings],
+    };
+}
+function loadAgentDefinitionFiles(agentsDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            filePaths: [],
+            warnings: [
+                createDiscoveryWarning(agentsDir, `Subagent directory could not be read: ${reason}`),
+            ],
+        };
+    }
+    return {
+        filePaths: entries
+            .filter((entry) => entry.name.endsWith(".md"))
+            .filter((entry) => entry.isFile() || entry.isSymbolicLink())
+            .map((entry) => path.join(agentsDir, entry.name)),
+        warnings: [],
+    };
+}
+function parseOverrideFields(agentName, value, filePath) {
+    const warnings = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {
+            override: null,
+            warnings: [
+                createDiscoveryWarning(filePath, `Subagent override "${agentName}" must be a JSON object, ignoring`),
+            ],
+        };
+    }
+    const record = value;
+    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 parsedFields = parseSharedFields(record, {
+        warnOnInvalidType: true,
+        setValueOnInvalidType: false,
+    });
+    warnings.push(...toDiscoveryWarnings(filePath, "subagent override", agentName, parsedFields.warnings));
+    const override = {};
+    if (parsedFields.model !== undefined) {
+        override.model = parsedFields.model;
+    }
+    if (parsedFields.parsedModel !== undefined) {
+        override.parsedModel = parsedFields.parsedModel;
+    }
+    if (parsedFields.thinking !== undefined) {
+        override.thinking = parsedFields.thinking;
+    }
+    if (parsedFields.tools !== undefined) {
+        override.tools = parsedFields.tools;
+    }
+    if (parsedFields.skills !== undefined) {
+        override.skills = parsedFields.skills;
+    }
+    if (parsedFields.compaction !== undefined) {
+        override.compaction = parsedFields.compaction;
+    }
+    if (parsedFields.interactive !== undefined) {
+        override.interactive = parsedFields.interactive;
+    }
+    return { override, warnings };
+}
+function parseConfigFile(content, filePath) {
+    let parsed;
+    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;
+    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 = {};
+    const overrideSources = {};
+    const warnings = [];
+    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 = parseOverrideFields(agentName, value, filePath);
+        warnings.push(...parsedOverride.warnings);
+        if (parsedOverride.override) {
+            overrides[agentName] = parsedOverride.override;
+            overrideSources[agentName] = filePath;
+        }
+    }
+    return { overrides, overrideSources, warnings };
+}
+function loadConfigOverridesFromFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return { overrides: {}, overrideSources: {}, warnings: [] };
+    }
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return parseConfigFile(content, filePath);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            overrides: {},
+            overrideSources: {},
+            warnings: [
+                createDiscoveryWarning(filePath, `Ignored pi-crew config. File could not be read: ${reason}`),
+            ],
+        };
+    }
+}
+function mergeConfigOverrides(base, override) {
+    const merged = { ...base };
+    for (const [agentName, agentOverride] of Object.entries(override)) {
+        merged[agentName] = {
+            ...(merged[agentName] ?? {}),
+            ...agentOverride,
+        };
+    }
+    return merged;
+}
+function mergeOverrideSources(base, override) {
+    return {
+        ...base,
+        ...override,
+    };
+}
+function loadConfigOverrides(cwd) {
+    const globalPath = path.join(getAgentDir(), "pi-crew.json");
+    const projectPath = path.join(cwd, ".pi", "pi-crew.json");
+    const globalConfig = loadConfigOverridesFromFile(globalPath);
+    const projectConfig = loadConfigOverridesFromFile(projectPath);
+    return {
+        overrides: mergeConfigOverrides(globalConfig.overrides, projectConfig.overrides),
+        overrideSources: mergeOverrideSources(globalConfig.overrideSources, projectConfig.overrideSources),
+        warnings: [...globalConfig.warnings, ...projectConfig.warnings],
+    };
+}
+function applyAgentOverride(agent, override) {
+    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 } : {}),
+    };
+}
+const bundledAgentsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
+/**
+ * Loads agents from a single directory into the agents list.
+ * Skips agents whose name already exists in seenNames (higher-priority source wins).
+ * Within the same directory, duplicate names produce a warning.
+ */
+function loadAgentsFromDir(agentsDir, seenNames, agents, warnings) {
+    if (!fs.existsSync(agentsDir))
+        return;
+    const fileLoad = loadAgentDefinitionFiles(agentsDir);
+    warnings.push(...fileLoad.warnings);
+    const dirNames = new Set();
+    for (const filePath of fileLoad.filePaths) {
+        const loaded = loadAgentDefinitionFromFile(filePath);
+        warnings.push(...loaded.warnings);
+        if (!loaded.agent)
+            continue;
+        const { name } = loaded.agent;
+        // Higher-priority source already registered this name
+        if (seenNames.has(name))
+            continue;
+        // Duplicate within the same directory
+        if (dirNames.has(name)) {
+            warnings.push(createDiscoveryWarning(filePath, `Duplicate subagent name "${name}" in ${agentsDir}, skipping`));
+            continue;
+        }
+        dirNames.add(name);
+        seenNames.set(name, filePath);
+        agents.push(loaded.agent);
+    }
+}
+export function discoverAgents(cwd = process.cwd()) {
+    const agents = [];
+    const warnings = [];
+    const seenNames = new Map();
+    // Priority 1: project-level agents
+    loadAgentsFromDir(path.join(cwd, ".pi", "agents"), seenNames, agents, warnings);
+    // Priority 2: user global agents
+    loadAgentsFromDir(path.join(getAgentDir(), "agents"), seenNames, agents, warnings);
+    // Priority 3: bundled agents
+    loadAgentsFromDir(bundledAgentsDir, seenNames, agents, warnings);
+    const configOverrides = loadConfigOverrides(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] ?? path.join(cwd, ".pi", "pi-crew.json"), `Subagent override "${agentName}" does not match any discovered subagent, ignoring`));
+        }
+    }
+    return { agents: finalAgents, warnings };
+}