Skip to main content

Stagecraft

@swamp/stagecraftv2026.10.15.2· AGPL-3.0-or-later· 3d agoBEHAVIORSWORKFLOWSREPORTS
01README

stagecraft builds factories. A factory describes your process as a set of stages: in each one, work makes an artifact or records evidence, and gates decide when a work item may move on. Agents, people and plain code can each drive different parts of the flow; where a person must decide, the work stops and waits for them. stagecraft defines the stages and gates, keeps each work item's state and journal, and enforces the transitions.

A factory can be for anything you can describe that way: writing software, building swamp extensions, editorial review, incident follow-up, or swamp models from an OpenAPI spec.

Getting started

In a directory for your project (skip swamp init if it is already a swamp repo):

swamp init
swamp extension pull @swamp/stagecraft

That installs the stagecraft models and the stagecraft skill. Then ask your agent to "set up a stagecraft factory" for your process: the skill interviews you, writes the factory from the closest example, validates it, shows it in the studio, and drives your first work item.

Models

  • @swamp/stagecraft/factory: holds a factory definition; validates and describes it
  • @swamp/stagecraft/work-item: starts work items and drives them through the stages, gates and human stops
  • @swamp/stagecraft/studio: a local page showing every factory and its work items
  • @swamp/stagecraft/tracker: the built-in tracker, kept in swamp data
  • @swamp/stagecraft/linear: publishes work items as Linear issues
  • @swamp/stagecraft/publisher: publishes work items to a tracker written as a separate extension

Workflows

Every tracker is driven through the same shipped workflows: @swamp/stagecraft/publish, claim, create, fetch-issue and mark-duplicate, each with --input tracker=<instance>, and @swamp/stagecraft/conformance, which checks a tracker against the tracker contract.

Your own tracker

A team that tracks work elsewhere (Jira, GitHub Issues, an in-house system) can write its tracker as a separate extension: a model with describe and operate, behind a publisher. TRACKERS.md, shipped with this extension, is the guide.

02Behaviors5
engine/factory.tsv2026.10.12.1

Global Arguments

ArgumentTypeDescription
definition?preprocess
trackerstringThe tracker instance work items publish to, e.g. board: a model of the
fn validate()
Check the definition in full, analyse it as a graph, and report every problem with its path
engine/studio.tsv2026.09.30.1
fn serve(publicOrigin?: string, server?: string)
Serve the studio page on 127.0.0.1 until Ctrl-C, and at publicOrigin through a proxy when given: every factory's definition and scenarios, read-only, reloaded as they change; with server, a remote swamp serve's factories instead
ArgumentTypeDescription
publicOrigin?stringThe origin a reverse proxy or tunnel publishes the studio at, such as https://studio.example.com. Requests with that Host or Origin are answered too; the studio has no authentication, so the proxy must provide it
server?stringA swamp serve to read instead of this repo, such as wss://swamp.example.com: its factories and work items, read-only, with your own swamp login, refreshed every few seconds. Not with publicOrigin
engine/work_item.tsv2026.10.12.1
fn start(factory: string, title?: string)
Start the work item on a factory's current definition, pinning a copy
ArgumentTypeDescription
factorystringThe factory's name
title?stringThe work's title, its ticket's; status and the studio show it
fn status()
Where the work item is, what its stage needs, and which exits are ready
fn summary()
The work item's timeline and metrics as markdown; the summary report persists it
fn rebuild_metrics()
Rewrite the derived metrics record from the run when it is missing or behind
fn record_artifact()
Record an artifact the current stage declares; a payload that breaks its schema is kept as feedback and refused
fn record_evidence()
Record evidence the current stage declares; a payload that breaks its schema is kept as feedback and refused
fn dispatch()
Record that the current stage's work is starting and report its dispatch packet
fn record_usage(model?: string)
Attach reported token usage to a dispatch, once: totalTokens,
ArgumentTypeDescription
model?string
fn record_outcome(outcome: enum, reason?: string)
Record how a dispatch ended, once: succeeded, failed, or interrupted
ArgumentTypeDescription
outcomeenum
reason?string
fn record_checkpoint()
Save a checkpoint for an open dispatch, as often as the work likes;
fn open_dispatches(driverId?: string)
List the open dispatches of the current stage and cycle, optionally
ArgumentTypeDescription
driverId?string
fn approve(gateId: string, note?: string)
Approve a human-approval gate on the ways out of this stage
ArgumentTypeDescription
gateIdstring
note?string
fn decline(gateId: string, note?: string)
Decline a human-approval gate, with a note on why
ArgumentTypeDescription
gateIdstring
note?string
fn grant_override(kind: enum, stage?: string, note?: string)
Grant one more entry into a stage (cycle) or one more dispatch in this
ArgumentTypeDescription
kindenum
stage?string
note?string
fn advance(transition: string, confirm?: stringbool)
Take a transition out of the current stage; a manual one needs confirm=true
ArgumentTypeDescription
transitionstring
confirm?stringbool
fn reset(confirm: string, repin?: stringbool)
Start the work item over in a new era (confirm=reset); repin=true adopts the factory's current definition
ArgumentTypeDescription
confirmstring
repin?stringbool
fn retarget(reason: string)
Point the work item at other tracker tickets: replace externalRefs and journal why; no stage change
ArgumentTypeDescription
reasonstringWhy the work moves ticket
tracker/linear.tsv2026.10.12.1

