@juicesharp/rpiv-pi 0.12.4 → 0.12.6

package/README.md

@@ -94,6 +94,22 @@ On first Pi Agent session start, rpiv-pi automatically:
 
 Each skill produces an artifact consumed by the next. Run them in order, or jump in at any stage if you already have the input artifact.
 
+### Recipes
+
+Skills compose. Pick the entry point that matches your intent:
+
+- **Form context before a task** — `/skill:discover "[topic]"` → `/skill:research <questions artifact>`. Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt.
+- **Compare approaches before designing** — `/skill:explore "[problem]"` → `/skill:design <solutions artifact>`. Use when multiple valid solutions exist; the solutions artifact is a first-class input to `design` alongside a `research` artifact.
+- **Full feature build** — `/skill:discover` → `research` → `design` → `plan` → `implement` → `validate` → (`code-review` ↔ `commit`). The default pipeline; jump in at any stage if you already have the input artifact. Review and commit are interchangeable in order — review `staged`/`working` before committing, or commit first and review the resulting branch (empty scope, first-parent vs default).
+- **Investigate a bug** — `/skill:discover "why does X fail"` → `/skill:research <questions artifact>`. Fix from the research output without writing a plan when the change is small.
+- **Adjust mid-implementation** — `/skill:revise <plan artifact>` → resume `/skill:implement`. Use when new constraints land after the plan is drafted.
+- **Review before shipping** — `/skill:code-review` ↔ `/skill:commit`. Order is your call: review `staged`/`working` before committing to catch issues at the smallest blast radius, or commit first and review the resulting branch (empty scope defaults to feature-branch-vs-default-branch, first-parent). Produces a Quality/Security/Dependencies artifact under `thoughts/shared/reviews/` with claim-verifier-grounded findings and `status: approved | needs_changes`.
+- **Audit a specific scope** — `/skill:code-review <commit|staged|working|hash|A..B|branch>`. Targeted lenses over a commit, range, staged/working tree, or PR branch; advisor adjudication applies when configured (`/advisor`).
+- **Review-driven plan revision** — `/skill:code-review` → `/skill:revise <plan artifact>` → resume `/skill:implement`. When a mid-stream review surfaces structural findings that the existing plan can't absorb as spot fixes.
+- **Scaffold manual UI test specs** — `/skill:outline-test-cases` → `/skill:write-test-cases <feature>`. Outline first via Frontend-First Discovery to map project scope and avoid duplicate coverage, then generate flow-based manual test cases (with a regression suite) under `.rpiv/test-cases/<feature>/`.
+- **Hand off across sessions** — `/skill:create-handoff` → (new session) `/skill:resume-handoff <doc>`. Preserves context when stopping mid-task.
+- **Onboard a fresh repo** — `/skill:annotate-guidance` once, then use the rest of the pipeline normally. Use `annotate-inline` instead if the project follows the `CLAUDE.md` convention.
+
 ### Skills
 
 Invoke via `/skill:<name>` from inside a Pi Agent session.
@@ -157,18 +173,18 @@ Agents are dispatched automatically by skills via the `Agent` tool — you don't
 
 | Agent | Purpose |
 |---|---|
-| `claim-verifier` | Grounds reconciled code-review findings at cited `file:line`; tags Verified / Weakened / Falsified |
+| `claim-verifier` | Grounds each supplied code-review claim against repository state and tags it Verified / Weakened / Falsified |
 | `codebase-analyzer` | Analyzes implementation details for specific components |
