pi-taskflow 0.0.4 → 0.0.6

package/DESIGN.md

@@ -204,6 +204,19 @@ pi-taskflow/
 | `map` | 对上游数组**动态 fan-out**，每项一个 agent | ≤concurrency |
 | `gate` | 质量门 / 对抗 review（可决定是否继续） | 1+ |
 | `reduce` | 把多结果聚合为一（synthesize） | 1 |
+| `approval` | **人在环**：暂停等待 approve / reject / edit | 1 |
+| `flow` | 把一个**已保存的 taskflow** 当作单个 phase 运行（组合复用） | 子流程并发 |
+
+### 3.3b 控制流 / 可靠性字段（任意 phase）
+
+| 字段 | 语义 |
+|------|------|
+| `when` | 条件守卫：表达式为假则 skip 该 phase。支持 `{refs}`、`== != < > <= >=`、`&& \|\| !`、括号、字符串/数字字面量。解析失败 fail-open（仍运行） |
+| `join` | 依赖 join：`all`（默认，等全部 dep）/ `any`（OR-join，任一 dep 完成即运行） |
+| `retry` | `{max, backoffMs, factor}`：失败重试，延迟 = `backoffMs * factor^attempt` |
+| `use` / `with` | `flow` 子流程的名字与入参（入参字符串值会插值） |
+
+顶层 `budget: {maxUSD, maxTokens}`：累计成本/token 超限即停（剩余 phase skip，运行态 `blocked`）。
 
 ### 3.4 模板插值
 
@@ -293,7 +306,8 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 | **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` 工作流 | ⏳ 待办 |
+| **v0.6** | 控制流 & 可靠性：`when` 条件分支 + `join:any` OR-join + 声明式 `retry` + `approval` 人在环 + `flow` 子流程组合 + `budget` 成本上限 | ✅ 已完成 |
+| **v0.7+** | 真·后台执行（detached + 轮询）+ 事件/cron 触发 + 成本**预估** + mermaid DAG 导出 + 内置 `deep-research` 工作流 | ⏳ 待办 |
 
 ---
 

package/README.md

@@ -1,94 +1,269 @@
-# pi-taskflow
+<div align="center">
+
+<img src="./assets/hero.png" alt="pi-taskflow — declarative, multi-phase subagent workflows" width="880">
+
+<p>
+  <a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/v/pi-taskflow?style=flat-square&color=B692FF&label=npm" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-6E8BFF?style=flat-square" alt="for the Pi coding agent"></a>
+</p>
+
+</div>
 
 > 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:
 
-## Concepts
+```jsonc
+{ "tasks": [
+  { "task": "Audit auth in src/api",   "agent": "analyst" },
+  { "task": "Audit input validation in src/api", "agent": "analyst" }
+] }
+```
+
+**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.
 
-The model calls the `taskflow` tool; you can also drive it directly:
+Save it once → `/tf:summarize-files` forever.
+
+## 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` |
+| `approval` | **human-in-the-loop** pause — approve / reject / edit before continuing | — |
+| `flow` | run a **saved sub-flow** as one phase (composition/reuse) | `use` |
+
+Every phase needs `id`. Optional fields: `agent`, `dependsOn`, `output`,
+`model`, `thinking`, `tools`, `cwd`, `concurrency`, `final`, `optional`,
+`when` (conditional guard), `join` (`all`\|`any` dependency join), `retry`
+(`{max, backoffMs, factor}`), and `with` (args for a `flow` phase).
+Run-wide: `budget: {maxUSD, maxTokens}` halts the flow when exceeded.
+
+### Control flow & reliability
+
+- **`when`** — skip a phase unless an expression is truthy. Supports `{refs}`,
+  `== != < > <= >=`, `&& || !`, parentheses, and quoted strings/numbers, e.g.
+  `"when": "{steps.triage.json.route} == deep"`. Pair with `join: "any"` on the
+  merge phase to build real if/else routing. Parse errors **fail open**.
+- **`join: "any"`** — an OR-join: the phase runs as soon as *one* dependency
+  completes (default `"all"` waits for every dep).
+- **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing
+  subagent with fixed (`factor:1`) or exponential backoff; usage is summed and
+  the attempt count shows as `↻N` in the TUI.
+- **`approval`** — pause for a human (`select`: Approve / Reject / Edit). Reject
+  halts the flow; Edit injects the typed note as the phase output for downstream
+  steps. Non-interactive runs auto-approve.
+- **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }`
+  runs a saved flow as a phase (recursion is detected and rejected).
+- **`budget`** — a run-wide `{maxUSD, maxTokens}` ceiling; once exceeded, pending
+  phases are skipped (and in-flight fan-out stops spawning) and the run is
+  `blocked`.
+
+### `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 +273,74 @@ 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.6** — control flow & reliability: conditional `when` guards, `join: any`
+  OR-joins, declarative `retry`/backoff, `approval` (human-in-the-loop) phases,
+  `flow` (saved sub-flow composition), and run-wide `budget` caps — on top of the
+  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 (and event/cron triggers on top of it) 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/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
 
 # 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/examples/conditional-research.json

