| 1 | import type { DocsFleetDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/fleet/page.tsx` |
| 5 | * ("Run a workflow"). Checked against `WorkflowCommand` and `LaneArgs` in |
| 6 | * crates/cli/src/lib.rs, the Lane runtime backends in |
| 7 | * crates/lane/src/runtime.rs, `FleetCommand` in crates/tui/src/lib.rs, and |
| 8 | * docs/FLEET_WORKFLOW_TUTORIAL.md / docs/WORKFLOW_AUTHORING.md. |
| 9 | */ |
| 10 | export const docsFleet: DocsFleetDict = { |
| 11 | metaTitle: "Run a workflow · Codewhale Docs", |
| 12 | metaDescription: |
| 13 | "Save roles and models in a Fleet, write a repeatable Workflow, run it as a Lane you can watch and stop, and run batches of tasks with durable workers.", |
| 14 | bodyClassName: "text-ink-soft leading-relaxed", |
| 15 | title: "Run a workflow", |
| 16 | lede: |
| 17 | "For most multi-step work you only need to ask: in Operate, Codewhale plans the steps and runs independent ones in parallel. Write a Workflow when you want the same ordered plan every time — phases, parallel branches, and a summary — with a record of each run.", |
| 18 | sections: [ |
| 19 | { |
| 20 | id: "fleet", |
| 21 | title: "Save roles in a Fleet", |
| 22 | blocks: [ |
| 23 | { |
| 24 | p: "Your Fleet is the list of roles Codewhale can hand work to, and the model each role uses. Set it up once inside a session:", |
| 25 | }, |
| 26 | { code: "/fleet setup\n/fleet\n/fleet saved", lang: "Codewhale" }, |
| 27 | { |
| 28 | p: "`/fleet setup` walks you through a role, its model (or “use the session's model”), and where to save it: this project, or your personal profile for every repository. You review the exact file before it is written. `/fleet` shows the members of the selected Fleet, and `/fleet saved` switches between named Fleets.", |
| 29 | }, |
| 30 | { |
| 31 | p: "A Fleet only chooses who does the work. What a worker may read, write, or run still comes from your workspace trust, [approval setting](/docs/modes), and sandbox.", |
| 32 | }, |
| 33 | ], |
| 34 | }, |
| 35 | { |
| 36 | id: "write", |
| 37 | title: "Write a workflow", |
| 38 | blocks: [ |
| 39 | { |
| 40 | p: "A Workflow is a JavaScript file in your repository's `workflows/` folder. It describes steps; it does not do the work itself. This one reviews two areas in parallel, then combines the findings. Save it as `workflows/docs_readiness.workflow.js`:", |
| 41 | }, |
| 42 | { |
| 43 | code: `export default workflow({ |
| 44 | "id": "docs-readiness", |
| 45 | "goal": "Review the docs and code for gaps, then summarize the next edit", |
| 46 | "nodes": [ |
| 47 | { |
| 48 | "branch": { |
| 49 | "id": "parallel-review", |
| 50 | "parallel": true, |
| 51 | "children": [ |
| 52 | { "agent": { "id": "code-review", "prompt": "Inspect src/ for undocumented behavior.", |
| 53 | "agent_type": "review", "mode": "read_only", "file_scope": ["src"] } }, |
| 54 | { "agent": { "id": "docs-review", "prompt": "Inspect docs/ for stale or missing steps.", |
| 55 | "agent_type": "review", "mode": "read_only", "file_scope": ["docs"] } } |
| 56 | ] |
| 57 | } |
| 58 | }, |
| 59 | { |
| 60 | "reduce": { |
| 61 | "id": "summary", |
| 62 | "inputs": ["code-review", "docs-review"], |
| 63 | "prompt": "Combine the findings into the safest next edit." |
| 64 | } |
| 65 | } |
| 66 | ] |
| 67 | });`, |
| 68 | lang: "workflows/docs_readiness.workflow.js", |
| 69 | }, |
| 70 | { |
| 71 | p: "Steps can be `agent`, `branch`, `sequence`, `reduce`, `loop_until`, `cond`, `expand`, and `teacher_review`. A workflow file has no file, shell, or network access of its own, and `import`, `fetch`, `eval`, and `async` are rejected. The agents it starts do the real work, under your normal permissions.", |
| 72 | }, |
| 73 | { |
| 74 | note: "One run can start up to 1,000 agents, with at most 16 working at once; the rest wait for a slot. Loops must declare `max_iterations`.", |
| 75 | }, |
| 76 | ], |
| 77 | }, |
| 78 | { |
| 79 | id: "run", |
| 80 | title: "Run it", |
| 81 | blocks: [ |
| 82 | { |
| 83 | code: `codewhale workflow run docs-readiness --runtime inline |
| 84 | codewhale workflow run docs-readiness --goal "prepare the 1.2 release" --verify`, |
| 85 | lang: "Terminal", |
| 86 | }, |
| 87 | { |
| 88 | p: "Codewhale finds `workflows/docs_readiness.workflow.js` from the name, checks it, and starts it. `--runtime inline` runs it in this terminal. The default, `tmux`, runs it in a detached tmux session that keeps going after you close the terminal. `--verify` runs the verification gates after a successful finish, and `--fleet <name>` uses a named Fleet instead of the built-in roles.", |
| 89 | }, |
| 90 | { |
| 91 | p: "To keep the work off your checkout, add `--worktree-repo . --branch <name>`: the run gets its own git worktree and branch.", |
| 92 | }, |
| 93 | { |
| 94 | p: "Inside a session, `/workflow` starts a workflow and `/workflows` lists or cancels the runs in that session.", |
| 95 | }, |
| 96 | ], |
| 97 | }, |
| 98 | { |
| 99 | id: "watch", |
| 100 | title: "Watch and stop a run", |
| 101 | blocks: [ |
| 102 | { p: "Each run is a Lane. Lanes are saved to disk, so you can check on them from any terminal:" }, |
| 103 | { |
| 104 | code: `codewhale lane list |
| 105 | codewhale lane status <lane-id> |
| 106 | codewhale lane logs <lane-id> |
| 107 | codewhale lane attach <lane-id> |
| 108 | codewhale lane interrupt <lane-id>`, |
| 109 | lang: "Terminal", |
| 110 | }, |
| 111 | { |
| 112 | p: "`lane list`, `lane status`, and `lane interrupt` accept `--json` and print a machine-readable receipt. In a session, `/lane` offers the same controls with the same results.", |
| 113 | }, |
| 114 | ], |
| 115 | }, |
| 116 | { |
| 117 | id: "batch", |
| 118 | title: "Run a batch of tasks", |
| 119 | blocks: [ |
| 120 | { |
| 121 | p: "When you have a list of separate tasks rather than one plan, write them as a task file and run them as a Fleet run. Each task names its goal, its role, and the paths it may write. [The tutorial](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/FLEET_WORKFLOW_TUTORIAL.md) has a complete `tasks.json`.", |
| 122 | }, |
| 123 | { |
| 124 | code: `codewhale fleet init |
| 125 | codewhale fleet run tasks.json --max-workers 4 |
| 126 | codewhale fleet status |
| 127 | codewhale fleet logs <worker-id> |
| 128 | codewhale fleet resume <run-id> |
| 129 | codewhale fleet stop --all`, |
| 130 | lang: "Terminal", |
| 131 | }, |
| 132 | { |
| 133 | p: "`fleet status` counts queued, running, finished, and failed work from this workspace's run record. `fleet resume` picks a run back up after the laptop slept or the manager exited, without starting a new one. For the agents attached to your current session only, use `/fleet workers` (or `/subagents`).", |
| 134 | }, |
| 135 | ], |
| 136 | }, |
| 137 | ], |
| 138 | next: [ |
| 139 | { |
| 140 | href: "/docs/subagents", |
| 141 | label: "Run agents in parallel", |
| 142 | note: "Hand independent pieces of one task to sub-agents without writing a workflow.", |
| 143 | }, |
| 144 | { |
| 145 | href: "/docs/review", |
| 146 | label: "Review what changed", |
| 147 | note: "Check the diff a run produced and get a review before you push.", |
| 148 | }, |
| 149 | { |
| 150 | href: "/docs/vocabulary", |
| 151 | label: "Product terms", |
| 152 | note: "Fleet, Workflow, Lane, and Runtime, each in one sentence.", |
| 153 | }, |
| 154 | ], |
| 155 | sourceNote: |
| 156 | "Source documents: docs/FLEET.md, docs/FLEET_WORKFLOW_TUTORIAL.md, docs/WORKFLOW_AUTHORING.md · Update docs-map.ts when changing.", |
| 157 | }; |
| 158 |