-| `codebase-locator` | Locates files and components relevant to a task |
-| `codebase-pattern-finder` | Finds similar implementations and usage patterns |
-| `diff-auditor` | Row-only patch auditor; walks a patch against a caller-supplied surface-list and emits `file:line \| verbatim \| surface-id \| note` rows |
-| `integration-scanner` | Maps inbound references, outbound deps, and config wiring |
-| `peer-comparator` | Pairwise peer-invariant comparator; tags each peer invariant Mirrored / Missing / Diverged / Intentionally-absent |
-| `precedent-locator` | Finds similar past changes in git history |
-| `test-case-locator` | Finds existing test cases and reports coverage stats |
-| `thoughts-analyzer` | Deep-dive analysis on research topics |
+| `codebase-locator` | Locates files, directories, and components relevant to a feature or task |
+| `codebase-pattern-finder` | Finds similar implementations and usage examples with concrete code snippets |
+| `diff-auditor` | Walks a patch against a caller-supplied surface-list and emits `file:line \| verbatim \| surface-id \| note` rows |
+| `integration-scanner` | Maps inbound references, outbound dependencies, config registrations, and event subscriptions for a component |
+| `peer-comparator` | Compares a new file against a peer sibling and tags each invariant Mirrored / Missing / Diverged / Intentionally-absent |
+| `precedent-locator` | Finds similar past changes in git history — commits, blast radius, and follow-up fixes |
+| `test-case-locator` | Catalogs existing manual test cases under `.rpiv/test-cases/` and reports coverage stats |
+| `thoughts-analyzer` | Performs deep-dive analysis on a research topic in `thoughts/` |
 | `thoughts-locator` | Discovers relevant documents in the `thoughts/` directory |
-| `web-search-researcher` | Researches web-based information and documentation |
+| `web-search-researcher` | Researches modern web-only information via deep search and fetch |
 
 ## Architecture
 
@@ -194,6 +210,8 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 rpiv-pi owns nicobailon's pi-subagents registration (runs it through an in-process proxy so the inline tool card stays quiet and the Subagents overlay is the live view). `/rpiv-setup` strips `"npm:pi-subagents"` from your `~/.pi/agent/settings.json#packages[]` to prevent Pi from loading it twice. If you remove rpiv-pi, subagents will stop loading until you re-add that entry.
 
