@maxiaochao/pi-toolkit 0.12.1 → 0.12.2

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-20 - v0.12.2
+
+- herdr-subagents v0.7.1: clarify Persona responsibilities and dispatch guidance
+- Clarify Herdr Persona selection and instructions: broad independent reviewer, codebase explorer, file-changing worker, and neutral charter-driven agent-team analyst. Make the Agent Team skill explicitly select analyst when dispatching through Personas.
+
 ## 2026-10-19 - v0.12.1
 
 - herdr-subagents v0.7.0: add global and project default extension sources with Persona overrides

package/README.md

@@ -39,7 +39,7 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Personas can opt into local extension files or npm/git Pi packages through `extensions`. Set top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` (or project `.pi/herdr-subagents.json`) to share a fallback list; Persona-specific lists take precedence, and `[]` clears inherited sources. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
+Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Choose `reviewer` for independent reviews of proposals, designs, documents, implementations, or analysis; `explorer` for codebase investigation; `worker` for file-changing work; and `analyst` for charter-defined agent-team roles. See [built-in Personas](packages/herdr-subagents/README.md#built-in-personas) for selection guidance and the distinction between parent-facing descriptions and child instructions. Personas can opt into local extension files or npm/git Pi packages through `extensions`. Set top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` (or project `.pi/herdr-subagents.json`) to share a fallback list; Persona-specific lists take precedence, and `[]` clears inherited sources. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
 
 Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above is embedded, so a second install exposes the same resource twice.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-20 - v0.7.1
+
+- clarify Persona responsibilities and dispatch guidance
+- Clarify parent-facing Persona selection and child instructions: reviewer independently reviews proposals, designs, documents, implementations, and analysis; analyst is the neutral agent-team execution persona with task-defined roles; explorer investigates codebase structure, behavior, and dependencies. Preserve worker instructions and all tool/access boundaries.
+
 ## 2026-10-19 - v0.7.0
 
 - add global and project default extension sources with Persona overrides

package/packages/herdr-subagents/README.md

@@ -257,9 +257,13 @@ None of the bundled Personas pins a model, thinking level, skill, or optional ex
 | Persona | Access | Built-in tools | Intended use |
 | --- | --- | --- | --- |
 | `worker` | `write` | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `codemode` | One focused implementation or other file-changing task. |
-| `explorer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Fast codebase investigation without file changes. |
-| `analyst` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Neutral analysis where the task prompt supplies the role and evaluation method. |
-| `reviewer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Correctness and maintainability review with actionable evidence. |
+| `explorer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Codebase structure, behavior, and dependency investigation without file changes. |
+| `analyst` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Neutral agent-team execution where each task supplies the role charter and evaluation method. |
+| `reviewer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Independent review of proposals, designs, documents, implementations, and analysis against goals and constraints. |
+
+Choose `reviewer` for an independent assessment of existing work, `explorer` to investigate how the codebase works, `worker` for file-changing work, and `analyst` for agent-team members whose role is supplied by the task charter. An analyst may perform a review when its charter calls for one; its neutral execution role does not replace the reviewer selection for ordinary review requests.
+
+The control tool's `list` action exposes each effective `description` to help the parent choose a Persona. The Markdown body instead becomes the selected child's appended system prompt. Put selection guidance in `description` and execution instructions in the body; bundled definitions keep both in English.
 
 `access` is a scheduling declaration: any `write` Persona requires serial execution. It is not by itself a sandbox. For a custom read-only Persona, also omit write-capable tools and load only trusted extensions.
 

package/packages/herdr-subagents/TESTING.md

@@ -15,6 +15,8 @@ It verifies:
 - ordered results despite concurrent completion;
 - sibling continuation after failure and all-failed aggregation;
 - required explicit Personas in the tool schema and execution, including legacy single-task argument normalization;
+- model-facing role selection guidance for broad independent review, codebase investigation, file-changing work, and charter-driven agent-team execution;
+- effective Persona descriptions in parent listings, corresponding bodies in child system prompts, and unchanged read/write tool boundaries;
 - rejection of missing, blank, invalid, and unknown Personas before creating runs, while custom Personas remain supported;
 - explicit rejection of parallel write-capable tasks with the conflicting task, Persona, and corrective action;
 - waiting through a delayed authoritative report after a prompt transport error while the Pi process is alive;

