Choose how to orchestrate work

Start with the outcome you need. Use the smallest shape that preserves the work at the right scope.

Repeat the same visible process on issues: use a recipe

Use a recipe when people should launch the same sequence from an issue, see its steps before launch, and inspect each agent, gate, and artifact in one execution.

Example: every implementation issue should run a builder, open a pull request, and then run review. Build that once as a recipe. Do not write a workflow merely to reproduce a canvas that operators need to understand and adjust.

Next: build and run a recipe.

Run a supervised program with many short model calls: use a workflow

Use a workflow when TypeScript needs to coordinate many ephemeral agent calls, ordinary computation, fan-out, or multi-stage aggregation. Workflows have declared inputs and outputs and appear as supervised runs, but they are authored as code rather than edited as an issue recipe.

Example: classify 500 records in parallel, combine the structured responses, and emit one report. Use a workflow. A recipe would make the repeated calls cumbersome to author and inspect.

Next: choose a scripting surface.

Hand off one bounded part of the current job: delegate a task

Use a delegated task when the current agent can continue after a focused piece of exploration, implementation, or review returns. The delegated agent works inside the parent's current execution and reports back to it.

Example: while implementing a feature, ask another agent to trace the parser or review one isolated module. Delegate that task. Do not create a child issue unless the work needs its own durable outcome and branch.

Give work its own branch and reviewable result: create a child issue

Use a child issue when a piece of work should be tracked, run, reviewed, and merged independently. It can proceed in parallel with sibling issues and retains its own history and pull request.

Example: a feature needs independent backend, frontend, and documentation changes that different builders can deliver and review separately. Create child issues. If one current agent only needs temporary help, delegate tasks instead.

Deliver one larger feature across child issues: use a coordinator

Use a coordinator when one finite mission needs planning, several child issues, review of their results, and follow-up decisions over hours or days. The coordinator drives the work; builders implement each child.

Example: ship account recovery across API, desktop, web, migration, and documentation changes. Start a coordinator for that feature. It is finished when the feature ships.

Next: Coordinators.

Keep an ongoing subject coherent: use a thread

Use a thread when the subject continues after any one change is merged. A thread holds the conversation and a living summary, then files issues for concrete changes.

Example: keep performance work, settings design, or a subsystem roadmap coherent over months. Create a thread. For one feature with a finish line, use a coordinator instead.

Next: Threads.

Common combinations

These shapes compose without replacing one another. A thread can start a coordinator for one feature. A coordinator creates child issues. Each child issue can launch a recipe, and an agent in that recipe can delegate a bounded task. A workflow is the separate code-authored choice when the useful unit is a supervised program of many calls rather than issue work.