+The bundled built-in agents from `pi-subagents` (`scout`, `planner`, `oracle`, …) are hidden from both the `subagent` tool that the assistant dispatches to and the `/agents` manager overlay (and `ctrl+shift+a`). The overlay filter is best-effort — if a future `pi-subagents` release changes its manager UI, rpiv-pi will print one boot-time warning to stderr and the built-in rows will reappear in `/agents` until rpiv-pi ships an update. The assistant-side filter is unaffected by upstream changes. To re-enable a built-in agent yourself, edit `subagents.disableBuiltins` in `~/.pi/agent/settings.json` (set to `false` or delete the key) and restart Pi.
+
 To fully uninstall:
 
 1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`

package/agents/general-purpose.md

@@ -1,9 +1,8 @@
 ---
 name: general-purpose
 description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you."
-tools: read, grep, find, ls, bash
-systemPromptMode: replace
-inheritProjectContext: false
+systemPromptMode: append
+inheritProjectContext: true
 inheritSkills: false
 ---
 

package/extensions/subagent-widget/hide-builtin-manager-rows.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	__resetManagerRowFilterForTests,
+	INSTALLED_SENTINEL,
+	installManagerRowFilter,
+	LOAD_ENTRIES_SOURCE_FRAGMENT,
+	type SkipReason,
+} from "./hide-builtin-manager-rows.js";
+
+interface AgentEntry {
+	name: string;
+}
+interface AgentDataFixture {
+	builtin: AgentEntry[];
+	user: AgentEntry[];
+	project: AgentEntry[];
+}
+interface ManagerLike {
+	agentData: AgentDataFixture;
+	_walkedBuiltin: string[];
+}
+
+// Synthetic constructor whose `loadEntries` mirrors the load-bearing shape
+// of upstream agent-manager.ts:120-124 — references `this.agentData.builtin`
+// (drift anchor) and walks it, recording names into a side-channel so tests
+// can assert what would have been rendered.
+function makeFixtureCtor(): new () => ManagerLike {
+	function FixtureCtor(this: ManagerLike) {
+		this.agentData = { builtin: [], user: [], project: [] };
+		this._walkedBuiltin = [];
+	}
+	FixtureCtor.prototype.loadEntries = function (this: ManagerLike) {
+		this._walkedBuiltin = [];
+		// Keep the literal substring so the drift guard accepts this fixture.
+		for (const config of this.agentData.builtin) {
+			this._walkedBuiltin.push(config.name);
+		}
+	};
+	return FixtureCtor as unknown as new () => ManagerLike;
+}
+
+describe("installManagerRowFilter", () => {
+	it("filters PI_SUBAGENTS_BUILTINS rows from the walked list", () => {
+		const Ctor = makeFixtureCtor();
+		const result = installManagerRowFilter(Ctor);
+		expect(result).toBe("installed");
+
+		const instance = new Ctor();
+		instance.agentData = {
+			builtin: [{ name: "scout" }, { name: "planner" }, { name: "general-purpose" }, { name: "codebase-locator" }],
+			user: [],
+			project: [],
+		};
+		instance._walkedBuiltin = [];
+		instance.constructor.prototype.loadEntries.call(instance);
+
+		expect(instance._walkedBuiltin).toEqual(["general-purpose", "codebase-locator"]);
+		__resetManagerRowFilterForTests();
+	});
+
+	it("filters on every invocation (covers refreshAgentData re-call)", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+
+		instance.agentData = { builtin: [{ name: "scout" }, { name: "thoughts-locator" }], user: [], project: [] };
+		instance.constructor.prototype.loadEntries.call(instance);
+		expect(instance._walkedBuiltin).toEqual(["thoughts-locator"]);
+
+		instance.agentData = { builtin: [{ name: "oracle" }, { name: "diff-auditor" }], user: [], project: [] };
+		instance.constructor.prototype.loadEntries.call(instance);
+		expect(instance._walkedBuiltin).toEqual(["diff-auditor"]);
+
+		__resetManagerRowFilterForTests();
+	});
+
+	it("restores the unfiltered agentData reference after loadEntries returns", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+		const unfiltered = {
+			builtin: [{ name: "scout" }, { name: "general-purpose" }],
+			user: [],
+			project: [],
+		};
+		instance.agentData = unfiltered;
+		instance.constructor.prototype.loadEntries.call(instance);
+
+		expect(instance.agentData).toBe(unfiltered);
+		expect(instance.agentData.builtin.map((c) => c.name)).toEqual(["scout", "general-purpose"]);
+		__resetManagerRowFilterForTests();
+	});
+
+	it("is idempotent — second install returns 'skipped' with reason 'already-installed'", () => {
+		const Ctor = makeFixtureCtor();
+		const first = installManagerRowFilter(Ctor);
+		const patched = (Ctor.prototype as { loadEntries: () => void }).loadEntries;
+
+		const onSkip = vi.fn<(reason: SkipReason) => void>();
+		const second = installManagerRowFilter(Ctor, { onSkip });
+		expect(first).toBe("installed");
+		expect(second).toBe("skipped");
+		expect(onSkip).toHaveBeenCalledWith("already-installed");
+		expect((Ctor.prototype as { loadEntries: () => void }).loadEntries).toBe(patched);
+		expect((Ctor as { [INSTALLED_SENTINEL]?: boolean })[INSTALLED_SENTINEL]).toBe(true);
+
+		__resetManagerRowFilterForTests();
+	});
+
+	it.each<[string, unknown, SkipReason]>([
+		["missing constructor (undefined)", undefined, "missing-constructor"],
+		["missing constructor (null)", null, "missing-constructor"],
+		["missing prototype", { prototype: undefined }, "missing-prototype"],
+		["missing loadEntries", { prototype: {} }, "missing-loadentries"],
+		["loadEntries lacks drift anchor", { prototype: { loadEntries: () => 1 } }, "drift-detected"],
+	])("fails soft on %s — onSkip(%s) and never throws", (_label, ctor, expectedReason) => {
+		const onSkip = vi.fn<(reason: SkipReason) => void>();
+		expect(() => installManagerRowFilter(ctor, { onSkip })).not.toThrow();
+		expect(onSkip).toHaveBeenCalledExactlyOnceWith(expectedReason);
+	});
+
+	it("survives invocation when agentData.builtin is missing", () => {
+		const Ctor = makeFixtureCtor();
+		installManagerRowFilter(Ctor);
+		const instance = new Ctor();
+		instance.agentData = { builtin: undefined as unknown as AgentEntry[], user: [], project: [] };
+		expect(() => instance.constructor.prototype.loadEntries.call(instance)).not.toThrow();
+		__resetManagerRowFilterForTests();
+	});
+});
+
+describe("real pi-subagents AgentManagerComponent contract", () => {
+	// Canary: this is the only test that touches the live upstream module.
+	// Failing here means upstream pi-subagents drifted between our pin and
+	// our release — bump the dep, update LOAD_ENTRIES_SOURCE_FRAGMENT (or
+	// retire the patch), and re-snapshot. At user runtime the patch fails
+	// soft via onSkip; this test exists so we catch drift before shipping.
+	it("loadEntries body still contains the load-bearing drift anchor", async () => {
+		// Dynamic import: matches the runtime guarded import in renderer-override.ts
+		// and avoids tsc resolving into the upstream .ts source via the path stub.
+		const mod = (await import("pi-subagents/agent-manager")) as {
+			AgentManagerComponent?: { prototype?: { loadEntries?: () => void } };
+		};
+		const proto = mod.AgentManagerComponent?.prototype;
+		const fn = proto?.loadEntries;
+		expect(typeof fn).toBe("function");
+		expect(fn?.toString()).toContain(LOAD_ENTRIES_SOURCE_FRAGMENT);
+	});
+});

package/extensions/subagent-widget/hide-builtin-manager-rows.ts

@@ -0,0 +1,129 @@
+// Hides the upstream pi-subagents built-in agent rows from the `/agents`
+// manager overlay (and ctrl+shift+a). Companion to hide-builtin-subagents.ts,
+// which hides the same names from the LLM-facing `subagent` tool surface.
+//
+// Strategy: monkey-patch `AgentManagerComponent.prototype.loadEntries` — the
+// single chokepoint that converts agentData → rendered AgentEntry rows. The
+// constructor calls it, refreshAgentData() calls it after every in-overlay
+// mutation, so one patch covers both code paths.
+//
+// Fail-soft contract: never throw at user runtime. Drift, missing class, or
+// missing method routes through the caller-supplied `onSkip` so Pi can
+// surface a single warning notify and continue booting. The /agents overlay
+// silently regains the upstream rows; the LLM-facing filter (Proxy in
+// renderer-override.ts) is unaffected because it lives on a different layer.
+
+import { PI_SUBAGENTS_BUILTINS } from "./hide-builtin-subagents.js";
+
+const BUILTIN_NAMES_SET = new Set<string>(PI_SUBAGENTS_BUILTINS);
+
+// Drift anchor: the load-bearing substring inside upstream
+// agent-manager.ts:120-124 loadEntries. If upstream rewrites the method to
+// stop reading agentData.builtin (rename, inline into ctor, route through a
+// helper), this fragment disappears and we skip with reason "drift-detected"
+// before mutating the prototype.
+export const LOAD_ENTRIES_SOURCE_FRAGMENT = "this.agentData.builtin";
+
+export const INSTALLED_SENTINEL = Symbol.for("rpiv-pi.manager-row-filter-installed");
+
+export type InstallResult = "installed" | "skipped";
+
+export type SkipReason =
+	| "missing-constructor"
+	| "missing-prototype"
+	| "missing-loadentries"
+	| "drift-detected"
+	| "already-installed";
+
+export interface InstallOptions {
+	onSkip?: (reason: SkipReason) => void;
+}
+
+interface AgentDataLike {
+	builtin?: Array<{ name?: unknown }>;
+}
+
+interface ManagerInstanceLike {
+	agentData?: AgentDataLike;
+}
+
+interface ManagerCtorLike {
+	prototype?: { loadEntries?: (this: ManagerInstanceLike) => void };
+	[INSTALLED_SENTINEL]?: boolean;
+}
+
+interface PatchRecord {
+	ctor: ManagerCtorLike;
+	original: (this: ManagerInstanceLike) => void;
+}
+
+let installedPatch: PatchRecord | undefined;
+
+function isFilteredBuiltin(entry: { name?: unknown }): boolean {
+	return typeof entry.name === "string" && BUILTIN_NAMES_SET.has(entry.name);
+}
+
+export function installManagerRowFilter(managerCtor: unknown, options: InstallOptions = {}): InstallResult {
+	const onSkip = options.onSkip ?? (() => {});
+	const ctor = managerCtor as ManagerCtorLike | undefined | null;
+
+	if (!ctor) {
+		onSkip("missing-constructor");
+		return "skipped";
+	}
+	if (ctor[INSTALLED_SENTINEL] === true) {
+		onSkip("already-installed");
+		return "skipped";
+	}
+	const proto = ctor.prototype;
+	if (!proto) {
+		onSkip("missing-prototype");
+		return "skipped";
+	}
+	const original = proto.loadEntries;
+	if (typeof original !== "function") {
+		onSkip("missing-loadentries");
+		return "skipped";
+	}
+	let source: string;
+	try {
+		source = original.toString();
+	} catch {
+		onSkip("drift-detected");
+		return "skipped";
+	}
+	if (!source.includes(LOAD_ENTRIES_SOURCE_FRAGMENT)) {
+		onSkip("drift-detected");
+		return "skipped";
+	}
+
+	proto.loadEntries = function patchedLoadEntries(this: ManagerInstanceLike): void {
+		// Defensive clone: never mutate the agentData reference we received.
+		// Other manager screens (override-scope, edit) read agentData directly
+		// and may rely on the unfiltered shape.
+		const original = this.agentData;
+		const builtin = Array.isArray(original?.builtin) ? original.builtin : [];
+		const filteredBuiltin = builtin.filter((c) => !isFilteredBuiltin(c ?? {}));
+		const filteredAgentData = { ...(original ?? {}), builtin: filteredBuiltin };
+		this.agentData = filteredAgentData as AgentDataLike;
+		try {
+			(installedPatch?.original ?? (() => {})).call(this);
+		} finally {
+			// Restore the unfiltered view for downstream reads outside loadEntries.
+			this.agentData = original;
+		}
+	};
+	ctor[INSTALLED_SENTINEL] = true;
+	installedPatch = { ctor, original };
+	return "installed";
+}
+
+// Test-only: undo the prototype mutation so each test sees a fresh slate.
+// Wired into test/setup.ts beforeEach. No-op when nothing is installed.
+export function __resetManagerRowFilterForTests(): void {
+	if (!installedPatch) return;
+	const { ctor, original } = installedPatch;
+	if (ctor.prototype) ctor.prototype.loadEntries = original;
+	delete ctor[INSTALLED_SENTINEL];
+	installedPatch = undefined;
+}

package/extensions/subagent-widget/pi-subagents-stubs/agent-manager.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compile-time stub for `pi-subagents/agent-manager` — see `./index.d.ts`
+ * for the stub rationale.
+ *
+ * Surface kept opaque on purpose: we touch exactly one thing on this
+ * class — `prototype.loadEntries` — via a runtime prototype patch in
+ * hide-builtin-manager-rows.ts. Typing the full upstream class (30+
+ * private fields, a dozen managed screens) would force us to mirror
+ * internal state we never read.
+ */
+
+export declare class AgentManagerComponent {
+	private readonly __piSubagentsAgentManagerComponent: true;
+}

package/extensions/subagent-widget/renderer-override.test.ts

@@ -63,6 +63,19 @@ Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", tas
 	});
 vi.mock("pi-subagents", () => ({ default: registerSubagentExtensionMock }));
 vi.mock("pi-subagents/render", () => ({ renderSubagentResult: vi.fn() }));
+// Stub AgentManagerComponent for the manager-row-filter install. Body
+// includes "this.agentData.builtin" to satisfy the drift anchor — the
+// install path is exercised end-to-end without touching the real upstream
+// class. Per-test prototype reset is wired in test/setup.ts.
+vi.mock("pi-subagents/agent-manager", () => {
+	class AgentManagerComponent {
+		agentData: { builtin: Array<{ name: string }> } = { builtin: [] };
+		loadEntries() {
+			void this.agentData.builtin;
+		}
+	}
+	return { AgentManagerComponent };
+});
 
 import { registerSubagentsWithQuietRenderer } from "./renderer-override.js";
 

package/extensions/subagent-widget/renderer-override.ts

@@ -6,6 +6,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import registerSubagentExtension from "pi-subagents";
 import { buildAgentEnumDescription } from "./agent-catalog.js";
+import { installManagerRowFilter, type SkipReason } from "./hide-builtin-manager-rows.js";
 import {
 	filterDisabledFromListResult,
 	getCuratedSubagentDescription,
@@ -87,6 +88,33 @@ function interceptRegisterTool(pi: ExtensionAPI): ExtensionAPI {
 	});
 }
 
+// Fail-soft install: the /agents overlay row-filter is best-effort UI polish
+// tied to pi-subagents@0.17.5 internals (AgentManagerComponent.prototype.
+// loadEntries). On any drift — module moved, class renamed, method body
+// changed — we log one stderr line and continue. The LLM-side filter
+// (interceptRegisterTool above) lives entirely on our boundary and is
+// unaffected. See hide-builtin-manager-rows.ts for skip-reason semantics.
+async function tryInstallManagerRowFilter(): Promise<void> {
+	let mod: { AgentManagerComponent?: unknown };
+	try {
+		mod = (await import("pi-subagents/agent-manager")) as { AgentManagerComponent?: unknown };
+	} catch {
+		process.stderr.write(
+			"[rpiv-pi] /agents overlay built-in filter disabled: pi-subagents/agent-manager not found.\n",
+		);
+		return;
+	}
+	installManagerRowFilter(mod.AgentManagerComponent, {
+		onSkip: (reason: SkipReason) => {
+			if (reason === "already-installed") return;
+			process.stderr.write(
+				`[rpiv-pi] /agents overlay built-in filter disabled (${reason}); built-in agents will be visible until rpiv-pi updates.\n`,
+			);
+		},
+	});
+}
+
 export async function registerSubagentsWithQuietRenderer(pi: ExtensionAPI): Promise<void> {
+	await tryInstallManagerRowFilter();
 	await registerSubagentExtension(interceptRegisterTool(pi));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": [
     "pi-package",

package/skills/annotate-guidance/SKILL.md

@@ -22,7 +22,7 @@ Use the current working directory as the target project by default. If the user
    - This ensures you have full context before decomposing the work
 
 2. **Pass 1 — Map the project (parallel agents):**
-   - Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   - Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    **Agent A — Project tree mapping:**
    - agent: `codebase-locator`
@@ -75,7 +75,7 @@ Use the current working directory as the target project by default. If the user
    - Adjust the target list based on user feedback
 
 4. **Pass 2 — Analyze each layer (parallel analyzer agents):**
-   - For each confirmed target folder, dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   - For each confirmed target folder, dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    **For each target folder, spawn TWO agents:**
 
@@ -286,7 +286,7 @@ See the following for well-formed subfolder architecture.md examples:
 - Folder is a simple grouping without unique constraints
 
 ## Important notes:
-- Parallel subagent dispatch — one `subagent(...)` call per agent in a SINGLE tool-use batch (same response), never sequentially. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
+- Parallel subagent dispatch — every `subagent(...)` call in the same assistant message (multiple tool_use blocks in one response), never one per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
 - **File reading**: Always read mentioned files FULLY (no limit/offset) before invoking skills
 - **Critical ordering**: Follow the numbered steps exactly
   - ALWAYS read mentioned files first before invoking skills (step 1)

package/skills/annotate-inline/SKILL.md

@@ -22,7 +22,7 @@ Use the current working directory as the target project by default. If the user
    - This ensures you have full context before decomposing the work
 
 2. **Pass 1 — Map the project (parallel agents):**
-   - Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   - Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    **Agent A — Project tree mapping:**
    - agent: `codebase-locator`
@@ -73,7 +73,7 @@ Use the current working directory as the target project by default. If the user
    - Adjust the target list based on user feedback
 
 4. **Pass 2 — Analyze each layer (parallel analyzer agents):**
-   - For each confirmed target folder, dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   - For each confirmed target folder, dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    **For each target folder, spawn TWO agents:**
 
@@ -282,7 +282,7 @@ See the following for well-formed subfolder CLAUDE.md examples:
 - Folder is a simple grouping without unique constraints
 
 ## Important notes:
-- Parallel subagent dispatch — one `subagent(...)` call per agent in a SINGLE tool-use batch (same response), never sequentially. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
+- Parallel subagent dispatch — every `subagent(...)` call in the same assistant message (multiple tool_use blocks in one response), never one per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
 - **File reading**: Always read mentioned files FULLY (no limit/offset) before invoking skills
 - **Critical ordering**: Follow the numbered steps exactly
   - ALWAYS read mentioned files first before invoking skills (step 1)

package/skills/code-review/SKILL.md

@@ -69,7 +69,7 @@ Every Wave-2 agent prompt contains EXACTLY: (a) `Known Context:` followed by the
 
 ## Step 2: Dispatch Wave-1 — Integration + Precedents + Deps/CVE + Peer-Mirror
 
-Dispatch ALL agents below at T=0 in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })` (isolated conversation per agent). Do NOT wait for integration-scanner before dispatching precedents / dependencies / CVE — they do not consume Discovery-Map output, only `ChangedFiles` and the manifest diff (both orchestrator-produced in Step 1). Wait for all to return before proceeding.
+Dispatch ALL agents below at T=0 as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })` (isolated conversation per agent). Do NOT wait for integration-scanner before dispatching precedents / dependencies / CVE — they do not consume Discovery-Map output, only `ChangedFiles` and the manifest diff (both orchestrator-produced in Step 1). Wait for all to return before proceeding.
 
 **Agent — Integration map:**
 - agent: `integration-scanner`
@@ -152,7 +152,7 @@ Peer mirrors: [peer-mirror agent output verbatim — Missing/Diverged rows only;
 
 ## Step 3: Dispatch Wave-2 — Quality + Security Lenses
 
-Dispatch Quality + Security in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })` (isolated conversation per agent). Each receives the `## Discovery Map` block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
+Dispatch Quality + Security as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })` (isolated conversation per agent). Each receives the `## Discovery Map` block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
 
 **Wave-2 context isolation (LOAD-BEARING — violations cause silent quality collapse)**: Each Wave-2 agent receives EXACTLY two things, nothing else: (1) the Discovery Map (digested form) and (2) the literal path string `.git/code-review-patch.diff`.
 

