pi-taskflow 0.0.4 → 0.0.6

package/extensions/schema.ts

@@ -12,10 +12,11 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce"] as const;
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow"] as const;
 export type PhaseType = (typeof PHASE_TYPES)[number];
 
 export const OUTPUT_FORMATS = ["text", "json"] as const;
+export const JOIN_MODES = ["all", "any"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -25,6 +26,29 @@ const ParallelTaskSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/** Declarative retry policy for a phase's subagent call(s). */
+const RetrySchema = Type.Object(
+	{
+		max: Type.Number({ description: "Max retry attempts after the first try (>= 0)" }),
+		backoffMs: Type.Optional(Type.Number({ description: "Base delay between attempts, in ms", default: 0 })),
+		factor: Type.Optional(
+			Type.Number({ description: "Backoff multiplier per attempt (1 = fixed, 2 = exponential)", default: 1 }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+/** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
+const BudgetSchema = Type.Object(
+	{
+		maxUSD: Type.Optional(Type.Number({ description: "Halt the run once accumulated cost exceeds this many USD" })),
+		maxTokens: Type.Optional(
+			Type.Number({ description: "Halt the run once accumulated input+output tokens exceed this" }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 const PhaseSchema = Type.Object(
 	{
 		id: Type.String({ description: "Unique phase identifier (referenced via {steps.<id>.output})" }),
@@ -46,7 +70,28 @@ const PhaseSchema = Type.Object(
 			Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" }),
 		),
 
+		// sub-workflow (flow)
+		use: Type.Optional(Type.String({ description: "[flow] Name of a saved taskflow to run as this phase" })),
+		with: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description: "[flow] Args passed to the sub-flow (string values support interpolation)",
+			}),
+		),
+
 		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
+		join: Type.Optional(
+			StringEnum(JOIN_MODES, {
+				description: "Dependency join: 'all' (default) waits for every dep; 'any' runs as soon as one dep completes",
+				default: "all",
+			}),
+		),
+		when: Type.Optional(
+			Type.String({
+				description:
+					"Conditional guard: skip this phase unless the expression is truthy. Supports {refs} and == != < > <= >= && || ! ()",
+			}),
+		),
+		retry: Type.Optional(RetrySchema),
 		output: Type.Optional(StringEnum(OUTPUT_FORMATS, { description: "Parse output as text or json", default: "text" })),
 		model: Type.Optional(Type.String({ description: "Model override for this phase" })),
 		thinking: Type.Optional(Type.String({ description: "Thinking level override for this phase" })),
@@ -77,6 +122,7 @@ export const TaskflowSchema = Type.Object(
 		version: Type.Optional(Type.Number({ default: 1 })),
 		args: Type.Optional(Type.Record(Type.String(), ArgSpecSchema, { description: "Declared invocation arguments" })),
 		concurrency: Type.Optional(Type.Number({ description: "Default max concurrent subagents", default: 8 })),
+		budget: Type.Optional(BudgetSchema),
 		agentScope: Type.Optional(
 			StringEnum(["user", "project", "both"] as const, { description: "Agent discovery scope", default: "user" }),
 		),
@@ -89,6 +135,9 @@ export type ParallelTask = Static<typeof ParallelTaskSchema>;
 export type Phase = Static<typeof PhaseSchema>;
 export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
+export type RetryPolicy = Static<typeof RetrySchema>;
+export type Budget = Static<typeof BudgetSchema>;
+export type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
 // Shorthand (non-DAG) specs — subagent-style ergonomics
@@ -227,6 +276,25 @@ export function validateTaskflow(def: unknown): ValidationResult {
 			if (!p.from || p.from.length === 0) errors.push(`Phase '${p.id}' (reduce) requires 'from'`);
 			if (!p.task) errors.push(`Phase '${p.id}' (reduce) requires 'task'`);
 		}
+		if (type === "flow") {
+			if (!p.use) errors.push(`Phase '${p.id}' (flow) requires 'use' (a saved flow name)`);
+		}
+		if (p.retry) {
+			if (typeof p.retry.max !== "number" || p.retry.max < 0) {
+				errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);
+			} else if (p.retry.max > 20) {
+				errors.push(`Phase '${p.id}': retry.max must be <= 20`);
+			}
+			if (p.retry.backoffMs !== undefined && (p.retry.backoffMs < 0 || p.retry.backoffMs > 60000)) {
+				errors.push(`Phase '${p.id}': retry.backoffMs must be between 0 and 60000`);
+			}
+			if (p.retry.factor !== undefined && (p.retry.factor < 1 || p.retry.factor > 10)) {
+				errors.push(`Phase '${p.id}': retry.factor must be between 1 and 10`);
+			}
+		}
+		if (p.join && !JOIN_MODES.includes(p.join as JoinMode)) {
+			errors.push(`Phase '${p.id}': unknown join mode '${p.join}'`);
+		}
 	}
 
 	// dependsOn / from references must exist
@@ -247,7 +315,7 @@ export function validateTaskflow(def: unknown): ValidationResult {
 	}
 
 	// Exactly handle final-phase resolution lazily (0 finals => last phase is final)
-	const finals = (flow.phases as Phase[]).filter((p) => p.final);
+	const finals = (flow.phases as Phase[]).filter((p) => p?.final);
 	if (finals.length > 1) errors.push(`Only one phase may be marked 'final' (found ${finals.length})`);
 
 	return { ok: errors.length === 0, errors };
@@ -341,3 +409,18 @@ export function topoLayers(phases: Phase[]): Phase[][] {
 export function finalPhase(phases: Phase[]): Phase {
 	return phases.find((p) => p.final) ?? phases[phases.length - 1];
 }
+
+/**
+ * Apply a flow's declared arg defaults over the provided values, then pass
+ * through any extra provided keys. Shared by the tool entrypoint (index) and the
+ * sub-flow (`flow`) phase (runtime).
+ */
+export function resolveArgs(def: Taskflow, provided?: Record<string, unknown>): Record<string, unknown> {
+	const args: Record<string, unknown> = {};
+	for (const [key, spec] of Object.entries(def.args ?? {})) {
+		if (provided && key in provided) args[key] = provided[key];
+		else if (spec.default !== undefined) args[key] = spec.default;
+	}
+	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
+	return args;
+}

package/extensions/store.ts

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { Taskflow } from "./schema.ts";
-import type { UsageStats } from "./runner.ts";
+import type { UsageStats } from "./usage.ts";
 
 export interface SavedFlow {
 	name: string;
@@ -39,6 +39,12 @@ export interface PhaseState {
 	liveText?: string;
 	/** Gate verdict (gate phases only). */
 	gate?: { verdict: "pass" | "block"; reason?: string };
+	/** Total subagent attempts incl. retries (when > calls, a retry happened). */
+	attempts?: number;
+	/** True when a map/parallel fan-out was cut short by the budget cap. */
+	budgetTruncated?: boolean;
+	/** Human-in-the-loop outcome (approval phases only). */
+	approval?: { decision: "approve" | "reject" | "edit"; note?: string; auto?: boolean };
 }
 
 export interface RunState {
@@ -118,7 +124,7 @@ export function saveFlow(
 	fs.mkdirSync(dir, { recursive: true });
 	const safe = def.name.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(dir, `${safe}.json`);
-	fs.writeFileSync(filePath, `${JSON.stringify(def, null, 2)}\n`, "utf-8");
+	writeFileAtomic(filePath, `${JSON.stringify(def, null, 2)}\n`);
 	return { filePath };
 }
 
@@ -138,7 +144,7 @@ export function saveRun(state: RunState): void {
 	const dir = runsDir(state.cwd);
 	fs.mkdirSync(dir, { recursive: true });
 	state.updatedAt = Date.now();
-	fs.writeFileSync(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2), "utf-8");
+	writeFileAtomic(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2));
 }
 
 export function loadRun(cwd: string, runId: string): RunState | null {
@@ -174,3 +180,23 @@ export function listRuns(cwd: string, limit = 20): RunState[] {
 export function hashInput(...parts: string[]): string {
 	return crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
 }
+
+/**
+ * Write a file atomically: write to a unique temp file in the same directory,
+ * then rename over the target (rename is atomic on the same filesystem). Prevents
+ * a crash or concurrent write from leaving a half-written, corrupt JSON file.
+ */
+function writeFileAtomic(filePath: string, data: string): void {
+	const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	try {
+		fs.writeFileSync(tmp, data, "utf-8");
+		fs.renameSync(tmp, filePath);
+	} catch (e) {
+		try {
+			if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+		} catch {
+			/* ignore cleanup failure */
+		}
+		throw e;
+	}
+}

package/extensions/usage.ts

@@ -0,0 +1,42 @@
+/**
+ * Usage accounting — token/cost stats shared across the runner (producer),
+ * runtime (aggregation), store (persistence), and render (display).
+ *
+ * Kept in its own leaf module so persistence and TUI don't have to depend on
+ * the process-spawning layer (`runner.ts`) just for these types/helpers.
+ */
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+/** Sum numeric usage fields across runs. `contextTokens` is intentionally excluded (it is a point-in-time gauge, not additive). */
+export function aggregateUsage(usages: UsageStats[]): UsageStats {
+	const total = emptyUsage();
+	for (const u of usages) {
+		total.input += u.input;
+		total.output += u.output;
+		total.cacheRead += u.cacheRead;
+		total.cacheWrite += u.cacheWrite;
+		total.cost += u.cost;
+		total.turns += u.turns;
+	}
+	return total;
+}
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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/runner.test.ts test/store.test.ts test/agents.test.ts test/render.test.ts test/desugar.test.ts",
+    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.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

@@ -86,6 +86,71 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
 | `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
+| `approval` | **human-in-the-loop** pause: ask a person to approve / reject / edit before continuing |
+| `flow` | run a **saved sub-flow** (by `use`) as a single phase — composition/reuse |
+
+### Control-flow fields (any phase)
+
+| field | meaning |
+|-------|---------|
+| `when` | conditional guard — skip the phase unless the expression is truthy. Supports `{refs}`, `== != < > <= >=`, `&& \|\| !`, parentheses, quoted strings/numbers. Parse errors fail **open** (phase runs). |
+| `join` | dependency join: `"all"` (default — wait for every dep) or `"any"` (OR-join — run as soon as one dep completes). |
+| `retry` | `{ "max": N, "backoffMs": ms, "factor": k }` — retry a failing subagent up to N times; delay is `backoffMs * factor^attempt` (`factor:1`=fixed, `2`=exponential). |
+
+### Conditional routing (when + gate/branches)
+
+Pair `when` with an upstream phase that emits a decision to build real if/else
+routing. Use `join: "any"` on the merge phase so it runs whichever branch fired:
+
+```jsonc
+{ "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
+  "task": "Classify the task. Output ONLY {\"route\":\"deep\"} or {\"route\":\"quick\"}." },
+{ "id": "deep",  "when": "{steps.triage.json.route} == deep",  "dependsOn": ["triage"], "agent": "analyst", "task": "..." },
+{ "id": "quick", "when": "{steps.triage.json.route} == quick", "dependsOn": ["triage"], "agent": "executor_fast", "task": "..." },
+{ "id": "report", "type": "reduce", "from": ["deep","quick"], "join": "any",
+  "dependsOn": ["deep","quick"], "agent": "writer", "task": "...", "final": true }
+```
+
+> `when` should reference **upstream** (`dependsOn`) phases — a ref to a phase
+> that hasn't completed resolves empty and the guard is treated as false.
+
+### Approval phases (human-in-the-loop)
+
+An `approval` phase pauses the run and asks the operator to **Approve / Reject /
+Edit**. Distinct from `gate` (which is an *agent* reviewing): this is a *human*
+deciding. The (interpolated) `task` is the prompt shown.
+
+- **Approve** → continue; the phase output is `(approve)`.
+- **Reject** → halt the flow (same mechanism as a blocking gate).
+- **Edit** → the typed note becomes this phase's `output`, so you can inject
+  guidance mid-run: reference it downstream with `{steps.<id>.output}`.
+- **Non-interactive** runs (headless/CI/print mode) **auto-approve** and record it.
+
+```jsonc
+{ "id": "checkpoint", "type": "approval", "dependsOn": ["plan"],
+  "task": "Review the plan above before the expensive fan-out. Approve, reject, or add guidance." }
+```
+
+### Sub-flows (composition)
+
+A `flow` phase runs another **saved** taskflow by name and bubbles up its final
+output. Pass args via `with` (string values interpolate). Recursion is detected
+and rejected.
+
+```jsonc
+{ "id": "research", "type": "flow", "use": "deep-research",
+  "with": { "topic": "{item}" }, "dependsOn": ["plan"] }
+```
+
+### Budget (cost / token caps)
+
+Add a run-wide ceiling at the top level. When accumulated cost/tokens exceed it,
+remaining phases are skipped (and an in-flight `map`/`parallel` stops spawning
+new items); the run ends as `blocked`.
+
+```jsonc
+{ "name": "...", "budget": { "maxUSD": 1.50, "maxTokens": 2000000 }, "phases": [ ... ] }
+```
 
 ### Gate phases (quality control)
 
@@ -123,6 +188,20 @@ Review the audit results below. If any endpoint is missing auth, end with
 3. Reference upstream results explicitly with `{steps.ID...}` and set `dependsOn`.
 4. Mark the result-bearing phase with `"final": true` (else the last phase wins).
 
+## Configuration
+
+For the full set of knobs — per-phase `model`/`thinking`/`tools`/`cwd`, the
+two-level concurrency model, model/thinking/tools resolution precedence,
+`agentScope` & agent discovery, `settings.json` overrides, environment
+variables, and storage paths — read `configuration.md` (next to this file).
+
+Quick reference:
+
+- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`.
+- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `final`.
+- **Precedence (model/thinking/tools):** phase value → `settings.subagents.agentOverrides[agent]` → agent frontmatter → global/default.
+- **Concurrency:** same-layer phases use `flow.concurrency`; a `map`/`parallel` phase uses `phase.concurrency ?? flow.concurrency ?? 8`.
+
 ## Actions
 
 - `action: "run"` — run inline `define` or a saved `name` (with optional `args`).

package/skills/taskflow/configuration.md

@@ -0,0 +1,275 @@
+# Taskflow Configuration Reference
+
+Every knob you can set on a taskflow, where it lives, and how the values are
+resolved. Read this when you need fine control over models, concurrency, agent
+discovery, working directories, tool restrictions, or storage.
+
+Configuration lives in **five layers**, from most local to most global:
+
+| Layer | Where | Sets |
+|-------|-------|------|
+| Phase | a phase object in the DSL | per-step model/thinking/tools/cwd/output/concurrency |
+| Flow | the top-level DSL object | name, args, default concurrency, agent scope |
+| Agent | `~/.pi/agent/agents/*.md`, `.pi/agents/*.md` frontmatter | per-agent default model/thinking/tools + system prompt |
+| Settings | `~/.pi/agent/settings.json` | `subagents.agentOverrides`, global thinking |
+| Environment | shell env | `PI_TASKFLOW_PI_BIN` |
+
+---
+
+## 1. Flow-level options
+
+Top-level keys of the taskflow definition object.
+
+```jsonc
+{
+  "name": "audit-endpoints",        // required — also becomes /tf:<name> when saved
+  "description": "Audit API auth",  // shown in /tf list and the command palette
+  "concurrency": 8,                 // default max concurrent subagents (default: 8)
+  "agentScope": "user",             // user | project | both (default: user)
+  "args": { /* see §3 */ },
+  "phases": [ /* see §2 */ ]        // required, at least one phase
+}
+```
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `name` | string | — | **Required.** Saved as `/tf:<name>`. |
+| `description` | string | — | Surfaced in `/tf list` and the slash-command. |
+| `concurrency` | number | `8` | Default fan-out / same-layer parallelism cap. See §4. |
+| `agentScope` | `user`\|`project`\|`both` | `user` | Which agent dirs to load. See §6. |
+| `args` | record | `{}` | Declared invocation arguments. See §3. |
+| `phases` | array | — | **Required.** The phase DAG. See §2. |
+| `version` | number | `1` | ⚠️ Declared in schema but **not yet used** by the runtime. |
+
+---
+
+## 2. Phase-level options
+
+Keys of each object in `phases[]`. Some only apply to specific `type`s.
+
+```jsonc
+{
+  "id": "audit",            // required, unique — referenced via {steps.audit.output}
+  "type": "map",            // agent | parallel | map | gate | reduce (default: agent)
+  "agent": "analyst",       // agent name to run this phase
+  "task": "Audit {item.route}…",
+  "dependsOn": ["discover"],// DAG edges
+  "over": "{steps.discover.json}",  // [map] array to fan out over
+  "as": "item",             // [map] loop var name (default: item)
+  "branches": [ /* … */ ],  // [parallel] static task list
+  "from": ["audit"],        // [reduce] phase ids to aggregate
+  "output": "json",         // text | json (default: text)
+  "model": "claude-sonnet-4-5",   // per-phase model override
+  "thinking": "high",       // per-phase thinking override
+  "tools": ["read","bash"], // restrict tools for this phase's subagent
+  "cwd": "packages/api",    // working directory for this phase's subagent
+  "concurrency": 4,         // [map/parallel] fan-out cap for THIS phase
+  "final": true             // mark this phase's output as the workflow result
+}
+```
+
+| Key | Applies to | Default | Notes |
+|-----|-----------|---------|-------|
+| `id` | all | — | **Required, unique.** Used in `{steps.<id>…}`. |
+| `type` | all | `agent` | One of the 5 phase types. |
+| `agent` | all | first available | Agent name; resolved from the scoped pool. |
+| `task` | agent, gate, map, reduce | — | Prompt; supports interpolation. Required for these types. |
+| `over` | map | — | **Required for map.** Must resolve to an array. |
+| `as` | map | `item` | Loop variable bound per item. |
+| `branches` | parallel | — | **Required for parallel.** `[{task, agent?}]`. |
+| `from` | reduce | — | **Required for reduce.** Phase ids whose outputs are aggregated. |
+| `dependsOn` | all | `[]` | DAG edges. `from` also implies a dependency. |
+| `output` | all | `text` | `json` parses output so `{steps.id.json}` / map `over` work. |
+| `model` | all | agent/global | Per-phase model override. See §5. |
+| `thinking` | all | agent/global | Per-phase thinking level. See §5. |
+| `tools` | all | agent default | Whitelist of tools for the subagent. See §5. |
+| `cwd` | all | flow cwd | Run this phase's subagent in a different directory. |
+| `concurrency` | map, parallel | flow concurrency | Fan-out cap for this phase only. See §4. |
+| `final` | all | last phase | Exactly one phase may be `final`; its output is returned. |
+| `optional` | all | `false` | ⚠️ Declared in schema but **not yet enforced** — a failed phase still skips downstream. |
+
+---
+
+## 3. Declaring & passing arguments
+
+Declare arguments on the flow, then reference them with `{args.X}`.
+
+```jsonc
+"args": {
+  "dir":   { "default": "src", "description": "Directory to scan" },
+  "depth": { "default": 2 },
+  "token": { "required": true, "description": "API token" }
+}
+```
+
+| Field | Notes |
+|-------|-------|
+| `default` | Used when the caller omits the arg. |
+| `description` | Documentation only. |
+| `required` | ⚠️ Declared but **not enforced** at runtime — treat as documentation for now. |
+
+**Resolution:** for each declared arg, the provided value wins, else its
+`default`. Any extra provided keys are also passed through (so undeclared args
+still reach `{args.X}`).
+
+**Passing args:**
+
+```
+/tf run audit-endpoints {"dir":"packages/api"}     # JSON
+/tf run audit-endpoints dir=packages/api depth=3   # key=value pairs
+/tf run audit-endpoints packages/api               # single positional → first declared arg
+```
+
+Via the tool: `{ "action": "run", "name": "audit-endpoints", "args": { "dir": "packages/api" } }`.
+
+---
+
+## 4. Concurrency model
+
+There are **two independent concurrency limits**:
+
+1. **Same-layer parallelism** — phases with no dependency between them sit in the
+   same topological layer and run concurrently, bounded by **`flow.concurrency`**
+   (default `8`).
+2. **Fan-out within a `map`/`parallel` phase** — bounded by
+   **`phase.concurrency ?? flow.concurrency ?? 8`**.
+
+```jsonc
+{
+  "concurrency": 6,                 // ≤6 sibling phases run at once
+  "phases": [
+    { "id": "scan", "type": "map", "over": "{steps.list.json}",
+      "concurrency": 3,             // …but this map only fans out 3 at a time
+      "task": "…", "dependsOn": ["list"] }
+  ]
+}
+```
+
+Set a low `phase.concurrency` to protect rate-limited models or heavy bash work;
+keep `flow.concurrency` higher to let independent phases overlap.
+
+---
+
+## 5. Model, thinking & tools resolution
+
+For any phase, the effective value is resolved in this **precedence order**
+(first defined wins):
+
+| Setting | Precedence (high → low) |
+|---------|-------------------------|
+| **model** | `phase.model` → `settings.agentOverrides[agent].model` → agent frontmatter `model` → pi default |
+| **thinking** | `phase.thinking` → `settings.agentOverrides[agent].thinking` → agent frontmatter `thinking` → `settings` global thinking → pi default |
+| **tools** | `phase.tools` → `settings.agentOverrides[agent].tools` → agent frontmatter `tools` → all tools |
+
+Notes:
+- `tools` is a **whitelist** passed as `--tools a,b,c`. Omit it to allow all.
+- Each phase runs as an isolated process:
+  `pi --mode json -p --no-session [--model …] [--thinking …] [--tools …] [--append-system-prompt <agent>] "Task: …"`.
+- The agent's markdown body becomes the subagent's appended system prompt.
+
+---
+
+## 6. Agent discovery & scope
+
+`flow.agentScope` controls which agent directories are loaded:
+
+| Scope | Loads from |
+|-------|-----------|
+| `user` (default) | `~/.pi/agent/agents/*.md` |
+| `project` | nearest `.pi/agents/*.md` found walking up from cwd |
+| `both` | user **then** project (project overrides on name collision) |
+
+- Agents are `.md` files with frontmatter `name` + `description` (required), plus
+  optional `model`, `thinking`, `tools`. The body is the system prompt.
+- Reference agents in phases by their `name`. An unknown name fails that phase
+  with the list of available agents.
+- If a phase omits `agent`, the **first discovered agent** is used.
+
+---
+
+## 7. settings.json
+
+Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "subagents": {
+    "globalThinking": "medium",          // fallback thinking for all subagents
+    "agentOverrides": {
+      "analyst": { "model": "claude-sonnet-4-5", "thinking": "high" },
+      "scout":   { "tools": ["read", "bash", "grep"] }
+    }
+  },
+  "defaultThinkingLevel": "low"          // used if subagents.globalThinking is absent
+}
+```
+
+- `subagents.agentOverrides` — per-agent overrides applied at discovery; they beat
+  agent frontmatter but lose to a phase-level value (see §5).
+- `subagents.globalThinking` (or top-level `defaultThinkingLevel`) — global
+  thinking fallback.
+
+---
+
+## 8. Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `PI_TASKFLOW_PI_BIN` | Override the `pi` binary used to spawn subagents. Used by tests and unusual launch setups (e.g. `PI_TASKFLOW_PI_BIN=pi`). Normally auto-detected. |
+
+---
+
+## 9. Storage & file locations
+
+| What | Path | Commit? |
+|------|------|---------|
+| User-scoped flow | `~/.pi/agent/taskflows/<name>.json` | personal |
+| Project-scoped flow | `<nearest .pi>/taskflows/<name>.json` | ✅ commit to share |
+| Run state (resume) | `<project .pi>/taskflows/runs/<runId>.json` | ❌ gitignore |
+
+- `action: "save"` takes `scope: "project"` (default) or `"user"`.
+- Saved flows auto-register as `/tf:<name>` (immediately for the current session,
+  and on future `session_start`).
+- Project flows override user flows on a name collision.
+- Add `.pi/taskflows/runs/` to `.gitignore`.
+
+---
+
+## 10. Quick recipes
+
+**Pin a strong model only for the review gate:**
+```jsonc
+{ "id": "review", "type": "gate", "agent": "reviewer",
+  "model": "claude-opus-4", "thinking": "high",
+  "task": "…\nVERDICT:", "dependsOn": ["audit"] }
+```
+
+**Sandbox a phase to read-only in a subdirectory:**
+```jsonc
+{ "id": "scan", "type": "agent", "agent": "scout",
+  "cwd": "packages/api", "tools": ["read", "grep", "ls"],
+  "task": "List route files. Output ONLY a JSON array.", "output": "json" }
+```
+
+**Throttle a rate-limited fan-out:**
+```jsonc
+{ "id": "summarize", "type": "map", "over": "{steps.scan.json}",
+  "concurrency": 2, "agent": "writer",
+  "task": "Summarize {item.file}.", "dependsOn": ["scan"] }
+```
+
+**Project-only agents:**
+```jsonc
+{ "name": "ci-audit", "agentScope": "project", "phases": [ /* … */ ] }
+```
+
+---
+
+## Caveats (declared but not yet enforced)
+
+These keys validate but the runtime does **not** act on them yet — don't rely on
+them for behavior:
+
+- `phase.optional` — a failed phase still marks downstream phases as skipped.
+- `arg.required` — missing required args are not rejected.
+- `flow.version` — informational only.