@@ -0,0 +1,56 @@
+{
+  "name": "conditional-research",
+  "description": "Triage a topic, route to a deep or quick research branch (conditional `when` + OR-join), gate the result, and report.",
+  "version": 1,
+  "args": {
+    "topic": { "description": "The subject to research" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 1.0 },
+  "phases": [
+    {
+      "id": "triage",
+      "type": "agent",
+      "agent": "analyst",
+      "task": "Decide how much research the topic \"{args.topic}\" needs. Output ONLY JSON: {\"route\": \"deep\"} for broad/ambiguous topics, or {\"route\": \"quick\"} for narrow/well-defined ones.",
+      "output": "json"
+    },
+    {
+      "id": "deep",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == deep",
+      "dependsOn": ["triage"],
+      "task": "Do a thorough, multi-angle investigation of \"{args.topic}\". Cover background, key players, trade-offs, and open questions.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "quick",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == quick",
+      "dependsOn": ["triage"],
+      "task": "Give a concise, focused answer on \"{args.topic}\" with the 3 most important points.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "critic",
+      "join": "any",
+      "from": ["deep", "quick"],
+      "dependsOn": ["deep", "quick"],
+      "task": "Review the research below for unsupported claims. If it is solid, end with 'VERDICT: PASS'; if it is too thin, end with 'VERDICT: BLOCK' and one reason.\n\n{steps.deep.output}{steps.quick.output}"
+    },
+    {
+      "id": "report",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a clean markdown brief on \"{args.topic}\" from the validated research:\n\n{steps.deep.output}{steps.quick.output}",
+      "final": true
+    }
+  ]
+}

package/examples/guarded-refactor.json

@@ -0,0 +1,50 @@
+{
+  "name": "guarded-refactor",
+  "description": "Plan a change, pause for human approval before touching code (HITL), then implement with retries and a final review gate. Budget-capped.",
+  "version": 1,
+  "args": {
+    "target": { "default": "src", "description": "Directory or module to refactor" },
+    "goal": { "description": "What the refactor should achieve" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 2.0 },
+  "phases": [
+    {
+      "id": "plan",
+      "type": "agent",
+      "agent": "planner",
+      "task": "Produce a concrete, step-by-step refactor plan for {args.target} to achieve: {args.goal}. List the files you would change and the risks."
+    },
+    {
+      "id": "approve",
+      "type": "approval",
+      "dependsOn": ["plan"],
+      "task": "Review the refactor plan above. Approve to proceed, reject to abort, or edit to add constraints the implementer must follow."
+    },
+    {
+      "id": "implement",
+      "type": "agent",
+      "agent": "executor_code",
+      "dependsOn": ["approve"],
+      "task": "Implement the approved plan for {args.target}.\nPlan:\n{steps.plan.output}\nExtra human guidance (if any):\n{steps.approve.output}",
+      "retry": { "max": 1, "backoffMs": 1000 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "reviewer",
+      "dependsOn": ["implement"],
+      "task": "Review the implementation report below. If it is correct and complete, end with 'VERDICT: PASS'; otherwise 'VERDICT: BLOCK' with reasons.\n\n{steps.implement.output}"
+    },
+    {
+      "id": "summary",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a short changelog entry summarizing what was done:\n\n{steps.implement.output}",
+      "final": true
+    }
+  ]
+}

package/extensions/agents.ts

@@ -55,7 +55,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = (() => {
+			try {
+				return parseFrontmatter<Record<string, string>>(content);
+			} catch {
+				// A single malformed agent file must not break discovery for every flow.
+				return { frontmatter: {} as Record<string, string>, body: "" };
+			}
+		})();
 		if (!frontmatter.name || !frontmatter.description) continue;
 
 		const tools = frontmatter.tools

package/extensions/index.ts

@@ -18,8 +18,8 @@ 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, desugar, isShorthand } from "./schema.ts";
+import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
+import { finalPhase, resolveArgs, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
 	getFlow,
 	listFlows,
@@ -86,17 +86,6 @@ const TaskflowParams = Type.Object({
 	),
 });
 
-function resolveArgs(def: Taskflow, provided: Record<string, unknown> | undefined): 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;
-	}
-	// also pass through any extra provided args
-	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
-	return args;
-}
-
 function makeRunState(def: Taskflow, args: Record<string, unknown>, cwd: string): RunState {
 	return {
 		runId: newRunId(def.name),
@@ -153,6 +142,29 @@ async function runFlow(
 		(heartbeat as { unref?: () => void }).unref?.();
 	}
 
+	// Human-in-the-loop approver — only when an interactive UI is available.
+	const requestApproval = ctx.hasUI
+		? async (req: ApprovalRequest): Promise<ApprovalDecision> => {
+				if (req.upstream?.trim()) {
+					const snip = req.upstream.replace(/\s+/g, " ").trim();
+					ctx.ui.notify(`[${def.name}/${req.phaseId}] ${snip.length > 280 ? `${snip.slice(0, 280)}…` : snip}`, "info");
+				}
+				const choice = await ctx.ui.select(
+					`Taskflow approval — ${req.phaseId}: ${req.message}`,
+					["Approve", "Reject", "Edit / add guidance"],
+					{ signal },
+				);
+				if (!choice || choice === "Reject") return { decision: "reject" };
+				if (choice.startsWith("Edit")) {
+					const note = await ctx.ui.input("Guidance passed downstream as this phase's output", "type guidance…", {
+						signal,
+					});
+					return { decision: "edit", note: note ?? "" };
+				}
+				return { decision: "approve" };
+			}
+		: undefined;
+
 	try {
 		const result = await executeTaskflow(state, {
 			cwd: ctx.cwd,
@@ -160,6 +172,8 @@ async function runFlow(
 			globalThinking: settings.globalThinking,
 			signal,
 			persist: persistThrottled,
+			requestApproval,
+			loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
 		});
 		return result;
 	} finally {
@@ -199,11 +213,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Taskflow",
 		description: [
 			"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.",
+			"Phases (agent, parallel, map, gate, reduce, approval, flow) 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?}]}.",
+			"DSL: {name, args?, concurrency?, budget?:{maxUSD,maxTokens}, phases:[{id, type, agent, task, dependsOn?, join?:'all'|'any', when?, retry?:{max,backoffMs,factor}, over?(map), as?(map), branches?(parallel), from?(reduce), use?(flow), with?(flow), output?:'json', final?}]}.",
+			"Phase types: agent (one subagent), parallel (static branches), map (dynamic fan-out over an array), gate (VERDICT: PASS/BLOCK quality gate), reduce (aggregate from N phases), approval (human-in-the-loop pause), flow (run a saved sub-flow). join:'any' is an OR-join; when is a conditional guard; retry adds backoff; budget caps run cost.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,