workflow-volume-design

Use this skill before creating or changing steps that use named volumes or filesystem-backed state.

Users usually describe the product they want, not the storage primitive. Infer the volume shape from the workflow's data lifetime, write pattern, read pattern, and correctness needs. Do not ask nontechnical users to choose scope, concurrency, exclusive writers, branch state, or volume names. Ask product questions only when the answer changes the design.

Good questions are:

1. Should this data still be there for later Live runs, or only for this workflow run?
2. Can each delivery, job, customer, worker, or batch own its own folder, or does everyone need to update the same shared record?
3. Does any report, index, counter, or summary need to update immediately, or is a short delay acceptable?

Use user-facing names for steps, such as "Receive input", "Store files", "Generate artifacts", "Update reports", and "Read dashboard data". Explain persistence, concurrency, and conflict behavior in product terms. Translate independent product ownership into unique directories, and translate shared records into one writer path. Mention scope, concurrency, and exclusive writers only when the user is technical or the distinction changes behavior they asked about.

Core model

A volume is a named POSIX directory mounted at /storage/<name>. A step can open, read, write, rename, delete, and list files there just like a local filesystem. The name selects the storage; options on the VOLUME declaration independently control lifetime, access, and writer scheduling.

1. Lifetime: In Live, a volume belongs to the space and is selected by name. Every workflow in the space that declares the same name mounts the same committed files. Draft branches have isolated files for that name. scope=run gives one workflow run its own volume; every step in that run that declares the same name with scope=run mounts it.
2. Access: :ro mounts the volume read-only. A mount is writable when :ro is absent.
3. Writer scheduling: Writable mounts allow overlapping writers unless they declare concurrency=exclusive.