---
name: workflow-authoring
description: Decompose an authorized Agent Workflow deliverable into bounded scouts, isolated writers, reviewed artifact handoffs and fresh verification. Use when authoring or revising a multi-worker workflow; ordinary direct edits stay in the conversation.
---

Author a saved script using the existing separate QuickJS evaluator. Read [the runtime API](../agent-workflow/references/runtime-api.md) and use [the main skill](../agent-workflow/SKILL.md) for validation, saving, starting and inspection. Use existing CLI/native-worker surfaces; no planner service, custom MCP or host evaluation is needed. The immutable capability bundle and `agent` skill/tool selections are implemented. [Verification](../../docs/verification.md) records accepted native invocation/nonrendering authoring separately from unverified rendering/export.

Use the bundled [decomposition-delivery recipe](../../workflows/decomposition-delivery.js) when a fixed worklist needs actual deliverables after scouting. Read [the recipe contract](references/delivery-contract.md) for arguments, bounded result schemas and the coordinator acceptance gate. It has two explicit invocations: `deliver`, then `verify` from a coordinator-prepared integrated checkout. It never integrates files or decides to replan itself.

## Scope before dispatch

Retain the user's requested outcomes as objective IDs. Inventory enough real paths and prerequisites to choose a useful split. Give each task a stable ID, objective IDs, full phase label, inputs, exclusions, read scope, write ownership, prerequisites, dependency IDs, artifact contract, acceptance checks and timeout. Save this `PlanRevisionV1` in script arguments. Default to at most 32 tasks and two explicitly authored revision rounds; decide overrides before dispatch.

Shared interfaces, lockfiles and integration files each have one named writer. Several workers may read the same source; writers must have disjoint literal paths or directory prefixes, including case collisions on Windows. Reading a path is not permission to edit it. Reject overlapping ownership before dispatch. Do not assign the entire repository to every worker. The recipe refuses unsafe paths, forward dependencies and ownership overlaps.

Choose the shape that matches the work: independent readers can run in parallel; item-local transformation/checks can use `pipeline`; dependent calls need recorded `dependsOn` IDs; combined artifact integration needs a real barrier and coordinator review. A phase groups workers visually and conveys no dependency. Avoid splitting a change that requires simultaneous edits to the same interface.

## Select skills before workers start

Skill selection is a required authoring decision for every scout, writer and verifier. Before launching the run, identify the actual plugin skills each role needs and record `worker ID → skill IDs → required tool IDs` in its plan. Explicitly record none required for ordinary tasks; do not automatically expose every installed plugin or assume the parent's skill access transfers.

Read [worker capabilities](../../docs/worker-capabilities.md). Declare the selected original skill roots, hashes, resource references and associated executable/runtime/cache identities in the coordinator's immutable new-run bundle. Pass its declared IDs through each applicable `agent` call's `skills` and `requireTools` options. For example, when those exact IDs are in the bundle: `agent(prompt, {id: 'buddies', skills: ['sprite-editing'], requireTools: ['sprites-managed']})`. Do not put these fields into a recipe schema that does not forward them: the bundled delivery recipe currently requires supported custom calls for capability-enabled workers.

Preserve permission ceilings and admit required tool readiness in the actual worker environment before task execution. Exact `selectedCapabilityRoots` bindings expose genuine executor `skills.list`/`skills.read`; workers must invoke those actual tools with returned package/resource identities. Reading `SKILL.md` manually, copying its body, CLI discovery, or the parent's activation cannot substitute. Required admitted tools expose verified invocation metadata. Native calls, tool operations and artifact acceptance remain separate checks; rendering/listening/export gaps stay explicit. Baseline skills remain visible without blanket host grants.

Select before startup: the pinned native runtime cannot grant a missing skill root to an already-running worker. Steering does not change that selection. An unexpected out-of-bundle prerequisite requires a coordinator-reviewed plan for unfinished work, preserving original outcomes and effects; do not silently extend the bundle or restart an active worker.

## Scouts lead to deliverables

Scouts are read-only. Require bounded file/scope inventories, proposed independent slices, shared-interface ownership, prerequisite observations and uncertainties. Pass that JSON into the actual deliverable worker's prompt. Use file references instead of bulky source dumps. Scout suggestions cannot widen the fixed scope or invent more workers in this recipe; changed scope requires a reviewed new revision.

For evidence-led improvements, use bounded retained status/activity/diff pages within the assigned read scope. Record source/version, exact run/report identity and observed generation/position/attempt where available; retain cursors, truncation and missing evidence rather than reconstructing omitted history. Classify findings as shipped, open or superseded against the current architecture, and assign each regression to its existing invariant/test owner. The [friction ledger](../../docs/friction-delivery.md) gives examples and falsifiable acceptance; supplied JSON and reference strings remain context claims, not proof of files or authenticated receipts.

Separate prerequisites for source authoring from prerequisites for validation. Inspect tools in the actual isolated worker environment, using coordinator-verified executable/cache paths. Read [worker prerequisites](../agent-workflow/references/worker-prerequisites.md). Missing build, rendering or browser tools block those commands while useful authorized source work continues. Missing an authoring prerequisite blocks that task. A lost scout leaves a null task slot; it is not an empty successful inventory.