Global Arguments

ArgumentTypeDescription
apiTokenstringA Linear personal API key. Wire it from a vault:
apiUrl?stringLinear's GraphQL endpoint; defaults to https://api.linear.app/graphql.
statuses?unionStatus keys to Linear status names (per team, matched exactly), e.g.
teamId?stringThe id of the Linear team create files new issues in; create is
types?unionIssue types to Linear label names (the team's or the workspace's,
fn assign()
Assign a Linear issue, by UUID, to a user (the API key's owner by default), replacing the one assignee Linear allows; already assigned writes nothing
tracker/publisher.tsv2026.10.12.1

Global Arguments

ArgumentTypeDescription
trackerstringThe tracker instance to publish to: a model with describe and
statuses?unionStatus keys to the tracker's status names, e.g.
fn round()
One round of a run (publish, mark_duplicate, claim, create, fetch_issue), as the shipped workflows drive it: record the answers the tracker's operate wrote for the last round and plan the next
03Workflows6
@swamp/stagecraft/claim77b36c9c-f784-47a9-ab6d-39ea84599f09

Start from a ticket: report its work item, or reserve a key for a new one and print the start command.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
read-1Read the ticket the round needs
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
read-2Read the ticket the round needs
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
read-3Read the ticket the round needs
1.operate
checkFail the run if it stopped or did not finish
1.check
@swamp/stagecraft/conformance4343d3d9-9017-4696-a90f-d1b06c31cbb7

Check that a tracker meets the tracker contract: the checks stagecraft's own trackers pass, made through its operate one call at a time. It files and changes tickets, so point it at a tracker kept for testing.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
round-4Record the last round's answers and plan the next
1.round
write-4Make the round's writes on the tracker, in order
1.operate
round-5Record the last round's answers and plan the next
1.round
write-5Make the round's writes on the tracker, in order
1.operate
round-6Record the last round's answers and plan the next
1.round
write-6Make the round's writes on the tracker, in order
1.operate
round-7Record the last round's answers and plan the next
1.round
write-7Make the round's writes on the tracker, in order
1.operate
round-8Record the last round's answers and plan the next
1.round
write-8Make the round's writes on the tracker, in order
1.operate
round-9Record the last round's answers and plan the next
1.round
write-9Make the round's writes on the tracker, in order
1.operate
round-10Record the last round's answers and plan the next
1.round
write-10Make the round's writes on the tracker, in order
1.operate
round-11Record the last round's answers and plan the next
1.round
write-11Make the round's writes on the tracker, in order
1.operate
round-12Record the last round's answers and plan the next
1.round
write-12Make the round's writes on the tracker, in order
1.operate
round-13Record the last round's answers and plan the next
1.round
write-13Make the round's writes on the tracker, in order
1.operate
round-14Record the last round's answers and plan the next
1.round
write-14Make the round's writes on the tracker, in order
1.operate
round-15Record the last round's answers and plan the next
1.round
write-15Make the round's writes on the tracker, in order
1.operate
round-16Record the last round's answers and plan the next
1.round
write-16Make the round's writes on the tracker, in order
1.operate
round-17Record the last round's answers and plan the next
1.round
write-17Make the round's writes on the tracker, in order
1.operate
round-18Record the last round's answers and plan the next
1.round
write-18Make the round's writes on the tracker, in order
1.operate
round-19Record the last round's answers and plan the next
1.round
write-19Make the round's writes on the tracker, in order
1.operate
round-20Record the last round's answers and plan the next
1.round
write-20Make the round's writes on the tracker, in order
1.operate
round-21Record the last round's answers and plan the next
1.round
write-21Make the round's writes on the tracker, in order
1.operate
round-22Record the last round's answers and plan the next
1.round
write-22Make the round's writes on the tracker, in order
1.operate
round-23Record the last round's answers and plan the next
1.round
write-23Make the round's writes on the tracker, in order
1.operate
round-24Record the last round's answers and plan the next
1.round
write-24Make the round's writes on the tracker, in order
1.operate
round-25Record the last round's answers and plan the next
1.round
write-25Make the round's writes on the tracker, in order
1.operate
round-26Record the last round's answers and plan the next
1.round
write-26Make the round's writes on the tracker, in order
1.operate
round-27Record the last round's answers and plan the next
1.round
write-27Make the round's writes on the tracker, in order
1.operate
round-28Record the last round's answers and plan the next
1.round
write-28Make the round's writes on the tracker, in order
1.operate
round-29Record the last round's answers and plan the next
1.round
write-29Make the round's writes on the tracker, in order
1.operate
round-30Record the last round's answers and plan the next
1.round
write-30Make the round's writes on the tracker, in order
1.operate
round-31Record the last round's answers and plan the next
1.round
write-31Make the round's writes on the tracker, in order
1.operate
round-32Record the last round's answers and plan the next
1.round
write-32Make the round's writes on the tracker, in order
1.operate
round-33Record the last round's answers and plan the next
1.round
write-33Make the round's writes on the tracker, in order
1.operate
round-34Record the last round's answers and plan the next
1.round
write-34Make the round's writes on the tracker, in order
1.operate
round-35Record the last round's answers and plan the next
1.round
write-35Make the round's writes on the tracker, in order
1.operate
round-36Record the last round's answers and plan the next
1.round
write-36Make the round's writes on the tracker, in order
1.operate
round-37Record the last round's answers and plan the next
1.round
write-37Make the round's writes on the tracker, in order
1.operate
round-38Record the last round's answers and plan the next
1.round
write-38Make the round's writes on the tracker, in order
1.operate
round-39Record the last round's answers and plan the next
1.round
write-39Make the round's writes on the tracker, in order
1.operate
round-40Record the last round's answers and plan the next
1.round
write-40Make the round's writes on the tracker, in order
1.operate
round-41Record the last round's answers and plan the next
1.round
write-41Make the round's writes on the tracker, in order
1.operate
round-42Record the last round's answers and plan the next
1.round
write-42Make the round's writes on the tracker, in order
1.operate
round-43Record the last round's answers and plan the next
1.round
write-43Make the round's writes on the tracker, in order
1.operate
round-44Record the last round's answers and plan the next
1.round
write-44Make the round's writes on the tracker, in order
1.operate
round-45Record the last round's answers and plan the next
1.round
write-45Make the round's writes on the tracker, in order
1.operate
round-46Record the last round's answers and plan the next
1.round
write-46Make the round's writes on the tracker, in order
1.operate
round-47Record the last round's answers and plan the next
1.round
write-47Make the round's writes on the tracker, in order
1.operate
round-48Record the last round's answers and plan the next
1.round
write-48Make the round's writes on the tracker, in order
1.operate
round-49Record the last round's answers and plan the next
1.round
write-49Make the round's writes on the tracker, in order
1.operate
round-50Record the last round's answers and plan the next
1.round
write-50Make the round's writes on the tracker, in order
1.operate
round-51Record the last round's answers and plan the next
1.round
write-51Make the round's writes on the tracker, in order
1.operate
round-52Record the last round's answers and plan the next
1.round
write-52Make the round's writes on the tracker, in order
1.operate
round-53Record the last round's answers and plan the next
1.round
write-53Make the round's writes on the tracker, in order
1.operate
round-54Record the last round's answers and plan the next
1.round
write-54Make the round's writes on the tracker, in order
1.operate
round-55Record the last round's answers and plan the next
1.round
write-55Make the round's writes on the tracker, in order
1.operate
round-56Record the last round's answers and plan the next
1.round
write-56Make the round's writes on the tracker, in order
1.operate
round-57Record the last round's answers and plan the next
1.round
write-57Make the round's writes on the tracker, in order
1.operate
round-58Record the last round's answers and plan the next
1.round
write-58Make the round's writes on the tracker, in order
1.operate
round-59Record the last round's answers and plan the next
1.round
write-59Make the round's writes on the tracker, in order
1.operate
round-60Record the last round's answers and plan the next
1.round
write-60Make the round's writes on the tracker, in order
1.operate
round-61Record the last round's answers and plan the next
1.round
write-61Make the round's writes on the tracker, in order
1.operate
round-62Record the last round's answers and plan the next
1.round
write-62Make the round's writes on the tracker, in order
1.operate
round-63Record the last round's answers and plan the next
1.round
write-63Make the round's writes on the tracker, in order
1.operate
round-64Record the last round's answers and plan the next
1.round
write-64Make the round's writes on the tracker, in order
1.operate
round-65Record the last round's answers and plan the next
1.round
write-65Make the round's writes on the tracker, in order
1.operate
round-66Record the last round's answers and plan the next
1.round
write-66Make the round's writes on the tracker, in order
1.operate
round-67Record the last round's answers and plan the next
1.round
write-67Make the round's writes on the tracker, in order
1.operate
round-68Record the last round's answers and plan the next
1.round
write-68Make the round's writes on the tracker, in order
1.operate
round-69Record the last round's answers and plan the next
1.round
write-69Make the round's writes on the tracker, in order
1.operate
round-70Record the last round's answers and plan the next
1.round
write-70Make the round's writes on the tracker, in order
1.operate
round-71Record the last round's answers and plan the next
1.round
write-71Make the round's writes on the tracker, in order
1.operate
round-72Record the last round's answers and plan the next
1.round
write-72Make the round's writes on the tracker, in order
1.operate
round-73Record the last round's answers and plan the next
1.round
write-73Make the round's writes on the tracker, in order
1.operate
round-74Record the last round's answers and plan the next
1.round
write-74Make the round's writes on the tracker, in order
1.operate
round-75Record the last round's answers and plan the next
1.round
write-75Make the round's writes on the tracker, in order
1.operate
round-76Record the last round's answers and plan the next
1.round
write-76Make the round's writes on the tracker, in order
1.operate
round-77Record the last round's answers and plan the next
1.round
write-77Make the round's writes on the tracker, in order
1.operate
round-78Record the last round's answers and plan the next
1.round
write-78Make the round's writes on the tracker, in order
1.operate
round-79Record the last round's answers and plan the next
1.round
write-79Make the round's writes on the tracker, in order
1.operate
round-80Record the last round's answers and plan the next
1.round
write-80Make the round's writes on the tracker, in order
1.operate
round-81Record the last round's answers and plan the next
1.round
write-81Make the round's writes on the tracker, in order
1.operate
round-82Record the last round's answers and plan the next
1.round
write-82Make the round's writes on the tracker, in order
1.operate
round-83Record the last round's answers and plan the next
1.round
write-83Make the round's writes on the tracker, in order
1.operate
round-84Record the last round's answers and plan the next
1.round
write-84Make the round's writes on the tracker, in order
1.operate
round-85Record the last round's answers and plan the next
1.round
write-85Make the round's writes on the tracker, in order
1.operate
round-86Record the last round's answers and plan the next
1.round
write-86Make the round's writes on the tracker, in order
1.operate
round-87Record the last round's answers and plan the next
1.round
write-87Make the round's writes on the tracker, in order
1.operate
round-88Record the last round's answers and plan the next
1.round
write-88Make the round's writes on the tracker, in order
1.operate
round-89Record the last round's answers and plan the next
1.round
write-89Make the round's writes on the tracker, in order
1.operate
round-90Record the last round's answers and plan the next
1.round
write-90Make the round's writes on the tracker, in order
1.operate
round-91Record the last round's answers and plan the next
1.round
write-91Make the round's writes on the tracker, in order
1.operate
round-92Record the last round's answers and plan the next
1.round
write-92Make the round's writes on the tracker, in order
1.operate
round-93Record the last round's answers and plan the next
1.round
write-93Make the round's writes on the tracker, in order
1.operate
round-94Record the last round's answers and plan the next
1.round
write-94Make the round's writes on the tracker, in order
1.operate
round-95Record the last round's answers and plan the next
1.round
write-95Make the round's writes on the tracker, in order
1.operate
round-96Record the last round's answers and plan the next
1.round
write-96Make the round's writes on the tracker, in order
1.operate
round-97Record the last round's answers and plan the next
1.round
write-97Make the round's writes on the tracker, in order
1.operate
round-98Record the last round's answers and plan the next
1.round
write-98Make the round's writes on the tracker, in order
1.operate
round-99Record the last round's answers and plan the next
1.round
write-99Make the round's writes on the tracker, in order
1.operate
round-100Record the last round's answers and plan the next
1.round
write-100Make the round's writes on the tracker, in order
1.operate
checkFail the run if it stopped or did not finish
1.check
@swamp/stagecraft/createe0443507-7a20-48b2-bfed-25d06a9bb172

File a new ticket on the tracker and record it; a retry after the tracker accepted it files another.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
read-1Read the ticket the round needs
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
read-2Read the ticket the round needs
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
read-3Read the ticket the round needs
1.operate
checkFail the run if it stopped or did not finish
1.check
@swamp/stagecraft/fetch-issue8ef3524b-6bae-495d-97ad-91185f5a6ae2

Read a ticket and record it, with the externalRefs to start a work item from it.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
read-1Read the ticket the round needs
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
read-2Read the ticket the round needs
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
read-3Read the ticket the round needs
1.operate
checkFail the run if it stopped or did not finish
1.check
@swamp/stagecraft/mark-duplicate8b3681c8-1322-4637-9266-66a81dc5e9ed

Mark a ticket a duplicate of a primary: relate it duplicate_of and close it where the tracker does not. It moves no work item.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
read-1Read the ticket the round needs
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
read-2Read the ticket the round needs
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
read-3Read the ticket the round needs
1.operate
round-4Record the last round's answers and plan the next
1.round
write-4Make the round's writes on the tracker, in order
1.operate
read-4Read the ticket the round needs
1.operate
round-5Record the last round's answers and plan the next
1.round
write-5Make the round's writes on the tracker, in order
1.operate
read-5Read the ticket the round needs
1.operate
round-6Record the last round's answers and plan the next
1.round
write-6Make the round's writes on the tracker, in order
1.operate
read-6Read the ticket the round needs
1.operate
round-7Record the last round's answers and plan the next
1.round
write-7Make the round's writes on the tracker, in order
1.operate
read-7Read the ticket the round needs
1.operate
round-8Record the last round's answers and plan the next
1.round
write-8Make the round's writes on the tracker, in order
1.operate
read-8Read the ticket the round needs
1.operate
round-9Record the last round's answers and plan the next
1.round
write-9Make the round's writes on the tracker, in order
1.operate
read-9Read the ticket the round needs
1.operate
round-10Record the last round's answers and plan the next
1.round
write-10Make the round's writes on the tracker, in order
1.operate
read-10Read the ticket the round needs
1.operate
round-11Record the last round's answers and plan the next
1.round
write-11Make the round's writes on the tracker, in order
1.operate
read-11Read the ticket the round needs
1.operate
round-12Record the last round's answers and plan the next
1.round
write-12Make the round's writes on the tracker, in order
1.operate
read-12Read the ticket the round needs
1.operate
checkFail the run if it stopped or did not finish
1.check
@swamp/stagecraft/publish301c82d9-7df9-4fb2-bc57-3414ae9e2d15

Replay a work item's journal to its ticket: what publish does, for any tracker. Run it again after each step; it delivers only what is new.

round-1Plan the first round
1.round
write-1Make the round's writes on the tracker, in order
1.operate
read-1Read the ticket the round needs
1.operate
round-2Record the last round's answers and plan the next
1.round
write-2Make the round's writes on the tracker, in order
1.operate
read-2Read the ticket the round needs
1.operate
round-3Record the last round's answers and plan the next
1.round
write-3Make the round's writes on the tracker, in order
1.operate
read-3Read the ticket the round needs
1.operate
round-4Record the last round's answers and plan the next
1.round
write-4Make the round's writes on the tracker, in order
1.operate
read-4Read the ticket the round needs
1.operate
round-5Record the last round's answers and plan the next
1.round
write-5Make the round's writes on the tracker, in order
1.operate
read-5Read the ticket the round needs
1.operate
round-6Record the last round's answers and plan the next
1.round
write-6Make the round's writes on the tracker, in order
1.operate
read-6Read the ticket the round needs
1.operate
round-7Record the last round's answers and plan the next
1.round
write-7Make the round's writes on the tracker, in order
1.operate
read-7Read the ticket the round needs
1.operate
round-8Record the last round's answers and plan the next
1.round
write-8Make the round's writes on the tracker, in order
1.operate
read-8Read the ticket the round needs
1.operate
round-9Record the last round's answers and plan the next
1.round
write-9Make the round's writes on the tracker, in order
1.operate
read-9Read the ticket the round needs
1.operate
round-10Record the last round's answers and plan the next
1.round
write-10Make the round's writes on the tracker, in order
1.operate
read-10Read the ticket the round needs
1.operate
round-11Record the last round's answers and plan the next
1.round
write-11Make the round's writes on the tracker, in order
1.operate
read-11Read the ticket the round needs
1.operate
round-12Record the last round's answers and plan the next
1.round
write-12Make the round's writes on the tracker, in order
1.operate
read-12Read the ticket the round needs
1.operate
checkFail the run if it stopped or did not finish
1.check
04Reports1
@swamp/stagecraft/work-item-summarymethod
work_item_summary_report.ts

Timeline and metrics of a stagecraft work item, rendered statically from its run record

stagecraft
05Previous Versions10
2026.10.15.1AGPL-3.0-or-later(was none)
2026.10.13.1
2026.10.12.3

Added 1, removed 5 behaviors. Added 6 workflows. Removed 1 skills

2026.10.12.2
2026.10.12.1
2026.10.09.1
2026.10.08.2

Modified 1 behaviors

2026.10.08.1
2026.10.05.1
2026.10.02.1
06Stats
A
100 / 100
Downloads
54,295
Archive size
1.5 MB
Verified by Swamp
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
07Platforms
08Labels