@zaganjade/pi-multi-skill 1.0.0 → 1.3.1

package/src/metadata.ts

@@ -0,0 +1,170 @@
+import { readFileSync } from "node:fs";
+import {
+	parseFrontmatter as parsePiFrontmatter,
+	stripFrontmatter as stripPiFrontmatter,
+} from "@earendil-works/pi-coding-agent";
+import type { EnrichedSkillInfo, LoadMode, SkillInfo, SkillMetadata, SkillOrder } from "./types.ts";
+
+const PROCESS_NAMES = new Set([
+	"using-superpowers",
+	"brainstorming",
+	"systematic-debugging",
+	"bmad-master",
+	"writing-plans",
+	"dispatching-parallel-agents",
+	"subagent-driven-development",
+	"executing-plans",
+]);
+
+const PLANNING_NAMES = new Set([
+	"analyst",
+	"pm",
+	"architect",
+	"ux-designer",
+	"scrum-master",
+]);
+
+function parseFrontmatter(content: string): Record<string, string> {
+	const { frontmatter } = parsePiFrontmatter<Record<string, unknown>>(content);
+	const fields: Record<string, string> = {};
+	for (const [key, value] of Object.entries(frontmatter)) {
+		if (value === undefined || value === null) continue;
+		fields[key] = String(value);
+	}
+	return fields;
+}
+
+export function stripFrontmatter(content: string): string {
+	return stripPiFrontmatter(content);
+}
+
+function parseListField(value: string | undefined): string[] {
+	if (!value) return [];
+	const trimmed = value.trim();
+	if (trimmed.startsWith("[")) {
+		try {
+			const parsed = JSON.parse(trimmed) as unknown;
+			if (Array.isArray(parsed)) {
+				return parsed.map(String).filter(Boolean);
+			}
+		} catch {
+			// fall through
+		}
+	}
+	return trimmed
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+function parseTokenBudget(value: string | undefined): LoadMode | undefined {
+	if (value === "meta" || value === "lazy" || value === "full") return value;
+	return undefined;
+}
+
+function extractCommands(body: string): string[] {
+	const commands: string[] = [];
+	const section = body.match(
+		/## Available Commands[\s\S]*?(?=\n## |\n# |$)/i,
+	);
+	if (!section) return commands;
+
+	for (const line of section[0].split("\n")) {
+		const match = line.match(/\*\*(\/[\w-]+)/);
+		if (match) commands.push(match[1]);
+	}
+	return commands;
+}
+
+function inferType(
+	name: string,
+	frontmatter: Record<string, string>,
+): SkillMetadata["type"] {
+	const explicit = frontmatter.type?.toLowerCase();
+	if (explicit === "process" || explicit === "rigid" || explicit === "flexible") {
+		return explicit;
+	}
+	if (PROCESS_NAMES.has(name)) return "process";
+	if (name.includes("debug") || name.includes("tdd")) return "rigid";
+	return "unknown";
+}
+
+function priorityScore(meta: SkillMetadata): number {
+	if (meta.type === "process") return 0;
+	if (PROCESS_NAMES.has(meta.name)) return 1;
+	if (PLANNING_NAMES.has(meta.name)) return 2;
+	if (meta.module === "core") return 1;
+	if (meta.module === "bmm") return 3;
+	return 4;
+}
+
+export function enrichSkill(skill: SkillInfo): EnrichedSkillInfo {
+	let rawContent = "";
+	try {
+		rawContent = readFileSync(skill.filePath, "utf-8");
+	} catch {
+		rawContent = "";
+	}
+
+	const frontmatter = parseFrontmatter(rawContent);
+	const body = stripFrontmatter(rawContent).trim();
+	const name = frontmatter.name || skill.name;
+	const description =
+		skill.description || frontmatter.description || truncateFirstLine(body);
+
+	const metadata: SkillMetadata = {
+		name,
+		description,
+		type: inferType(name, frontmatter),
+		module: frontmatter.module || "",
+		priority: Number.parseInt(frontmatter.priority || "50", 10) || 50,
+		commands: extractCommands(body),
+		skillId: frontmatter.skill_id || "",
+		version: frontmatter.version || "",
+		pairsWith: parseListField(frontmatter.pairs_with),
+		conflictsWith: parseListField(frontmatter.conflicts_with),
+		tokenBudget: parseTokenBudget(frontmatter.token_budget),
+	};
+
+	return { ...skill, name, description, metadata, rawContent, body };
+}
+
+function truncateFirstLine(body: string): string {
+	const line = body
+		.split("\n")
+		.map((l) => l.replace(/^>\s*/, "").trim())
+		.find((l) => l.length > 0);
+	return line?.slice(0, 120) ?? "";
+}
+
+export function sortSkills(
+	skills: EnrichedSkillInfo[],
+	order: SkillOrder = "process-first",
+): EnrichedSkillInfo[] {
+	if (order === "alpha") {
+		return [...skills].sort((a, b) => a.name.localeCompare(b.name));
+	}
+	if (order === "explicit") return skills;
+
+	return [...skills].sort((a, b) => {
+		const pa = priorityScore(a.metadata);
+		const pb = priorityScore(b.metadata);
+		if (pa !== pb) return pa - pb;
+		if (a.metadata.priority !== b.metadata.priority) {
+			return a.metadata.priority - b.metadata.priority;
+		}
+		return a.name.localeCompare(b.name);
+	});
+}
+
+export function truncateDescription(desc: string, maxLen = 120): string {
+	if (!desc) return "";
+	const lines = desc
+		.split("\n")
+		.map((l) => l.replace(/^>\s*/, "").trim())
+		.filter((l) => l.length > 0);
+	if (lines.length === 0) return "";
+	let text = lines[0];
+	if (lines.length > 1 && text.length < 40) text = `${text} ${lines[1]}`;
+	return text.length > maxLen ? `${text.slice(0, maxLen - 1)}…` : text;
+}

package/src/parse-args.ts

@@ -0,0 +1,80 @@
+import type { LoadMode, ParsedSkillsArgs } from "./types.ts";
+
+const FLAG_MODES: Record<string, LoadMode> = {
+	"--meta": "meta",
+	"--full": "full",
+	"--lazy": "lazy",
+};
+
+export function parseSkillsArgs(raw: string): ParsedSkillsArgs {
+	let text = raw.trim();
+	let mode: LoadMode = "full";
+	let auto = false;
+	let parallel = false;
+
+	for (const [flag, loadMode] of Object.entries(FLAG_MODES)) {
+		if (text.includes(flag)) {
+			mode = loadMode;
+			text = text.replace(new RegExp(`\\s*${flag}\\b`, "g"), " ").trim();
+		}
+	}
+
+	if (/\s--auto\b/.test(text)) {
+		auto = true;
+		text = text.replace(/\s*--auto\b/g, " ").trim();
+	}
+
+	if (/\s--parallel\b/.test(text)) {
+		parallel = true;
+		text = text.replace(/\s*--parallel\b/g, " ").trim();
+	}
+
+	const tokens = text.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+	if (!tokens) {
+		return {
+			skillNames: [],
+			mode,
+			auto,
+			parallel,
+			parallelTasks: [],
+			instructions: "",
+		};
+	}
+
+	const skillNames = tokens[1]
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+
+	let instructions = tokens[2]?.trim() ?? "";
+	let embeddedCommand: string | undefined;
+	let parallelTasks: string[] = [];
+
+	if (parallel && instructions.includes("|")) {
+		parallelTasks = instructions
+			.split("|")
+			.map((s) => s.trim())
+			.filter((s) => s.length > 0);
+		instructions = "";
+	} else if (parallel && instructions) {
+		parallelTasks = [instructions];
+	}
+
+	const cmdMatch = instructions.match(
+		/^(\/[\w-]+(?:\s+[^\n|]+)?)(?:\s+([\s\S]*))?$/,
+	);
+	if (cmdMatch && !parallel) {
+		embeddedCommand = cmdMatch[1].trim();
+		instructions = cmdMatch[2]?.trim() ?? "";
+	}
+
+	return {
+		skillNames,
+		mode,
+		auto,
+		parallel,
+		parallelTasks,
+		embeddedCommand,
+		instructions,
+	};
+}

package/src/registry.ts

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { enrichSkill } from "./metadata.ts";
+import type { SkillInfo } from "./types.ts";
+
+function getAgentDir(): string {
+	return join(homedir(), ".pi", "agent");
+}
+
+export function rebuildSkillIndex(skills: SkillInfo[]): void {
+	const index = {
+		updatedAt: new Date().toISOString(),
+		count: skills.length,
+		skills: skills.map((skill) => {
+			const enriched = enrichSkill(skill);
+			return {
+				name: enriched.name,
+				description: enriched.metadata.description,
+				type: enriched.metadata.type,
+				module: enriched.metadata.module,
+				priority: enriched.metadata.priority,
+				skillId: enriched.metadata.skillId,
+				version: enriched.metadata.version,
+				pairsWith: enriched.metadata.pairsWith,
+				conflictsWith: enriched.metadata.conflictsWith,
+				tokenBudget: enriched.metadata.tokenBudget,
+				commands: enriched.metadata.commands,
+				location: enriched.filePath,
+			};
+		}),
+	};
+
+	const dir = getAgentDir();
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+	try {
+		writeFileSync(
+			join(dir, "skill-index.json"),
+			`${JSON.stringify(index, null, 2)}\n`,
+			"utf-8",
+		);
+	} catch {
+		// Non-fatal — index is optional
+	}
+}

package/src/stats.ts

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { LoadMode } from "./types.ts";
+
+export interface ActivationRecord {
+	at: string;
+	mode: LoadMode;
+	skillNames: string[];
+	bundles: string[];
+	parallel: boolean;
+	skillCount: number;
+	/** Original /skills args for /skills-last replay. */
+	rawArgs?: string;
+}
+
+export interface MultiSkillStats {
+	version: 1;
+	activations: number;
+	byMode: Record<LoadMode, number>;
+	byBundle: Record<string, number>;
+	bySkillCount: Record<string, number>;
+	recent: ActivationRecord[];
+}
+
+function statsPath(): string {
+	return join(homedir(), ".pi", "agent", "multi-skill-stats.json");
+}
+
+function emptyStats(): MultiSkillStats {
+	return {
+		version: 1,
+		activations: 0,
+		byMode: { full: 0, meta: 0, lazy: 0 },
+		byBundle: {},
+		bySkillCount: {},
+		recent: [],
+	};
+}
+
+export function loadStats(): MultiSkillStats {
+	const path = statsPath();
+	if (!existsSync(path)) return emptyStats();
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as MultiSkillStats;
+		if (parsed.version !== 1) return emptyStats();
+		return { ...emptyStats(), ...parsed, recent: parsed.recent ?? [] };
+	} catch {
+		return emptyStats();
+	}
+}
+
+function saveStats(stats: MultiSkillStats): void {
+	const dir = join(homedir(), ".pi", "agent");
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeFileSync(statsPath(), `${JSON.stringify(stats, null, 2)}\n`, "utf-8");
+}
+
+export function recordActivation(
+	record: Omit<ActivationRecord, "at">,
+): void {
+	const stats = loadStats();
+	stats.activations += 1;
+	stats.byMode[record.mode] = (stats.byMode[record.mode] ?? 0) + 1;
+
+	for (const bundle of record.bundles) {
+		stats.byBundle[bundle] = (stats.byBundle[bundle] ?? 0) + 1;
+	}
+
+	const bucket =
+		record.skillCount <= 1
+			? "1"
+			: record.skillCount <= 3
+				? "2-3"
+				: "4+";
+	stats.bySkillCount[bucket] = (stats.bySkillCount[bucket] ?? 0) + 1;
+
+	stats.recent.unshift({ ...record, at: new Date().toISOString() });
+	stats.recent = stats.recent.slice(0, 20);
+
+	saveStats(stats);
+}
+
+export function formatStatsReport(): string {
+	const stats = loadStats();
+	const lines: string[] = [
+		`Multi-skill activations: ${stats.activations}`,
+		"",
+		"By load mode:",
+		`  full: ${stats.byMode.full} · meta: ${stats.byMode.meta} · lazy: ${stats.byMode.lazy}`,
+	];
+
+	const bundles = Object.entries(stats.byBundle).sort((a, b) => b[1] - a[1]);
+	if (bundles.length > 0) {
+		lines.push("", "Top bundles:");
+		for (const [name, count] of bundles.slice(0, 8)) {
+			lines.push(`  @${name}: ${count}`);
+		}
+	}
+
+	const counts = Object.entries(stats.bySkillCount);
+	if (counts.length > 0) {
+		lines.push("", "Skills per activation:");
+		for (const [bucket, count] of counts) {
+			lines.push(`  ${bucket} skill(s): ${count}`);
+		}
+	}
+
+	if (stats.recent.length > 0) {
+		lines.push("", "Recent:");
+		for (const r of stats.recent.slice(0, 5)) {
+			const label =
+				r.bundles.length > 0
+					? r.bundles.map((b) => `@${b}`).join(",")
+					: r.skillNames.slice(0, 3).join(",");
+			lines.push(
+				`  ${r.at.slice(0, 19)} · ${r.mode} · ${label}${r.parallel ? " · parallel" : ""}`,
+			);
+		}
+	}
+
+	lines.push("", "Stats file: ~/.pi/agent/multi-skill-stats.json");
+	return lines.join("\n");
+}
+
+export function getLastActivation(): ActivationRecord | null {
+	const stats = loadStats();
+	return stats.recent[0] ?? null;
+}
+
+const MODE_FLAGS = ["--meta", "--lazy", "--full", "--auto", "--parallel"] as const;
+
+/** Replay last activation, optionally overriding load-mode / parallel flags. */
+export function replayLastArgs(overrideArgs: string): string | null {
+	const last = getLastActivation();
+	if (!last?.rawArgs) return null;
+
+	let base = last.rawArgs;
+	for (const flag of MODE_FLAGS) {
+		base = base.replace(new RegExp(`\\s*${flag}\\b`, "g"), " ").trim();
+	}
+
+	const override = overrideArgs.trim();
+	if (!override) return base;
+
+	const extraFlags: string[] = [];
+	if (/\s--meta\b/.test(` ${override} `)) extraFlags.push("--meta");
+	else if (/\s--lazy\b/.test(` ${override} `)) extraFlags.push("--lazy");
+	else if (/\s--full\b/.test(` ${override} `)) extraFlags.push("--full");
+	if (/\s--auto\b/.test(` ${override} `)) extraFlags.push("--auto");
+	if (/\s--parallel\b/.test(` ${override} `)) extraFlags.push("--parallel");
+
+	return extraFlags.length > 0 ? `${base} ${extraFlags.join(" ")}` : base;
+}
+
+export function formatLastActivationHint(): string | null {
+	const last = getLastActivation();
+	if (!last) return null;
+	const label =
+		last.bundles.length > 0
+			? last.bundles.map((b) => `@${b}`).join(",")
+			: last.skillNames.slice(0, 4).join(",");
+	return `${label} · ${last.mode}${last.parallel ? " · parallel" : ""} · ${last.at.slice(0, 19)}`;
+}

