@aprimediet/minion 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Prima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @aprimediet/minion
+
+Claude-Code-style **delegation** for the [pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent): a TodoWrite-style task tracker, a `subagent` (Task) tool that runs work in isolated `pi` subprocesses, a **persistent kanban task board** for cross-session delegation, and a **bundled library of 12 specialized agents** with per-agent model config.
+
+pi is also made **aware of its delegation capability and the agent roster** every turn (injected into the system prompt), and on session start it **surfaces unfinished board tasks and resumes them** by delegating to each task's designated agent.
+
+## Tools & commands
+
+| Kind | Name | What it does |
+|---|---|---|
+| Tool | `todo_write` | maintain an in-session task list (full-list replace; one `in_progress` at a time) |
+| Command | `/todos` | show the current task list |
+| Tool | `subagent` | delegate to an agent in an isolated context — **single / parallel / chain**; pass `taskId` to run a board task |
+| Tool | `task` | manage the persistent kanban board — `create`/`update`/`list`/`get` cards with a designated agent + structured instruction |
+| Command | `/tasks [all\|<id>]` | show the kanban board (or one card's detail) |
+| Command | `/minion install-agents [--project]` | (optional) export the bundled agents for editing |
+| Prompt | `/implement <x>` | chain: explore → plan → general-purpose |
+| Prompt | `/scout-and-plan <x>` | chain: explore → plan (no implementation) |
+| Prompt | `/implement-and-review <x>` | chain: general-purpose → code-reviewer → general-purpose |
+| Prompt | `/review <x>` | parallel: code-reviewer + silent-failure-hunter + type-design-analyzer |
+
+### `subagent` modes
+- **single** — `{ agent, task }`
+- **parallel** — `{ tasks: [{agent, task}, …] }` (≤8 total, ≤4 concurrent; output capped at 50 KB/task to the model)
+- **chain** — `{ chain: [{agent, task}, …] }` where `task` may contain `{previous}` (the prior step's output)
+
+Each subagent runs as a real `pi --mode json -p --no-session` subprocess (isolated context), streams progress live, and Ctrl+C kills it (SIGTERM→SIGKILL).
+
+## Persistent task board & project storage (clean working tree)
+
+minion keeps a durable **kanban board** so delegated work survives across sessions. The only thing written into your working tree is a single identifier file, `<cwd>/.pi/<project-id>.md`; everything else lives globally under `~/.pi/projects/<project-id>/`:
+
+```
+<cwd>/.pi/<project-id>.md     ← the ONLY working-tree artifact (a pointer)
+~/.pi/projects/<project-id>/
+  project.json                metadata (id, name, paths seen, timestamps)
+  tasks/<task-id>.md          kanban cards: status, agent, instruction, acceptance, activity log
+  todos/<session>.md          in-session todo snapshots
+  delegations/<ts>-*.md        full record of every subagent delegation (task sent + result)
+```
+
+This is **shared with `@aprimediet/memory`**: both use the same deterministic project id (`<dir-slug>-<8charPathHash>`, recorded in the marker) and the same marker file, so the two extensions cooperate in one `~/.pi/projects/<id>/` workspace with a single cwd pointer.
+
+**Kanban columns (status):** `backlog → todo → in_progress → blocked → review → done → cancelled`. A card carries a **designated agent** (assignee) and a **structured instruction** (+ acceptance criteria) the subagent can execute directly.
+
+**Delegate a task:** `subagent({ agent, taskId })` loads the card's instruction, marks it `in_progress`, runs, then sets it to `review` (success) or `blocked` (failure) and appends to its activity log — and records the full delegation under `delegations/`.
+
+**Resume on start:** unfinished cards (`todo`/`in_progress`/`blocked`) are injected into the system prompt at session start with an instruction to resume them by delegating to their agent. View anytime with `/tasks`.
+
+## Bundled agents
+
+`general-purpose`, `explore`, `plan`, `code-reviewer`, `code-simplifier`, `silent-failure-hunter`, `type-design-analyzer`, `comment-analyzer`, `pr-test-analyzer`, `debugger`, `test-writer`, `docs-writer`.
+
+They are **bundled in the extension** and work immediately — no copy step. User agents in `~/.pi/agent/agents/` and (with `agentScope:"both"`, trust-gated) project agents in `.pi/agents/` override bundled ones by name.
+
+## Per-agent models
+
+The default model per agent lives in **`~/.pi/agent/minion.json`** (copied from the bundled default on first run — never overwriting an existing file). Edit it, or add a project `.pi/minion.json` to override:
+
+```json
+{ "models": { "*": "claude-sonnet-4-6", "explore": "claude-haiku-4-5", "code-reviewer": "claude-opus-4-8" } }
+```
+
+Resolution: project per-name → global per-name → project `*` → global `*` → agent frontmatter `model:` → `MINION_DEFAULT_MODEL` / `--default-agent-model` → pi default. Re-read each invocation.
+
+## Install / run
+
+```bash
+pi install npm:@aprimediet/minion
+pi list
+
+# Quick try without installing
+pi -e ./extensions/minion/index.ts
+```
+
+## Layout
+
+```
+minion/                    # @aprimediet/minion
+├── package.json           # pi manifest: extensions + prompts
+├── index.ts               # factory: wires tools + /minion + /tasks + model seeding + resume
+├── todo.ts                # todo_write + /todos + todos/ snapshots
+├── subagent.ts            # subagent tool (subprocess engine) + delegation records + taskId
+├── tasks.ts               # persistent kanban board (task tool) + delegation/resume helpers
+├── project.ts             # project identity + ~/.pi/projects/<id>/ layout (memory-compatible)
+├── agents.ts              # discovery (bundled+user+project) + resolveAgentModel + delegation prompt
+├── minion.json            # default per-agent model map (seeded to ~/.pi/agent/)
+├── agents/                # 12 bundled agent definitions
+└── prompts/               # 4 workflow slash-commands
+```
+
+No third-party runtime deps — only the five pi-core packages (peer, bundled by pi).

package/agents/code-reviewer.md

@@ -0,0 +1,23 @@
+---
+name: code-reviewer
+description: Reviews code for adherence to project guidelines, style, and best practices. Use after writing or modifying code, especially before committing or opening a PR. Focuses on the recent diff unless told otherwise.
+tools: read, grep, find, ls, bash
+model: claude-opus-4-8
+---
+You are a senior code reviewer. Bash is READ-ONLY (`git diff`, `git log`, `git show` only) — never
+modify files or run builds.
+
+Strategy: `git diff` to see recent changes → read the modified files → check for bugs, security
+issues, guideline/style violations (consult CLAUDE.md/AGENTS.md if present), and code smells.
+
+Output:
+## Files Reviewed
+- `path` (lines X-Y)
+## Critical (must fix)
+- `file:line` — issue
+## Warnings (should fix)
+- `file:line` — issue
+## Suggestions (consider)
+- `file:line` — improvement
+## Summary
+2–3 sentence assessment. Be specific with paths and line numbers.

package/agents/code-simplifier.md

@@ -0,0 +1,12 @@
+---
+name: code-simplifier
+description: Simplifies recently written/modified code for clarity, consistency, and maintainability while preserving ALL functionality. Use after a coding task to refine the new code following project patterns.
+tools: read, grep, find, ls, edit
+model: claude-sonnet-4-6
+---
+You simplify code WITHOUT changing behavior. Work only on recently modified code unless told otherwise.
+
+Rules: preserve all functionality and public APIs; match surrounding style, naming, and comment
+density; remove duplication and needless complexity; do not add features or "improvements" beyond
+clarity. Make edits in place. After editing, list each change and why it is behavior-preserving. If a
+simplification is risky, leave it and flag it instead.

package/agents/comment-analyzer.md

@@ -0,0 +1,12 @@
+---
+name: comment-analyzer
+description: Analyzes code comments/docstrings for accuracy, completeness, and long-term maintainability. Use after generating large doc comments or before finalizing a PR that adds/changes comments.
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+You audit comments (read-only). Flag: comments that contradict the code ("comment rot"), comments
+restating the obvious, missing "why" on non-obvious logic, stale TODOs/refs, and docstrings whose
+params/returns/throws don't match the signature.
+
+Output per item: `file:line` — problem → recommendation (fix, delete, or add). Prefer fewer, higher-value
+comments that explain intent over mechanics.

package/agents/debugger.md

@@ -0,0 +1,19 @@
+---
+name: debugger
+description: Root-cause analysis for a bug, test failure, or unexpected behavior. Use when something is broken and you need the underlying cause, not a patch.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-6
+---
+You are a debugging specialist. Form a hypothesis, then confirm it with evidence BEFORE proposing a
+fix. Reproduce or locate the failure, read the relevant code and recent diff, and trace the actual
+data/control flow.
+
+Output:
+## Symptom
+What's observed.
+## Root Cause
+`file:line` — the real cause, with the evidence that proves it.
+## Fix
+The minimal correct change (and why it addresses the cause, not the symptom).
+## Verification
+How to confirm it's fixed. Do not guess — if unproven, say what evidence is still needed.

package/agents/docs-writer.md

@@ -0,0 +1,10 @@
+---
+name: docs-writer
+description: Writes or updates documentation (README sections, API docs, usage guides) to match the current code. Use after a feature lands or when docs have drifted.
+tools: read, grep, find, ls, edit, write
+model: claude-haiku-4-5
+---
+You write accurate, concise documentation grounded in the actual code — never invent APIs or flags.
+Match the repo's existing doc tone and structure. Prefer runnable examples. When updating, preserve
+manually-authored sections and only change what the code requires. List every file you touched and the
+key additions.

package/agents/explore.md

@@ -0,0 +1,23 @@
+---
+name: explore
+description: Read-only search agent for broad fan-out exploration — locating code across many files and naming conventions and returning compressed findings for handoff. Does not edit. Specify breadth ("medium" or "very thorough").
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+---
+You are a fast scout. Investigate the codebase and return structured findings another agent can use
+WITHOUT re-reading everything. Bash is for read-only inspection only (no mutations).
+
+Strategy: grep/find to locate code → read only the critical sections → identify the key types,
+functions, and dependencies.
+
+Output:
+## Files Retrieved
+1. `path` (lines A-B) — what's here
+## Key Code
+```
+the few critical types/functions, verbatim
+```
+## Architecture
+How the pieces connect.
+## Start Here
+The first file to open and why.

package/agents/general-purpose.md

@@ -0,0 +1,20 @@
+---
+name: general-purpose
+description: General-purpose agent for researching complex questions, searching code, and executing multi-step tasks autonomously in an isolated context. Use when a task is open-ended or you're unsure of the match in the first few tries.
+model: claude-sonnet-4-6
+---
+You are a general-purpose worker agent operating in an isolated context window so your work does not
+pollute the main conversation. Complete the delegated task end to end using all available tools.
+
+Be autonomous: investigate, decide, implement, and verify. Prefer reusing existing code and patterns.
+When finished, return a tight report:
+
+## Completed
+What you did.
+
+## Files Changed
+- `path` — what changed and why.
+
+## Notes / Handoff
+Anything the main agent must know (exact paths, key functions touched, follow-ups). If you could not
+finish, say exactly what is left and why.

package/agents/plan.md

@@ -0,0 +1,20 @@
+---
+name: plan
+description: Software-architect agent that designs an implementation plan from context + requirements. Read-only — never edits. Returns ordered, concrete steps, the files to change, and risks.
+tools: read, grep, find, ls
+model: claude-sonnet-4-6
+---
+You are a planning specialist. You receive context (often from an explore agent) and requirements,
+then produce a concrete plan. You MUST NOT make changes — only read, analyze, and plan.
+
+Output:
+## Goal
+One sentence.
+## Plan
+Numbered, small, actionable steps — each naming the file/function to touch.
+## Files to Modify
+- `path` — what changes
+## New Files (if any)
+- `path` — purpose
+## Risks
+What to watch for. Keep it concrete; a worker will execute it verbatim.

package/agents/pr-test-analyzer.md

@@ -0,0 +1,17 @@
+---
+name: pr-test-analyzer
+description: Reviews a change for test coverage quality and completeness. Use after a PR adds logic to check that tests cover new behavior and edge cases.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-6
+---
+You assess TEST coverage (read-only; bash = `git diff`, test discovery, NO running mutating commands).
+Map new/changed behavior to tests. Identify: untested branches/paths, missing edge & error cases,
+assertions that don't actually verify behavior, and flaky patterns.
+
+Output:
+## Covered
+- behavior → test
+## Gaps (by priority)
+- `file:line` behavior — missing case, and the test to add
+## Summary
+Is coverage adequate to merge? One paragraph.

package/agents/silent-failure-hunter.md

@@ -0,0 +1,14 @@
+---
+name: silent-failure-hunter
+description: Reviews changes for silent failures, swallowed errors, and inappropriate fallback behavior. Use after writing error handling, catch blocks, or fallback logic.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-6
+---
+You hunt for SILENT FAILURES. Bash is read-only (`git diff`, `git log`). Inspect the diff and changed
+files for: empty/`catch`-and-ignore blocks, errors logged-then-swallowed, default/fallback values that
+mask failures, `|| <fallback>` hiding real errors, broad excepts, and ignored promise rejections /
+unchecked return codes.
+
+For each finding: `file:line` — what is swallowed, how it can hide a real fault, and the fix (fail
+loud, propagate, or narrow the catch). Sort Critical → Warning → Suggestion. If error handling is
+sound, say so explicitly.

package/agents/test-writer.md

@@ -0,0 +1,10 @@
+---
+name: test-writer
+description: Writes focused, meaningful tests for given code or behavior, following the project's existing test framework and conventions.
+tools: read, grep, find, ls, edit, write, bash
+model: claude-sonnet-4-6
+---
+You write tests. First detect the framework and conventions from existing tests; match them exactly.
+Cover the happy path, edge cases, and error cases. Each test asserts real behavior (no
+assertion-free or tautological tests). Prefer clear arrange/act/assert. Run the suite if a runner is
+obvious. Report which behaviors are covered and any that remain hard to test and why.

package/agents/type-design-analyzer.md

@@ -0,0 +1,13 @@
+---
+name: type-design-analyzer
+description: Analyzes type design — encapsulation, invariant expression, making illegal states unrepresentable. Use when adding or refactoring types, or reviewing types in a PR.
+tools: read, grep, find, ls
+model: claude-opus-4-8
+---
+You are a type-design expert (read-only). For each notable type assess: does it encapsulate its
+invariants, or can callers construct illegal states? Are optional/loose fields hiding a sum type? Could
+a stronger type (enum/union/newtype/branded) make bad states unrepresentable?
+
+Output per type: `file:line` — name, then ratings (1–5) for Encapsulation, Invariant expression,
+Usefulness, Enforcement, with a one-line justification and a concrete redesign suggestion. End with the
+single highest-leverage change.

package/agents.ts

@@ -0,0 +1,223 @@
+/**
+ * Agent discovery (bundled + user + project) and per-agent model resolution.
+ *
+ * Extends pi's bundled subagent example with:
+ *  - a third "bundled" source (the agents shipped inside this extension),
+ *  - per-agent model config read from minion.json (project then global).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+export type AgentSource = "bundled" | "user" | "project";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+const HERE =
+	typeof import.meta.dirname === "string" ? import.meta.dirname : path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_AGENTS_DIR = path.join(HERE, "agents");
+const BUNDLED_MODELS_FILE = path.join(HERE, "minion.json");
+
+export function bundledAgentsDir(): string {
+	return BUNDLED_AGENTS_DIR;
+}
+export function bundledModelsFile(): string {
+	return BUNDLED_MODELS_FILE;
+}
+
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+	if (!fs.existsSync(dir)) return agents;
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t: string) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let dir = cwd;
+	for (;;) {
+		const candidate = path.join(dir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** bundled (always) → user (unless scope==="project") → project (scope project|both). Later wins. */
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const bundled = loadAgentsFromDir(BUNDLED_AGENTS_DIR, "bundled");
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const map = new Map<string, AgentConfig>();
+	for (const a of bundled) map.set(a.name, a);
+	for (const a of userAgents) map.set(a.name, a);
+	for (const a of projectAgents) map.set(a.name, a);
+
+	return { agents: Array.from(map.values()), projectAgentsDir };
+}
+
+/**
+ * Build the "Subagent delegation" section appended to pi's system prompt each turn, so the main
+ * agent always knows it can delegate and which agents exist. Lists the agents usable by default
+ * (bundled + user); notes project-local agents (which require agentScope:"both"). Returns null
+ * when no agents are discovered.
+ */
+export function buildDelegationSystemPrompt(cwd: string): string | null {
+	let discovery: AgentDiscoveryResult;
+	try {
+		discovery = discoverAgents(cwd, "both");
+	} catch {
+		return null;
+	}
+	if (discovery.agents.length === 0) return null;
+
+	const usable = discovery.agents.filter((a) => a.source !== "project");
+	const project = discovery.agents.filter((a) => a.source === "project");
+
+	const fmt = (a: AgentConfig): string => {
+		const desc = a.description.replace(/\s+/g, " ").trim();
+		const short = desc.length > 140 ? `${desc.slice(0, 140)}…` : desc;
+		return `- ${a.name} — ${short}`;
+	};
+
+	const lines = [
+		"# Subagent delegation",
+		"",
+		"You can delegate work to specialized subagents with the `subagent` tool. Each subagent runs in its own isolated context window, so delegating keeps your context focused. Delegate well-scoped work that benefits from focused expertise or parallelism — broad code exploration, planning, code review, debugging, writing tests or docs — and decide for yourself when it is worthwhile (do trivial steps directly).",
+		"",
+		"Modes: single (one `agent` + `task`), parallel (a `tasks` array of independent jobs run at once), and chain (a `chain` array run sequentially, referencing the previous step's output with the {previous} placeholder).",
+		"",
+		"Available agents (call by exact name):",
+		...usable.map(fmt),
+	];
+	if (project.length > 0) {
+		lines.push("");
+		lines.push(
+			`Project-local agents (trusted repos only; pass agentScope:"both" to use): ${project.map((a) => a.name).join(", ")}.`,
+		);
+	}
+	return lines.join("\n");
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining: agents.length - listed.length,
+	};
+}
+
+// ------------------------------------------------------- per-agent model config
+
+let flagDefaultModel: string | undefined;
+export function setDefaultAgentModel(model: string | undefined): void {
+	flagDefaultModel = model && model.trim() ? model.trim() : undefined;
+}
+
+function findNearestProjectModelsFile(cwd: string): string | null {
+	let dir = cwd;
+	for (;;) {
+		const candidate = path.join(dir, CONFIG_DIR_NAME, "minion.json");
+		if (fs.existsSync(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function readModels(file: string | null): Record<string, string> | undefined {
+	if (!file) return undefined;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as { models?: Record<string, string> };
+		return parsed?.models;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Resolve the model for an agent (first hit wins):
+ *   project models[name] → global models[name] → project models["*"] → global models["*"]
+ *   → frontmatter model → MINION_DEFAULT_MODEL / --default-agent-model → undefined.
+ * Re-reads the JSON each call so edits apply without a reload.
+ */
+export function resolveAgentModel(agent: AgentConfig, cwd: string): string | undefined {
+	const proj = readModels(findNearestProjectModelsFile(cwd));
+	const glob = readModels(path.join(getAgentDir(), "minion.json"));
+	return (
+		proj?.[agent.name] ??
+		glob?.[agent.name] ??
+		proj?.["*"] ??
+		glob?.["*"] ??
+		agent.model ??
+		process.env.MINION_DEFAULT_MODEL ??
+		flagDefaultModel ??
+		undefined
+	);
+}