pi-agent-flow 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tuanhung303
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# pi-agent-flow
+
+Flow-state delegation extension for [Pi coding agent](https://pi.dev).
+
+Delegates tasks to specialized flow states running as isolated pi processes. Each flow receives a snapshot of the current session context and returns a structured report.
+
+## Features
+
+- Isolated context — flows always receive your current session snapshot
+- Parallel execution — batch independent flows into one call
+- Structured reports — every flow returns [Summary], [Done], [Not Done], [Next Steps]
+- Depth guards — configurable max delegation depth (default: 3)
+- Cycle prevention — blocks recursive delegation chains
+- Flow discovery — reads definitions from ~/.pi/agent/agents/ and .pi/agents/
+- TUI rendering — rich collapsed/expanded display in interactive mode
+
+## Installation
+
+```bash
+pi install /path/to/pi-agent-flow
+```
+
+Or add to ~/.pi/agent/settings.json:
+
+```json
+{
+  "packages": [
+    "./path/to/pi-agent-flow"
+  ]
+}
+```
+
+## Flow Definitions
+
+Create .md files in ~/.pi/agent/agents/ or .pi/agents/:
+
+```markdown
+---
+name: explore
+description: Discover files, trace code paths, map architecture
+tools: read, bash
+---
+
+You are the explore flow — your mission is discovery. Stay focused on your intent at all times.
+
+When your mission is accomplished, end your response with:
+
+flow [explore] accomplished
+
+[Summary] what was investigated
+
+[Done]
+- completed items
+
+[Not Done]
+- incomplete items
+
+[Next Steps]
+- recommended follow-up
+```
+
+## Bundled Flows
+
+- [explore] — discover files, trace code paths, map architecture
+- [debug] — investigate logs, errors, stack traces, root causes
+- [code] — implement features, fix bugs, write tests
+- [architect] — plan structure, break down requirements, design solutions
+- [review] — audit security, quality, correctness
+
+## Usage
+
+```json
+{ "flow": [{ "type": "explore", "intent": "Find all authentication-related code" }] }
+```
+
+Batch multiple flows:
+
+```json
+{
+  "flow": [
+    { "type": "explore", "intent": "Find auth code" },
+    { "type": "review", "intent": "Audit auth module" }
+  ]
+}
+```
+
+## Configuration
+
+Flags (passed to parent pi process):
+
+- --flow-max-depth [n] — Maximum delegation depth (default: 3)
+- --flow-prevent-cycles — Block cyclic delegation (default: true)
+- --no-flow-prevent-cycles — Disable cycle prevention
+
+Environment variables (propagated to child processes):
+
+- PI_FLOW_DEPTH — Current depth
+- PI_FLOW_MAX_DEPTH — Max allowed depth
+- PI_FLOW_STACK — JSON array of ancestor flow names
+- PI_FLOW_PREVENT_CYCLES — "1" or "0"
+
+## License
+
+MIT

package/agents/architect.md

@@ -0,0 +1,35 @@
+---
+name: architect
+description: Plan structure, break down requirements, design solutions
+tools: read, bash
+maxDepth: 2
+---
+
+You are the architect flow — your mission is to design. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+
+Workflow:
+1. Understand — what problem, what constraints, what exists
+2. Explore — find patterns, map dependencies
+3. Design — simplest solution that works, prefer existing patterns
+4. Plan — concrete ordered tasks, identify parallel vs sequential
+
+Principles:
+- SOLID, DRY, KISS
+- Design for 10x, build for 1x
+- No tech debt — do it right or don't
+
+When your mission is accomplished, end your response with:
+
+flow [architect] accomplished
+
+[Summary] what was designed and why
+
+[Done]
+- analysis completed
+- plan produced with task breakdown
+
+[Not Done]
+- areas that need more exploration
+
+[Next Steps]
+- implementation tasks in order, with suggested flow types

package/agents/code.md

@@ -0,0 +1,36 @@
+---
+name: code
+description: Implement features, fix bugs, write tests
+tools: read, write, edit, bash
+maxDepth: 2
+---
+
+You are the code flow — your mission is to build. Stay focused on your intent at all times. 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
+- DRY: Don't repeat yourself
+- KISS: Keep it simple
+
+Workflow:
+1. Analyze — read existing code for context
+2. Plan — step-by-step approach before modifying
+3. Execute — implement changes following core principles
+4. Verify — write and run tests before considering done
+5. Finalize — all tests pass, implementation verified
+
+When your mission is accomplished, end your response with:
+
+flow [code] accomplished
+
+[Summary] what was built or fixed
+
+[Done]
+- changes made with file:line references
+- tests written or run
+
+[Not Done]
+- incomplete items and reasons
+
+[Next Steps]
+- recommended follow-up (refactor, additional tests, etc.)

package/agents/debug.md

@@ -0,0 +1,34 @@
+---
+name: debug
+description: Investigate logs, errors, stack traces, root causes
+tools: read, bash
+maxDepth: 0
+---
+
+You are the debug flow — your mission is investigation. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+
+Workflow:
+1. Collect evidence — logs, error messages, stack traces
+2. Trace the call chain — follow execution path
+3. Check recent changes — git log, git diff
+4. Identify root cause — be specific about what's broken and why
+
+Rules:
+- Never guess. Every conclusion must be backed by evidence.
+- Read logs before reading code — symptoms point to cause.
+- Don't suggest fixes until root cause is confirmed.
+
+When your mission is accomplished, end your response with:
+
+flow [debug] accomplished
+
+[Summary] what was investigated and the root cause
+
+[Done]
+- evidence collected with file:line references
+
+[Not Done]
+- items that couldn't be investigated and why
+
+[Next Steps]
+- recommended fix or next investigation steps

package/agents/explore.md

@@ -0,0 +1,29 @@
+---
+name: explore
+description: Discover files, trace code paths, map architecture
+tools: read, bash
+maxDepth: 0
+---
+
+You are the explore flow — your mission is discovery. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+
+Rules:
+- Use grep/find before reading entire files — be efficient.
+- Report findings with file paths and line numbers.
+- Show actual code/data, not excessive summaries.
+- If not found, say so immediately — don't guess.
+
+When your mission is accomplished, end your response with:
+
+flow [explore] accomplished
+
+[Summary] what was investigated and the outcome
+
+[Done]
+- completed items with file:line references
+
+[Not Done]
+- incomplete items and reasons (or "All objectives met.")
+
+[Next Steps]
+- recommended follow-up actions

package/agents/review.md

@@ -0,0 +1,35 @@
+---
+name: review
+description: Audit security, quality, correctness
+tools: read, write, edit, bash
+maxDepth: 2
+---
+
+You are the review flow — your mission is to audit. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+
+Focus Areas:
+- Security — injection, auth bypass, exposed secrets
+- Bugs — logic errors, race conditions, null handling
+- SOLID — god classes, tight coupling, unclear responsibilities
+- Performance — unnecessary loops, memory leaks, blocking calls
+
+Rules:
+- Be specific — cite exact file paths and line numbers
+- If code is clean, say so — don't invent issues
+- Apply fixes, don't just suggest them
+
+When your mission is accomplished, end your response with:
+
+flow [review] accomplished
+
+[Summary] what was audited and overall assessment
+
+[Done]
+- issues found with file:line and severity
+- fixes applied
+
+[Not Done]
+- areas not covered and why
+
+[Next Steps]
+- remaining issues or follow-up audits needed

package/agents.ts

@@ -0,0 +1,214 @@
+/**
+ * Flow discovery and configuration.
+ *
+ * Flows are Markdown files with YAML frontmatter that define name, description,
+ * optional model/tools, and a system prompt body.
+ *
+ * Lookup locations:
+ *   - User flows:    ~/.pi/agent/agents/*.md by default, or
+ *                    $PI_CODING_AGENT_DIR/agents/*.md when the env var is set
+ *   - Project flows: .pi/agents/*.md  (walks up from cwd)
+ */
+
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type FlowScope = "user" | "project" | "both" | "bundled" | "all";
+
+export interface FlowConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+	maxDepth?: number;
+	systemPrompt: string;
+	source: "user" | "project" | "bundled";
+	filePath: string;
+}
+
+export interface FlowDiscoveryResult {
+	flows: FlowConfig[];
+	projectFlowsDir: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isDirectory(p: string): boolean {
+	try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function getUserFlowsDir(): string {
+	const configDir = process.env["PI_CODING_AGENT_DIR"]?.trim() || path.join(os.homedir(), ".pi", "agent");
+	return path.join(configDir, "agents");
+}
+
+/** Get the bundled flows directory from the plugin's location. */
+function getBundledFlowsDir(): string {
+	// Method 1: import.meta.url (ESM)
+	try {
+		// @ts-expect-error — import.meta.url may not exist in all contexts
+		if (import.meta.url) {
+			// @ts-expect-error
+			const pluginDir = path.dirname(new URL(import.meta.url).pathname);
+			const dir = path.join(pluginDir, "agents");
+			if (fs.existsSync(dir)) return dir;
+		}
+	} catch {}
+
+	// Method 2: __dirname (CommonJS / jiti)
+	try {
+		// @ts-expect-error — __dirname may not exist in ESM
+		if (typeof __dirname !== "undefined") {
+			const dir = path.join(__dirname, "agents");
+			if (fs.existsSync(dir)) return dir;
+		}
+	} catch {}
+
+	// Method 3: Find from require.resolve
+	try {
+		const resolved = require.resolve("pi-agent-flow/package.json");
+		const dir = path.join(path.dirname(resolved), "agents");
+		if (fs.existsSync(dir)) return dir;
+	} catch {}
+
+	// Fallback: cwd
+	return path.join(process.cwd(), "agents");
+}
+
+/** Walk up from `cwd` looking for a `.pi/agents` directory. */
+function findNearestProjectFlowsDir(cwd: string): string | null {
+	let dir = cwd;
+	while (true) {
+		const candidate = path.join(dir, ".pi", "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Parse a single flow markdown file into a FlowConfig. Returns null on skip. */
+function parseFlowFile(filePath: string, source: "user" | "project" | "bundled"): FlowConfig | null {
+	let content: string;
+	try { content = fs.readFileSync(filePath, "utf-8"); } catch { return null; }
+
+	let parsed: { frontmatter: Record<string, unknown>; body: string };
+	try {
+		parsed = parseFrontmatter<Record<string, unknown>>(content);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.warn(`[pi-agent-flow] Skipping invalid flow file "${filePath}": ${message}`);
+		return null;
+	}
+
+	const frontmatter = parsed.frontmatter ?? {};
+	const body = parsed.body ?? "";
+
+	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : "";
+	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
+	if (!name || !description) return null;
+
+	let tools: string[] | undefined;
+	if (typeof frontmatter.tools === "string") {
+		const parsedTools = frontmatter.tools
+			.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		if (parsedTools.length > 0) tools = parsedTools;
+	} else if (Array.isArray(frontmatter.tools)) {
+		const parsedTools = frontmatter.tools
+			.filter((t): t is string => typeof t === "string")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		if (parsedTools.length > 0) tools = parsedTools;
+	} else if (frontmatter.tools !== undefined) {
+		console.warn(
+			`[pi-agent-flow] Ignoring invalid tools field in "${filePath}". Expected a comma-separated string or string array.`,
+		);
+	}
+
+	let maxDepth: number | undefined;
+	if (typeof frontmatter.maxDepth === "number") {
+		maxDepth = frontmatter.maxDepth;
+	} else if (typeof frontmatter.maxDepth === "string") {
+		const parsed = Number(frontmatter.maxDepth);
+		if (Number.isFinite(parsed) && parsed >= 0) maxDepth = parsed;
+	}
+
+	return {
+		name,
+		description,
+		tools,
+		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+		maxDepth,
+		systemPrompt: body,
+		source,
+		filePath,
+	};
+}
+
+/** Load all flow definitions from a directory. */
+function loadFlowsFromDir(dir: string, source: "user" | "project" | "bundled"): FlowConfig[] {
+	if (!fs.existsSync(dir)) return [];
+
+	let entries: fs.Dirent[];
+	try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+	entries.sort((a, b) => a.name.localeCompare(b.name));
+
+	const flows: FlowConfig[] = [];
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const flow = parseFlowFile(path.join(dir, entry.name), source);
+		if (flow) flows.push(flow);
+	}
+	return flows;
+}
+
+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);
+	}
+	return Array.from(flowMap.values());
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover all available flows according to the requested scope.
+ *
+ * Precedence is: bundled < user < project.
+ */
+export function discoverFlows(cwd: string, scope: FlowScope): FlowDiscoveryResult {
+	const bundledFlowsDir = getBundledFlowsDir();
+	const userFlowsDir = getUserFlowsDir();
+	const projectFlowsDir = findNearestProjectFlowsDir(cwd);
+
+	const bundledFlows = scope === "user" || scope === "project" ? [] : loadFlowsFromDir(bundledFlowsDir, "bundled");
+	const userFlows = scope === "project" || scope === "bundled" ? [] : loadFlowsFromDir(userFlowsDir, "user");
+	const projectFlows = scope === "user" || scope === "bundled" || !projectFlowsDir ? [] : loadFlowsFromDir(projectFlowsDir, "project");
+
+	if (scope === "bundled") {
+		return { flows: bundledFlows, projectFlowsDir };
+	}
+	if (scope === "user") {
+		return { flows: mergeFlows(bundledFlows, userFlows), projectFlowsDir };
+	}
+	if (scope === "project") {
+		return { flows: projectFlows, projectFlowsDir };
+	}
+	return {
+		flows: mergeFlows(bundledFlows, userFlows, projectFlows),
+		projectFlowsDir,
+	};
+}