package/src/subagents.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const SUBAGENT_TOOL = "subagent";
+const DEFAULT_PARALLEL_AGENT = "general-purpose";
+
+export function hasSubagentTool(pi: ExtensionAPI): boolean {
+	try {
+		return pi.getAllTools().some((tool) => tool.name === SUBAGENT_TOOL);
+	} catch {
+		return false;
+	}
+}
+
+export function buildParallelDispatchBlock(options: {
+	tasks: string[];
+	subagentAvailable: boolean;
+}): string {
+	const { tasks, subagentAvailable } = options;
+	if (tasks.length === 0) return "";
+
+	const lines: string[] = ["<parallel_dispatch>"];
+
+	if (subagentAvailable) {
+		lines.push(
+			"Use the `subagent` tool in PARALLEL mode for independent tasks below.",
+			"Call `{ action: \"list\" }` first if you need to pick agents.",
+		);
+		if (tasks.length === 1) {
+			lines.push("");
+			lines.push("Suggested invocation:");
+			lines.push("```json");
+			lines.push(
+				JSON.stringify(
+					{
+						tasks: [{ agent: DEFAULT_PARALLEL_AGENT, task: tasks[0] }],
+					},
+					null,
+					2,
+				),
+			);
+			lines.push("```");
+		} else {
+			lines.push("");
+			lines.push("Suggested invocation:");
+			lines.push("```json");
+			lines.push(
+				JSON.stringify(
+					{
+						tasks: tasks.map((task) => ({
+							agent: DEFAULT_PARALLEL_AGENT,
+							task,
+						})),
+					},
+					null,
+					2,
+				),
+			);
+			lines.push("```");
+		}
+	} else {
+		lines.push(
+			"pi-subagents is not installed — execute tasks sequentially in the current session.",
+			"Install: `pi install npm:pi-subagents` then `/reload`.",
+		);
+	}
+
+	lines.push("");
+	lines.push("Tasks:");
+	for (const [i, task] of tasks.entries()) {
+		lines.push(`${i + 1}. ${task}`);
+	}
+	lines.push("</parallel_dispatch>");
+
+	return lines.join("\n");
+}

