@ferris1225/pi-subagents 4.1.23 → 4.2.0

package/agents/synthesizer.md

@@ -1,39 +0,0 @@
----
-name: synthesizer
-description: "Read-only merge of many long inputs (result artifacts, reports, docs) into one deduplicated, attributed brief; conflicts and gaps stay explicit."
-tools: read, grep, find, ls, bash
-# The shell slot follows the parent and parent-active plugin tools are appended;
-# listed non-shell Pi built-ins are the permission boundary.
-thinking: low
----
-
-You are a synthesizer agent: a read-only specialist that merges several long inputs into one integrated brief so the caller never has to read them all itself. You have NOT got the caller's conversation history; the task brief names your inputs — result artifact files from earlier sub-agent runs, reports, documents, diffs, or logs — and they are your complete source material.
-
-## Hard constraints
-
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Read inputs with your `read` tool, not a shell command — the shell you were given may be POSIX or PowerShell, and `read` is identical everywhere. Keep shell use to read-only inspection (`git log/show/diff/status`).
-- Stay within the named inputs. Short verification reads of files those inputs cite are allowed; broad codebase exploration is `explorer` work — if the inputs cannot answer the brief, report that as a gap instead of searching for more.
-- Preserve attribution: every merged claim keeps a pointer to its source (file/section, or `path:line` when the source cites code).
-- Conflicts between sources are findings. Report them side by side with both attributions; never average them away or silently pick a winner.
-
-## Workflow
-
-1. Read every named input fully before writing anything.
-2. Deduplicate: collapse restatements of the same fact into one entry with all sources attached.
-3. Reconcile: where sources disagree, check whether a cited file settles it with a short verification read; otherwise record the conflict.
-4. Rank what remains by relevance to the brief's question — the caller reads your brief instead of the inputs, so anything omitted is invisible to it.
-
-## Final response
-
-Return one integrated brief:
-
-```text
-## Brief
-- merged, deduplicated findings in priority order, each with source attribution
-## Conflicts
-- source A says X; source B says Y (omit this section when none)
-## Gaps
-- questions the inputs cannot answer (omit this section when none)
-```
-
-Do not repeat the task brief, quote long passages when a pointer suffices, or narrate which input you read when. Keep the final response comfortably below the 40-line delivery cap unless the requested synthesis genuinely requires more.

package/agents/worker.md

@@ -1,43 +0,0 @@
----
-name: worker
-description: Default route for any non-trivial, self-contained code change — implement, fix, refactor, or test, then verify and hand off.
-thinking: high
-# No `tools` field => inherits all tools (full capability).
----
-
-You are a worker agent with full capabilities in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-## Procedure
-
-1. **Context.** Read the brief fully. Read referenced files — and referenced images (screenshots, mockups) when the model supports vision — before editing. If critical context is missing, state what an `explorer` should retrieve rather than guessing.
-2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity rather than rearranges it, and decompose rather than push a file toward ~1000 lines. For a large task, note files, order, and risks before editing. No unrelated refactors or standalone docs work unless the brief asks.
-3. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize existing README/docs/examples/comments directly affected by your change; do not defer obvious drift.
-4. **Verify.** Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
-5. **Handoff.** Return only the concrete outcome. Do not repeat the task brief, plan, root-cause investigation, or tool chronology; report only unresolved blockers and checks that remain failed.
-
-## Boundaries
-
-- Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate and every release action — even when repository instructions normally automate release after green checks.
-- Children are leaf processes: you cannot dispatch sub-agents.
-- When your brief carries reviewer findings, apply their fix instructions: implement each when it is sound; when it is wrong, out of scope, or a sounder fix exists, ship your fix and push back in your report — cite the finding, refute the instruction's reasoning, and describe what you shipped instead. A deviation without reasoning will be re-opened.
-- Do not ask the caller to duplicate downstream roles, and never treat your own verification as the final gate.
-
-## Output format
-
-## Completed
-
-What was done, in a few lines.
-
-## Files Changed
-
-- `path/to/file.ts` — what changed.
-
-## Verification
-
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
-
-## Notes (only when material)
-
-Unresolved blockers, rejected requirements, or decisions the caller must know. For a reviewer handoff: exact paths changed and the key functions/types touched. Omit when nothing actionable.
-
-Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.

package/src/workflow.ts

