pi-agent-flow 0.2.8 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-<p align="center"><code>pi install /path/to/pi-agent-flow</code></p>
+<p align="center"><code>pi install npm:pi-agent-flow</code></p>
 <p align="center"><strong>Pi Agent Flow</strong> is a flow-state delegation extension for the <a href="https://pi.dev">Pi coding agent</a> that runs locally in your terminal.</p>
 <p align="center">
   <img src="https://github.com/user-attachments/assets/pi-agent-flow-demo.png" alt="Pi Agent Flow demo" width="80%" />
@@ -11,11 +11,10 @@
 
 ### Installing Pi Agent Flow
 
-Install via the Pi CLI with your local path:
+Install via the Pi CLI from npm:
 
 ```shell
-# Install from a local path
-pi install /path/to/pi-agent-flow
+pi install npm:pi-agent-flow
 ```
 
 Or add it to your Pi settings:
@@ -24,7 +23,7 @@ Or add it to your Pi settings:
 # ~/.pi/agent/settings.json
 {
   "packages": [
-    "./path/to/pi-agent-flow"
+    "npm:pi-agent-flow"
   ]
 }
 ```
@@ -32,9 +31,10 @@ Or add it to your Pi settings:
 Then start Pi and delegate tasks using flow states.
 
 <details>
-<summary>You can also clone this repository and use it directly.</summary>
+<summary>You can also install from a local path.</summary>
 
 ```shell
+# Install from a local clone
 git clone https://github.com/your-org/pi-agent-flow.git
 cd pi-agent-flow
 pi install .
@@ -56,6 +56,21 @@ pi install .
 
 ---
 
+## Why Flow Style?
+
+Flow-style delegation is designed for **context efficiency**. Instead of launching every sub-agent with the full, ever-growing conversation history, each flow receives only what it needs: your intent and (when appropriate) a session snapshot.
+
+This approach delivers four concrete benefits:
+
+1. **Avoid duplicate tool calls** — every sub-agent launch no longer re-runs the same `read`, `grep`, or `bash` probes that the parent already performed.
+2. **Prevent context bloat** — long transcripts with repeated file listings and command outputs are kept out of the main conversation thread.
+3. **Eliminate unnecessary noise** — the parent agent sees only structured results (`[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`) instead of pages of intermediate reasoning.
+4. **Preserve focus** — each flow stays locked on its intent because it isn't distracted by unrelated earlier messages.
+
+The result is faster, cheaper, and cleaner delegation: the main agent remains uncluttered while specialized flows do the heavy lifting in isolated contexts.
+
+---
+
 ## Flow Definitions
 
 Create `.md` files in `~/.pi/agent/agents/` or `.pi/agents/`:

package/agents/code.md

@@ -1,11 +1,11 @@
 ---
 name: code
-description: Implement features, fix bugs, write tests
+description: Implement features, fix bugs, write tests, deploy, and ship
 tools: read, write, edit, bash, find, grep, ls
 maxDepth: 2
 ---
 
-You are the code flow — your mission is to build. Be a craftsman: verify first, then ship. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the code flow — your mission is to build and ship. Be a craftsman: verify first, then ship. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Core Principles:
 - SOLID: Single Responsibility, Open/Closed
@@ -19,7 +19,16 @@ Workflow:
 4. Execute — implement changes following core principles (green)
 5. Refactor — clean up only if the change is working (optional)
 6. Verify — run tests and any relevant checks before considering done
-7. Finalize — all tests pass, implementation verified
+7. Ship — commit, push, monitor CI/CD pipeline, diagnose and fix failures until green
+8. Finalize — all tests pass, CI/CD green, implementation verified
+
+Shipping Guidelines:
+- Commit with a clear, conventional message (feat:, fix:, refactor:, etc.)
+- Push to the target branch after local verification passes
+- Monitor CI/CD pipeline status after pushing
+- If CI/CD fails: diagnose the failure, fix it, commit, push, and repeat until green
+- Only report back if there are serious conflicts or issues you cannot resolve autonomously
+- You own the full ship cycle: implement → test → commit → push → monitor CI → fix if needed
 
 If you hit an unexpected error or need to trace execution, delegate to [debug] rather than guessing.
 
@@ -32,6 +41,7 @@ flow [code] accomplished
 [Done]
 - changes made with file:line references
 - tests written or run
+- CI/CD status (committed, pushed, pipeline status)
 
 [Not Done]
 - incomplete items and reasons

package/agents.ts

@@ -110,7 +110,7 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 	const frontmatter = parsed.frontmatter ?? {};
 	const body = parsed.body ?? "";
 
-	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : "";
+	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim().toLowerCase() : "";
 	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
 	if (!name || !description) return null;
 
