pi-taskflow 0.0.2 → 0.0.4

package/DESIGN.md

@@ -288,12 +288,12 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 
 ## 5. 路线图
 
-| 版本 | 范围 |
-|------|------|
-| **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 |
-| **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 阶段 + run 历史 TUI |
-| **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm |
-| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 |
+| 版本 | 范围 | 状态 |
+|------|------|------|
+| **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 | ✅ 已发布 (npm 0.0.1) |
+| **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 真门控 + run 历史交互 TUI | ✅ 已完成 (npm 0.0.3) |
+| **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm | 🚧 examples/SKILL/npm 已做；YAML 待办 |
+| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 | ⏳ 待办 |
 
 ---
 

package/extensions/index.ts

@@ -17,8 +17,9 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
+import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
 import { executeTaskflow, type RuntimeResult } from "./runtime.ts";
-import { finalPhase, type Taskflow, validateTaskflow } from "./schema.ts";
+import { finalPhase, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
 	getFlow,
 	listFlows,
@@ -40,6 +41,14 @@ interface TaskflowDetails {
 /** pi reads `isError` at runtime to mark tool failures; it is not in the public type. */
 type ToolResult = AgentToolResult<TaskflowDetails> & { isError?: boolean };
 
+const ShorthandStep = Type.Object(
+	{
+		agent: Type.Optional(Type.String({ description: "Agent for this step (defaults to the first available agent)" })),
+		task: Type.String({ description: "Task prompt for this step (supports {previous.output} in chains)" }),
+	},
+	{ additionalProperties: false },
+);
+
 const TaskflowParams = Type.Object({
 	action: StringEnum(["run", "save", "resume", "list"] as const, {
 		description: "What to do: run a flow, save a definition, resume a paused run, or list saved flows",
@@ -52,6 +61,24 @@ const TaskflowParams = Type.Object({
 				"Inline taskflow definition (JSON object matching the taskflow DSL). Use to run or save a new flow.",
 		}),
 	),
+	// --- Shorthand (non-DAG) modes, like the subagent tool. No DSL required. ---
+	agent: Type.Optional(
+		Type.String({ description: "Shorthand single mode: agent to run with `task` (like subagent single mode)" }),
+	),
+	task: Type.Optional(
+		Type.String({ description: "Shorthand single mode: the task prompt (like subagent single mode)" }),
+	),
+	tasks: Type.Optional(
+		Type.Array(ShorthandStep, {
+			description: "Shorthand parallel mode: run these tasks concurrently and merge results (like subagent parallel)",
+		}),
+	),
+	chain: Type.Optional(
+		Type.Array(ShorthandStep, {
+			description:
+				"Shorthand chain mode: run sequentially; reference the prior step with {previous.output} (like subagent chain)",
+		}),
+	),
 	args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Invocation arguments for the flow" })),
 	runId: Type.Optional(Type.String({ description: "Run id to resume (for action=resume)" })),
 	scope: Type.Optional(
@@ -174,6 +201,7 @@ export default function (pi: ExtensionAPI) {
 			"Orchestrate a multi-phase workflow of subagents from a declarative definition.",
 			"Phases (agent, parallel, map, gate, reduce) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
 			"Use action=run with an inline `define` (you write the DSL) or a saved `name`.",
+			"For simple non-DAG delegations (like the subagent tool) skip the DSL: pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` to run in parallel, or `chain:[{task,agent?}]` to run sequentially (reference the prior step with {previous.output}).",
 			"Use action=save to persist a definition as a reusable /tf:<name> command. action=resume continues a paused run. action=list shows saved flows.",
 			"DSL: {name, args?, concurrency?, phases:[{id, type, agent, task, dependsOn?, over?(map), as?(map), branches?(parallel), from?(reduce), output?:'json', final?}]}.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
@@ -182,7 +210,7 @@ export default function (pi: ExtensionAPI) {
 		promptSnippet: "Orchestrate many subagents over a whole codebase/many items (declarative DAG with map fan-out)",
 		promptGuidelines: [
 			"Prefer taskflow whenever a request spans a whole project/codebase or many items — e.g. 'explore / 探索 / 审计 / analyze the project', auditing endpoints, reviewing or migrating many files/modules, or cross-checked research. It fans out to many subagents across phases and aggregates the result, keeping intermediate work out of your context.",
-			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. Use the plain subagent tool only for a single delegated task.",
+			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. For simple single/parallel/chain delegations use the shorthand `task`/`tasks`/`chain` (no DSL) when you want the run tracked, resumable, or saveable; otherwise the plain subagent tool is fine.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
 
@@ -208,18 +236,39 @@ export default function (pi: ExtensionAPI) {
 				return finalResult(action, result);
 			}
 
-			// resolve the definition (inline define wins, else saved name)
+			// resolve the definition: inline `define` / shorthand (single|parallel|chain), else saved `name`.
 			let def: Taskflow | undefined;
-			if (params.define) {
-				const v = validateTaskflow(params.define);
+
+			// A shorthand spec can come from `define` (no phases) or top-level params.
+			const shorthandSpec: unknown =
+				params.define ??
+				(params.chain
+					? { chain: params.chain, name: params.name }
+					: params.tasks
+						? { tasks: params.tasks, name: params.name }
+						: params.task
+							? { task: params.task, agent: params.agent, name: params.name }
+							: undefined);
+
+			if (shorthandSpec !== undefined) {
+				let candidate: unknown = shorthandSpec;
+				if (isShorthand(candidate)) {
+					try {
+						candidate = desugar(candidate);
+					} catch (e) {
+						return errorResult(action, `Invalid shorthand: ${e instanceof Error ? e.message : String(e)}`);
+					}
+				}
+				const v = validateTaskflow(candidate);
 				if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
-				def = params.define as Taskflow;
+				def = candidate as Taskflow;
 			} else if (params.name) {
 				const saved = getFlow(ctx.cwd, params.name);
 				if (!saved) return errorResult(action, `Saved flow not found: ${params.name}`);
 				def = saved.def;
 			}
-			if (!def) return errorResult(action, "Provide 'define' (inline) or 'name' (saved).");
+			if (!def)
+				return errorResult(action, "Provide 'define' (DSL), shorthand 'task'/'tasks'/'chain', or 'name' (saved).");
 
 			// save
 			if (action === "save") {
@@ -255,10 +304,23 @@ export default function (pi: ExtensionAPI) {
 
 		renderCall(args, theme) {
 			const action = args.action ?? "run";
-			const name = args.name || (args.define as any)?.name || "(inline)";
-			let text = theme.fg("toolTitle", theme.bold("taskflow ")) + theme.fg("accent", `${action} `) + theme.fg("muted", name);
+			let label = args.name || (args.define as { name?: string } | undefined)?.name;
+			let suffix = "";
 			const phases = (args.define as Taskflow | undefined)?.phases;
-			if (phases) text += theme.fg("dim", ` (${phases.length} phases)`);
+			if (phases) suffix = ` (${phases.length} phases)`;
+			else if (args.chain) {
+				label ||= "chain";
+				suffix = ` (${(args.chain as unknown[]).length} steps)`;
+			} else if (args.tasks) {
+				label ||= "parallel";
+				suffix = ` (${(args.tasks as unknown[]).length} tasks)`;
+			} else if (args.task) {
+				label ||= "task";
+			}
+			label ||= "(inline)";
+			let text =
+				theme.fg("toolTitle", theme.bold("taskflow ")) + theme.fg("accent", `${action} `) + theme.fg("muted", label);
+			if (suffix) text += theme.fg("dim", suffix);
 			return new Text(text, 0, 0);
 		},
 
@@ -306,15 +368,30 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (sub === "runs") {
-				const runs = listRuns(ctx.cwd);
+				const runs = listRuns(ctx.cwd, 50);
 				if (runs.length === 0) {
 					ctx.ui.notify("No taskflow runs yet.", "info");
 					return;
 				}
-				ctx.ui.notify(
-					runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
-					"info",
-				);
+				if (!ctx.hasUI) {
+					ctx.ui.notify(
+						runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
+						"info",
+					);
+					return;
+				}
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
+					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				});
+				if (result?.action === "resume") {
+					if (ctx.isIdle()) {
+						pi.sendUserMessage(
+							`Resume the taskflow run "${result.runId}" using the taskflow tool with action="resume", runId="${result.runId}".`,
+						);
+					} else {
+						ctx.ui.notify("Agent is busy; try /tf resume when idle.", "warning");
+					}
+				}
 				return;
 			}
 

package/extensions/render.ts

@@ -9,7 +9,7 @@ import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { formatTokens, type UsageStats } from "./runner.ts";
 import type { PhaseState, RunState } from "./store.ts";
-import type { Phase } from "./schema.ts";
+import { dependenciesOf, type Phase, topoLayers } from "./schema.ts";
 
 // Single-width glyphs (Geometric Shapes / check marks) — keep columns aligned.
 const ICON: Record<PhaseState["status"], { ch: string; color: string }> = {
@@ -115,7 +115,11 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	const type = phase.type ?? "agent";
 	if (!ps || ps.status === "pending") return theme.fg("dim", "—");
 
-	if (ps.status === "skipped") return theme.fg("muted", "skipped · upstream failed");
+	if (ps.status === "skipped") {
+		const reason = (ps.error ?? "upstream failed").replace(/\s+/g, " ");
+		const snip = reason.length > 52 ? `${reason.slice(0, 52)}…` : reason;
+		return theme.fg("muted", `skipped · ${snip}`);
+	}
 
 	const isFanout = type === "map" || type === "parallel";
 
@@ -167,6 +171,18 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	// single-agent done
 	const model = shortModel(ps.model);
 	const u = compactUsage(ps.usage, theme);
+	if (ps.gate) {
+		const badge =
+			ps.gate.verdict === "block" ? theme.fg("error", theme.bold("BLOCK")) : theme.fg("success", "PASS");
+		let g = badge;
+		if (ps.gate.reason) {
+			const r = ps.gate.reason.replace(/\s+/g, " ");
+			g += theme.fg("dim", ` ${r.length > 44 ? `${r.slice(0, 44)}…` : r}`);
+		}
+		if (model) g += `  ${theme.fg("dim", model)}`;
+		if (time) g += `  ${time}`;
+		return g;
+	}
 	let s = "";
 	if (model) s += theme.fg("accent", model);
 	if (u) s += (s ? "  " : "") + u;
@@ -187,9 +203,11 @@ function headerLine(state: RunState, theme: Theme): string {
 			? theme.fg("success", "✓")
 			: state.status === "failed"
 				? theme.fg("error", "✗")
-				: state.status === "paused"
-					? theme.fg("warning", "‖")
-					: theme.fg("warning", spinnerFrame());
+				: state.status === "blocked"
+					? theme.fg("error", "⊗")
+					: state.status === "paused"
+						? theme.fg("warning", "‖")
+						: theme.fg("warning", spinnerFrame());
 
 	let line =
 		`${head} ${theme.fg("toolTitle", theme.bold("taskflow"))} ` +
@@ -197,6 +215,7 @@ function headerLine(state: RunState, theme: Theme): string {
 		theme.fg("muted", `  ${done}/${total}`);
 	if (running) line += theme.fg("warning", ` · ${running}▸`);
 	if (failed) line += theme.fg("error", ` · ${failed}✗`);
+	if (state.status === "blocked") line += theme.fg("error", " · blocked");
 	const cost = aggregateCost(state);
 	if (cost) line += theme.fg("muted", ` · $${cost.toFixed(3)}`);
 	const el = runElapsed(state);
@@ -204,35 +223,81 @@ function headerLine(state: RunState, theme: Theme): string {
 	return line;
 }
 
-/** The full dense progress block (header + aligned phase rows). */
+/**
+ * Left-gutter rail glyph for a phase at `i` within a parallel group of `size`.
+ * A group is a topological layer with >1 phase (they run concurrently); the
+ * bracket (┌ ├ └) visually fans them out from the preceding layer. Single-phase
+ * layers get a blank gutter so the column stays quiet.
+ */
+function railGlyph(i: number, size: number): string {
+	if (size <= 1) return " ";
+	if (i === 0) return "┌";
+	if (i === size - 1) return "└";
+	return "├";
+}
+
+/** The full dense progress block (header + DAG-ordered phase rows). */
 export function renderProgress(state: RunState, theme: Theme): string {
 	const phases = state.def.phases;
 	const idW = Math.max(...phases.map((p) => p.id.length), 2);
 	const typeW = Math.max(...phases.map((p) => (p.type ?? "agent").length), 4);
+	const defIndex = new Map(phases.map((p, i) => [p.id, i]));
+
+	// Render in topological order: each layer is a set of phases that can run
+	// concurrently; later layers depend on earlier ones. This makes the DAG's
+	// flow legible top-to-bottom without drawing a full graph.
+	const layers = topoLayers(phases);
+	const rendered = new Set<string>();
 
 	let text = headerLine(state, theme);
-	for (const phase of phases) {
+
+	const renderRow = (phase: Phase, rail: string, prevLayerIds: Set<string>) => {
 		const ps = state.phases[phase.id];
 		const status = ps?.status ?? "pending";
 		const id = phase.id.padEnd(idW);
 		const type = (phase.type ?? "agent").padEnd(typeW);
 		const detail = phaseDetail(phase, ps, theme);
+
+		// Annotate only "long" edges — dependencies that skip past the adjacent
+		// layer. Edges into the immediately-preceding layer are implied by position
+		// (and the rail), so showing them would just add noise.
+		const longEdges = dependenciesOf(phase).filter((d) => !prevLayerIds.has(d));
+		const dep = longEdges.length
+			? theme.fg("dim", `  ↳ ${longEdges.join(", ")}`)
+			: "";
+
+		const gutter = rail === " " ? " " : theme.fg("borderMuted", rail);
 		text +=
-			`\n  ${icon(status, theme)} ` +
+			`\n  ${gutter} ${icon(status, theme)} ` +
 			theme.fg(status === "pending" ? "dim" : "text", id) +
 			"  " +
 			theme.fg("dim", type) +
 			"  " +
-			detail;
+			detail +
+			dep;
 
 		// Live activity sub-line (only while running, only if we have a message).
 		if (status === "running" && ps?.liveText) {
-			const indent = " ".repeat(2 + 2 + idW + 2);
+			const indent = " ".repeat(2 + 2 + 2 + idW + 2);
 			const msg = ps.liveText.replace(/\s+/g, " ").trim();
 			const snip = msg.length > 88 ? `${msg.slice(0, 88)}…` : msg;
 			text += `\n${indent}${theme.fg("dim", "› ")}${theme.fg("muted", snip)}`;
 		}
+		rendered.add(phase.id);
+	};
+
+	let prevLayerIds = new Set<string>();
+	for (const layer of layers) {
+		const ordered = [...layer].sort((a, b) => (defIndex.get(a.id) ?? 0) - (defIndex.get(b.id) ?? 0));
+		ordered.forEach((phase, i) => renderRow(phase, railGlyph(i, ordered.length), prevLayerIds));
+		prevLayerIds = new Set(ordered.map((p) => p.id));
 	}
+
+	// Safety net: render any phase a malformed DAG left out of the layering.
+	for (const phase of phases) {
+		if (!rendered.has(phase.id)) renderRow(phase, " ", prevLayerIds);
+	}
+
 	return text;
 }
 

package/extensions/runner.ts

@@ -289,7 +289,7 @@ export async function runAgentTask(
 		}
 		if (tmpPromptDir) {
 			try {
-				fs.rmdirSync(tmpPromptDir);
+				fs.rmSync(tmpPromptDir, { recursive: true, force: true });
 			} catch {
 				/* ignore */
 			}

package/extensions/runs-view.ts

@@ -0,0 +1,141 @@
+/**
+ * Interactive run-history view for `/tf runs` (ctx.ui.custom).
+ * List view: navigate runs; Enter → detail; r → resume; Esc/q → close.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { renderProgress, summarizeRun } from "./render.ts";
+import type { RunState } from "./store.ts";
+
+export interface RunHistoryResult {
+	action: "resume";
+	runId: string;
+}
+
+function statusBadge(status: RunState["status"], theme: Theme): string {
+	switch (status) {
+		case "completed":
+			return theme.fg("success", "✓ done");
+		case "failed":
+			return theme.fg("error", "✗ failed");
+		case "blocked":
+			return theme.fg("error", "⊗ blocked");
+		case "paused":
+			return theme.fg("warning", "‖ paused");
+		default:
+			return theme.fg("warning", "◐ running");
+	}
+}
+
+function timeAgo(ts: number): string {
+	const s = Math.floor((Date.now() - ts) / 1000);
+	if (s < 60) return `${s}s ago`;
+	if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+	if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+	return `${Math.floor(s / 86400)}d ago`;
+}
+
+function isResumable(r: RunState): boolean {
+	return r.status === "paused" || r.status === "failed" || r.status === "blocked";
+}
+
+export class RunHistoryComponent {
+	private runs: RunState[];
+	private theme: Theme;
+	private onDone: (result?: RunHistoryResult) => void;
+	private selected = 0;
+	private mode: "list" | "detail" = "list";
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(runs: RunState[], theme: Theme, onDone: (result?: RunHistoryResult) => void) {
+		this.runs = runs;
+		this.theme = theme;
+		this.onDone = onDone;
+	}
+
+	handleInput(data: string): void {
+		this.invalidate();
+		if (this.mode === "detail") {
+			if (matchesKey(data, "escape")) {
+				this.mode = "list";
+				return;
+			}
+			if (data === "r" && isResumable(this.runs[this.selected])) {
+				this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+			}
+			return;
+		}
+		// list mode
+		if (matchesKey(data, "escape") || data === "q" || matchesKey(data, "ctrl+c")) {
+			this.onDone();
+			return;
+		}
+		if (matchesKey(data, "up")) {
+			this.selected = (this.selected - 1 + this.runs.length) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.selected = (this.selected + 1) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "return")) {
+			this.mode = "detail";
+			return;
+		}
+		if (data === "r" && isResumable(this.runs[this.selected])) {
+			this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines: string[] = [""];
+
+		if (this.mode === "detail") {
+			const run = this.runs[this.selected];
+			lines.push(truncateToWidth(`  ${th.fg("accent", "Run ")}${th.fg("muted", run.runId)}`, width));
+			lines.push("");
+			for (const l of renderProgress(run, th).split("\n")) lines.push(truncateToWidth(l, width));
+			lines.push("");
+			const hint = isResumable(run) ? "Esc back · r resume" : "Esc back";
+			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}`, width));
+			lines.push("");
+			this.cachedWidth = width;
+			this.cachedLines = lines;
+			return lines;
+		}
+
+		// list mode
+		const header =
+			th.fg("borderMuted", "─".repeat(3)) +
+			th.fg("accent", " Taskflow runs ") +
+			th.fg("borderMuted", "─".repeat(Math.max(0, width - 18)));
+		lines.push(truncateToWidth(header, width));
+		lines.push("");
+
+		this.runs.forEach((run, i) => {
+			const sel = i === this.selected;
+			const marker = sel ? th.fg("accent", "❯ ") : "  ";
+			const badge = statusBadge(run.status, th);
+			const name = sel ? th.fg("text", run.flowName) : th.fg("muted", run.flowName);
+			const meta = th.fg("dim", `${summarizeRun(run)} · ${timeAgo(run.updatedAt)}`);
+			lines.push(truncateToWidth(`  ${marker}${badge}  ${name}  ${meta}`, width));
+		});
+
+		lines.push("");
+		lines.push(truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/extensions/runtime.ts

@@ -178,7 +178,9 @@ async function executePhase(
 			}
 			emitProgress();
 		});
-		return resultToPhaseState(phase.id, r, inputHash, parseJson);
+		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
+		return ps;
 	}
 
 	if (type === "parallel") {
@@ -257,12 +259,20 @@ async function executePhase(
 
 /** Resolve a `{steps.x.json}`-style ref directly to its parsed value (bypassing stringify). */
 function directRef(over: string, state: RunState): unknown {
-	const m = over.match(/^\{steps\.([a-zA-Z0-9_]+)\.(output|json)\}$/);
+	const m = over.match(/^\{steps\.([a-zA-Z0-9_]+)\.(output|json)(?:\.([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*))?\}$/);
 	if (!m) return undefined;
 	const step = state.phases[m[1]];
 	if (!step || step.status !== "done") return undefined;
-	if (m[2] === "json") return step.json ?? safeParse(step.output ?? "");
-	return safeParse(step.output ?? "");
+	let value: unknown;
+	if (m[2] === "json") value = step.json ?? safeParse(step.output ?? "");
+	else value = safeParse(step.output ?? "");
+	if (m[3]) {
+		for (const key of m[3].split(".")) {
+			if (value == null || typeof value !== "object") return undefined;
+			value = (value as Record<string, unknown>)[key];
+		}
+	}
+	return value;
 }
 
 function lastCompletedOutput(state: RunState, phase: Phase): string | undefined {
@@ -285,6 +295,36 @@ function defaultAgent(deps: RuntimeDeps): string {
 	return deps.agents[0]?.name ?? "default";
 }
 
+/**
+ * Parse a gate phase's output into a verdict. Blocks the flow only on an
+ * explicit negative signal; ambiguous output passes (fail-open).
+ * Accepts JSON ({continue|pass: bool} or {verdict: "..."}) or a text marker
+ * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins).
+ */
+export function parseGateVerdict(output: string): { verdict: "pass" | "block"; reason?: string } {
+	const json = safeParse(output);
+	if (json && typeof json === "object") {
+		const o = json as Record<string, unknown>;
+		if (typeof o.continue === "boolean") return { verdict: o.continue ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.pass === "boolean") return { verdict: o.pass ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.verdict === "string") {
+			const block = /block|fail|stop|reject|halt|\bno\b/i.test(o.verdict);
+			return { verdict: block ? "block" : "pass", reason: asReason(o.reason) };
+		}
+	}
+	const matches = [...output.matchAll(/VERDICT\s*[:=]\s*(PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT)/gi)];
+	if (matches.length) {
+		const v = matches[matches.length - 1][1].toUpperCase();
+		const pass = v === "PASS" || v === "OK";
+		return { verdict: pass ? "pass" : "block" };
+	}
+	return { verdict: "pass" };
+}
+
+function asReason(v: unknown): string | undefined {
+	return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
 /**
  * Execute a full taskflow. Mutates and persists `state` as it progresses.
  */
@@ -297,6 +337,9 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	deps.onProgress?.(state);
 
 	let aborted = false;
+	let gateBlocked = false;
+	let gateReason = "";
+	let gateOutput = "";
 
 	for (const layer of layers) {
 		if (deps.signal?.aborted) {
@@ -308,13 +351,13 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 		await mapWithConcurrencyLimit(layer, layerConcurrency, async (phase) => {
 			// Snapshot prior state BEFORE marking running, so resume cache checks work.
 			const prior = state.phases[phase.id];
-			// Skip if a dependency failed (unless this phase is optional).
+			// Skip if a dependency failed, or an upstream gate blocked the flow.
 			const failedDep = dependenciesOf(phase).some((d) => state.phases[d]?.status === "failed");
-			if (failedDep) {
+			if (gateBlocked || failedDep) {
 				state.phases[phase.id] = {
 					id: phase.id,
 					status: "skipped",
-					error: "Upstream dependency failed",
+					error: gateBlocked ? `Gate blocked${gateReason ? `: ${gateReason}` : ""}` : "Upstream dependency failed",
 					endedAt: Date.now(),
 					usage: emptyUsage(),
 				};
@@ -333,6 +376,11 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 
 			const ps = await executePhase(phase, state, deps, prior, () => deps.onProgress?.(state));
 			state.phases[phase.id] = ps;
+			if ((phase.type ?? "agent") === "gate" && ps.gate?.verdict === "block") {
+				gateBlocked = true;
+				gateReason = ps.gate.reason ?? "";
+				gateOutput = ps.output ?? "";
+			}
 			deps.persist?.(state);
 			deps.onProgress?.(state);
 		});
@@ -342,14 +390,19 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	const finalState = state.phases[fp.id];
 	const anyFailed = Object.values(state.phases).some((p) => p.status === "failed");
 
-	state.status = aborted ? "paused" : anyFailed ? "failed" : "completed";
+	state.status = aborted ? "paused" : gateBlocked ? "blocked" : anyFailed ? "failed" : "completed";
 	deps.persist?.(state);
 	deps.onProgress?.(state);
 
+	let finalOutput = finalState?.output ?? "(no output)";
+	if (gateBlocked && (!finalState || finalState.status === "skipped")) {
+		finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
+	}
+
 	const totalUsage = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
 	return {
 		state,
-		finalOutput: finalState?.output ?? "(no output)",
+		finalOutput,
 		ok: state.status === "completed",
 		totalUsage,
 	};

package/extensions/schema.ts

@@ -90,6 +90,88 @@ export type Phase = Static<typeof PhaseSchema>;
 export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
 
+// ---------------------------------------------------------------------------
+// Shorthand (non-DAG) specs — subagent-style ergonomics
+// ---------------------------------------------------------------------------
+//
+// For simple delegations you should not have to author a phases DAG. A
+// shorthand spec mirrors the subagent tool's modes and is desugared into a
+// full Taskflow before validation/execution:
+//
+//   { task, agent? }                  → one `agent` phase           (single)
+//   { tasks: [{task, agent?}, ...] }  → one `parallel` phase        (parallel)
+//   { chain: [{task, agent?}, ...] }  → sequential `agent` phases   (chain)
+//
+// Chain steps reference the prior step's output with {previous.output}, exactly
+// like the subagent tool's {previous} placeholder.
+
+export interface ShorthandStep {
+	agent?: string;
+	task: string;
+}
+
+/** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
+export function isShorthand(def: unknown): boolean {
+	if (typeof def !== "object" || def === null) return false;
+	const d = def as Record<string, unknown>;
+	if (Array.isArray(d.phases)) return false;
+	return Array.isArray(d.chain) || Array.isArray(d.tasks) || typeof d.task === "string";
+}
+
+function readStep(s: unknown): ShorthandStep {
+	if (typeof s === "string") return { task: s };
+	if (s && typeof s === "object") {
+		const o = s as Record<string, unknown>;
+		return { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+	}
+	return { task: "" };
+}
+
+/**
+ * Desugar a shorthand spec into a full Taskflow DAG. Throws if no recognizable
+ * shorthand field is present. Carries through optional name/description/
+ * concurrency/agentScope/args.
+ */
+export function desugar(def: unknown): Taskflow {
+	if (typeof def !== "object" || def === null) throw new Error("Shorthand spec must be an object");
+	const d = def as Record<string, unknown>;
+
+	const meta: Partial<Taskflow> = {};
+	if (typeof d.description === "string") meta.description = d.description;
+	if (typeof d.concurrency === "number") meta.concurrency = d.concurrency;
+	if (d.agentScope === "user" || d.agentScope === "project" || d.agentScope === "both") meta.agentScope = d.agentScope;
+	if (d.args && typeof d.args === "object") meta.args = d.args as Taskflow["args"];
+	const nameOf = (fallback: string) => (typeof d.name === "string" && d.name.trim() ? d.name.trim() : fallback);
+
+	// chain → sequential agent phases
+	if (Array.isArray(d.chain) && d.chain.length > 0) {
+		const steps = d.chain.map(readStep);
+		const phases: Phase[] = steps.map((s, i) => {
+			const phase: Phase = { id: `step${i + 1}`, type: "agent", task: s.task };
+			if (s.agent) phase.agent = s.agent;
+			if (i > 0) phase.dependsOn = [`step${i}`];
+			if (i === steps.length - 1) phase.final = true;
+			return phase;
+		});
+		return { name: nameOf("chain"), ...meta, phases };
+	}
+
+	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent
+	if (Array.isArray(d.tasks) && d.tasks.length > 0) {
+		const branches: ParallelTask[] = d.tasks.map(readStep).map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
+		return { name: nameOf("parallel"), ...meta, phases: [{ id: "parallel", type: "parallel", branches, final: true }] };
+	}
+
+	// single task → one agent phase
+	if (typeof d.task === "string") {
+		const phase: Phase = { id: "main", type: "agent", task: d.task, final: true };
+		if (typeof d.agent === "string") phase.agent = d.agent;
+		return { name: nameOf("task"), ...meta, phases: [phase] };
+	}
+
+	throw new Error("Shorthand spec needs one of: 'task' (single), 'tasks' (parallel), or 'chain' (sequential)");
+}
+
 // ---------------------------------------------------------------------------
 // Validation (beyond schema: DAG integrity, phase-type requirements)
 // ---------------------------------------------------------------------------

package/extensions/store.ts

@@ -37,6 +37,8 @@ export interface PhaseState {
 	subProgress?: { done: number; total: number; running: number; failed: number };
 	/** Latest activity line from the running subagent(s). */
 	liveText?: string;
+	/** Gate verdict (gate phases only). */
+	gate?: { verdict: "pass" | "block"; reason?: string };
 }
 
 export interface RunState {
@@ -44,7 +46,7 @@ export interface RunState {
 	flowName: string;
 	def: Taskflow;
 	args: Record<string, unknown>;
-	status: "running" | "completed" | "failed" | "paused";
+	status: "running" | "completed" | "failed" | "paused" | "blocked";
 	phases: Record<string, PhaseState>;
 	createdAt: number;
 	updatedAt: number;
@@ -112,7 +114,7 @@ export function saveFlow(
 	def: Taskflow,
 	scope: "user" | "project" = "project",
 ): { filePath: string } {
-	const dir = scope === "user" ? userFlowsDir() : findProjectFlowsDir(cwd, true)!;
+	const dir = scope === "user" ? userFlowsDir() : (findProjectFlowsDir(cwd, true) ?? path.join(cwd, ".pi", "taskflows"));
 	fs.mkdirSync(dir, { recursive: true });
 	const safe = def.name.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(dir, `${safe}.json`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -36,7 +36,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/schema.test.ts test/runtime.test.ts",
+    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/schema.test.ts test/runtime.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/render.test.ts test/desugar.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
   },
   "pi": {

package/skills/taskflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskflow
-description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use whenever a request spans a whole project or many items — deeply exploring / 探索 / auditing / 审计 / analyzing a codebase, reviewing or migrating many files or modules in parallel, cross-checked/adversarial review, codebase-wide research, or any repeatable orchestration you want to save and rerun. Prefer this over ad-hoc parallel subagents when the work has multiple phases or dynamic fan-out over a discovered list. Not for a single delegated task — use the subagent tool for that.
+description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use whenever a request spans a whole project or many items — deeply exploring / 探索 / auditing / 审计 / analyzing a codebase, reviewing or migrating many files or modules in parallel, cross-checked/adversarial review, codebase-wide research, or any repeatable orchestration you want to save and rerun. Prefer this over ad-hoc parallel subagents when the work has multiple phases or dynamic fan-out over a discovered list. Also supports subagent-style shorthand (single / parallel / chain) for simple non-DAG delegations you want tracked, resumable, or saveable.
 ---
 
 # Taskflow
@@ -16,7 +16,36 @@ the final answer — not every step's transcript.
 - You want **cross-checked / adversarial review** before reporting.
 - You want a **repeatable** orchestration saved as a `/tf:<name>` command.
 
-For a single delegated task, use the `subagent` tool instead.
+For a single quick delegation you can use the **shorthand modes** below (no DSL),
+or the plain `subagent` tool. Use the shorthand when you want the run tracked,
+resumable, or saveable as a `/tf` command.
+
+## Shorthand (non-DAG) — like the subagent tool
+
+Skip the DSL entirely for simple delegations. The runtime desugars these into a
+proper flow, so you still get progress, persistence, resume, and `save`.
+
+```jsonc
+// single  — one agent, one task
+{ "task": "Summarize the architecture of src/", "agent": "explorer" }
+
+// parallel — run several tasks at once, outputs merged
+{ "tasks": [
+  { "task": "Audit auth in src/api", "agent": "analyst" },
+  { "task": "Audit input validation in src/api", "agent": "analyst" }
+] }
+
+// chain — run sequentially; reference the prior step with {previous.output}
+{ "chain": [
+  { "task": "List the public API of src/lib", "agent": "scout" },
+  { "task": "Write docs for:\n{previous.output}", "agent": "writer" }
+] }
+```
+
+- `agent` is optional (defaults to the first available agent).
+- Add `name` to label the run (and to `save` it as a `/tf:<name>` command).
+- Precedence if several are given: `chain` > `tasks` > `task`.
+- You can pass these as top-level tool params **or** inside `define`.
 
 ## How to author a taskflow
 
@@ -55,9 +84,29 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `agent` | one subagent runs `task` |
 | `parallel` | run `branches[]` concurrently |
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
-| `gate` | quality/review step (a focused agent pass) |
+| `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
 
+### Gate phases (quality control)
+
+A `gate` phase runs an agent to review upstream output and can **block the rest
+of the workflow**. End the gate task's instructions by asking the agent to emit a
+verdict the runtime can read:
+
+- a final line `VERDICT: PASS` or `VERDICT: BLOCK` (also accepts OK/FAIL/STOP/REJECT/HALT), or
+- JSON like `{"continue": false, "reason": "missing auth checks"}` / `{"verdict": "block", "reason": "..."}`
+
+On **BLOCK**, downstream phases are skipped and the run ends as `blocked` with the
+reason surfaced. Ambiguous output **fails open** (treated as PASS) so a gate never
+halts the flow by accident. Example gate task:
+
+```
+Review the audit results below. If any endpoint is missing auth, end with
+"VERDICT: BLOCK" and a one-line reason; otherwise end with "VERDICT: PASS".
+
+{steps.audit.output}
+```
+
 ### Interpolation
 
 - `{args.X}` — invocation argument