@aprimediet/minion 1.0.0

package/index.ts

@@ -0,0 +1,146 @@
+/**
+ * @aprimediet/minion
+ *
+ * Claude-Code-style delegation for the pi coding agent:
+ *   - todo_write  (TodoWrite) + /todos
+ *   - subagent    (Task: single / parallel / chain, isolated pi subprocesses)
+ *   - a bundled library of 12 specialized agents, with per-agent model config
+ *
+ * Agents are bundled inside the extension and loaded directly (no install step).
+ * The default model map (minion.json) is copied into ~/.pi/agent/ on first run.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type ExtensionAPI, type ExtensionContext, CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { buildDelegationSystemPrompt, bundledAgentsDir, bundledModelsFile, setDefaultAgentModel } from "./agents.ts";
+import { ensureProject, resolveProject } from "./project.ts";
+import { registerSubagentTool } from "./subagent.ts";
+import { buildResumePrompt, getTask, listTasks, registerTaskTool, renderBoard } from "./tasks.ts";
+import { registerTodoTool } from "./todo.ts";
+
+function copyAgentFiles(srcDir: string, destDir: string): { copied: number; skipped: number } {
+	fs.mkdirSync(destDir, { recursive: true });
+	let copied = 0;
+	let skipped = 0;
+	for (const name of fs.readdirSync(srcDir)) {
+		if (!name.endsWith(".md")) continue;
+		const dest = path.join(destDir, name);
+		if (fs.existsSync(dest)) {
+			skipped++;
+			continue;
+		}
+		fs.copyFileSync(path.join(srcDir, name), dest);
+		copied++;
+	}
+	return { copied, skipped };
+}
+
+export default function minionExtension(pi: ExtensionAPI): void {
+	registerTodoTool(pi);
+	registerSubagentTool(pi);
+	registerTaskTool(pi);
+
+	pi.registerFlag("default-agent-model", {
+		description: "Fallback model for subagents with no configured/frontmatter model",
+		type: "string",
+	});
+
+	// Seed the per-agent model config into ~/.pi/agent/minion.json on first run (idempotent), and
+	// create the project workspace (~/.pi/projects/<id>/ + the cwd marker), keeping cwd clean.
+	pi.on("session_start", async (_e, ctx: ExtensionContext) => {
+		const flag = pi.getFlag("default-agent-model");
+		if (typeof flag === "string" && flag) setDefaultAgentModel(flag);
+
+		try {
+			const target = path.join(getAgentDir(), "minion.json");
+			if (!fs.existsSync(target)) {
+				const src = bundledModelsFile();
+				if (fs.existsSync(src)) {
+					fs.mkdirSync(path.dirname(target), { recursive: true });
+					fs.copyFileSync(src, target);
+				}
+			}
+		} catch {
+			/* non-fatal */
+		}
+
+		try {
+			await ensureProject(ctx.cwd);
+		} catch {
+			/* non-fatal */
+		}
+	});
+
+	// Make pi aware, every turn, that it can delegate and which subagents exist — by appending a
+	// "Subagent delegation" section (with the live agent list) to the system prompt. Rebuilt per
+	// turn from base options, so it stays in sync with bundled/user/project agent changes.
+	// Also surface unfinished board tasks each turn so the agent resumes them by delegating to the
+	// designated agent (subagent + taskId). This is the "check status → delegate" behavior.
+	pi.on("before_agent_start", async (event, ctx) => {
+		const parts = [buildDelegationSystemPrompt(ctx.cwd), buildResumePrompt(ctx.cwd)].filter(Boolean);
+		if (parts.length === 0) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n\n${parts.join("\n\n")}` };
+	});
+
+	// Optional convenience: export the bundled agents (and model config) for editing / native use.
+	pi.registerCommand("minion", {
+		description: "minion: 'install-agents [--project]' exports the bundled agents for editing",
+		handler: async (args, ctx: ExtensionContext) => {
+			const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			const sub = tokens[0];
+			if (sub !== "install-agents") {
+				if (ctx.hasUI) ctx.ui.notify("Usage: /minion install-agents [--project]", "info");
+				return;
+			}
+			const toProject = tokens.includes("--project");
+			const destAgents = toProject
+				? path.join(ctx.cwd, CONFIG_DIR_NAME, "agents")
+				: path.join(getAgentDir(), "agents");
+			if (ctx.hasUI) {
+				const ok = await ctx.ui.confirm(
+					"Export bundled agents?",
+					`Copy the 12 bundled agents to:\n${destAgents}\n(existing files are kept, not overwritten)`,
+				);
+				if (!ok) return;
+			}
+			try {
+				const { copied, skipped } = copyAgentFiles(bundledAgentsDir(), destAgents);
+				// Also drop the model config in the matching scope if absent.
+				const modelsTarget = toProject
+					? path.join(ctx.cwd, CONFIG_DIR_NAME, "minion.json")
+					: path.join(getAgentDir(), "minion.json");
+				if (!fs.existsSync(modelsTarget) && fs.existsSync(bundledModelsFile())) {
+					fs.mkdirSync(path.dirname(modelsTarget), { recursive: true });
+					fs.copyFileSync(bundledModelsFile(), modelsTarget);
+				}
+				if (ctx.hasUI) ctx.ui.notify(`Exported ${copied} agent(s), skipped ${skipped} existing → ${destAgents}`, "info");
+			} catch (err) {
+				if (ctx.hasUI) ctx.ui.notify(`Export failed: ${(err as Error).message}`, "error");
+			}
+		},
+	});
+
+	// View the persistent kanban board for this project.
+	pi.registerCommand("tasks", {
+		description: "tasks: show the project kanban board ('/tasks all' includes done/cancelled; '/tasks <id>' shows one)",
+		handler: async (args, ctx: ExtensionContext) => {
+			if (!ctx.hasUI) return;
+			const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			const project = resolveProject(ctx.cwd);
+			if (tokens[0] && tokens[0] !== "all") {
+				const t = getTask(project.tasksDir, tokens[0]);
+				ctx.ui.notify(
+					t
+						? `${t.id} [${t.status}]${t.agent ? ` @${t.agent}` : ""}\n${t.title}\n\nInstruction:\n${t.instruction || "(none)"}`
+						: `No task ${tokens[0]}.`,
+					t ? "info" : "error",
+				);
+				return;
+			}
+			const all = listTasks(project.tasksDir);
+			const shown = tokens[0] === "all" ? all : all.filter((t) => t.status !== "done" && t.status !== "cancelled");
+			ctx.ui.notify(`Board (${project.id}):\n${renderBoard(shown)}`, "info");
+		},
+	});
+}

package/minion.json

@@ -0,0 +1,17 @@
+{
+  "models": {
+    "*": "claude-sonnet-4-6",
+    "general-purpose": "claude-sonnet-4-6",
+    "explore": "claude-haiku-4-5",
+    "plan": "claude-sonnet-4-6",
+    "code-reviewer": "claude-opus-4-8",
+    "code-simplifier": "claude-sonnet-4-6",
+    "silent-failure-hunter": "claude-sonnet-4-6",
+    "type-design-analyzer": "claude-opus-4-8",
+    "comment-analyzer": "claude-haiku-4-5",
+    "pr-test-analyzer": "claude-sonnet-4-6",
+    "debugger": "claude-sonnet-4-6",
+    "test-writer": "claude-sonnet-4-6",
+    "docs-writer": "claude-haiku-4-5"
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aprimediet/minion",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "TodoWrite + subagent/Task + a bundled library of 12 specialized agents for the pi coding agent.",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aprimediet/pi-minion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aprimediet/pi-minion/issues"
+  },
+  "homepage": "https://github.com/aprimediet/pi-minion#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"const pkg=require('./package.json'); if(!pkg.files||pkg.files.length===0){console.error('files field empty — abort');process.exit(1)}; console.log('Publishing '+pkg.name+'@'+pkg.version+' with files:', pkg.files)\"",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "prompts": ["./prompts"]
+  },
+  "files": ["*.ts", "minion.json", "agents/**", "prompts/**", "README.md", "LICENSE"],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}

package/project.ts

@@ -0,0 +1,170 @@
+/**
+ * Project identity + path layout for minion's persistent delegation/task board.
+ *
+ * The working tree stays clean: the only artifact written into <cwd>/.pi is a single identifier
+ * file `<project-id>.md`. Tasks, todos and delegation records live globally under
+ * ~/.pi/projects/<project-id>/.
+ *
+ * IMPORTANT: this is intentionally COMPATIBLE with @aprimediet/memory's project.ts — same id
+ * algorithm (`<slug>-<sha1(root)[:8]>`), same marker format (`pi-project: true` + `id`), same
+ * detection. So both extensions share ONE cwd marker and ONE ~/.pi/projects/<id>/ workspace.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+export interface ProjectPaths {
+	id: string;
+	root: string;
+	configDir: string; // <root>/.pi
+	markerPath: string; // <root>/.pi/<id>.md
+	globalDir: string; // ~/.pi/projects/<id>
+	tasksDir: string; // <globalDir>/tasks
+	todosDir: string; // <globalDir>/todos
+	delegationsDir: string; // <globalDir>/delegations
+	projectJson: string; // <globalDir>/project.json
+}
+
+function piHome(): string {
+	return path.dirname(getAgentDir()); // getAgentDir() === ~/.pi/agent
+}
+export function projectsRoot(): string {
+	return path.join(piHome(), "projects");
+}
+
+function slug(name: string): string {
+	const s = name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 40);
+	return s || "project";
+}
+function pathHash(abs: string): string {
+	return crypto.createHash("sha1").update(abs).digest("hex").slice(0, 8);
+}
+
+function findProjectRoot(cwd: string): string {
+	let dir = cwd;
+	for (;;) {
+		if (fs.existsSync(path.join(dir, CONFIG_DIR_NAME)) || fs.existsSync(path.join(dir, ".git"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return cwd;
+		dir = parent;
+	}
+}
+
+function readMarker(configDir: string): { id: string; file: string } | null {
+	if (!fs.existsSync(configDir)) return null;
+	let names: string[];
+	try {
+		names = fs.readdirSync(configDir).filter((n) => n.endsWith(".md"));
+	} catch {
+		return null;
+	}
+	for (const name of names) {
+		const file = path.join(configDir, name);
+		try {
+			const { frontmatter } = parseFrontmatter<Record<string, string>>(fs.readFileSync(file, "utf-8"));
+			if (frontmatter && String(frontmatter["pi-project"]) === "true" && frontmatter.id) return { id: frontmatter.id, file };
+		} catch {
+			/* not a marker */
+		}
+	}
+	return null;
+}
+
+function pathsForId(id: string, root: string, configDir: string, markerPath: string): ProjectPaths {
+	const globalDir = path.join(projectsRoot(), id);
+	return {
+		id,
+		root,
+		configDir,
+		markerPath,
+		globalDir,
+		tasksDir: path.join(globalDir, "tasks"),
+		todosDir: path.join(globalDir, "todos"),
+		delegationsDir: path.join(globalDir, "delegations"),
+		projectJson: path.join(globalDir, "project.json"),
+	};
+}
+
+/** Resolve project identity for a cwd (read-only — creates nothing). */
+export function resolveProject(cwd: string): ProjectPaths {
+	const root = findProjectRoot(cwd);
+	const configDir = path.join(root, CONFIG_DIR_NAME);
+	const existing = readMarker(configDir);
+	const id = existing?.id ?? `${slug(path.basename(root))}-${pathHash(root)}`;
+	const markerPath = existing?.file ?? path.join(configDir, `${id}.md`);
+	return pathsForId(id, root, configDir, markerPath);
+}
+
+function markerBody(id: string, createdISO: string): string {
+	return [
+		"---",
+		"pi-project: true",
+		`id: ${id}`,
+		`created: ${createdISO}`,
+		"---",
+		"# pi project",
+		"",
+		"This file marks this directory as a pi project. To keep your working tree clean, pi",
+		"extensions store their per-project data globally — NOT here — under:",
+		"",
+		`    ~/.pi/projects/${id}/`,
+		"",
+		"minion stores here:",
+		"- `tasks/`       persistent kanban task cards (delegation board)",
+		"- `todos/`       in-session todo snapshots",
+		"- `delegations/` full records of every subagent delegation",
+		"",
+		"Managed by pi extensions (@aprimediet/minion, @aprimediet/memory). Safe to commit",
+		"(stable id) and safe to delete (recreated).",
+		"",
+	].join("\n");
+}
+
+/** Create the global directory structure + the cwd marker (idempotent). */
+export async function ensureProject(cwd: string): Promise<ProjectPaths> {
+	const p = resolveProject(cwd);
+	const nowISO = new Date().toISOString();
+
+	for (const dir of [p.tasksDir, p.todosDir, p.delegationsDir]) fs.mkdirSync(dir, { recursive: true });
+
+	if (!fs.existsSync(p.markerPath)) {
+		fs.mkdirSync(p.configDir, { recursive: true });
+		await withFileMutationQueue(p.markerPath, async () => {
+			const tmp = `${p.markerPath}.tmp`;
+			await fs.promises.writeFile(tmp, markerBody(p.id, nowISO), { encoding: "utf-8", mode: 0o644 });
+			await fs.promises.rename(tmp, p.markerPath);
+		});
+	}
+
+	// project.json — shared with the memory extension; preserve unknown keys, just update ours.
+	try {
+		let meta: Record<string, unknown> = {};
+		try {
+			meta = JSON.parse(fs.readFileSync(p.projectJson, "utf-8")) as Record<string, unknown>;
+		} catch {
+			/* first run */
+		}
+		meta.id = p.id;
+		meta.name = meta.name ?? path.basename(p.root);
+		const paths = Array.isArray(meta.paths) ? (meta.paths as string[]) : [];
+		if (!paths.includes(p.root)) paths.push(p.root);
+		meta.paths = paths;
+		meta.created = meta.created ?? nowISO;
+		meta.lastSeen = nowISO;
+		await withFileMutationQueue(p.projectJson, async () => {
+			const tmp = `${p.projectJson}.tmp`;
+			await fs.promises.writeFile(tmp, JSON.stringify(meta, null, 2), { encoding: "utf-8", mode: 0o600 });
+			await fs.promises.rename(tmp, p.projectJson);
+		});
+	} catch {
+		/* non-fatal */
+	}
+
+	return p;
+}

package/prompts/implement-and-review.md

@@ -0,0 +1,10 @@
+---
+description: general-purpose implements, code-reviewer reviews, general-purpose applies the feedback
+---
+Use the `subagent` tool with the `chain` parameter for: $@
+
+1. First, use the "general-purpose" agent to implement: $@
+2. Then, use the "code-reviewer" agent to review the implementation from the previous step (use the {previous} placeholder).
+3. Finally, use the "general-purpose" agent to apply the feedback from the review (use the {previous} placeholder).
+
+Execute this as a chain, passing output between steps via {previous}.

package/prompts/implement.md

@@ -0,0 +1,10 @@
+---
+description: Full implementation workflow — explore gathers context, plan designs, general-purpose implements
+---
+Use the `subagent` tool with the `chain` parameter to execute this workflow for: $@
+
+1. First, use the "explore" agent to find all code relevant to: $@
+2. Then, use the "plan" agent to create an implementation plan for "$@" using the context from the previous step (use the {previous} placeholder).
+3. Finally, use the "general-purpose" agent to implement the plan from the previous step (use the {previous} placeholder).
+
+Execute this as a single chain, passing output between steps via {previous}.

package/prompts/review.md

@@ -0,0 +1,11 @@
+---
+description: Multi-perspective review of the current changes (code-reviewer + silent-failure-hunter + type-design-analyzer)
+---
+Use the `subagent` tool with the `tasks` parameter to review the current changes in parallel, focusing on: $@
+
+Run these three agents concurrently, each on the current diff for "$@":
+- "code-reviewer" — bugs, style, guideline violations
+- "silent-failure-hunter" — swallowed errors / bad fallbacks
+- "type-design-analyzer" — type-design weaknesses
+
+Then synthesize their findings into one prioritized review (Critical → Warning → Suggestion), de-duplicating overlaps.

package/prompts/scout-and-plan.md

@@ -0,0 +1,9 @@
+---
+description: Explore gathers context, plan creates an implementation plan (no implementation)
+---
+Use the `subagent` tool with the `chain` parameter for: $@
+
+1. First, use the "explore" agent to find all code relevant to: $@
+2. Then, use the "plan" agent to create an implementation plan for "$@" using the context from the previous step (use the {previous} placeholder).
+
+Execute this as a chain, passing output between steps via {previous}. Do NOT implement — just return the plan.