| 1 | # Automatic Workflows |
| 2 | |
| 3 | You do **not** need to write a `.workflow.js` file to coordinate agents. In |
| 4 | Operate, ordinary messages can use direct tools or background workers; workers |
| 5 | are preferred for independent, parallel, background, or long-running work. |
| 6 | Workflow is reserved for ordered phases, gates, shared budgets, replay, or |
| 7 | deterministic fan-in. Act/Agent can still use the optional soft-auto policy |
| 8 | described below. |
| 9 | |
| 10 | Related docs: |
| 11 | |
| 12 | - [Workflow Authoring](WORKFLOW_AUTHORING.md) — checked-in scripts and IR |
| 13 | - [Fleet + Workflow Tutorial](FLEET_WORKFLOW_TUTORIAL.md) — manual Fleet paths |
| 14 | - [Configuration](CONFIGURATION.md) — `[workflow]` knobs |
| 15 | - [Sandbox](SANDBOX.md) — what the Workflow VM cannot do |
| 16 | |
| 17 | ## Soft-auto in Act/Agent |
| 18 | |
| 19 | 1. **You ask naturally** — “audit every crate for unsafe,” “scout then implement,” |
| 20 | “compare these two providers in parallel.” |
| 21 | 2. **Codewhale decides in Act/Agent** — broad, independent, or staged work can |
| 22 | trigger Workflow; one-file edits, simple commands, and pure Q&A do not. |
| 23 | 3. **It tells you first** — e.g. “This looks set up for a Workflow — three scouts |
| 24 | then one verifier.” |
| 25 | 4. **Optional setup** — if one or two facts would change the plan (read-only vs |
| 26 | writes, scope, child count), it opens the **`request_user_input`** modal |
| 27 | (structured multiple choice, not a long free-form interview). |
| 28 | 5. **Launch** — structured `plan` JSON (goal / phases / children) or a short |
| 29 | inline script. Parallel branches use `parallel()` partial-success semantics. |
| 30 | |
| 31 | In Operate, those same asks prefer one or more direct background workers when |
| 32 | the split improves throughput, isolation, or context focus. Small or tightly |
| 33 | coupled work can stay in the parent under the active tool and approval policy. |
| 34 | You can always type `/workflow` to request orchestration explicitly. |
| 35 | |
| 36 | ## Read-only auto-start vs write approval |
| 37 | |
| 38 | `[workflow]` config (see `config.example.toml`): |
| 39 | |
| 40 | | Knob | Default | Meaning | |
| 41 | |------|---------|---------| |
| 42 | | `automatic` | `true` | Soft-auto orchestration is enabled | |
| 43 | | `auto_start_read_only` | `true` | Read-only plans may start without a write-approval card | |
| 44 | | `require_approval_for_writes` | `true` | Writes / elevated plans need explicit approval | |
| 45 | | `auto_start_child_limit` | `8` | Soft cap on automatic child count | |
| 46 | | `max_children` / `max_depth` | `64` / `2` | Hard ceilings | |
| 47 | | `default_token_budget` | `120000` | Shared admission hint; not an exact mid-stream cutoff | |
| 48 | | `persist_completed_activity` | `true` | Keep completed panel/history activity | |
| 49 | |
| 50 | Elevated work (writes, shell beyond read-only, network, secrets, worktrees, high |
| 51 | budget) should surface an approval card with goal, child summary, capability |
| 52 | flags, and budget before launch (#4126). |
| 53 | |
| 54 | Worktree isolation and write ownership are separate. A write-capable `task()` |
| 55 | declares `writeAuthority: "workspace_write"` or `"worktree_write"` plus at |
| 56 | least one repo-relative `writeRoots`, `exactFiles`, or |
| 57 | `coordinationContracts` value. `worktree: true` selects isolation but does not |
| 58 | silently grant mutation authority. A prompt-only general task is read-only. |
| 59 | `dependencies` and `acceptance` carry bounded child-specific prerequisites and |
| 60 | observable completion checks; they are not a parent-transcript copy. |
| 61 | |
| 62 | When a workflow runs from a workspace containing multiple repositories, a |
| 63 | child that needs shell or file access must set `cwd` to the repository-relative |
| 64 | directory it should use. The host validates that the directory exists inside |
| 65 | the parent workspace before dispatch. Use `worktree: true` for isolated writes; |
| 66 | `cwd` selects an existing checkout and does not grant write authority or |
| 67 | isolation by itself. |
| 68 | |
| 69 | ## What you see while it runs |
| 70 | |
| 71 | - **Workflow panel** — phases, children, status, budget |
| 72 | - **Compact history card** — one calm row that expands for detail |
| 73 | - **One artifact per delegated unit** — no duplicate “delegate + tool card” |
| 74 | - **Typed child identity** — labels/roles; no “unknown child” in the default UI |
| 75 | |
| 76 | Cancel stops the run and child agents. Completed activity can persist across the |
| 77 | session (and across restarts when configured). |
| 78 | |
| 79 | ## Sandbox guarantees |
| 80 | |
| 81 | The Workflow JS VM has **no** filesystem, shell, network, env, imports, clock, or |
| 82 | randomness. Allowed host calls: `task`, `parallel`, `pipeline`, `phase`, `log`, |
| 83 | `budget`, `args`. Real work happens in sub-agents / Fleet under normal tool and |
| 84 | approval policy. See [Sandbox](SANDBOX.md). |
| 85 | |
| 86 | ## Synthesis and compatibility |
| 87 | |
| 88 | - Prefer `responseSchema` on children that must return structured fields. |
| 89 | - Ordinary failed parallel slots become `null` (partial success); filter them |
| 90 | before synthesizing one operator-facing summary. A `responseSchema` mismatch |
| 91 | is a contract failure and intentionally fails the run instead of being |
| 92 | silently converted to `null`. |
| 93 | - Workflow token budgets govern admission and aggregate accounting. Once |
| 94 | exhausted they reject later or descendant spawns, but children already |
| 95 | running in parallel can reconcile aggregate usage above the hint because |
| 96 | providers report usage only at response boundaries. |
| 97 | - Compatibility paths remain: `script`, `source_path` (checked-in |
| 98 | `.workflow.js` / `.workflow.ts`), and structured `plan`. |
| 99 | |
| 100 | ## When automatic stays off |
| 101 | |
| 102 | Automatic Workflow is suppressed for: |
| 103 | |
| 104 | - One-file edits and tiny one-step asks |
| 105 | - Simple commands / factual questions |
| 106 | - Highly interactive design conversations |
| 107 | - Risky writes without a clear decomposition |
| 108 | - Estimated children above `auto_start_child_limit` (ask or shrink first) |
| 109 | |
| 110 | In those cases Codewhale uses direct tools or a single `agent` instead. |
| 111 | |
| 112 | ## Example scenarios (#4131) |
| 113 | |
| 114 | Checked-in example workflows cover four automatic-Workflow scenarios: |
| 115 | |
| 116 | 1. Read-only repo audit |
| 117 | 2. Staged bug fix with worktree implementer + verifier |
| 118 | 3. Partial failure and synthesis |
| 119 | 4. Cancellation mid-run |
| 120 | |
| 121 | Fixtures: [`docs/examples/dogfood-automatic/`](examples/dogfood-automatic/). |
| 122 | Panel regression tests use the `dogfood_` prefix in |
| 123 | `crates/tui/src/tui/widgets/workflow_panel.rs`. |
| 124 |