pi-workflow-engine 1.1.0 → 1.3.0

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -1,5 +1,5 @@
 import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
@@ -9,6 +9,7 @@ import {
   formatEvidence,
   formatLocation,
   runLensVerificationPipeline,
+  verifierCandidates,
   EMPTY_LENS_REVIEW_STATS,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
@@ -23,6 +24,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "code-review",
   description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
+  whenToUse: "Use to review a PR, branch diff, ref range, or focused target for correctness bugs and cleanups, with every finding independently verified; args are the target or review instructions, blank auto-detects the diff.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
@@ -34,6 +36,16 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
+// With review instructions, scope splits them by stage: finders get only where to look, because a reporting bar in a
+// finder prompt makes finders filter their own candidates before any verifier sees them; the bar goes to synthesis.
+const InstructedScopeSchema = Type.Object({
+  ...ScopeSchema.properties,
+  conventions: Type.Optional(Type.String({ description: "Repository conventions from AGENTS.md and project docs only. Do not restate the user's review instructions, filtering rules or already-reported findings here." })),
+  focus: Type.String({ description: "Where the user wants reviewers to look: areas, files, risks and lenses named in the instructions. Exclude any filtering, evidence, reporting or deduplication rules; write (none) if the instructions name no focus." }),
+  reportingBar: Type.String({ description: "The user's filtering, evidence, severity and reporting rules restated so a reader without file access can apply them, listing every already-reported issue to exclude (read any files the instructions reference). Write (none) if the instructions set no bar." }),
+});
+type Scope = Static<typeof ScopeSchema> & Partial<Pick<Static<typeof InstructedScopeSchema>, "focus" | "reportingBar">>;
+
 // The review lenses — this is the part you customise to your codebase's real failure modes.
 const ANGLES: AdvisoryLens[] = [
   { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
@@ -53,7 +65,7 @@ export function buildCodeReviewScopeBlock(input: {
   readonly summary: string;
   readonly conventions?: string;
   readonly diffText: string;
-  readonly target: string;
+  readonly instructions?: { readonly heading: string; readonly text: string };
 }): string {
   const diffBlock = input.diffText
     ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
@@ -66,7 +78,7 @@ export function buildCodeReviewScopeBlock(input: {
     `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
     diffBlock +
-    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
+    (input.instructions?.text ? `\n## ${input.instructions.heading}\n${input.instructions.text}\n` : "")
   );
 }
 
@@ -81,7 +93,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
 
   // ─── Phase 0: Scope ───
   phase("Scope");
-  const scope = await agent(
+  const scopePrompt =
     "Establish the scope of a code review.\n" +
       (target
         ? `Target / instructions (verbatim): "${target}". If it names a PR number, branch, ref range, or files, build the matching diff command (use 'gh pr diff <number>' for a PR). Otherwise use the default selection below.\n`
@@ -97,9 +109,14 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "4. Run the chosen command to confirm the diff is non-empty.\n\n" +
       "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
       "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
-      "Return diffCommand exactly as a reviewer should run it. Structured output only.",
-    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
-  );
+      "Return diffCommand exactly as a reviewer should run it. Structured output only.";
+  const scopeOptions = { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium" } as const;
+  const scope: Scope = target
+    ? await agent(
+        `${scopePrompt}\nKeep the user's instructions out of conventions. Return focus (where to look) and reportingBar (the self-contained filtering and reporting bar, with every already-reported issue spelled out) as separate fields.`,
+        { ...scopeOptions, schema: InstructedScopeSchema },
+      )
+    : await agent(scopePrompt, { ...scopeOptions, schema: ScopeSchema });
 
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
   const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
@@ -147,19 +164,27 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       : {}),
   };
 
-  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
-    diffCommand,
-    files: scope.files,
-    summary: scope.summary,
-    conventions: scope.conventions,
-    diffText,
-    target,
-  });
+  const blockFor = (instructions?: { heading: string; text: string }) =>
+    `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
+      diffCommand,
+      files: scope.files,
+      summary: scope.summary,
+      conventions: scope.conventions,
+      diffText,
+      ...(instructions ? { instructions } : {}),
+    });
+  const scopeBlock = blockFor({ heading: "User instructions (verbatim)", text: target });
+  const focus = stated(scope.focus);
+  const reportingBar = stated(scope.reportingBar);
+  const finderBlock = blockFor(focus ? { heading: "Review focus (from the user's instructions)", text: focus } : undefined);
+  if (focus) log(`review focus: ${focus}`);
 
   const pipelineResult = await runLensVerificationPipeline({
     api,
     lenses: ANGLES,
     perLens: PER_ANGLE,
+    // Finders on `small` (thinking low by default) returned nothing on real PRs; they are the stage that must dig.
+    finderProfile: "medium",
     boundCandidate: (candidate, lens) => {
       const reviewAnchor = candidate.reviewAnchor
         ? diffAnchor(changed, candidate.reviewAnchor)
@@ -167,18 +192,18 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       return reviewAnchor ? { ...candidate, category: lens.category, reviewAnchor } : undefined;
     },
     finderPrompt: (lens) =>
-      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `## Code-review finder — ${lens.label}\n\n${finderBlock}\n` +
       `Review the change through ONLY this lens:\n${lens.text}\n` +
       "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
       "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
       `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
       "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
       "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\n` +
-      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
-      "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
+    verifierPrompt: (candidates) =>
+      `## Code-review verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}`) + "\n\n" +
+      "Run the diff command, read the relevant file(s), and return exactly one verdict per candidate (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
       "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
   });
   const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
