Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesskunk-ape

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 with repin=true.
  • validate reads 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.
  • validate errors 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 16 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

11/20/2026, 7:16:41 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/20/2026, 4:40:17 PM

Sign in to post a ripple.