@@ -197,7 +197,7 @@ function loadFlowsFromDir(dir: string, source: "user" | "project" | "bundled"):
 function mergeFlows(...groups: FlowConfig[][]): FlowConfig[] {
 	const flowMap = new Map<string, FlowConfig>();
 	for (const group of groups) {
-		for (const flow of group) flowMap.set(flow.name, flow);
+		for (const flow of group) flowMap.set(flow.name.toLowerCase(), flow);
 	}
 	return Array.from(flowMap.values());
 }
@@ -227,7 +227,7 @@ export function discoverFlows(cwd: string, scope: FlowScope): FlowDiscoveryResul
 		return { flows: mergeFlows(bundledFlows, userFlows), projectFlowsDir };
 	}
 	if (scope === "project") {
-		return { flows: projectFlows, projectFlowsDir };
+		return { flows: mergeFlows(projectFlows), projectFlowsDir };
 	}
 	return {
 		flows: mergeFlows(bundledFlows, userFlows, projectFlows),

package/flow.ts

@@ -195,11 +195,12 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		makeDetails,
 	} = opts;
 
-	const flow = flows.find((f) => f.name === flowName);
+	const normalizedFlowName = flowName.toLowerCase();
+	const flow = flows.find((f) => f.name === normalizedFlowName);
 	if (!flow) {
 		const available = flows.map((f) => `"${f.name}"`).join(", ") || "none";
 		return {
-			type: flowName,
+			type: normalizedFlowName,
 			agentSource: "unknown",
 			intent,
 			exitCode: 1,
@@ -210,7 +211,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 	}
 
 	const result: SingleResult = {
-		type: flowName,
+		type: normalizedFlowName,
 		agentSource: flow.source,
 		intent,
 		exitCode: -1,
@@ -255,7 +256,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		const exitCode = await new Promise<number>((resolve) => {
 			const nextDepth = Math.max(0, Math.floor(parentDepth)) + 1;
 			const propagatedMaxDepth = Math.max(0, Math.floor(maxDepth));
-			const propagatedStack = [...parentFlowStack, flowName];
+			const propagatedStack = [...parentFlowStack, normalizedFlowName];
 			const { command, prefixArgs } = resolveFlowSpawn();
 			const proc = spawn(command, [...prefixArgs, ...piArgs], {
 				cwd: taskCwd ?? cwd,

package/index.ts

@@ -36,7 +36,7 @@ const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
 
 const FlowItem = Type.Object({
 	type: Type.String({
-		description: "Flow type. Must match an available flow name exactly: explore, debug, code, architect, review, brainstorm.",
+		description: "Flow type. Matching is case-insensitive. Must correspond to an available flow name such as explore, debug, code, architect, review, or brainstorm.",
 	}),
 	intent: Type.String({
 		description: "Clear, specific mission for this flow.",
@@ -137,7 +137,7 @@ function parseFlowStack(raw: unknown): string[] | null {
 	if (!Array.isArray(parsed)) return null;
 	if (!parsed.every((value) => typeof value === "string")) return null;
 	return parsed
-		.map((value) => value.trim())
+		.map((value) => value.trim().toLowerCase())
 		.filter((value) => value.length > 0);
 }
 
@@ -303,7 +303,7 @@ function getRequestedProjectFlows(
 	requestedNames: Set<string>,
 ): FlowConfig[] {
 	return Array.from(requestedNames)
-		.map((name) => flows.find((f) => f.name === name))
+		.map((name) => flows.find((f) => f.name === name.toLowerCase()))
 		.filter((f): f is FlowConfig => f?.source === "project");
 }
 
@@ -405,10 +405,26 @@ flow [type] accomplished
 			label: "Flow",
 			description: [
 				"Delegate work to flow states running in isolated pi processes.",
-				"Each flow receives a snapshot of your current session context.",
+				"Each flow receives a forked snapshot of your current session context.",
 				"All flows run in parallel — batch independent tasks into one call.",
 				"",
 				'Usage: { "flow": [{ "type": "explore", "intent": "..." }, ...] }',
+				"",
+				"Each flow type is a specialized agent configuration. Standard types:",
+				"\u2022 explore \u2014 Discovery, trace code paths, map architecture",
+				"\u2022 debug \u2014 Root-cause analysis, investigate errors and stack traces",
+				"\u2022 code \u2014 Implementation, tests, builds, deploy, git commit",
+				"\u2022 architect \u2014 Structural design, planning before building",
+				"\u2022 review \u2014 Read-only audit for security, quality, correctness",
+				"\u2022 brainstorm \u2014 Fresh ideas from a clean slate (no inherited context)",
+				"",
+				"Custom flows can be defined as .md files in .pi/agents/ (project)",
+				"or ~/.pi/agent/agents/ (user). They override bundled flows by name.",
+				"",
+				"Each flow returns: [Summary], [Done], [Not Done], [Next Steps]",
+				"",
+				"Guards: Max delegation depth and cycle prevention are enforced.",
+				"Blocked flows return an error with the reason.",
 			].join("\n"),
 			parameters: FlowParams,
 
@@ -423,7 +439,7 @@ flow [type] accomplished
 				);
 
 				// Collect all requested flow names
-				const requested = new Set(params.flow.map((f) => f.type));
+				const requested = new Set(params.flow.map((f) => f.type.toLowerCase()));
 
 				// Cycle check
 				if (preventCycles) {
@@ -483,58 +499,52 @@ flow [type] accomplished
 				}
 
 				let lastStreamingText = "";
+				let lastEmittedText: string | undefined;
 				const emitProgress = (streamingText?: string) => {
 					if (!onUpdate) return;
-					if (streamingText) lastStreamingText = streamingText;
+					if (streamingText !== undefined) lastStreamingText = streamingText;
+					const text = lastStreamingText || "";
+					if (text === lastEmittedText) return;
+					lastEmittedText = text;
 					onUpdate({
-						content: [{ type: "text", text: lastStreamingText || "" }],
+						content: [{ type: "text", text }],
 						details: makeDetails([...allResults]),
 					});
 				};
 
-				let heartbeat: NodeJS.Timeout | undefined;
-				if (onUpdate) {
-					emitProgress();
-					heartbeat = setInterval(() => {
-						if (allResults.some((r) => r.exitCode === -1)) emitProgress();
-					}, 1000);
-				}
-
-				let results: SingleResult[];
-				try {
-					results = await mapFlowConcurrent(params.flow, 4, async (item, index) => {
-						const targetFlow = flows.find((f) => f.name === item.type);
-						const effectiveMaxDepth =
-							targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
-
-						const shouldInheritContext = targetFlow?.inheritContext !== false;
-						const result = await runFlow({
-							cwd: ctx.cwd,
-							flows,
-							flowName: item.type,
-							intent: item.intent,
-							taskCwd: item.cwd,
-							forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
-							parentDepth: currentDepth,
-							parentFlowStack: ancestorFlowStack,
-							maxDepth: effectiveMaxDepth,
-							preventCycles,
-							signal,
-							onUpdate: (partial) => {
-								if (partial.details?.results[0]) {
-									allResults[index] = partial.details.results[0];
-									emitProgress(partial.content?.[0]?.text);
-								}
-							},
-							makeDetails,
-						});
-						allResults[index] = result;
-						emitProgress();
-						return result;
+				if (onUpdate) emitProgress();
+
+				const results = await mapFlowConcurrent(params.flow, 4, async (item, index) => {
+					const normalizedType = item.type.toLowerCase();
+					const targetFlow = flows.find((f) => f.name === normalizedType);
+					const effectiveMaxDepth =
+						targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
+
+					const shouldInheritContext = targetFlow?.inheritContext !== false;
+					const result = await runFlow({
+						cwd: ctx.cwd,
+						flows,
+						flowName: normalizedType,
+						intent: item.intent,
+						taskCwd: item.cwd,
+						forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
+						parentDepth: currentDepth,
+						parentFlowStack: ancestorFlowStack,
+						maxDepth: effectiveMaxDepth,
+						preventCycles,
+						signal,
+						onUpdate: (partial) => {
+							if (partial.details?.results[0]) {
+								allResults[index] = partial.details.results[0];
+								emitProgress(partial.content?.[0]?.text);
+							}
+						},
+						makeDetails,
 					});
-				} finally {
-					if (heartbeat) clearInterval(heartbeat);
-				}
+					allResults[index] = result;
+					emitProgress();
+					return result;
+				});
 
 				// Build tool result with FULL flow output — no truncation
 				const successCount = results.filter((r) => isFlowSuccess(r)).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "index.ts",

package/render-utils.ts

@@ -48,14 +48,14 @@ export function formatFixedTokens(count: number): string {
 }
 
 /**
- * Format flow type name to fixed width (10 chars) in uppercase with dot padding.
- * Examples: "debug" → "DEBUG.....", "architect" → "ARCHITECT.", "brainstorm" → "BRAINSTORM"
+ * Format flow type name to fixed width (10 chars) in lowercase with dot padding.
+ * Examples: "debug" → "debug.....", "architect" → "architect.", "brainstorm" → "brainstorm"
  */
 export function formatFlowTypeName(type: string): string {
-	const upper = type.toUpperCase();
+	const lower = type.toLowerCase();
 	const targetWidth = 10;
-	if (upper.length >= targetWidth) return upper.slice(0, targetWidth);
-	return upper + ".".repeat(targetWidth - upper.length);
+	if (lower.length >= targetWidth) return lower.slice(0, targetWidth);
+	return lower + ".".repeat(targetWidth - lower.length);
 }
 
 export function formatCompactStats(usage: Partial<UsageStats>, model?: string): string {
@@ -157,6 +157,7 @@ function truncateAnsi(text: string, max: number): string {
 }
 
 export function truncateChars(text: string, max: number): string {
+	text = text.replace(/[\n\r\t]+/g, " ").replace(/ +/g, " ").trim();
 	if (visibleLength(text) <= max) return text;
 	return truncateAnsi(text, max);
 }