package/skills/design/SKILL.md

@@ -52,7 +52,7 @@ When this command is invoked:
 
 This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
 
-1. **Dispatch all agents below in a SINGLE tool-use batch** — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+1. **Dispatch all agents below as parallel `subagent` tool calls in the same assistant message** — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    - Use **codebase-pattern-finder** to find existing implementations to model after — the primary template for code shape
    - Use **codebase-analyzer** to understand HOW integration points work in detail
@@ -387,7 +387,7 @@ The artifact was created as a skeleton in Step 6 and filled progressively in Ste
 | Novel work (new library/pattern) | + web-search-researcher |
 | During code writing (if needed) | targeted codebase-analyzer for specific files |
 
-When agents are searching for different things, dispatch them in a SINGLE tool-use batch — one `subagent(...)` call per agent in the SAME response (parallel tool calls, not sequential turns). Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Each agent runs in isolation — provide complete context in the prompt, including specific directory paths when the feature targets a known module. Don't write detailed prompts about HOW to search — just tell it what you're looking for and where.
+When agents are searching for different things, dispatch them as parallel `subagent(...)` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Each agent runs in isolation — provide complete context in the prompt, including specific directory paths when the feature targets a known module. Don't write detailed prompts about HOW to search — just tell it what you're looking for and where.
 
 ## Important Notes
 