Return the exact blocked command, executable/cache path and observed evidence. A process that launched and exited nonzero may have mutated files. Call it `notStarted` only with explicit evidence that no process began. Do not automatically install dependencies, change execution policy or permissions, or try an alternate mutating command after an uncertain effect. The coordinator prepares the toolchain and decides any authorized installation. Required tool readiness gates tool-dependent inference; optional unavailable tools leave dependent operations unrun while independent authoring continues. Admitted workers perform actual authorized tool operations and retain required generated outputs; deferring every asset operation to the coordinator does not deliver the worker skill/tool requirement. Source support for native list/read does not certify Windows invocation or plugin artifact production.

## Early artifact checkpoints and live ownership

Give each writer an early minimal artifact checkpoint before polish: create the smallest useful owned source/artifact and run its first applicable check, then refine it. Record the checkpoint and its evidence in the task inputs/acceptance plan using existing fields; do not invent recipe schema fields. A long stream of analysis or commentary is not an artifact checkpoint. An observed file change still requires retained-capture integrity and coordinator review before acceptance.

Name a live observer for every detached launch, resume and restart. Follow [live observation](../agent-workflow/SKILL.md#live-observation-after-every-detached-start): consume the returned watch arguments, confirm attachment, retain processed durable cursors, and relay failure/unknown, idle and terminal events promptly to the originating coordinator. Missing observation must be reconciled explicitly. Neither dashboard visibility nor a startup receipt proves that somebody is watching. A warning triggers bounded inspection and a report, not an uncertain-effect retry or cancellation.

## Review, integrate, verify

Dependency completion orders calls. It does **not** transfer predecessor edits between isolated worktrees. JSON reports are context and artifact claims. A writer that needs predecessor bytes must stop that dependent portion and report it incomplete until a coordinator supplies a new verified snapshot. Do not reconstruct, copy or apply predecessor patches from prompt claims.

For each handoff, the coordinator records the producer run, generation, position and observed cumulative attempt, authoritative capture reference and hashes, allowed paths, and reviewed acceptance evidence. Resolve those identities from saved records rather than guessing dispatch positions. The evaluator does not expose them to scripts, so recipe `workerRef` fields stay null until the coordinator resolves them externally.

The coordinator checks verified drain, original outcome/effect reconciliation, manifest/blob integrity, source ownership and complete output scope before using retained artifacts. Review partial and binary artifacts too. A hash confirms bytes; it does not prove that an objective is satisfied. Worker ignores, prose, `delivered`, or a `passed` Boolean cannot supply authoritative capture or acceptance evidence.

After reviewed integration, prepare a dedicated checkout of the combined source and record its content identity. Start a **new** `verify` run there with the originating session and data instance, recording its selected runtime identity. Supply the reviewed producer handoffs and integration/snapshot references. Read-only workers inspect the launch checkout; the runtime does not create an isolated writer capture for them. Keep that checkout stable during verification and recheck its content identity before accepting results. Verification workers inspect actual files and run admitted checks within their task/permission scope. Assign authorized build/export operations to suitable writers with verified readiness; services/shared sessions require separate authorization and ownership. Root owns independent combined verification and actual render/listening acceptance; absent prerequisites remain reported gaps. Cached replay results cannot establish freshness.

Use the [coordinator handoff checklist](references/delivery-contract.md#coordinator-handoff-checklist) beside the integration example. It records reviewed captures/allowed paths, stable snapshot identity, one browser owner with explicit handoff, and pending checks in separate coordinator evidence. For an exact persistent dashboard instance, name who retains it through verification and who uses Close afterward; retain shutdown evidence. Closing a tab or ending the host conversation does not prove shutdown. Close ends the dashboard; Stop controls workflow execution.

The recipe records supplied references as claims; it cannot authenticate them. It reports fresh checks as `reported` or `unverified`, never `accepted`. Its `complete` stays false and all unaccepted objective IDs remain missing. For the final user-facing completion decision, the coordinator must independently accept every retained objective, resolve captures and check receipts, finish integration, and pass all required fresh checks. Retain the recipe output unchanged and keep the authoritative acceptance report separate. Missing or null verifier slots, missing artifacts, failed checks and incomplete integration cannot be filled by synthesis or worker count.

## Revise explicitly

A revision appends replacement links for unfinished scope, names the prior run and exact generation/position/attempt, and preserves prior failed/unknown outcomes, usage, effects, artifacts and controls. Do not overwrite old execution evidence or silently drop objective IDs. Explicitly describe a user-authorized objective change rather than treating it as delivered.

This guest has no trusted receipt resolver. An uncertain-effect or unknown-outcome replacement is **coordinator-required and never dispatched**, even if JSON arguments contain nonempty reconciliation/drain references or label effects `reconciled`. Independent safe tasks can still proceed; dependencies of the blocked task retain null coverage. Native restart/recovery admission must be performed through the existing authenticated runtime outside this recipe. A revision, new task ID or new run is not a way to bypass that admission. Do not autonomously retry or replan after a failed or unknown worker.

Native restart repeats the selected worker **and every later worker**, including completed writers. Review the entire suffix and its effects before authenticated admission. Clean job drain alone, claimed reconciliation or successful later delivery cannot authorize uncertain repetition or rewrite historical outcomes.

When reporting progress, distinguish execution status, declared task outcome, artifact integrity, integration and accepted verification. A schema-valid blocked report can come from an engine-completed worker. Report all missing objective IDs, null reports, blocked commands and required coordinator actions explicitly.