pi-crew 0.2.3 → 0.2.5

package/src/runtime/settings-store.ts

@@ -0,0 +1,103 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import type { JoinMode } from "./group-join.ts";
+
+export interface CrewSettings {
+	maxConcurrent?: number;
+	defaultMaxTurns?: number;
+	graceTurns?: number;
+	defaultJoinMode?: JoinMode;
+	schedulingEnabled?: boolean;
+	notifierIntervalMs?: number;
+}
+
+const MAX_CONCURRENT_CEILING = 1024;
+const MAX_TURNS_CEILING = 10_000;
+const GRACE_TURNS_CEILING = 1_000;
+const VALID_JOIN_MODES = new Set<JoinMode>(["async", "group", "smart"]);
+
+function sanitizeSettings(raw: unknown): CrewSettings {
+	if (!raw || typeof raw !== "object") return {};
+	const r = raw as Record<string, unknown>;
+	const out: CrewSettings = {};
+	if (
+		typeof r.maxConcurrent === "number" &&
+		Number.isInteger(r.maxConcurrent) &&
+		r.maxConcurrent >= 1 &&
+		r.maxConcurrent <= MAX_CONCURRENT_CEILING
+	) {
+		out.maxConcurrent = r.maxConcurrent;
+	}
+	if (
+		typeof r.defaultMaxTurns === "number" &&
+		Number.isInteger(r.defaultMaxTurns) &&
+		r.defaultMaxTurns >= 0 &&
+		r.defaultMaxTurns <= MAX_TURNS_CEILING
+	) {
+		out.defaultMaxTurns = r.defaultMaxTurns;
+	}
+	if (
+		typeof r.graceTurns === "number" &&
+		Number.isInteger(r.graceTurns) &&
+		r.graceTurns >= 1 &&
+		r.graceTurns <= GRACE_TURNS_CEILING
+	) {
+		out.graceTurns = r.graceTurns;
+	}
+	if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode as JoinMode)) {
+		out.defaultJoinMode = r.defaultJoinMode as JoinMode;
+	}
+	if (typeof r.schedulingEnabled === "boolean") {
+		out.schedulingEnabled = r.schedulingEnabled;
+	}
+	if (typeof r.notifierIntervalMs === "number" && r.notifierIntervalMs >= 1000) {
+		out.notifierIntervalMs = r.notifierIntervalMs;
+	}
+	return out;
+}
+
+function globalPath(): string {
+	return path.join(homedir(), ".pi", "crew-settings.json");
+}
+
+function projectPath(cwd: string): string {
+	return path.join(cwd, ".pi", "crew-settings.json");
+}
+
+function readSettingsFile(filePath: string): CrewSettings {
+	if (!fs.existsSync(filePath)) return {};
+	try {
+		return sanitizeSettings(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		console.warn(`[pi-crew] Ignoring malformed settings at ${filePath}: ${reason}`);
+		return {};
+	}
+}
+
+export function loadCrewSettings(cwd: string = process.cwd()): CrewSettings {
+	return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+
+export function saveCrewSettings(s: CrewSettings, cwd: string = process.cwd()): boolean {
+	const p = projectPath(cwd);
+	try {
+		fs.mkdirSync(path.dirname(p), { recursive: true });
+		fs.writeFileSync(p, JSON.stringify(s, null, 2), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function applyCrewSettingsToConfig(
+	config: { limits?: { maxConcurrentWorkers?: number }; runtime?: { maxTurns?: number; graceTurns?: number; groupJoin?: string }; notifierIntervalMs?: number },
+	settings: CrewSettings,
+): void {
+	if (settings.maxConcurrent != null && config.limits) config.limits.maxConcurrentWorkers = settings.maxConcurrent;
+	if (settings.defaultMaxTurns != null && config.runtime) config.runtime.maxTurns = settings.defaultMaxTurns;
+	if (settings.graceTurns != null && config.runtime) config.runtime.graceTurns = settings.graceTurns;
+	if (settings.defaultJoinMode != null && config.runtime) config.runtime.groupJoin = settings.defaultJoinMode;
+	if (settings.notifierIntervalMs != null) config.notifierIntervalMs = settings.notifierIntervalMs;
+}

package/src/runtime/sidechain-output.ts

@@ -1,29 +1,29 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { redactSecrets } from "../utils/redaction.ts";
-
-export interface SidechainEntry {
-	isSidechain: true;
-	agentId: string;
-	type: string;
-	message: unknown;
-	timestamp: string;
-	cwd: string;
-}
-
-export function writeSidechainEntry(filePath: string, entry: Omit<SidechainEntry, "isSidechain" | "timestamp">): void {
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ isSidechain: true, timestamp: new Date().toISOString(), ...entry }))}\n`, "utf-8");
-}
-
-export function sidechainOutputPath(stateRoot: string, taskId: string): string {
-	return path.join(stateRoot, "agents", taskId, "sidechain.output.jsonl");
-}
-
-export function eventToSidechainType(event: unknown): string | undefined {
-	if (!event || typeof event !== "object" || Array.isArray(event)) return undefined;
-	const type = (event as { type?: unknown }).type;
-	if (type === "message_start" || type === "message_update" || type === "message_end") return "message";
-	if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") return "tool";
-	return typeof type === "string" ? type : undefined;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { redactSecrets } from "../utils/redaction.ts";
+
+export interface SidechainEntry {
+	isSidechain: true;
+	agentId: string;
+	type: string;
+	message: unknown;
+	timestamp: string;
+	cwd: string;
+}
+
+export function writeSidechainEntry(filePath: string, entry: Omit<SidechainEntry, "isSidechain" | "timestamp">): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ isSidechain: true, timestamp: new Date().toISOString(), ...entry }))}\n`, "utf-8");
+}
+
+export function sidechainOutputPath(stateRoot: string, taskId: string): string {
+	return path.join(stateRoot, "agents", taskId, "sidechain.output.jsonl");
+}
+
+export function eventToSidechainType(event: unknown): string | undefined {
+	if (!event || typeof event !== "object" || Array.isArray(event)) return undefined;
+	const type = (event as { type?: unknown }).type;
+	if (type === "message_start" || type === "message_update" || type === "message_end") return "message";
+	if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") return "tool";
+	return typeof type === "string" ? type : undefined;
+}