package/packages/herdr-subagents/agents/analyst.md

@@ -1,8 +1,8 @@
 ---
 name: analyst
-description: Neutral read-only analyst for dynamically assigned roles
+description: Neutral read-only execution persona for agent-team, with roles defined by each task
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.
+Serve as a neutral execution persona for agent-team. Follow the role charter and evaluation method supplied in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful source references.

package/packages/herdr-subagents/agents/explorer.md

@@ -1,8 +1,8 @@
 ---
 name: explorer
-description: Read-only explorer for fast codebase investigation
+description: Read-only explorer for codebase structure, behavior, and dependencies
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Investigate the assigned question without modifying files. Report concrete evidence and useful paths.
+Investigate the assigned question without modifying files. Locate relevant files, trace behavior and dependencies, and report concrete evidence with useful paths. Distinguish confirmed behavior from unresolved questions.

package/packages/herdr-subagents/agents/reviewer.md

@@ -1,8 +1,8 @@
 ---
 name: reviewer
-description: Read-only reviewer for correctness and maintainability risks
+description: Independent read-only reviewer for proposals, designs, documents, implementations, and analysis
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Review the assigned work without modifying files. Report actionable findings with concrete evidence.
+Independently review the assigned work against its goals and constraints. Examine assumptions, logic, evidence, trade-offs, and risks. Identify gaps and provide actionable recommendations with concrete evidence. Do not modify project files.

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -148,7 +148,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 		name: "herdr_subagents",
 		...(exposure ? { exposure } : {}),
 		label: "Herdr Subagents",
-		description: "Run ordered tasks in visible Herdr Pi panes, with an explicit agent for each task. concurrency 1 is serial; higher values require read-only Personas. Returns after all tasks complete, fail, or cancel; full results and sessions remain in project-local records.",
+		description: "Run ordered tasks in visible Herdr Pi panes, with an explicit agent for each task. Choose reviewer for independent reviews, explorer for codebase investigation, worker for file changes, or analyst for agent-team tasks with a supplied role charter; use control list to inspect effective and custom Personas. concurrency 1 is serial; higher values require read-only Personas. Returns after all tasks complete, fail, or cancel; full results and sessions remain in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
 		parameters: HerdrSubagentsParams,
 		prepareArguments: normalizeHerdrSubagentsArguments,

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

package/packages/herdr-subagents/tests/core-state-machine.mjs

@@ -7,7 +7,7 @@ import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
 import { normalizeHerdrSubagentsArguments, registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
 import { applyTaskStatus } from "../src/records.ts";
-import { executeHerdrSubagents } from "../src/tool.ts";
+import { executeHerdrSubagents, executeHerdrSubagentsControl } from "../src/tool.ts";
 
 process.env.HERDR_ENV = "1";
 process.env.HERDR_WORKSPACE_ID = "test-workspace";
@@ -101,6 +101,32 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 		configurationPaths: { globalConfig: join(root, "global-config.json") },
 		herdr,
 	});