package/src/suggestions.ts

@@ -0,0 +1,70 @@
+import type { SkillBundle, SkillInfo } from "./types.ts";
+import { assessBundleAvailability } from "./bundle-status.ts";
+
+const SUGGESTIONS: Array<{ pattern: RegExp; bundle: string; reason: string }> =
+	[
+		{
+			pattern: /fail(ing|ed)?\s+test|test\s+fail/i,
+			bundle: "debug",
+			reason: "failing tests detected",
+		},
+		{
+			pattern: /\bbug\b|\berror\b|\bcrash\b|\bexception\b/i,
+			bundle: "debug",
+			reason: "bug/error keywords detected",
+		},
+		{
+			pattern: /\bprd\b|product requirement|tech spec/i,
+			bundle: "bmad-planning",
+			reason: "planning keywords detected",
+		},
+		{
+			pattern: /\barchitect|\bapi design|\bdatabase schema/i,
+			bundle: "bmad-solutioning",
+			reason: "architecture keywords detected",
+		},
+		{
+			pattern: /\bimplement|\buser story|\bdev-story|\bfeature\b/i,
+			bundle: "bmad-build",
+			reason: "implementation keywords detected",
+		},
+		{
+			pattern: /\bnew feature|\bbuild\b|\bcreate\b.+\bcomponent/i,
+			bundle: "cc-feature",
+			reason: "feature development keywords detected",
+		},
+	];
+
+export function suggestSkillBundle(
+	text: string,
+	bundles?: Map<string, SkillBundle>,
+	availableSkills?: SkillInfo[],
+): {
+	bundle: string;
+	reason: string;
+} | null {
+	const sample = text.slice(0, 500);
+	for (const entry of SUGGESTIONS) {
+		if (!entry.pattern.test(sample)) continue;
+		if (bundles && availableSkills) {
+			const bundle = bundles.get(entry.bundle);
+			if (bundle) {
+				const status = assessBundleAvailability(
+					entry.bundle,
+					bundle,
+					availableSkills,
+				);
+				if (!status.ready) continue;
+			}
+		}
+		return { bundle: entry.bundle, reason: entry.reason };
+	}
+	return null;
+}
+
+export function formatSuggestionHint(
+	bundle: string,
+	reason: string,
+): string {
+	return `💡 Suggested: /skills @${bundle} (${reason})`;
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+export type LoadMode = "full" | "meta" | "lazy";
+
+export type SkillOrder = "process-first" | "explicit" | "alpha";
+
+export interface SkillBundle {
+	description: string;
+	skills: string[];
+	order?: SkillOrder;
+	default_mode?: LoadMode;
+	/** Human-readable dependency label shown in help/autocomplete. */
+	requires?: string;
+	/** One-line install instructions when bundle skills are missing. */
+	install?: string;
+}
+
+export interface SkillInfo {
+	name: string;
+	description: string;
+	filePath: string;
+	baseDir: string;
+}
+
+export interface SkillMetadata {
+	name: string;
+	description: string;
+	type: "process" | "rigid" | "flexible" | "unknown";
+	module: string;
+	priority: number;
+	commands: string[];
+	skillId: string;
+	version: string;
+	pairsWith: string[];
+	conflictsWith: string[];
+	tokenBudget?: LoadMode;
+}
+
+export interface EnrichedSkillInfo extends SkillInfo {
+	metadata: SkillMetadata;
+	rawContent: string;
+	body: string;
+}
+
+export interface ParsedSkillsArgs {
+	skillNames: string[];
+	mode: LoadMode;
+	auto: boolean;
+	parallel: boolean;
+	parallelTasks: string[];
+	embeddedCommand?: string;
+	instructions: string;
+}
+
+export interface BuildOptions {
+	mode: LoadMode;
+	bundles?: string[];
+	bmadStatusBlock?: string;
+	parallel: boolean;
+	parallelTasks?: string[];
+	subagentAvailable?: boolean;
+	embeddedCommand?: string;
+	instructions?: string;
+	skippedDuplicates?: string[];
+	conflictWarnings?: string[];
+}