package/skills/discover/SKILL.md

@@ -55,7 +55,7 @@ Before Step 1, create a todo list tracking every step below (Step 1 through Step
 
    This plan stays internal — do NOT present it to the developer unless asked.
 
-3. **Dispatch all discovery agents in a SINGLE tool-use batch** — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+3. **Dispatch all discovery agents as parallel `subagent` tool calls in the same assistant message** — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    - Use **codebase-locator** for "Where do these files/symbols live?" slices — spawn one per focused code/discovery seam. Prefer 5-9 narrow discovery agents over 2-3 broad ones when the topic spans multiple subsystems.
    - Use **thoughts-locator** only for historical docs, decisions, plans, and prior artifacts about the topic

package/skills/explore/SKILL.md

@@ -322,7 +322,7 @@ Wait for ALL agents to complete before proceeding.
 
 ## Important Notes
 
-- Parallel subagent dispatch — one `subagent(...)` call per agent in a SINGLE tool-use batch (same response), never sequentially. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
+- Parallel subagent dispatch — every `subagent(...)` call in the same assistant message (multiple tool_use blocks in one response), never one per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
 - Always spawn fresh research to validate current state - never rely on old research docs as source of truth
 - Old research documents can provide historical context but must be validated against current code
 - Generate 2-4 named candidates in Step 2; confirm them with the developer at Step 3 before per-candidate fit dispatch

package/skills/outline-test-cases/SKILL.md

@@ -51,7 +51,7 @@ Report detected mode:
 
 First, detect the project's technology stack by checking for framework indicators (see Framework Detection Reference below).
 
-Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 - Use the **codebase-locator** agent to find all registered routes, navigation menus, and page entry points
 - Use the **codebase-locator** agent to find all frontend HTTP API call sites — report each call-site `file:line` and the literal URL template string found at the call site (e.g., ``${base}/users/${id}``). Frontend-to-backend URL correlation happens orchestrator-side in Step 3's Cross-Reference synthesis (`skills/outline-test-cases/SKILL.md:71-79`) using the backend-controller findings from the next agent.
 - Use the **codebase-locator** agent to find all backend API controllers and route handlers

package/skills/research/SKILL.md

@@ -47,7 +47,7 @@ You are tasked with answering structured research questions by spawning targeted
 
 ## Step 2: Dispatch Analysis Agents
 
-Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
 **Default agent**: `codebase-analyzer` for all codebase questions. This agent has Read, Grep, Glob, LS — it can trace code paths, find patterns, and analyze integration points.
 

package/skills/resume-handoff/SKILL.md

@@ -45,7 +45,7 @@ Then wait for the user's input.
      - Other notes
 
 2. **Spawn focused research agents**:
-   After reading all critical handoff/plan/research documents directly, dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   After reading all critical handoff/plan/research documents directly, dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
    ```
    Task 1 - Gather artifact context:

package/skills/revise/SKILL.md

@@ -78,7 +78,7 @@ When this command is invoked:
 
 If the user's feedback requires understanding new code patterns or validating assumptions:
 
-1. **Dispatch all agents below in a SINGLE tool-use batch** — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+1. **Dispatch all agents below as parallel `subagent` tool calls in the same assistant message** — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
    **For code investigation:**
    - Use the **codebase-locator** agent to find relevant files
    - Use the **codebase-analyzer** agent to understand implementation details
@@ -217,7 +217,7 @@ When updating success criteria, always maintain the two-category structure:
 When spawning research agents:
 
 1. **Only spawn if truly needed** - don't research for simple changes
-2. **Parallel dispatch** — one `subagent(...)` call per agent in a SINGLE tool-use batch (same response), never sequentially. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
+2. **Parallel dispatch** — every `subagent(...)` call in the same assistant message (multiple tool_use blocks in one response), never one per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`.
 3. **Each agent should be focused** on a specific area
 4. **Provide detailed instructions** including:
    - Exactly what to search for

package/skills/validate/SKILL.md

@@ -49,7 +49,7 @@ If starting fresh or need more context:
 
 3. **Spawn parallel research agents** to verify implementation:
 
-   Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+   Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
    - **general-purpose** agent — Verify implementation details match plan specifications (analyzer role)
    - **general-purpose** agent — Verify implementation follows established codebase patterns (pattern-finder role)
 

package/skills/write-test-cases/SKILL.md

@@ -70,7 +70,7 @@ When no _meta.md, detect the project's technology stack before spawning agents:
 
 ### Step 2: Discover Feature Code (parallel agents)
 
-Dispatch all agents below in a SINGLE tool-use batch — one call per agent in the SAME response (parallel tool calls, not sequential turns). Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+Dispatch all agents below as parallel `subagent` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
 
 **Agent A — Web Layer Discovery:**
 - agent: `codebase-locator`