@@ -193,11 +218,23 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     synthesisPrompt: (block, ranked) =>
       `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
-      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
+      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only." +
+      // Only a stated bar filters: a focus alone must not drop verified findings outside it.
+      (reportingBar
+        ? `\n\n## Reporting bar (the user's rules with referenced context resolved)\n${reportingBar}` +
+          `\n\n## User instructions (verbatim)\n${target}\n\n` +
+          "Apply the reporting bar when choosing which IDs to report: leave out findings it excludes, and say in the summary what you left out and why."
+        : ""),
   });
   return { ...report, reviewContext };
 }
 
+/** A scope field's text, or undefined when the scope agent left it blank or wrote (none). */
+function stated(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text && text !== "(none)" ? text : undefined;
+}
+
 function rank(finding: AdvisoryVerified): number {
   return (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
 }

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -8,6 +8,7 @@ import {
   formatLocation,
   formatRankedFinding,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -16,6 +17,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "diagnose",
   description: "Advisory-only bug diagnosis: scope symptoms → competing hypotheses → independent verify → synthesize likely root causes.",
+  whenToUse: "Use when a bug, failing command, flaky test, or regression has an unclear cause and competing hypotheses should be checked independently before anyone edits code; args describe the symptom.",
   phases: [{ title: "Scope" }, { title: "Hypothesize" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
@@ -76,10 +78,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
       `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
       "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Diagnose verifier\n\n${scopeBlock}\n## Hypothesis\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Diagnose verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Hypothesis", many: "Hypotheses" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read relevant files and, when useful, run only safe read-only diagnostic commands from the scoped command list or commands explicitly requested by the user. " +
       "Do not run mutation, install, commit, network, or destructive commands. Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence. " +
       "Use NOT_SUBSTANTIATED when evidence is missing; REFUTED requires disproof. Structured output only.",

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -9,6 +9,7 @@ import {
   EMPTY_LENS_REVIEW_STATS,
   formatLocation,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -17,6 +18,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "perf-review",
   description: "Advisory-only performance review: scope slow path → per-lens bottleneck hypotheses → verify evidence → synthesize measurements and safe optimizations.",
+  whenToUse: "Use for a slow path, startup cost, or performance concern where measured bottlenecks and safe optimizations matter more than guesses; args name the path, workload, or command.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
@@ -84,10 +86,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
       "Each candidate must include a one-line summary, locations, impact stating the suspected performance consequence and workload where it matters, " +
       "and an optional recommendation. Prefer measurement recommendations when evidence is weak. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Perf-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Perf-review verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommendation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read relevant files and package/scripts. Run only safe read-only measurement or inspection commands when useful. " +
       "Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence from code, scripts, config, or measurement output. " +
       "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -10,6 +10,7 @@ import {
   formatLocation,
   formatRankedFinding,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -18,6 +19,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "refactor-scout",
   description: "Advisory-only refactor scout: scope → per-lens find → independent verify → synthesize safe refactor opportunities.",
+  whenToUse: "Use to find small, behaviour-preserving refactors (duplication, complexity, type safety, boundaries, dead code) in a path or module without changing it; args name the target.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
@@ -82,10 +84,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
       "Each candidate must include a one-line summary, locations, impact on maintainability or future correctness, and an optional safe first recommendation. " +
       "Only include opportunities where a small, reviewable first step is plausible. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Refactor-scout verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommendation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read the relevant files and return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED. " +
       "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
       "Evidence must quote or cite code. Structured output only.",

package/.pi/extensions/pi-workflow-engine/workflows/research.ts

@@ -1,5 +1,6 @@
 import {
   MAX_RESEARCH_LANES,
+  MAX_VERIFICATION_CLAIMS,
   ResearchLaneResultSchema,
   ResearchPlanSchema,
   ResearchReportSchema,
@@ -23,6 +24,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "research",
   description: "Source-grounded external research: decompose → gather direct-page evidence → independently verify claims → cited synthesis.",
+  whenToUse: "Use for questions that need current external sources and cited, independently verified claims; needs an installed web search or browsing tool; args are the question and any scope constraints.",
   phases: [{ title: "Plan" }, { title: "Gather" }, { title: "Verify" }, { title: "Synthesize" }],
 };
 
@@ -105,10 +107,11 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   const gathered = gatherResults.flatMap((result) => (result.ok ? [result.value] : []));
   const failedLanes = lanes.filter((_, index) => !gatherResults[index]!.ok);
 
-  const candidates = buildClaimCandidates(gathered);
+  const { candidates, overCap } = buildClaimCandidates(gathered);
   if (candidates.length === 0) return unavailableResearchReport(failedLanes.length > 0 ? "lanes-failed" : "no-evidence");
   progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
   log(`${candidates.length} bounded claim(s) selected for independent verification`);
+  if (overCap > 0) log(`Dropped ${overCap} lower-priority claim(s) over the verification cap of ${MAX_VERIFICATION_CLAIMS}`);
 
   phase("Verify");
   const verificationResults = await parallel(
@@ -162,9 +165,14 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   }
 
   const report = sanitizeResearchReport(synthesis, synthesisInputs);
-  if (failedLanes.length === 0) return report;
-  const laneGap = `${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`;
-  return { ...report, limitations: [...report.limitations, laneGap] };
+  const gaps: string[] = [];
+  if (failedLanes.length > 0) {
+    gaps.push(`${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`);
+  }
+  if (overCap > 0) {
+    gaps.push(`${overCap} lower-priority claim(s) were not independently verified; verification is capped at ${MAX_VERIFICATION_CLAIMS} claims.`);
+  }
+  return gaps.length === 0 ? report : { ...report, limitations: [...report.limitations, ...gaps] };
 }
 
 function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {

package/README.md

@@ -72,15 +72,21 @@ dynamax investigate this flaky test using separate timing, fixture, diff, and ex
 dynamax argue both implementation options, then have another agent challenge the recommendation
 ```
 
-The token enables Dynamax for one turn. Sticky mode remains active for the pi
-session:
+The token enables Dynamax for that one request. Sticky mode instead makes
+workflow orchestration the default for every substantive task in the pi session;
+`/workflow:dynamax` with no argument toggles it:
 
 ```text
+/workflow:dynamax
 /workflow:dynamax on
 /workflow:dynamax off
 /workflow:dynamax status
 ```
 
+`/workflow:size small|medium|large|off` sets how many agents pi aims to keep
+each authored workflow under (5, 10 by default, or 25); see the
+[size guideline](USAGE.md#workflow-size-guideline).
+
 In the TUI, a standalone `dynamax` token receives a short moving-shine sweep and
 then stays highlighted. Use `PI_DYNAMAX_EFFECT=static` or
 `PI_DYNAMAX_EFFECT=off` to reduce or disable the cue; the
@@ -108,7 +114,9 @@ covers review actions and recent run history.
 ## Create your own workflows
 
 Saved workflows are TypeScript modules for repeatable orchestration; inline
-workflows are useful for one-off Dynamax tasks. The
+workflows are useful for one-off Dynamax tasks. An inline script that proves
+useful can be saved as a `.js` file in a project's `.pi/workflows/` or in
+`~/.pi/agent/workflows/` and run by name. The
 [workflow authoring guide](USAGE.md#author-a-saved-workflow) covers the API,
 typed handoffs, model profiles, tool access, composition, and registration.