package/src/runtime/skill-instructions.ts

@@ -1,222 +1,222 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { AgentConfig } from "../agents/agent-config.ts";
-import type { TeamRole } from "../teams/team-config.ts";
-import type { WorkflowStep } from "../workflows/workflow-config.ts";
-import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
-
-const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
-const MAX_SKILL_CHARS = 1500;
-const MAX_TOTAL_CHARS = 6000;
-const MAX_SKILL_NAME_CHARS = 80;
-const MAX_SELECTED_SKILLS = 32;
-const SKILL_CACHE_MAX_ENTRIES = 128;
-
-const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
-	explorer: ["read-only-explorer", "context-artifact-hygiene"],
-	analyst: ["read-only-explorer", "requirements-to-task-packet"],
-	planner: ["delegation-patterns", "requirements-to-task-packet"],
-	critic: ["read-only-explorer", "multi-perspective-review"],
-	executor: ["state-mutation-locking", "safe-bash", "verification-before-done"],
-	reviewer: ["read-only-explorer", "multi-perspective-review"],
-	"security-reviewer": ["secure-agent-orchestration-review", "ownership-session-security"],
-	"test-engineer": ["verification-before-done", "safe-bash"],
-	verifier: ["verification-before-done", "runtime-state-reader"],
-	writer: ["context-artifact-hygiene", "verify-evidence"],
-};
-
-export interface ResolveTaskSkillsInput {
-	role: string;
-	agent?: Pick<AgentConfig, "skills">;
-	teamRole?: Pick<TeamRole, "skills">;
-	step?: Pick<WorkflowStep, "skills">;
-	override?: string[] | false;
-}
-
-export interface RenderSkillInstructionsInput extends ResolveTaskSkillsInput {
-	cwd: string;
-}
-
-function isValidSkillName(name: string): boolean {
-	return name.length > 0 && name.length <= MAX_SKILL_NAME_CHARS && isSafePathId(name);
-}
-
-function sanitizeSkillName(name: string): string {
-	return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SKILL_NAME_CHARS) || "invalid";
-}
-
-function unique(items: string[]): string[] {
-	const seen = new Set<string>();
-	const result: string[] = [];
-	for (const item of items.map((entry) => entry.trim()).filter(Boolean)) {
-		if (!isValidSkillName(item)) continue;
-		if (seen.has(item)) continue;
-		seen.add(item);
-		result.push(item);
-	}
-	return result;
-}
-
-export function normalizeSkillOverride(value: string | string[] | boolean | undefined): string[] | false | undefined {
-	if (value === false) return false;
-	if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
-	if (value === true) return undefined;
-	if (Array.isArray(value)) return value.map((entry) => entry.trim()).filter(Boolean);
-	return undefined;
-}
-
-export function defaultSkillsForRole(role: string): string[] {
-	return DEFAULT_ROLE_SKILLS[role] ?? [];
-}
-
-function collectTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
-	if (input.override === false) return [];
-	const roleDefaultsDisabled = input.teamRole?.skills === false || input.step?.skills === false;
-	const names = roleDefaultsDisabled ? [] : defaultSkillsForRole(input.role);
-	if (input.agent?.skills?.length) names.push(...input.agent.skills);
-	if (Array.isArray(input.teamRole?.skills)) names.push(...input.teamRole.skills);
-	if (Array.isArray(input.step?.skills)) names.push(...input.step.skills);
-	if (Array.isArray(input.override)) names.push(...input.override);
-	return unique(names);
-}
-
-export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
-	return collectTaskSkillNames(input).slice(0, MAX_SELECTED_SKILLS);
-}
-
-function candidateSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
-	return [
-		{ root: path.resolve(cwd, "skills"), source: "project" },
-		{ root: PACKAGE_SKILLS_DIR, source: "package" },
-	];
-}
-
-interface CachedSkillMarkdown {
-	path: string;
-	source: "project" | "package";
-	content: string;
-	mtimeMs: number;
-	size: number;
-}
-
-const skillReadCache = new Map<string, CachedSkillMarkdown>();
-
-function rememberSkill(key: string, value: CachedSkillMarkdown): CachedSkillMarkdown {
-	if (skillReadCache.has(key)) skillReadCache.delete(key);
-	skillReadCache.set(key, value);
-	while (skillReadCache.size > SKILL_CACHE_MAX_ENTRIES) {
-		const oldest = skillReadCache.keys().next().value;
-		if (!oldest) break;
-		skillReadCache.delete(oldest);
-	}
-	return value;
-}
-
-export function clearSkillInstructionCache(): void {
-	skillReadCache.clear();
-}
-
-function cachedSkillFresh(value: CachedSkillMarkdown): boolean {
-	try {
-		const stat = fs.statSync(value.path);
-		return stat.mtimeMs === value.mtimeMs && stat.size === value.size;
-	} catch {
-		return false;
-	}
-}
-
-function readSkillMarkdown(cwd: string, name: string): { path: string; source: "project" | "package"; content: string } | undefined {
-	if (!isValidSkillName(name)) return undefined;
-	const cacheKey = `${path.resolve(cwd)}:${name}`;
-	const cached = skillReadCache.get(cacheKey);
-	if (cached && cachedSkillFresh(cached)) return cached;
-	if (cached) skillReadCache.delete(cacheKey);
-	for (const entry of candidateSkillDirs(cwd)) {
-		try {
-			const relative = path.join(name, "SKILL.md");
-			const contained = resolveContainedPath(entry.root, relative);
-			if (!fs.existsSync(contained)) continue;
-			if (fs.lstatSync(contained).isSymbolicLink()) continue;
-			const filePath = resolveRealContainedPath(entry.root, relative);
-			const stat = fs.statSync(filePath);
-			return rememberSkill(cacheKey, { path: filePath, source: entry.source, content: fs.readFileSync(filePath, "utf-8"), mtimeMs: stat.mtimeMs, size: stat.size });
-		} catch {
-			continue;
-		}
-	}
-	return undefined;
-}
-
-function frontmatterDescription(content: string): string | undefined {
-	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
-	if (!match) return undefined;
-	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
-	return line?.slice("description:".length).trim();
-}
-
-function stripFrontmatter(content: string): string {
-	return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
-}
-
-function compactSkillContent(content: string): string {
-	const body = stripFrontmatter(content);
-	if (body.length <= MAX_SKILL_CHARS) return body;
-	const preferred = body.split(/\r?\n## Verification\r?\n/)[0]?.trim() ?? body;
-	const truncated = preferred.length > MAX_SKILL_CHARS ? preferred.slice(0, MAX_SKILL_CHARS - 40).trimEnd() : preferred;
-	return `${truncated}\n\n[skill instructions truncated]`;
-}
-
-export interface RenderedSkillInstructions {
-	names: string[];
-	paths: string[];
-	block: string;
-}
-
-export function renderSkillInstructions(input: RenderSkillInstructionsInput): RenderedSkillInstructions {
-	const allNames = collectTaskSkillNames(input);
-	const names = allNames.slice(0, MAX_SELECTED_SKILLS);
-	const overflowCount = Math.max(0, allNames.length - names.length);
-	if (names.length === 0) return { names, paths: [], block: "" };
-	const sections: string[] = [];
-	const skillPaths: string[] = [];
-	let total = 0;
-	let omittedCount = overflowCount;
-	const pushSection = (section: string): boolean => {
-		if (total + section.length > MAX_TOTAL_CHARS) return false;
-		sections.push(section);
-		total += section.length;
-		return true;
-	};
-	for (const name of names) {
-		const safeName = sanitizeSkillName(name);
-		const loaded = readSkillMarkdown(input.cwd, name);
-		if (!loaded) {
-			const missing = `## ${safeName}\n\nSkill '${safeName}' was selected but no SKILL.md file was found. Continue with the task packet and report this missing skill.`;
-			if (!pushSection(missing)) omittedCount += 1;
-			continue;
-		}
-		skillPaths.push(path.dirname(loaded.path));
-		const description = frontmatterDescription(loaded.content);
-		const source = loaded.source === "project" ? `project:skills/${safeName}` : `package:skills/${safeName}`;
-		const header = [`## ${safeName}`, description ? `Description: ${description}` : undefined, `Source: ${source}`].filter(Boolean).join("\n");
-		const section = `${header}\n\n${compactSkillContent(loaded.content)}`;
-		if (!pushSection(section)) omittedCount += 1;
-	}
-	if (omittedCount > 0) {
-		const summary = `## Omitted skills\n\n[omitted ${omittedCount} selected skill(s): skill instruction budget exceeded]`;
-		if (!pushSection(summary) && sections.length > 0) {
-			sections[sections.length - 1] = summary;
-		}
-	}
-	return {
-		names,
-		paths: [...new Set(skillPaths)],
-		block: [
-			"# Applicable Skills",
-			"The following skills were selected for this worker. Follow them when they match the current task. If a selected skill conflicts with the explicit task packet, project AGENTS.md, or user request, follow the stricter/higher-priority instruction and report the conflict.",
-			"",
-			sections.join("\n\n---\n\n"),
-		].join("\n"),
-	};
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamRole } from "../teams/team-config.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const MAX_SKILL_CHARS = 1500;
+const MAX_TOTAL_CHARS = 6000;
+const MAX_SKILL_NAME_CHARS = 80;
+const MAX_SELECTED_SKILLS = 32;
+const SKILL_CACHE_MAX_ENTRIES = 128;
+
+const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
+	explorer: ["read-only-explorer", "context-artifact-hygiene"],
+	analyst: ["read-only-explorer", "requirements-to-task-packet"],
+	planner: ["delegation-patterns", "requirements-to-task-packet"],
+	critic: ["read-only-explorer", "multi-perspective-review"],
+	executor: ["state-mutation-locking", "safe-bash", "verification-before-done"],
+	reviewer: ["read-only-explorer", "multi-perspective-review"],
+	"security-reviewer": ["secure-agent-orchestration-review", "ownership-session-security"],
+	"test-engineer": ["verification-before-done", "safe-bash"],
+	verifier: ["verification-before-done", "runtime-state-reader"],
+	writer: ["context-artifact-hygiene", "verify-evidence"],
+};
+
+export interface ResolveTaskSkillsInput {
+	role: string;
+	agent?: Pick<AgentConfig, "skills">;
+	teamRole?: Pick<TeamRole, "skills">;
+	step?: Pick<WorkflowStep, "skills">;
+	override?: string[] | false;
+}
+
+export interface RenderSkillInstructionsInput extends ResolveTaskSkillsInput {
+	cwd: string;
+}
+
+function isValidSkillName(name: string): boolean {
+	return name.length > 0 && name.length <= MAX_SKILL_NAME_CHARS && isSafePathId(name);
+}
+
+function sanitizeSkillName(name: string): string {
+	return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SKILL_NAME_CHARS) || "invalid";
+}
+
+function unique(items: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const item of items.map((entry) => entry.trim()).filter(Boolean)) {
+		if (!isValidSkillName(item)) continue;
+		if (seen.has(item)) continue;
+		seen.add(item);
+		result.push(item);
+	}
+	return result;
+}
+
+export function normalizeSkillOverride(value: string | string[] | boolean | undefined): string[] | false | undefined {
+	if (value === false) return false;
+	if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (value === true) return undefined;
+	if (Array.isArray(value)) return value.map((entry) => entry.trim()).filter(Boolean);
+	return undefined;
+}
+
+export function defaultSkillsForRole(role: string): string[] {
+	return DEFAULT_ROLE_SKILLS[role] ?? [];
+}
+
+function collectTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
+	if (input.override === false) return [];
+	const roleDefaultsDisabled = input.teamRole?.skills === false || input.step?.skills === false;
+	const names = roleDefaultsDisabled ? [] : defaultSkillsForRole(input.role);
+	if (input.agent?.skills?.length) names.push(...input.agent.skills);
+	if (Array.isArray(input.teamRole?.skills)) names.push(...input.teamRole.skills);
+	if (Array.isArray(input.step?.skills)) names.push(...input.step.skills);
+	if (Array.isArray(input.override)) names.push(...input.override);
+	return unique(names);
+}
+
+export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
+	return collectTaskSkillNames(input).slice(0, MAX_SELECTED_SKILLS);
+}
+
+function candidateSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
+	return [
+		{ root: path.resolve(cwd, "skills"), source: "project" },
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+	];
+}
+
+interface CachedSkillMarkdown {
+	path: string;
+	source: "project" | "package";
+	content: string;
+	mtimeMs: number;
+	size: number;
+}
+
+const skillReadCache = new Map<string, CachedSkillMarkdown>();
+
+function rememberSkill(key: string, value: CachedSkillMarkdown): CachedSkillMarkdown {
+	if (skillReadCache.has(key)) skillReadCache.delete(key);
+	skillReadCache.set(key, value);
+	while (skillReadCache.size > SKILL_CACHE_MAX_ENTRIES) {
+		const oldest = skillReadCache.keys().next().value;
+		if (!oldest) break;
+		skillReadCache.delete(oldest);
+	}
+	return value;
+}
+
+export function clearSkillInstructionCache(): void {
+	skillReadCache.clear();
+}
+
+function cachedSkillFresh(value: CachedSkillMarkdown): boolean {
+	try {
+		const stat = fs.statSync(value.path);
+		return stat.mtimeMs === value.mtimeMs && stat.size === value.size;
+	} catch {
+		return false;
+	}
+}
+
+function readSkillMarkdown(cwd: string, name: string): { path: string; source: "project" | "package"; content: string } | undefined {
+	if (!isValidSkillName(name)) return undefined;
+	const cacheKey = `${path.resolve(cwd)}:${name}`;
+	const cached = skillReadCache.get(cacheKey);
+	if (cached && cachedSkillFresh(cached)) return cached;
+	if (cached) skillReadCache.delete(cacheKey);
+	for (const entry of candidateSkillDirs(cwd)) {
+		try {
+			const relative = path.join(name, "SKILL.md");
+			const contained = resolveContainedPath(entry.root, relative);
+			if (!fs.existsSync(contained)) continue;
+			if (fs.lstatSync(contained).isSymbolicLink()) continue;
+			const filePath = resolveRealContainedPath(entry.root, relative);
+			const stat = fs.statSync(filePath);
+			return rememberSkill(cacheKey, { path: filePath, source: entry.source, content: fs.readFileSync(filePath, "utf-8"), mtimeMs: stat.mtimeMs, size: stat.size });
+		} catch {
+			continue;
+		}
+	}
+	return undefined;
+}
+
+function frontmatterDescription(content: string): string | undefined {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return undefined;
+	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+	return line?.slice("description:".length).trim();
+}
+
+function stripFrontmatter(content: string): string {
+	return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+}
+
+function compactSkillContent(content: string): string {
+	const body = stripFrontmatter(content);
+	if (body.length <= MAX_SKILL_CHARS) return body;
+	const preferred = body.split(/\r?\n## Verification\r?\n/)[0]?.trim() ?? body;
+	const truncated = preferred.length > MAX_SKILL_CHARS ? preferred.slice(0, MAX_SKILL_CHARS - 40).trimEnd() : preferred;
+	return `${truncated}\n\n[skill instructions truncated]`;
+}
+
+export interface RenderedSkillInstructions {
+	names: string[];
+	paths: string[];
+	block: string;
+}
+
+export function renderSkillInstructions(input: RenderSkillInstructionsInput): RenderedSkillInstructions {
+	const allNames = collectTaskSkillNames(input);
+	const names = allNames.slice(0, MAX_SELECTED_SKILLS);
+	const overflowCount = Math.max(0, allNames.length - names.length);
+	if (names.length === 0) return { names, paths: [], block: "" };
+	const sections: string[] = [];
+	const skillPaths: string[] = [];
+	let total = 0;
+	let omittedCount = overflowCount;
+	const pushSection = (section: string): boolean => {
+		if (total + section.length > MAX_TOTAL_CHARS) return false;
+		sections.push(section);
+		total += section.length;
+		return true;
+	};
+	for (const name of names) {
+		const safeName = sanitizeSkillName(name);
+		const loaded = readSkillMarkdown(input.cwd, name);
+		if (!loaded) {
+			const missing = `## ${safeName}\n\nSkill '${safeName}' was selected but no SKILL.md file was found. Continue with the task packet and report this missing skill.`;
+			if (!pushSection(missing)) omittedCount += 1;
+			continue;
+		}
+		skillPaths.push(path.dirname(loaded.path));
+		const description = frontmatterDescription(loaded.content);
+		const source = loaded.source === "project" ? `project:skills/${safeName}` : `package:skills/${safeName}`;
+		const header = [`## ${safeName}`, description ? `Description: ${description}` : undefined, `Source: ${source}`].filter(Boolean).join("\n");
+		const section = `${header}\n\n${compactSkillContent(loaded.content)}`;
+		if (!pushSection(section)) omittedCount += 1;
+	}
+	if (omittedCount > 0) {
+		const summary = `## Omitted skills\n\n[omitted ${omittedCount} selected skill(s): skill instruction budget exceeded]`;
+		if (!pushSection(summary) && sections.length > 0) {
+			sections[sections.length - 1] = summary;
+		}
+	}
+	return {
+		names,
+		paths: [...new Set(skillPaths)],
+		block: [
+			"# Applicable Skills",
+			"The following skills were selected for this worker. Follow them when they match the current task. If a selected skill conflicts with the explicit task packet, project AGENTS.md, or user request, follow the stricter/higher-priority instruction and report the conflict.",
+			"",
+			sections.join("\n\n---\n\n"),
+		].join("\n"),
+	};
+}