pi-taskflow 0.0.4 → 0.0.5

package/README.md

@@ -1,94 +1,238 @@
 # pi-taskflow
 
+[![npm](https://img.shields.io/npm/v/pi-taskflow.svg)](https://www.npmjs.com/package/pi-taskflow)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Pi coding agent](https://img.shields.io/badge/for-Pi%20coding%20agent-7c3aed.svg)](https://pi.dev)
+
 > Lightweight workflow orchestration for the [Pi coding agent](https://pi.dev).
 
-Describe a multi-phase workflow once; let a deterministic runtime orchestrate
-isolated subagents to execute it. Intermediate results stay **out of your main
-context** — only the final answer comes back. Inspired by Claude Code's Dynamic
-Workflows, rebuilt as a lightweight, declarative pi extension.
+**Orchestrate your Pi subagents. Not by prompting — by declaring.**
+
+If you've used the built-in subagent tool's `task` / `tasks` / `chain`, you
+already know the shorthand — your runs just get tracked, resumable, and
+saveable as a one-word `/tf:<name>` command.
 
 ```bash
 pi install npm:pi-taskflow
 ```
 
+Fan out one subagent per item, gate the results with an adversarial review, and
+get back only the final report — none of the intermediate transcripts ever touch
+your conversation.
+
 ## Why
 
-`subagent` is great for a single delegated task. But when a job needs **many
-coordinated steps**, **fan-out over dozens of items**, **cross-checked review**,
-or a **repeatable** pipeline, you want orchestration — without bloating your
-conversation with every step's transcript.
+The built-in subagent tool is great for a single delegated task. But when a job
+needs many coordinated steps, fan-out over dozens of items, cross-checked review,
+or a repeatable pipeline, you want orchestration — without the intermediate
+transcripts eating your context window.
 
 `pi-taskflow` moves the plan into a small declarative definition. The runtime
 holds the DAG, the loops, and the intermediate results; your context receives
 only the final phase's output.
 
-| | `subagent` | `pi-taskflow` |
+| | `subagent` tool | `pi-taskflow` |
 |---|---|---|
 | Who drives | the model, turn by turn | the runtime, from a definition |
 | Intermediate results | in your context window | in the runtime (not your context) |
 | Reusable | re-described each time | saved as `/tf:<name>` |
 | Scale | a few tasks | dynamic `map` fan-out |
-| Resumable | no | yes (cross-session) |
+| Resumable | no | yes (cross-session, cached phases skip) |
+| Quality gates | no | `gate` phases with `VERDICT: BLOCK / PASS` |
+| Progress visibility | opaque while running | live DAG render with timing + cost |
+| Ergonomics | inline JSON each time | shorthand (`task`/`tasks`/`chain`) or DSL |
+
+## Show me
+
+Describe a pipeline once, then run it from a pi session by name:
+
+> `/tf:summarize-files dir=src`
+
+The runtime fans out one subagent per file, merges the summaries in a `reduce`
+phase, and returns only the final overview. Every intermediate transcript stays
+in the runtime — never in your context window. (Full definition in
+[Quickstart](#then-go-declarative) below.)
+
+## Quickstart
+
+### Shorthand: same effort as `subagent`, but tracked & resumable
+
+**Single task** — one agent, one job:
+
+```jsonc
+{ "task": "Summarize the architecture of src/", "agent": "explorer" }
+```
+
+**Parallel tasks** — fire several at once, outputs merge:
+
+```jsonc
+{ "tasks": [
+  { "task": "Audit auth in src/api",   "agent": "analyst" },
+  { "task": "Audit input validation in src/api", "agent": "analyst" }
+] }
+```
 
-## Concepts
+**Chain** — sequential, each step sees the previous one's output:
+
+```jsonc
+{ "chain": [
+  { "task": "List the public API of src/lib", "agent": "scout" },
+  { "task": "Write docs for:\n{previous.output}", "agent": "writer" }
+] }
+```
 
-A **taskflow** is a set of **phases** forming a DAG via `dependsOn`. Each phase
-delegates to a subagent (an isolated `pi` process). Phases in the same DAG layer
-run concurrently (bounded by `concurrency`).
+`agent` is optional (defaults to the first available agent). Add `name` to label
+the run and enable saving it as a reusable command.
 
-### Phase types
+Try it inline — tell the model something like:
 
-| type | meaning |
-|------|---------|
-| `agent` | one subagent runs `task` |
-| `parallel` | run `branches[]` concurrently |
-| `map` | fan out over an array — one subagent per item, `{item}` bound |
-| `gate` | quality/adversarial-review step |
-| `reduce` | aggregate several phases' outputs into one |
+> Run a chain: first explore the auth flow, then summarize findings.
 
-### Interpolation
+The model calls the `taskflow` tool; you get live progress, per-step timing,
+token cost, and a run record. Ask to `save` it and you get `/tf:<name>`.
 
-- `{args.X}` — invocation argument
-- `{steps.ID.output}` — a prior phase's text output
-- `{steps.ID.json}` / `{steps.ID.json.field}` — prior output parsed as JSON
-- `{item}` / `{item.field}` — current item inside a `map` phase
-- `{previous.output}` — the immediately-upstream phase output
+### Then go declarative
 
-## Example
+When your pipeline outgrows the shorthand — when you need dynamic fan-out,
+intermediate JSON routing, or quality gates — graduate to the full DSL:
 
 ```jsonc
 {
   "name": "summarize-files",
+  "description": "Discover files, summarize each, produce a report",
   "args": { "dir": { "default": "." } },
-  "concurrency": 4,
+  "concurrency": 8,
   "phases": [
     { "id": "discover", "type": "agent", "agent": "scout",
-      "task": "List source files under {args.dir}. Output ONLY a JSON array [{\"file\":\"\"}].",
+      "task": "List source files under {args.dir} (non-recursive).\nOutput ONLY a JSON array [{\"file\":\"\"}]. No prose.",
       "output": "json" },
-    { "id": "summarize", "type": "map", "over": "{steps.discover.json}", "as": "item",
-      "agent": "scout", "task": "Read {item.file} and summarize it in one sentence.",
+    { "id": "summarize", "type": "map",
+      "over": "{steps.discover.json}", "as": "item",
+      "agent": "scout",
+      "task": "Read {item.file} and give a one-sentence summary.",
       "dependsOn": ["discover"] },
-    { "id": "report", "type": "reduce", "from": ["summarize"], "agent": "writer",
+    { "id": "report", "type": "reduce", "from": ["summarize"],
+      "agent": "writer",
       "task": "Combine into a short overview:\n{steps.summarize.output}",
       "dependsOn": ["summarize"], "final": true }
   ]
 }
 ```
 
-## Usage
+What this does:
+
+1. **`discover`** — an agent lists every file in the directory and outputs a JSON array.
+2. **`summarize`** — a `map` fans out, spawning one subagent per file in parallel
+   (throttled to 8 concurrent). Each gets `{item.file}` bound to its file path.
+3. **`report`** — a `reduce` merges all summaries into one clean overview.
+
+Intermediate outputs never enter your context. The runtime owns them. You get
+only the final report back.
+
+Save it once → `/tf:summarize-files` forever.
 
-The model calls the `taskflow` tool; you can also drive it directly:
+## Watch it run
+
+This is the live progress render for a real run — the `self-improve` flow that
+writes and verifies its own test suites, caught here mid-block by a quality gate:
 
 ```
-/tf list                 # saved flows
-/tf run <name> [args]     # run a saved flow
-/tf show <name>           # print a definition
-/tf runs                  # recent run history
-/tf resume <runId>        # continue a paused/failed run (cached phases skipped)
-/tf:<name> [args]         # shortcut per saved flow
+⊗ taskflow self-improve  6/7 · blocked · $0.095
+    ✓ discover            agent   deepseek-v4-flash  10t ↑38k ↓6.7k $0.011
+  ┌ ✓ write-runner-tests  agent   claude-sonnet-4-6  10t ↑13 ↓6.6k $0.020
+  ├ ✓ write-store-tests   agent   claude-sonnet-4-6  10t ↑11 ↓10k $0.018
+  ├ ✓ write-agents-tests  agent   claude-sonnet-4-6  10t ↑28 ↓13k $0.030
+  └ ✓ fix-stability       agent   claude-sonnet-4-6  10t ↑13 ↓3.9k $0.012
+    ✓ verify              gate    BLOCK 3 type errors in test files  deepseek-v4-flash
+    ⊘ report              reduce  skipped · Gate blocked  ↳ fix-stability
 ```
 
-Tool actions: `run` (inline `define` or saved `name`), `save`, `resume`, `list`.
+**How to read it — the layout *is* the DAG:**
+
+- **Header** — `⊗` means the flow is blocked (a gate halted it); `6/7` phases
+  processed, aggregate cost `$0.095`.
+- **Status icons** — `✓` done, `◐` running, `✗` failed, `⊘` skipped, `○` pending.
+- **Rail `┌ ├ └`** — phases in the same DAG layer, running concurrently. The four
+  `write-*`/`fix-stability` tasks all fan out from `discover`. A blank gutter is
+  a single-phase layer.
+- **`↳`** — a long (layer-skipping) dependency. `report` depends on `verify` (the
+  adjacent layer, implied by position) *and* `fix-stability` two layers back, so
+  only that skip edge is annotated.
+- **Gate** — `verify` emitted `VERDICT: BLOCK`, so the runtime skipped `report`
+  and ended the run as `blocked`, surfacing the reason.
+- **Detail** — per phase: model, token counts (`↑`in `↓`out), cost, and timing.
+  Fan-out phases also show sub-task progress.
+
+## Phase types
+
+| type | meaning | required fields |
+|------|---------|-----------------|
+| `agent` | one subagent runs a single task | `task` |
+| `parallel` | run `branches[]` concurrently | `branches` (array of `{task, agent?}`) |
+| `map` | fan out over an array — one subagent per item, `{item}` bound | `over`, `task` |
+| `gate` | quality/review step that can **halt the flow** | `task` |
+| `reduce` | aggregate `from[]` phase outputs into one | `from`, `task` |
+
+Every phase needs `id`. Optional fields: `agent`, `dependsOn`, `output`,
+`model`, `thinking`, `tools`, `cwd`, `concurrency`, `final`, `optional`.
+
+### `output` format
+
+- `output: "text"` (default) — the raw subagent output.
+- `output: "json"` — the subagent output is parsed as JSON and exposed via
+  `{steps.ID.json}` / `{steps.ID.json.field}`. Set this on phases whose output
+  a downstream `map` or `reduce` needs to consume as structured data.
+
+There is no `output: "file"`. For file-based output, have the agent write to
+disk with a `write` tool call.
+
+### Gate phases (quality control)
+
+A `gate` 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` — last occurrence wins), 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) — a gate
+never halts the flow by accident.
+
+```
+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
+
+| placeholder | resolves to |
+|---|---|
+| `{args.X}` | invocation argument |
+| `{steps.ID.output}` | a prior phase's text output |
+| `{steps.ID.json}` | prior output parsed as JSON (or `{steps.ID.json.field}`) |
+| `{item}` / `{item.field}` | current item inside a `map` phase |
+| `{previous.output}` | the immediately-upstream phase output |
+
+## Commands
+
+Saved flows become CLI shortcuts. All commands work in the pi session:
+
+| Command | What it does |
+|---|---|
+| `/tf list` | List all saved flows |
+| `/tf run <name> [args]` | Run a saved flow (e.g. `/tf run summarize-files dir=src`) |
+| `/tf show <name>` | Print a flow's definition |
+| `/tf runs` | Browse recent run history (interactive TUI) |
+| `/tf resume <runId>` | Continue a paused/failed run — cached phases skip automatically |
+| `/tf:<name> [args]` | Shortcut — runs the flow in one tap |
+
+Tool actions (used by the model): `run` (inline `define` or saved `name`),
+`save`, `resume`, `list`.
 
 ## Storage
 
@@ -98,30 +242,70 @@ Tool actions: `run` (inline `define` or saved `name`), `save`, `resume`, `list`.
 .pi/taskflows/runs/<runId>.json    # run state (resume); gitignore this
 ```
 
+Agent discovery scope (set via `agentScope` in the flow definition):
+
+| value | discovers agents from |
+|---|---|
+| `"user"` (default) | `~/.pi/agent/agents/*.md` |
+| `"project"` | `.pi/agents/*.md` (walks up the tree) |
+| `"both"` | user + project; project wins on name collision |
+
 ## Agents
 
-Taskflow reuses your existing pi agents (`~/.pi/agent/agents/*.md`,
-`.pi/agents/*.md`) and honors `subagents.agentOverrides` in settings. Reference
-agents by `name`.
+Taskflow reuses your existing pi agent files (`~/.pi/agent/agents/*.md`,
+`.pi/agents/*.md`). Reference agents by `name` in a phase or shorthand.
+
+When running a phase, the runtime extracts the agent's `systemPrompt` from its
+`.md` frontmatter and passes it via `--append-system-prompt` (written to a temp
+file). Phase-level overrides for `model`, `thinking`, and `tools` are passed as
+`--model` / `--thinking` / `--tools` flags to the subagent invocation.
+
+Settings from `~/.pi/agent/settings.json` (the `subagents.agentOverrides` map)
+are honored, letting you tweak model, thinking, or tools per agent across all flows.
+
+## Status & limits
+
+- **v0.0.4** — DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
+  inline + saved flows, cross-session resume, live progress, isolated context.
+  Default `concurrency` is 8 (set on the flow; per-phase `concurrency` overrides
+  for that phase).
+- A run executes as one streaming tool call (live progress while it runs).
+- `map` requires the upstream phase to emit a JSON array (`output: "json"`).
+- Gate verdicts are **fail-open**: if the agent output contains no recognizable
+  verdict marker (`VERDICT: BLOCK/PASS/OK/FAIL/STOP/REJECT/HALT` or
+  `{continue: false}` / `{verdict: "block"}`), the gate passes. This prevents
+  an accidental missing verdict from blocking your workflow.
+
+### What it doesn't do (yet)
+
+- **No detached background execution.** A run needs the pi session to stay open.
+  True background execution is on the roadmap.
+- **No `output: "file"`.** Outputs are text/JSON only. Write files via agent
+  tool calls if needed.
+- **`map` requires a JSON array.** The `over` field must resolve to
+  `{steps.ID.json}` where the upstream phase emitted `output: "json"`. If the
+  source is a plain text list, wrap it in a single-agent phase that outputs JSON.
+- **Cycles are rejected at validation.** The DAG must be acyclic.
 
 ## Development
 
 ```bash
 npm install
 npm run typecheck
-node --experimental-strip-types --test test/interpolate.test.ts test/schema.test.ts test/runtime.test.ts
+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
 
 # real end-to-end (spawns live subagents; needs model access)
 PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts
 ```
 
-## Status & limits
+## Contributing
 
-- **v0.1** — DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
-  inline + saved flows, cross-session resume, live progress, isolated context.
-- A run executes as one streaming tool call (live progress while it runs). True
-  detached background execution is on the roadmap.
-- `map` requires the upstream phase to emit a JSON array (`output: "json"`).
+Contributions welcome! This is a young project — open an issue or PR on
+[GitHub](https://github.com/heggria/pi-taskflow). Tests live in `test/`, the
+runtime in `extensions/`.
 
 ## License
 

package/extensions/runtime.ts

@@ -366,16 +366,19 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 				return;
 			}
 
+			const startedAt = Date.now();
 			state.phases[phase.id] = {
 				...(state.phases[phase.id] ?? { id: phase.id }),
 				id: phase.id,
 				status: "running",
-				startedAt: Date.now(),
+				startedAt,
 			};
 			deps.onProgress?.(state);
 
 			const ps = await executePhase(phase, state, deps, prior, () => deps.onProgress?.(state));
-			state.phases[phase.id] = ps;
+			// Preserve the phase start time: executePhase returns a fresh PhaseState
+			// that omits startedAt (cached/resumed results carry their own).
+			state.phases[phase.id] = ps.startedAt ? ps : { ...ps, startedAt };
 			if ((phase.type ?? "agent") === "gate" && ps.gate?.verdict === "block") {
 				gateBlocked = true;
 				gateReason = ps.gate.reason ?? "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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",

package/skills/taskflow/SKILL.md

@@ -123,6 +123,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), `agentScope` (user|project|both), `args`.
+- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `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.