| 1 | # Fleet + Workflow Tutorial |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/FLEET_WORKFLOW_TUTORIAL.md](zh_hans/FLEET_WORKFLOW_TUTORIAL.md)。 |
| 4 | |
| 5 | Fleet and Workflow are meant to work together, but they solve different parts |
| 6 | of the problem: |
| 7 | |
| 8 | - **Fleet** configures and manages the same sub-agents: reusable roles, model |
| 9 | routes, permissions, logs, artifacts, and status/restart/stop controls. |
| 10 | - **Workflow** describes orchestration: phases, branches, reducers, loops, and |
| 11 | agent leaves that can dispatch through the fleet/sub-agent runtime. |
| 12 | |
| 13 | **Default product path:** ask in natural language. Operate handles small or |
| 14 | tightly coupled work directly under the active posture. Multi-step delegation |
| 15 | uses a compact Workflow plan with named steps, dependencies, bounded scopes, |
| 16 | and completion checks; results and evidence pass to the steps that need them. |
| 17 | One bounded, independent task can use a direct background agent. Reuse that |
| 18 | agent with `followup` for continued work. Background work keeps the composer |
| 19 | available, and ordinary multi-agent work does not require workflow files. Details: |
| 20 | [Automatic Workflows](AUTOMATIC_WORKFLOWS.md). |
| 21 | |
| 22 | This tutorial covers the **manual** fleet task-spec / checked-in Workflow path |
| 23 | for operators who want durable host workers and reviewable specs. A |
| 24 | one-sentence request should still not silently generate `tasks.json`; worker |
| 25 | cards and permission posture make dispatch visible without exposing authoring |
| 26 | mechanics. |
| 27 | |
| 28 | The examples use `codewhale fleet` and `/fleet`. |
| 29 | On-disk paths, config keys, and the Workflow `--fleet` flag use the Fleet name. |
| 30 | |
| 31 | ## 1. Prepare The Workspace |
| 32 | |
| 33 | Run fleet from the workspace you want workers to inspect or modify: |
| 34 | |
| 35 | ```sh |
| 36 | codewhale fleet init |
| 37 | ``` |
| 38 | |
| 39 | This creates the workspace ledger at `.codewhale/fleet.jsonl`. Worker logs and |
| 40 | bounded artifacts live under `.codewhale/fleet/`; host adapter logs live under |
| 41 | `.codewhale/fleet-host/`. |
| 42 | |
| 43 | If you want named reusable workers, open the TUI and run: |
| 44 | |
| 45 | ```text |
| 46 | /fleet setup |
| 47 | ``` |
| 48 | |
| 49 | Pick a role, choose whether that profile inherits the operator route or pins a |
| 50 | specific provider/model, choose where the profile lives (**This project** → |
| 51 | `.codewhale/agents/<role>.toml`, or **Personal** → |
| 52 | `$CODEWHALE_HOME/agents/<role>.toml`, available across repositories while a |
| 53 | same-id project profile remains the higher-priority override), then review the |
| 54 | exact file, permissions/tools/route posture, and save. The save control names |
| 55 | its effect ("Save to this project" / "Save as Personal profile"), and |
| 56 | replacing an existing file always asks for a second confirmation. fleet task |
| 57 | specs can reference either resolved profile with `worker.agent_profile` or the |
| 58 | shorter `worker.profile` alias. |
| 59 | |
| 60 | This makes the fleet definition cross-repository, not the authority of one |
| 61 | running session. For a multi-repository operation, launch Codewhale from a |
| 62 | shared parent workspace. Profile availability does not grant filesystem access; |
| 63 | the session's workspace, explicit trusted paths, trust mode, and permission |
| 64 | posture remain authoritative. |
| 65 | |
| 66 | ## 2. Write A fleet Task Spec |
| 67 | |
| 68 | `codewhale fleet run` accepts JSON or TOML. The checked-in |
| 69 | `docs/examples/fleet-dogfood.toml` file is the realistic manual smoke example; |
| 70 | the JSON below shows the same authoring shape with one read-only reviewer and |
| 71 | one bounded docs-note worker. The live Runtime policy controls secrets and |
| 72 | trust; fleet identity carries neither. |
| 73 | |
| 74 | ```json |
| 75 | { |
| 76 | "name": "docs readiness check", |
| 77 | "labels": { |
| 78 | "kind": "tutorial" |
| 79 | }, |
| 80 | "tasks": [ |
| 81 | { |
| 82 | "id": "map-docs", |
| 83 | "name": "Map current docs", |
| 84 | "objective": "Find the docs that describe fleet and Workflow.", |
| 85 | "instructions": "Read docs/FLEET.md and docs/WORKFLOW_AUTHORING.md. Report the command surfaces, current limitations, and any confusing gaps.", |
| 86 | "worker": { |
| 87 | "role": "reviewer", |
| 88 | "profile": "reviewer", |
| 89 | "tools": ["rg", "sed", "git"], |
| 90 | "model": "deepseek-v4-flash" |
| 91 | }, |
| 92 | "workspace": { |
| 93 | "required_files": ["docs/FLEET.md", "docs/WORKFLOW_AUTHORING.md"], |
| 94 | "writable_paths": [], |
| 95 | "environment": { |
| 96 | "required": [], |
| 97 | "allowlist": [] |
| 98 | } |
| 99 | }, |
| 100 | "input_files": ["docs/FLEET.md", "docs/WORKFLOW_AUTHORING.md"], |
| 101 | "expected_artifacts": ["log", "report"], |
| 102 | "scorer": { |
| 103 | "kind": "manual" |
| 104 | }, |
| 105 | "retry_policy": { |
| 106 | "max_attempts": 1 |
| 107 | } |
| 108 | }, |
| 109 | { |
| 110 | "id": "draft-gap-note", |
| 111 | "name": "Draft gap note", |
| 112 | "objective": "Draft a short local note for any missing tutorial steps.", |
| 113 | "instructions": "Write a concise Markdown note with the missing fleet + Workflow tutorial steps. Do not edit public docs unless explicitly asked.", |
| 114 | "worker": { |
| 115 | "role": "builder", |
| 116 | "tools": ["rg", "sed"] |
| 117 | }, |
| 118 | "workspace": { |
| 119 | "required_files": ["docs/FLEET.md"], |
| 120 | "writable_paths": [".codewhale/fleet"], |
| 121 | "environment": { |
| 122 | "allowlist": [] |
| 123 | } |
| 124 | }, |
| 125 | "expected_artifacts": ["log", "report"], |
| 126 | "scorer": { |
| 127 | "kind": "manual" |
| 128 | } |
| 129 | } |
| 130 | ] |
| 131 | } |
| 132 | ``` |
| 133 | |
| 134 | Save it as `tasks.json`. |
| 135 | |
| 136 | Common task fields: |
| 137 | |
| 138 | | Field | Purpose | |
| 139 | | --- | --- | |
| 140 | | `id`, `name` | Stable task identity and display name. | |
| 141 | | `objective`, `instructions` | The worker goal and exact operating instructions. | |
| 142 | | `worker.role` | Built-in or custom role intent, such as `reviewer`, `builder`, `read-only`, or `smoke-runner`. | |
| 143 | | `worker.profile` / `worker.agent_profile` | Saved fleet roster profile resolved from project `.codewhale/agents/`, personal `$CODEWHALE_HOME/agents/`, or `[fleet.profiles]`. | |
| 144 | | `worker.tools` | Tool names the task expects the worker to use. | |
| 145 | | `worker.model` | Preferred explicit model pin. Route resolution still owns provider/model validation. | |
| 146 | | `worker.model_class`, `worker.loadout` | Compatibility routing hints for older task specs; prefer `worker.profile` plus saved profile route pins for new specs. | |
| 147 | | `workspace.required_files` | Files that must exist before the task starts. | |
| 148 | | `workspace.writable_paths` | Paths the task is allowed to write when the effective runtime posture allows writing. | |
| 149 | | `workspace.environment` | Required or allowlisted environment variables, by name only. | |
| 150 | | `input_files`, `context` | Extra files and strings to thread into the task prompt. | |
| 151 | | `expected_artifacts` | Artifact kinds to expect: `log`, `report`, `patch`, `test_result`, `checkpoint`, or `receipt`. | |
| 152 | | `scorer` | Deterministic or manual verification rule. | |
| 153 | | `retry_policy`, `timeout_seconds`, `budget` | Retry and budget controls. | |
| 154 | |
| 155 | Do not put `security_policy` or worker `trust_level` in a new fleet task spec. |
| 156 | Those legacy fields remain readable only for old ledger replay and new-run |
| 157 | validation rejects them. Project trust, filesystem/network reach, secrets, |
| 158 | approvals, sandboxing, and tool authority are Runtime policy inputs. |
| 159 | |
| 160 | ## 3. Start And Monitor fleet |
| 161 | |
| 162 | Launch the run: |
| 163 | |
| 164 | ```sh |
| 165 | codewhale fleet run tasks.json --max-workers 4 |
| 166 | ``` |
| 167 | |
| 168 | The command prints the run id and worker ids. In another terminal, monitor the |
| 169 | ledgered state: |
| 170 | |
| 171 | ```sh |
| 172 | codewhale fleet status |
| 173 | codewhale fleet inspect <worker-id> |
| 174 | codewhale fleet logs <worker-id> |
| 175 | codewhale fleet artifacts <worker-id> |
| 176 | ``` |
| 177 | |
| 178 | Use typed controls when a worker needs intervention: |
| 179 | |
| 180 | ```sh |
| 181 | codewhale fleet interrupt <worker-id> |
| 182 | codewhale fleet restart <worker-id> |
| 183 | codewhale fleet resume <run-id> |
| 184 | codewhale fleet stop --all |
| 185 | ``` |
| 186 | |
| 187 | `resume` is for restart recovery after a manager exit, laptop sleep, or stale |
| 188 | lease. It replays the ledger and reconciles stale work without creating a new |
| 189 | run. |
| 190 | |
| 191 | ## 4. Author A Workflow |
| 192 | |
| 193 | Workflow source is declarative JavaScript or TypeScript that lowers to typed |
| 194 | Rust `WorkflowSpec`. It is not a general JavaScript runtime: imports, process |
| 195 | access, filesystem reads/writes, network calls, `eval`, `async`, and `await` |
| 196 | are rejected. |
| 197 | |
| 198 | Create a checked-in file such as `workflows/docs_readiness.workflow.js`. The |
| 199 | repo also includes `workflows/issue_audit.workflow.js` as a maintained example. |
| 200 | |
| 201 | ```js |
| 202 | export default workflow({ |
| 203 | "id": "docs-readiness", |
| 204 | "goal": "Inspect fleet and Workflow docs, then synthesize a readiness note", |
| 205 | "nodes": [ |
| 206 | { |
| 207 | "branch": { |
| 208 | "id": "parallel-docs-audit", |
| 209 | "parallel": true, |
| 210 | "children": [ |
| 211 | { |
| 212 | "agent": { |
| 213 | "id": "fleet-docs", |
| 214 | "prompt": "Inspect docs/FLEET.md for command and task-spec coverage.", |
| 215 | "agent_type": "review", |
| 216 | "mode": "read_only", |
| 217 | "profile": "reviewer", |
| 218 | "file_scope": ["docs/FLEET.md"] |
| 219 | } |
| 220 | }, |
| 221 | { |
| 222 | "agent": { |
| 223 | "id": "workflow-docs", |
| 224 | "prompt": "Inspect docs/WORKFLOW_AUTHORING.md for Workflow authoring coverage.", |
| 225 | "agent_type": "review", |
| 226 | "mode": "read_only", |
| 227 | "profile": "reviewer", |
| 228 | "file_scope": ["docs/WORKFLOW_AUTHORING.md"] |
| 229 | } |
| 230 | } |
| 231 | ] |
| 232 | } |
| 233 | }, |
| 234 | { |
| 235 | "reduce": { |
| 236 | "id": "readiness-summary", |
| 237 | "inputs": ["fleet-docs", "workflow-docs"], |
| 238 | "prompt": "Summarize the exact docs gaps and the safest next edit." |
| 239 | } |
| 240 | } |
| 241 | ] |
| 242 | }); |
| 243 | ``` |
| 244 | |
| 245 | Current Workflow node wrappers are `agent`, `branch`, `sequence`, `reduce`, |
| 246 | `teacher_review`, `loop_until`, `cond`, and `expand`. `agent.profile` names a |
| 247 | fleet roster profile; explicit agent fields override profile defaults. |
| 248 | |
| 249 | The model-facing `workflow` tool can start, run, inspect, or cancel a workflow |
| 250 | from inline source or a `source_path`. When Codewhale uses this path, ask it to |
| 251 | show the plan first if the workflow will launch multiple workers or touch files. |
| 252 | |
| 253 | ## 5. Natural Language Intake |
| 254 | |
| 255 | A good prompt today is: |
| 256 | |
| 257 | ```text |
| 258 | Draft a fleet task spec for this goal, but do not run it yet. |
| 259 | Show the proposed tasks, worker profiles, writable paths, expected artifacts, |
| 260 | scorers, and security policy. Keep secrets disabled unless I explicitly grant |
| 261 | them. |
| 262 | ``` |
| 263 | |
| 264 | After reviewing the generated spec, save it as `tasks.json` and run the fleet |
| 265 | commands above. For workflows, ask Codewhale to draft a `.workflow.js` file, |
| 266 | show the plan, and use the workflow tool path only after approval. |
| 267 | |
| 268 | This review step is intentional. It keeps provider routing, DeepSeek or other |
| 269 | model support, writable paths, network access, and secret use explicit before |
| 270 | durable workers start. |
| 271 |