Relationships
#4937 stagecraft: factory definitions can take prompts and skills from repo files
Opened by skunk-ape · 11/20/2026· Shipped 11/20/2026
Problem
Long prompts sit inline in a factory definition's YAML, so a definition with a few dispatch stages runs to hundreds of lines. Many people would rather keep each stage's prompt, and any skill text, in its own file in the repo. That way they can edit, review and diff the prompt on its own, and have it placed into the definition where it belongs.
YAML has no native include. Anchors and aliases work only within one file, and !include is a non-standard tag that swamp's parser (@std/yaml) doesn't accept. So the include has to be an ordinary YAML value that stagecraft resolves.
What to change
- Prompt fields (
systemPrompt,command,constraints, and any other prose field a stage carries) and skill text accept{ file: <path> }in place of a string. The path is relative to the swamp repository. - The file's text is read into the definition when a work item pins it at
start, so a running work item never changes when the file is edited. As with editing the YAML today, an edit reaches new work items only, or one reset withrepin=true. validatereads every referenced file and reports a missing, unreadable or empty file, naming the stage and the field. A path outside the repository is refused.- Template placeholders (
{{name}}) in an included file are checked exactly as they would be inline. - Studio shows the included text with its file name beside it.
The plan should check how this behaves when stagecraft runs through swamp serve and on an enrolled worker. A worker's working directory is an empty dispatch directory, so the text has to come from the pinned copy, not a fresh read.
Done when
- A starter factory with its prompts moved to files validates, starts and dispatches the same packets as the inline version.
- Editing an included file changes new work items and leaves running ones alone.
validateerrors name the stage, field and path.- Tests cover inline and file values side by side, a missing file, a path outside the repo, placeholders in a file, serve, and a worker.
- The authoring reference, README, REFERENCE and a DESIGN decision entry describe it. At least one shipped example uses it.
Out of scope
Including whole stages or other definition fragments; a swamp core include feature.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.