claude-taskflow 0.1.8 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -25
- package/package.json +4 -6
package/README.md
CHANGED
|
@@ -6,13 +6,14 @@
|
|
|
6
6
|
<a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/v/pi-taskflow?style=flat-square&color=4B4ACF&label=npm" alt="npm version"></a>
|
|
7
7
|
<a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/dm/pi-taskflow?style=flat-square&color=5A5D63&label=downloads" alt="npm downloads"></a>
|
|
8
8
|
<a href="https://github.com/heggria/taskflow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8A66?style=flat-square" alt="MIT license"></a>
|
|
9
|
-
<a href="#whats-inside"><img src="https://img.shields.io/badge/runtime%20deps-0-0E8A66?style=flat-square" alt="zero runtime dependencies"></a>
|
|
10
9
|
<a href="https://github.com/heggria/taskflow/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/heggria/taskflow/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
|
|
11
|
-
<a href="#whats-inside"><img src="https://img.shields.io/badge/tests-
|
|
10
|
+
<a href="#whats-inside"><img src="https://img.shields.io/badge/tests-1500+-4B4ACF?style=flat-square" alt="1500+ tests"></a>
|
|
12
11
|
<a href="#whats-inside"><img src="https://img.shields.io/badge/dogfooded-%E2%9C%93-0E8A66?style=flat-square" alt="dogfooded"></a>
|
|
13
|
-
<a href="#run-it-on-your-agent"><img src="https://img.shields.io/badge/runs%20on-Pi%20%2B%20Codex%20%2B%20Claude%20Code%20%2B%20OpenCode-4B4ACF?style=flat-square" alt="runs on Pi, Codex, Claude Code, and
|
|
12
|
+
<a href="#run-it-on-your-agent"><img src="https://img.shields.io/badge/runs%20on-Pi%20%2B%20Codex%20%2B%20Claude%20Code%20%2B%20OpenCode%20%2B%20Grok-4B4ACF?style=flat-square" alt="runs on Pi, Codex, Claude Code, OpenCode, and Grok Build"></a>
|
|
14
13
|
</p>
|
|
15
14
|
|
|
15
|
+
<p align="center"><em>Release line <code>0.2.0</code> — monorepo packages and plugin pins are <code>0.2.0</code>; npm registry updates after the <code>v0.2.0</code> tag publish job. Badge above tracks the published npm line until then.</em></p>
|
|
16
|
+
|
|
16
17
|
<p align="center">
|
|
17
18
|
<b>English</b> ·
|
|
18
19
|
<a href="https://github.com/heggria/taskflow/blob/main/README.zh-CN.md">简体中文</a>
|
|
@@ -24,7 +25,7 @@
|
|
|
24
25
|
|
|
25
26
|
<p><strong>A declarative, verifiable <em>graph of tasks</em> for coding-agent subagents.</strong><br/>
|
|
26
27
|
Not a workflow you script — a DAG you declare. Fan out · gate · loop · tournament · resume · save as a command — intermediate results stay out of your context.<br/>
|
|
27
|
-
Runs on the <a href="https://pi.dev">Pi</a> coding agent, on <a href="https://github.com/openai/codex">OpenAI Codex</a>, on <a href="https://claude.com/product/claude-code">Claude Code</a>,
|
|
28
|
+
Runs on the <a href="https://pi.dev">Pi</a> coding agent, on <a href="https://github.com/openai/codex">OpenAI Codex</a>, on <a href="https://claude.com/product/claude-code">Claude Code</a>, on <a href="https://opencode.ai">OpenCode</a>, and on <a href="https://docs.x.ai/build/overview">Grok Build</a>.</p>
|
|
28
29
|
|
|
29
30
|
</div>
|
|
30
31
|
|
|
@@ -42,13 +43,20 @@ claude plugin install claude-taskflow@taskflow
|
|
|
42
43
|
|
|
43
44
|
# OpenCode — add the MCP server to opencode.json (see the OpenCode guide)
|
|
44
45
|
opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
|
|
46
|
+
|
|
47
|
+
# Grok Build (published MCP package)
|
|
48
|
+
# First define custom taskflow-workspace/taskflow-readonly profiles extending
|
|
49
|
+
# workspace/read-only respectively in ~/.grok/sandbox.toml, then:
|
|
50
|
+
export PI_TASKFLOW_GROK_MUTATING_SANDBOX_PROFILE=taskflow-workspace
|
|
51
|
+
export PI_TASKFLOW_GROK_READONLY_SANDBOX_PROFILE=taskflow-readonly
|
|
52
|
+
grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.0 grok-taskflow-mcp
|
|
45
53
|
```
|
|
46
54
|
|
|
47
55
|
---
|
|
48
56
|
|
|
49
57
|
**A `workflow` flows. A `taskflow` is a *graph*.** Other orchestrators let the model *script* the work — imperative code that flows step by step, with the graph hidden inside control flow. `taskflow` does the opposite: you **declare** the work as a graph of discrete, named **task** nodes connected by `dependsOn` edges — and the runtime *verifies that graph before it spends a single token.*
|
|
50
58
|
|
|
51
|
-
You already know your agent's built-in subagent shorthand — `task` / `tasks` / `chain`. `taskflow` speaks the *same* shorthand — so your existing delegations instantly become **tracked, resumable, and saveable by name** (on Pi, a saved flow becomes a one-word `/tf:<name>` command; on Codex, Claude Code, and
|
|
59
|
+
You already know your agent's built-in subagent shorthand — `task` / `tasks` / `chain`. `taskflow` speaks the *same* shorthand — so your existing delegations instantly become **tracked, resumable, and saveable by name** (on Pi, a saved flow becomes a one-word `/tf:<name>` command; on Codex, Claude Code, OpenCode, and Grok Build you run it by name through `taskflow_run`). When you outgrow the shorthand, the full DSL gives you a real DAG: dynamic fan-out over dozens of items, conditional routing, quality gates, human approvals, retries, loops, tournaments, and an observed-usage budget stop-loss.
|
|
52
60
|
|
|
53
61
|
And the whole time, **only the final phase reaches your conversation.** Every intermediate transcript stays in the runtime, never your context window.
|
|
54
62
|
|
|
@@ -91,7 +99,7 @@ Here's the wall you hit with raw subagents: you describe a multi-step plan in pr
|
|
|
91
99
|
| **Conditional routing** | ✗ | **`when` guards + `join: any` OR-joins** |
|
|
92
100
|
| **Fault tolerance** | ✗ | **per-phase `retry` + auto-retry on transient errors** |
|
|
93
101
|
| **Human-in-the-loop** | ✗ | **`approval` phases (approve / reject / edit)** |
|
|
94
|
-
| **Cost control** | ✗ | **run-wide `budget` (USD /
|
|
102
|
+
| **Cost control** | ✗ | **run-wide observed-usage `budget` stop-losses (USD / tokens)** |
|
|
95
103
|
| **Composition** | ✗ | **`flow` phases run saved *or runtime-generated* sub-flows** |
|
|
96
104
|
| **Iterative loops** | ✗ | **`loop` phases — repeat until condition, convergence, or cap** |
|
|
97
105
|
| **Competitive selection** | ✗ | **`tournament` phases — N variants + judge** |
|
|
@@ -122,9 +130,9 @@ We chose the **verifiable** side on purpose. The expressivity you give up is rea
|
|
|
122
130
|
|
|
123
131
|
The Pi ecosystem now has **20+ delegation, workflow, and orchestration extensions** — each great at what it's for. Here's an honest map of where `pi-taskflow` sits (verified against each package's latest npm release, June 2026). For the full breakdown — every package, strengths *and* weaknesses — see [`docs/internal/PI-ECOSYSTEM.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/PI-ECOSYSTEM.md). For the broader, non-Pi landscape (LangGraph, Temporal, CrewAI, Mastra…) see [`docs/internal/COMPETITORS.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/COMPETITORS.md).
|
|
124
132
|
|
|
125
|
-
| Extension | Model | Custom DSL | DAG | Dynamic fan-out | Cross-session resume | Quality gate | Human approval | Save as command | Zero deps |
|
|
133
|
+
| Extension | Model | Custom DSL | DAG | Dynamic fan-out | Cross-session resume | Quality gate | Human approval | Save as command | Zero runtime deps |
|
|
126
134
|
|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
127
|
-
| **taskflow** | **declarative multi-phase taskflows** | **✓** | **✓** | **✓ `map`** | **✓ phase-hash** | **✓** | **✓** | **✓ `/tf:<name>`** |
|
|
135
|
+
| **taskflow** | **declarative multi-phase taskflows** | **✓** | **✓** | **✓ `map`** | **✓ phase-hash** | **✓** | **✓** | **✓ `/tf:<name>`** | **✕ (1 + peers)** |
|
|
128
136
|
| [`@pi-agents/orchid`](https://www.npmjs.com/package/@pi-agents/orchid) | opinionated 9-phase pipeline + Ralph loop | fixed | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ (2) |
|
|
129
137
|
| [`pi-crew`](https://www.npmjs.com/package/pi-crew) | role teams + git worktrees + async | partial | ✓ | ✓ | ✓ | ✓ | ✓ | – | ✕ (7) |
|
|
130
138
|
| [`ultimate-pi`](https://www.npmjs.com/package/ultimate-pi) | governed plan→execute→review harness | YAML contracts | ✓ (plan-time) | ✕ | ✓ | ✓ (3-tier) | ✓ | ✓ | ✕ (16) |
|
|
@@ -139,14 +147,14 @@ The Pi ecosystem now has **20+ delegation, workflow, and orchestration extension
|
|
|
139
147
|
|
|
140
148
|
**How to choose:**
|
|
141
149
|
|
|
142
|
-
- **`@pi-agents/orchid`** is the most feature-complete orchestrator in the ecosystem (DAG + worktrees + Ralph loop + agent mailbox) — but its DSL is a *fixed* 9-phase pipeline, it carries runtime deps + jiti, and it's beta. Reach for `taskflow` when you want to **define your own graph** (not adopt an opinionated one) with **
|
|
143
|
-
- **`pi-crew` / `ultimate-pi`** go heavier — worktree isolation, durable async teams, multi-tier governance. If you want lightweight
|
|
150
|
+
- **`@pi-agents/orchid`** is the most feature-complete orchestrator in the ecosystem (DAG + worktrees + Ralph loop + agent mailbox) — but its DSL is a *fixed* 9-phase pipeline, it carries runtime deps + jiti, and it's beta. Reach for `taskflow` when you want to **define your own graph** (not adopt an opinionated one) with **no host-SDK coupling** and a one-command install.
|
|
151
|
+
- **`pi-crew` / `ultimate-pi`** go heavier — worktree isolation, durable async teams, multi-tier governance. If you want a lightweight declarative engine with no host-SDK coupling, that's this project.
|
|
144
152
|
- **`@zhushanwen/pi-workflow`** is the closest in spirit and also zero-dep, but it's the **imperative** side of the split above: you author workflows as **JavaScript scripts** the model writes and runs. `taskflow`'s **declarative JSON DAG** is the verifiable side — statically checkable, visualizable, safe to LLM-generate, and resumable at phase granularity rather than call-cache dedup.
|
|
145
153
|
- **`@fiale-plus/pi-rogue-orchestration`** has a real **loop-until-done** (goal-driven iteration). `taskflow` now ships its own `loop` phase (v0.0.13+) plus `tournament` for competitive selection — and unlike rogue-orchestration, `taskflow` has a full DAG with gates, compositional sub-flows, and cross-session resume. For raw "keep going until the goal is met" with minimal structure, rogue-orchestration is still lighter; for structured, branching pipelines, `taskflow` covers the same ground and more.
|
|
146
154
|
- **`pi-subagents` / `@gotgenes/pi-subagents`** are the mature picks for ad-hoc "use reviewer on this diff" delegation and background jobs. `taskflow` is for when those delegations need to become a *repeatable, resumable pipeline*.
|
|
147
155
|
- **`pi-pipeline` / `pi-agent-flow`** ship *opinionated, fixed* flows. `taskflow` ships an *empty canvas*: you (or the model) declare the graph that fits the job.
|
|
148
156
|
|
|
149
|
-
> The honest one-liner: **`pi-taskflow`
|
|
157
|
+
> The honest one-liner: **`pi-taskflow` gives you a *declarative, verifiable, resumable* DAG of task nodes — saved as a one-word `/tf:<name>` command, with context isolation by design** (and the same engine runs on MCP hosts). The engine avoids host-SDK coupling; `typebox` is a peer dependency, the TypeScript DSL includes the compiler, and delivery packages depend on the internal taskflow packages.
|
|
150
158
|
|
|
151
159
|
## 30-second start
|
|
152
160
|
|
|
@@ -193,7 +201,7 @@ claude plugin marketplace add heggria/taskflow
|
|
|
193
201
|
claude plugin install claude-taskflow@taskflow
|
|
194
202
|
```
|
|
195
203
|
|
|
196
|
-
The plugin's MCP server runs via `npx` (a version-pinned `claude-taskflow`), so there's nothing else to install globally and the plugin version binds the exact code that runs. Each phase's subagent then runs as an isolated `claude -p` session. Just ask Claude Code to run a multi-phase or fan-out job and it calls the tools. See the [Claude Code guide](https://github.com/heggria/taskflow/blob/main/docs/claude-mcp.md).
|
|
204
|
+
The plugin's MCP server runs via `npx` (a version-pinned `claude-taskflow`), so there's nothing else to install globally and the plugin version binds the exact code that runs. Each phase's subagent then runs as an isolated `claude -p` session. **Claude Code 2.1.169+ is required** for the safe-mode isolation contract. Just ask Claude Code to run a multi-phase or fan-out job and it calls the tools. See the [Claude Code guide](https://github.com/heggria/taskflow/blob/main/docs/claude-mcp.md).
|
|
197
205
|
|
|
198
206
|
### On OpenCode
|
|
199
207
|
|
|
@@ -219,6 +227,36 @@ opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
|
|
|
219
227
|
|
|
220
228
|
The server runs via `npx` (a version-pinned `opencode-taskflow`), and each phase's subagent runs as an isolated `opencode run` session. OpenCode also auto-discovers the bundled routing skill (`**/SKILL.md`). Then just ask OpenCode to run a multi-phase or fan-out job and it calls the tools. See the [OpenCode guide](https://github.com/heggria/taskflow/blob/main/docs/opencode-mcp.md).
|
|
221
229
|
|
|
230
|
+
### On Grok Build
|
|
231
|
+
|
|
232
|
+
The published path is the MCP package:
|
|
233
|
+
|
|
234
|
+
```toml
|
|
235
|
+
# ~/.grok/sandbox.toml
|
|
236
|
+
[profiles.taskflow-workspace]
|
|
237
|
+
extends = "workspace"
|
|
238
|
+
|
|
239
|
+
[profiles.taskflow-readonly]
|
|
240
|
+
extends = "read-only"
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
export PI_TASKFLOW_GROK_MUTATING_SANDBOX_PROFILE=taskflow-workspace
|
|
245
|
+
export PI_TASKFLOW_GROK_READONLY_SANDBOX_PROFILE=taskflow-readonly
|
|
246
|
+
grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.0 grok-taskflow-mcp
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
A plugin scaffold is also available from a monorepo checkout:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
pnpm --filter grok-taskflow build
|
|
253
|
+
grok plugin install ./packages/grok-taskflow/plugin --trust
|
|
254
|
+
grok plugin enable taskflow
|
|
255
|
+
grok mcp add taskflow -- node "$(pwd)/packages/grok-taskflow/dist/mcp/bin.js"
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
A public Grok plugin marketplace/source is not published yet; do not substitute a placeholder source. Each phase's subagent runs as an isolated `grok -p --output-format streaming-json` session. Mutating or omitted-tool phases require the custom profile above because Grok's built-in profiles may fail open when kernel enforcement is unavailable. Grok 0.2.93 does not report usage, so it rejects every flow that declares `budget`. Codex reports tokens but not cost, so it accepts `maxTokens` and rejects `maxUSD`; Pi, Claude Code, and OpenCode can enforce both dimensions as observed-usage stop-losses. See the [Grok Build guide](https://github.com/heggria/taskflow/blob/main/docs/grok-mcp.md).
|
|
259
|
+
|
|
222
260
|
### The shorthand (same shape as the built-in tool)
|
|
223
261
|
|
|
224
262
|
```jsonc
|
|
@@ -307,7 +345,7 @@ The shorthand is your onramp. The DSL is where `taskflow` earns its keep — dyn
|
|
|
307
345
|
|
|
308
346
|
The intermediate summaries never enter your context. The runtime owns them; you get the report. **Save it once → `/tf:summarize-files dir=src` forever.**
|
|
309
347
|
|
|
310
|
-
### Route, gate, retry, approve, and
|
|
348
|
+
### Route, gate, retry, approve, and stop runaway spend
|
|
311
349
|
|
|
312
350
|
```jsonc
|
|
313
351
|
{
|
|
@@ -331,7 +369,7 @@ The intermediate summaries never enter your context. The runtime owns them; you
|
|
|
331
369
|
|
|
332
370
|
- **`when`** routes to `deep` *or* `quick` from the triage JSON — the other branch is skipped.
|
|
333
371
|
- **`join: "any"`** lets `approve` fire the moment whichever branch ran completes (an OR-join).
|
|
334
|
-
- **`retry`** re-runs a flaky patch with backoff; **`budget`**
|
|
372
|
+
- **`retry`** re-runs a flaky patch with backoff; **`budget`** stops admitting new calls after reported usage crosses the threshold. A call already in flight may overshoot it.
|
|
335
373
|
- **`approval`** pauses for a human (approve / reject / edit) before the final `ship`.
|
|
336
374
|
|
|
337
375
|
No scripting. No JavaScript `eval`. Just data the runtime executes — safe enough to run LLM-generated definitions directly.
|
|
@@ -404,6 +442,8 @@ See [Tournament phases](#tournament-tournament) for the full reference.
|
|
|
404
442
|
| `loop` | **iterate a task until done** — re-run a body until a condition, convergence, or a cap | `task`, `until` |
|
|
405
443
|
| `tournament` | **N variants compete**, a judge picks the best (or aggregates) | `task` \| `branches` |
|
|
406
444
|
| `script` | run a **shell command** — no LLM, zero tokens — capturing stdout as the phase output | `run` |
|
|
445
|
+
| `race` | **first successful** branch wins (optional `cancelLosers` abort) | `branches` (≥2) |
|
|
446
|
+
| `expand` | run a dynamic fragment (`nested` or `graft` promote) | `def` (+ `expandMode?`) |
|
|
407
447
|
|
|
408
448
|
### Common phase fields
|
|
409
449
|
|
|
@@ -433,6 +473,10 @@ Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8), `agen
|
|
|
433
473
|
|
|
434
474
|
### Shared Context Tree (blackboard + supervision)
|
|
435
475
|
|
|
476
|
+
> **Host scope in 0.2.0:** `ctx_read` / `ctx_write` / `ctx_report` /
|
|
477
|
+
> `ctx_spawn` tool injection is available through `pi-taskflow`. The Codex,
|
|
478
|
+
> Claude, OpenCode, and Grok runners do not inject these tools yet.
|
|
479
|
+
|
|
436
480
|
By default subagents are fully isolated — they share nothing and only return a
|
|
437
481
|
final string. Opt a phase in with `shareContext: true` (or `contextSharing: true`
|
|
438
482
|
flow-wide) to give its subagent four extra tools backed by a per-run, file-based
|
|
@@ -638,7 +682,7 @@ Condition grammar (for `when`): `== != < > <= >=`, `&& || !`, parentheses, quote
|
|
|
638
682
|
|
|
639
683
|
## Commands
|
|
640
684
|
|
|
641
|
-
Saved flows become CLI shortcuts. **These `/tf` commands are Pi-only** (they run in the Pi session). On Codex, Claude Code, and
|
|
685
|
+
Saved flows become CLI shortcuts. **These `/tf` commands are Pi-only** (they run in the Pi session). On Codex, Claude Code, OpenCode, and Grok Build, use the `taskflow_*` MCP tools instead — full set: `taskflow_run` / `list` / `show` / `verify` / `compile` / `peek` / `trace` / `replay` / `why_stale` / `recompute` (dry-run) / `save` / `search`.
|
|
642
686
|
|
|
643
687
|
| Command | What it does |
|
|
644
688
|
|---|---|
|
|
@@ -646,14 +690,19 @@ Saved flows become CLI shortcuts. **These `/tf` commands are Pi-only** (they run
|
|
|
646
690
|
| `/tf run <name> [args]` | Run a saved flow (e.g. `/tf run summarize-files dir=src`) |
|
|
647
691
|
| `/tf show <name>` | Print a flow's definition |
|
|
648
692
|
| `/tf compile <name> [lr\|td]` | **Render the flow as a Mermaid diagram + verification overlay** — 0 tokens, no LLM; paste into a README/issue/PR |
|
|
693
|
+
| `/tf ir <name>` | Compile to **FlowIR** + content hash (`ir:<64-hex>`) — 0 tokens |
|
|
649
694
|
| `/tf runs` | Browse recent run history (interactive TUI — **live auto-refreshes** while any run is active) |
|
|
650
695
|
| `/tf resume <runId>` | Continue a paused/failed run — cached phases skip automatically |
|
|
651
696
|
| `/tf peek <runId> [phaseId]` | Inspect a phase's intermediate output (the debugging escape hatch) |
|
|
697
|
+
| `/tf provenance <runId>` | Show observed read-sets for a completed run |
|
|
652
698
|
| `/tf trace <runId> [--json]` | Show a run's **deterministic-replay event trace** (each subagent call + runtime decisions) |
|
|
699
|
+
| `/tf replay <runId> [--threshold phase=n] [--budget-usd n] [--json]` | **Offline what-if** re-judge of thresholds/budget from a recorded trace (zero tokens) |
|
|
700
|
+
| `/tf why-stale <runId> [phaseId]` | Explain the stale frontier (observed ∪ declared deps) |
|
|
701
|
+
| `/tf recompute <runId> <phaseId> [--apply]` | Dry-run (default) or apply minimal recompute of the stale frontier |
|
|
653
702
|
| `/tf init` | **Interactively map model roles** to your enabled models (writes `~/.pi/agent/settings.json`) |
|
|
654
703
|
| `/tf:<name> [args]` | Shortcut — runs the flow in one tap |
|
|
655
704
|
|
|
656
|
-
Tool actions (used by the model on Pi): `run` (inline `define` or saved `name`), `save`, `resume`, `list`, `agents`, `init`, `verify`, `compile`, `ir`, `provenance`, `trace`, `why-stale`, `recompute`, `cache-clear`, `search`. On Codex, Claude Code, and
|
|
705
|
+
Tool actions (used by the model on Pi): `run` (inline `define` or saved `name`), `save`, `resume`, `list`, `agents`, `init`, `verify`, `compile`, `ir`, `provenance`, `trace`, `replay`, `why-stale`, `recompute`, `cache-clear`, `search`. On Codex, Claude Code, OpenCode, and Grok Build the exposed MCP tools are `taskflow_run` / `taskflow_list` / `taskflow_show` / `taskflow_verify` / `taskflow_compile` / `taskflow_peek` / `taskflow_trace` / `taskflow_replay` / `taskflow_why_stale` / `taskflow_recompute` (dry-run only) / `taskflow_save` / `taskflow_search`.
|
|
657
706
|
|
|
658
707
|
## Background (detached) execution
|
|
659
708
|
|
|
@@ -867,12 +916,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
|
|
|
867
916
|
|
|
868
917
|
<div align="center">
|
|
869
918
|
|
|
870
|
-
**
|
|
919
|
+
**Node.js ≥ 22.19.0** · **1500+ tests / 100 test files** · **12 phase types** · **shared context tree** · **cross-session resume** · **cross-run memoization** · **per-item map caching** · **incremental recompute** · **FlowIR compile seam** · **detached execution** · **MCP compile: SVG + text** · **Pi compile: Mermaid**
|
|
871
920
|
|
|
872
921
|
</div>
|
|
873
922
|
|
|
874
|
-
- **
|
|
875
|
-
- **
|
|
923
|
+
- **Accurate dependency boundary.** The MCP protocol implementation has no MCP SDK dependency and uses Node built-ins. `taskflow-core` has no direct `dependencies` but peers on `typebox`; `taskflow-dsl` depends on TypeScript; host delivery packages depend on the internal core/runner/MCP packages. All packages require Node.js ≥ 22.19.0.
|
|
924
|
+
- **1500+ tests across 100 test files** covering concurrency, persistence, security, resume/cache, all 12 phase kinds, FlowIR/replay, the TypeScript DSL, and host argv/MCP contracts.
|
|
876
925
|
- **Hardened by design.** Path-traversal defense (lexical + `realpath` containment check), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents (SIGTERM → SIGKILL after 5 minutes of silence). Dynamic sub-flows additionally get breadth caps, `cwd` containment, budget clamping, nesting depth caps, and prototype-pollution defense.
|
|
877
926
|
- **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
|
|
878
927
|
|
|
@@ -897,7 +946,10 @@ Our `self-improve` flow is a 10-phase DAG — it audits the codebase, patches de
|
|
|
897
946
|
|
|
898
947
|
## Status & limits
|
|
899
948
|
|
|
900
|
-
**
|
|
949
|
+
**Compatibility baseline from v0.1.8:** interpolation placeholders in phase
|
|
950
|
+
`cwd` are rejected; the release dependency/security sweep is also retained.
|
|
951
|
+
|
|
952
|
+
**v0.2.0** (this monorepo release line — npm after `v0.2.0` tag) — adds the `taskflow-dsl` TypeScript frontend, Grok Build delivery package, 12 phase kinds with `race`/`expand`, FlowIR content hashes, event-kernel trace/fold, and offline replay. **v0.1.7** — **file loaders now report *why* a file failed with the parse position** (line/column) instead of a merged "not found or unparseable" message — `defineFile`, saved flows, run records, and library sidecars all distinguish *missing* from *malformed*, so a stray bare newline in a hand-authored flow is diagnosable in seconds; `safeParse` stays lenient for LLM output. Also fixes a pi-taskflow hint that re-printed every session. **Gate safety hardening (issue #54)**: a shared emphasis-tolerant marker factory now covers **all three decision markers** — `VERDICT`, `WINNER`, and `SCORE` — so Markdown-wrapped tokens (`VERDICT: **BLOCK**`, `WINNER: __3__`, `SCORE: `0.8``) are never silently mis-read (a genuine BLOCK no longer becomes PASS; a judge's pick no longer silently reverts to variant 1); **unparseable gate *model output now fails closed* (BLOCK)** instead of rubber-stamping PASS — a gate that cannot reach a verdict cannot be trusted to pass, while *config* slips (unresolved `score.target`, malformed `scorers`) stay fail-open with a warning; and free-text gates whose task omits a `VERDICT:` instruction now get the exact format suffix **auto-appended**. For the most robust decision phases, use `output: "json"` + `expect` to machine-validate the output (now the documented default for gate verdicts, tournament winners, and router branches). **v0.1.6** added **library Phase 1** (search-before-author + reusable-flow sidecar metadata), the **`defineFile`** parameter (verify/compile/run a flow from a path on disk), and **JSONC comment support** in flow definition files (`//` and `/* */` comments + trailing commas, parsed by the new zero-dependency `parseJsonc`). **v0.1.5** added **Claude Code and OpenCode as hosts**, **extracted the MCP server into its own `taskflow-mcp-core` package**, and **de-duplicated the three host runners** into a shared `runSubagentProcess`. See [CHANGELOG](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md) for the full history. Baseline: **multi-host monorepo of nine packages** — the host-neutral `taskflow-core` engine, the host-neutral `taskflow-mcp-core` MCP server, the shared host-runner `taskflow-hosts`, the `taskflow-dsl` compiler, plus `pi-taskflow` (Pi adapter), `codex-taskflow`, `claude-taskflow`, `opencode-taskflow`, and `grok-taskflow` (the four delivery packages re-export their runners from `taskflow-hosts` and each ships an MCP bin + plugin/config), all sharing the host-neutral MCP server in `taskflow-mcp-core`. **Library Phase 1**: save flows with `purpose`+`tags` via `taskflow_save` (MCP) or `action=save` (Pi), search them with structural + CJK-aware keyword scoring via `taskflow_search`/`action=search`, and track `reuseCount` via `reusedFromSearch`. **`defineFile`**: pass a `defineFile` path (or `{defineFile, name}`) to `action=run` (Pi) or `taskflow_run`/`taskflow_verify`/`taskflow_compile` (MCP) instead of an inline `define`, and the engine reads the flow from disk — pair it with JSONC comments to annotate saved flows. **JSONC**: flow-definition `.json` files may now carry `//` and `/* */` comments and trailing commas (parsed by `parseJsonc`, re-exported from the `taskflow-core` barrel); LLM-output parsing via `safeParse` stays strict. **Shared Context Tree**: opt-in (`shareContext` / `contextSharing`) blackboard + supervision tools (`ctx_read`/`ctx_write` horizontal reuse, `ctx_report`/`ctx_spawn` vertical supervision); `ctx_spawn` accepts a flat task **or** a dependency-bearing `subflow` (a runtime-validated nested DAG), depth-capped on a unified nesting counter with budget accounting. **Workspace isolation**: a phase's `cwd` accepts reserved keywords `temp`/`dedicated`/`worktree` — the runtime allocates an isolated dir (or a git worktree on a throwaway branch) and tears it down after the phase, fail-open, rejected in LLM-authored sub-flows. **Detached execution**: runs can execute in the background, detached from the Pi session. Prior: loop-until-done (`loop`), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init`, configurable built-in agents, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, `onBlock: "retry"`, `eval` machine gates, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
|
|
901
953
|
|
|
902
954
|
Known boundaries (tracked, bounded — no surprises mid-flow):
|
|
903
955
|
|
|
@@ -906,31 +958,34 @@ Known boundaries (tracked, bounded — no surprises mid-flow):
|
|
|
906
958
|
- **No `output: "file"`.** Outputs are text/JSON only — write files via an agent's `write` tool call.
|
|
907
959
|
- **`map` fans out over a JSON array from a string `over`.** The `over` field is a string that either interpolates to a JSON array (e.g. `{steps.ID.json}`) or is a literal JSON-array string. Wrap a plain text list in a single-agent `output: "json"` phase first, or pass `JSON.stringify([...])` for a fixed list. (A raw literal array is rejected — emit it from a phase and reference that.)
|
|
908
960
|
- **The DAG must be acyclic.** Cycles are rejected at validation.
|
|
909
|
-
- **Cross-run cache excludes `gate`, `approval`, `loop`, `tournament`, and `
|
|
961
|
+
- **Cross-run cache excludes `gate`, `approval`, `loop`, `tournament`, `script`, `race`, and `expand`.** These must produce a fresh result each run.
|
|
910
962
|
- **Approval auto-rejects in detached mode.** This is a safety invariant — approval gates are never silently bypassed.
|
|
911
963
|
|
|
912
964
|
## Development
|
|
913
965
|
|
|
914
|
-
`taskflow` is a pnpm-workspace monorepo of
|
|
966
|
+
`taskflow` is a pnpm-workspace monorepo of nine packages (eight host/core + `taskflow-dsl`):
|
|
915
967
|
|
|
916
968
|
| Package | Role |
|
|
917
969
|
|---------|------|
|
|
918
970
|
| [`taskflow-core`](https://github.com/heggria/taskflow/blob/main/packages/taskflow-core) | Host-neutral orchestration engine (zero host-SDK deps; only `typebox`) — runtime, DSL, cache, verify |
|
|
919
971
|
| [`taskflow-mcp-core`](https://github.com/heggria/taskflow/blob/main/packages/taskflow-mcp-core) | Host-neutral MCP server (stdio JSON-RPC + `taskflow_*` tools + DAG renderer); depends on core |
|
|
920
|
-
| [`taskflow-hosts`](https://github.com/heggria/taskflow/blob/main/packages/taskflow-hosts) | Shared host-runner collection — the codex/claude/opencode `SubagentRunner` impls + their argv builders + event-stream parsers; depends on core |
|
|
972
|
+
| [`taskflow-hosts`](https://github.com/heggria/taskflow/blob/main/packages/taskflow-hosts) | Shared host-runner collection — the codex/claude/opencode/grok `SubagentRunner` impls + their argv builders + event-stream parsers; depends on core |
|
|
973
|
+
| [`taskflow-dsl`](https://github.com/heggria/taskflow/blob/main/packages/taskflow-dsl) | TypeScript DSL CLI/package — erases `.tf.ts` to Taskflow JSON and optional FlowIR; depends on core |
|
|
921
974
|
| [`pi-taskflow`](https://github.com/heggria/taskflow/blob/main/packages/pi-taskflow) | Pi extension adapter — `taskflow` tool + `/tf` commands (what `pi install npm:pi-taskflow` gives you) |
|
|
922
975
|
| [`codex-taskflow`](https://github.com/heggria/taskflow/blob/main/packages/codex-taskflow) | Codex MCP server + bin + [Codex plugin](https://github.com/heggria/taskflow/blob/main/packages/codex-taskflow/plugin) (re-exports the runner from `taskflow-hosts`) ([guide](https://github.com/heggria/taskflow/blob/main/docs/codex-mcp.md)) |
|
|
923
976
|
| [`claude-taskflow`](https://github.com/heggria/taskflow/blob/main/packages/claude-taskflow) | Claude Code MCP server + bin + [Claude Code plugin](https://github.com/heggria/taskflow/blob/main/packages/claude-taskflow/plugin) (re-exports the runner from `taskflow-hosts`) ([guide](https://github.com/heggria/taskflow/blob/main/docs/claude-mcp.md)) |
|
|
924
977
|
| [`opencode-taskflow`](https://github.com/heggria/taskflow/blob/main/packages/opencode-taskflow) | OpenCode MCP server + bin + [OpenCode config scaffold](https://github.com/heggria/taskflow/blob/main/packages/opencode-taskflow/plugin) (re-exports the runner from `taskflow-hosts`) ([guide](https://github.com/heggria/taskflow/blob/main/docs/opencode-mcp.md)) |
|
|
978
|
+
| [`grok-taskflow`](https://github.com/heggria/taskflow/blob/main/packages/grok-taskflow) | Grok Build MCP server + bin + [Grok plugin](https://github.com/heggria/taskflow/blob/main/packages/grok-taskflow/plugin) (re-exports the runner from `taskflow-hosts`) ([guide](https://github.com/heggria/taskflow/blob/main/docs/grok-mcp.md)) |
|
|
925
979
|
|
|
926
980
|
```bash
|
|
927
981
|
pnpm install
|
|
928
982
|
pnpm run typecheck # tsc --noEmit across all packages (no build needed)
|
|
929
983
|
pnpm test # unit tests — no network, no process spawning
|
|
930
|
-
pnpm run test:hosts # host-runner tests only (also: test:pi, test:codex, test:claude, test:opencode)
|
|
931
|
-
pnpm run build # emit dist/*.js + .d.ts for all
|
|
984
|
+
pnpm run test:hosts # host-runner tests only (also: test:pi, test:codex, test:claude, test:opencode, test:grok)
|
|
985
|
+
pnpm run build # emit dist/*.js + .d.ts for all nine packages
|
|
932
986
|
pnpm run test:e2e-codex # codex executor e2e (needs `codex` + model access)
|
|
933
987
|
pnpm run test:e2e-codex-mcp # codex MCP server e2e
|
|
988
|
+
pnpm run test:e2e-grok-mcp # grok MCP server e2e (no live model required)
|
|
934
989
|
```
|
|
935
990
|
|
|
936
991
|
The pi end-to-end suites spawn live `pi` subagents and are run directly (they use
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-taskflow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Run taskflow on Claude Code: a Claude subagent runner plus an MCP server (and a plug-and-play Claude Code plugin) that exposes the taskflow_* tools to Claude Code users.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
|
@@ -30,12 +30,10 @@
|
|
|
30
30
|
"types": "./dist/index.d.ts",
|
|
31
31
|
"exports": {
|
|
32
32
|
".": {
|
|
33
|
-
"development": "./src/index.ts",
|
|
34
33
|
"types": "./dist/index.d.ts",
|
|
35
34
|
"default": "./dist/index.js"
|
|
36
35
|
},
|
|
37
36
|
"./mcp/server": {
|
|
38
|
-
"development": "./src/mcp/server.ts",
|
|
39
37
|
"types": "./dist/mcp/server.d.ts",
|
|
40
38
|
"default": "./dist/mcp/server.js"
|
|
41
39
|
}
|
|
@@ -50,9 +48,9 @@
|
|
|
50
48
|
"access": "public"
|
|
51
49
|
},
|
|
52
50
|
"dependencies": {
|
|
53
|
-
"taskflow-
|
|
54
|
-
"taskflow-
|
|
55
|
-
"taskflow-
|
|
51
|
+
"taskflow-hosts": "0.2.0",
|
|
52
|
+
"taskflow-mcp-core": "0.2.0",
|
|
53
|
+
"taskflow-core": "0.2.0"
|
|
56
54
|
},
|
|
57
55
|
"scripts": {
|
|
58
56
|
"build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/copy-readme.mjs claude-taskflow"
|