@@ -1,215 +0,0 @@
-/**
- * Managed workflow policy and handoff formatting.
- *
- * Successful top-level worker/cleaner runs continue through one independent
- * code review gate. A failing managed gate continues into the reviewer fix
- * stage: the same retained reviewer session gets write access and applies its
- * own fix instructions, so nobody outside the gate has to guess what satisfies
- * it. Direct reviewer results never chain — a failing direct gate returns its
- * findings to the main agent, which owns that fix decision. Documentation
- * drift is an ordinary gate finding; dispatching a documenter stays the main
- * agent's call. Internal steps are launched by dispatch directly, so they
- * never re-enter this policy or wake the main agent mid-chain.
- */
-
-import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
-import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
-import { formatUsageCompact, sumUsage } from "./monitor.ts";
-
-export interface WorkflowAgentAvailability {
-	reviewer: boolean;
-	writer: boolean;
-}
-
-export function workflowAgentAvailability(
-	agents: readonly Pick<AgentConfig, "name" | "tools">[],
-): WorkflowAgentAvailability {
-	const names = new Set(agents.map((agent) => agent.name));
-	return {
-		reviewer: names.has("reviewer"),
-		writer: agents.some(isWriteCapableAgent),
-	};
-}
-
-export interface ManagedWorkflowPlan {
-	initialRelation: string;
-}
-
-/** Dispatch-time gate intensity for one worker/cleaner task. "gate" (default)
- * keeps the automatic post-writer reviewer; "none" skips it so a mechanical,
- * low-risk edit does not pay for a full adversarial review — the dispatching
- * model owns that proportionality call because it knows the task's risk. */
-export type ReviewMode = "gate" | "none";
-
-/** Fixed cap on reviewer fix → re-review rounds inside one managed workflow.
- * Re-reviews converge by construction (they verify fixes and fix regressions
- * instead of re-scanning the whole surface); the cap only stops pathological
- * burn and hands the still-failing gate back to the main agent. */
-export const MAX_REVIEW_FIX_ROUNDS = 2;
-
-/** Conservative pre-run check used to reserve one shared-repository lane
- * around a complete writer workflow or a reviewer that needs a stable diff. */
-export function canStartManagedWorkflow(
-	agent: Pick<AgentConfig, "name" | "tools">,
-	availability: WorkflowAgentAvailability,
-): boolean {
-	// Every shared write-capable role—including custom agents—owns the repository
-	// lane even when no downstream role is enabled. Otherwise its edits can race
-	// a managed writer's pending diff.
-	if (isWriteCapableAgent(agent)) return true;
-	if (agent.name === "reviewer") {
-		// Hold a stable diff snapshot against every discoverable writer even when
-		// this review is advisory: a gate over a moving diff is unsound.
-		return availability.writer;
-	}
-	return false;
-}
-
-/** Classify only healthy top-level writer results; everything else delivers
- * directly, including every reviewer result — a direct reviewer dispatch never
- * starts another child. A failing managed gate is expanded by the workflow
- * itself into the reviewer fix stage. A dispatch that opted out of the gate
- * (review: "none") delivers directly too.
- *
- * `changedWorkspace: false` also delivers directly. A gate reviews a pending
- * diff, so a run that produced none — a cleaner that found no safe cut, a worker
- * that concluded there was nothing to do, both explicitly valid outcomes — has
- * nothing to review, and spending a reviewer on an empty diff buys nothing.
- * Only a proven absence of changes skips: `undefined` keeps the gate. */
-export function getManagedWorkflowPlan(
-	result: SingleResult,
-	availability: WorkflowAgentAvailability,
-	review: ReviewMode = "gate",
-	changedWorkspace?: boolean,
-): ManagedWorkflowPlan | undefined {
-	if (review === "none") return undefined;
-	if (changedWorkspace === false) return undefined;
-	if (result.dispatchFailed || isFailedResult(result)) return undefined;
-	if (result.agent === "worker" || result.agent === "cleaner") {
-		if (!availability.reviewer) return undefined;
-		return {
-			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
-		};
-	}
-	return undefined;
-}
-
-/** Build the code gate that runs directly after a top-level writer. Reports
- * carry intent; the actual pending diff remains authoritative. */
-export function buildFinalReviewBrief(initialResult: SingleResult): string {
-	return [
-		`Fresh code gate for a managed ${initialResult.agent} workflow.`,
-		``,
-		`The top-level ${initialResult.agent}'s full report:`,
-		`---`,
-		getResultOutput(initialResult),
-		`---`,
-		``,
-		`Run \`git status\` and \`git diff\` and judge the actual pending code; the report is context, not proof.`,
-		`Scale the gate to the change: a small, contained diff gets a fast, focused review of its correctness,`,
-		`regressions, and blast radius — not a whole-surface audit or a redesign of surrounding code it merely touches.`,
-		`Remain read-only. Attach a concrete fix instruction to EVERY gate finding — including documentation drift —:`,
-		`what to change, where, and how to verify it. A failing gate continues into your own write-enabled fix stage,`,
-		`so make every instruction executable exactly as written.`,
-		`End with exactly one standalone machine verdict line:`,
-		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
-	].join("\n");
-}
-
-/** Build the follow-up brief for the reviewer fix stage: the same retained
- * reviewer session continues with its read-only boundary lifted and applies
- * its own fix instructions. The workflow continues with a converging re-review. */
-export function buildReviewerFixBrief(gateOutput: string): string {
-	return [
-		`Fix stage: your gate review returned REVIEW_FAIL. You now have full write access in this same session.`,
-		`Apply every one of your own fix instructions now — exactly the changes you specified, nothing broader.`,
-		`Then re-check the code your fixes touch, so the next scan does not open with your own regression, and run`,
-		`the narrowest decisive checks (type check, focused tests) to verify.`,
-		``,
-		`Your gate review:`,
-		`---`,
-		gateOutput,
-		`---`,
-		``,
-		`Report:`,
-		`## Fixed`,
-		`- each finding → the exact fix applied (path + what changed)`,
-		`## Verification`,
-		`- checks actually run and their results`,
-		`Do not emit another VERDICT; a converging gate re-reviews the diff after you.`,
-	].join("\n");
-}
-
-/** Fresh gate over the updated diff after a fix round. The re-review runs in a
- * brand-new context but with a converging contract: verify the recorded fixes
- * landed and hunt regressions the fixes introduced. It must not reopen new
- * structural or style findings — the initial gate owned those — or every fresh
- * scan would surface fresh nits forever and the loop would never end. */
-export function buildReReviewBrief(fixResult: SingleResult, round: number): string {
-	return [
-		`Re-review after fix round ${round}. This gate CONVERGES: it verifies fixes, it does not re-scan the whole surface.`,
-		``,
-		`The fix stage reported:`,
-		`---`,
-		getResultOutput(fixResult),
-		`---`,
-		``,
-		`Verify every recorded fix actually landed in the code, and hunt regressions the fixes introduced in the touched`,
-		`code and its direct blast radius (\`git status\` + \`git diff\`). Do NOT open new structural, style, or pre-existing`,
-		`findings — the initial gate owned those; a remaining earlier finding counts only if its fix failed to land.`,
-		`Remain read-only. Attach a concrete fix instruction to every finding you do report.`,
-		`End with exactly one standalone machine verdict line:`,
-		`VERDICT: REVIEW_PASS when nothing remains, otherwise VERDICT: REVIEW_FAIL.`,
-	].join("\n");
-}
-
-/**
- * One step of a managed workflow as delivered: the run id (the stable handle
- * for resume/stop), the result, and the human-readable role within the
- * workflow ("initial implementation", "final review"). runId is optional only
- * for synthetic steps that never spawned a child.
- */
-export interface ChainStep {
-	runId?: number;
-	result: SingleResult;
-	relation: string;
-}
-
-export interface ManagedWorkflowOutcome {
-	steps: ChainStep[];
-}
-
-function workflowResultStatus(result: SingleResult, relation?: string): string {
-	if (isFailedResult(result)) return "failed";
-	// The fix stage is reviewer-named writer work: judge it by outcome, not by
-	// the verdict contract its review stage was held to.
-	if (relation === "review fix") return "completed";
-	if (result.agent === "reviewer") {
-		const verdict = reviewVerdict(getResultOutput(result));
-		return verdict ? verdict.toUpperCase() : "NO_VERDICT";
-	}
-	return "completed";
-}
-
-function workflowStepLine(step: ChainStep): string {
-	const id = step.runId !== undefined ? `#${step.runId} ` : "";
-	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result, step.relation)}`;
-}
-
-function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): void {
-	const total = sumUsage(steps.map((step) => step.result.usage));
-	const usage = formatUsageCompact(total);
-	lines.push("", `Totals: ${steps.length} run${steps.length === 1 ? "" : "s"}${usage ? ` · ${usage}` : ""}`);
-}
-
-/** One clear final delivery for managed writer → gate workflows. */
-export function formatManagedWorkflowSummary(
-	steps: readonly ChainStep[],
-	terminalResult: SingleResult = steps[steps.length - 1]!.result,
-	terminalRelation: string = steps[steps.length - 1]!.relation,
-): string {
-	const route = steps.map((step) => step.result.agent).join(" → ");
-	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult, terminalRelation)}`, "", ...steps.map(workflowStepLine)];
-	appendWorkflowFooter(lines, steps);
-	return lines.join("\n");
-}