+	const listed = await executeHerdrSubagentsControl({ action: "list" }, undefined, undefined, { cwd: root }, {
+		agentsDirectory: fileURLToPath(new URL("../agents/", import.meta.url)),
+		configurationPaths: { globalConfig: join(root, "global-config.json") },
+	});
+	const personas = new Map(listed.details.agents.map((persona) => [persona.name, persona]));
+	const analyst = personas.get("analyst");
+	assert.match(analyst.description, /agent-team.*roles defined by each task/);
+	assert.match(analyst.systemPrompt, /role charter and evaluation method/);
+	const reviewer = personas.get("reviewer");
+	assert.match(reviewer.description, /proposals, designs, documents, implementations, and analysis/);
+	assert.match(reviewer.systemPrompt, /goals and constraints/);
+	assert.match(reviewer.systemPrompt, /assumptions, logic, evidence, trade-offs, and risks/);
+	const explorer = personas.get("explorer");
+	assert.match(explorer.description, /codebase structure, behavior, and dependencies/);
+	assert.match(explorer.systemPrompt, /Locate relevant files, trace behavior and dependencies/);
+	const readTools = ["read", "bash", "grep", "find", "ls", "codemode"];
+	for (const name of ["analyst", "reviewer", "explorer"]) {
+		const persona = personas.get(name);
+		assert.equal(persona.access, "read");
+		assert.deepEqual(persona.tools, readTools);
+		assert.ok(listed.content[0].text.includes(`${name}: ${persona.description}`), "The parent must see role selection guidance in Persona listings");
+		assert.ok(!listed.content[0].text.includes(persona.systemPrompt), "Persona listings must not embed the child instructions");
+	}
+	assert.equal(personas.get("worker").access, "write");
+	assert.equal(personas.get("worker").description, "General-purpose worker for one focused task");
+	assert.match(personas.get("worker").systemPrompt, /Do not delegate to another agent/);
 	const missing = { name: "review", prompt: "Read-only review" };
 	for (const params of [
 		{ tasks: [missing] },
@@ -125,6 +151,12 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	const parallel = await execute({ tasks: ["analyst", "reviewer", "explorer"].map((agent) => ({ ...missing, agent })), concurrency: 2 });
 	assert.equal(parallel.details.status, "completed");
 	assert.equal(parallel.details.effectiveConcurrency, 2);
+	for (const [index, name] of ["analyst", "reviewer", "explorer"].entries()) {
+		const directory = parallel.details.tasks[index].recordDirectory;
+		const instructions = readFileSync(join(directory, "system-prompt.md"), "utf8");
+		assert.ok(instructions.startsWith(personas.get(name).systemPrompt), "Each child must receive its selected Persona body");
+		assert.match(instructions, /call subagent_report exactly once/);
+	}
 
 	const projectAgents = join(root, ".pi", "herdr-subagents", "agents");
 	mkdirSync(projectAgents, { recursive: true });
@@ -231,6 +263,11 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	assert.deepEqual(herdrCalls, [], "Pi startup must not inspect or close historical Subagent tabs");
 	assert.deepEqual(JSON.parse(readFileSync(join(runDirectory, "run.json"), "utf8")), historicalRun, "Pi startup must not mutate historical Subagent records");
 	const taskSchema = registeredTools.get("herdr_subagents").parameters.properties.tasks.items;
+	const description = registeredTools.get("herdr_subagents").description;
+	assert.match(description, /reviewer for independent reviews/);
+	assert.match(description, /explorer for codebase investigation/);
+	assert.match(description, /worker for file changes/);
+	assert.match(description, /analyst for agent-team/);
 	assert.ok(taskSchema.required.includes("agent"), "The model-facing schema must require agent");
 	assert.equal(taskSchema.properties.agent.enum, undefined, "Custom Persona names must remain valid");
 	assert.equal(registeredTools.get("herdr_subagents")?.exposure, undefined, "Unconfigured Subagent execution must inherit Pi's exposure default");

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -598,7 +598,7 @@ try {
 	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
 	const packageDiscovery = discoverPackageAgents(join(process.cwd(), "agents"));
 	const analystPersona = packageDiscovery.agents.find((persona) => persona.name === "analyst");
-	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
+	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /neutral execution persona for agent-team/.test(analystPersona.systemPrompt) && /role charter and evaluation method/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
 
 	const configRoot = join(root, "configuration");
 	const packageAgents = join(configRoot, "package-agents");

package/skills/agent-team/SKILL.md

@@ -28,7 +28,7 @@ description: 多模型协作分析：主 Agent 按配置的模型和角色调度
 
 读取本 skill 同目录的 [models.json](models.json)：`members` 是成员与模型的唯一配置来源，`roles` 是角色职责的唯一配置来源。默认将两个数组按顺序一一对应；配置为空或数量不匹配时，报告配置问题后再启动。
 
-按配置成员数并发启动子代理，显式传入各自的 `model`，并将对应角色的 `charter` 放入任务。成员使用相同的中性只读执行约束。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认或与配置不符时，该成员结果无效并报告原因。
+按配置成员数并发启动子代理，显式传入各自的 `model`，并将对应角色的 `charter` 放入任务。使用 Persona 派发时，成员统一选择 `agent: "analyst"`，作为中立执行载体；具体职责由本轮 `charter` 注入。成员使用相同的中性只读执行约束。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认或与配置不符时，该成员结果无效并报告原因。
 
 每轮在 `rounds/N.md` 写明成员、模型、角色、输入文件和分派问题。默认沿用角色映射；需要交叉复核时可轮换，并记录新的映射。