Design a workflow
The guardian described an automation. You take it from idea to an installed,
runnable workflow app in this one conversation, in three phases: shape it into a
spec → get approval → build it. There is no separate design surface, no
intermediate plan format, and no hand-off — you do all three.
Phase 1 — Shape the idea into a spec
Turn what the guardian said into a short, plain-language spec they can read and
sign off on. The spec is the thing they approve, so write it for a non-technical
reader — what the automation does, not how it's coded. Use this shape:
Trigger — what kicks it off (a schedule, an event, a "run now").
Steps — the ordered things it does, one short verb phrase each
("fetch my unread emails", "summarize them", "post the digest to my chat").
Decisions — any branch ("if the total is over $5k, escalate; otherwise file
it"), stated as plain conditions.
Per-item work — anything done "for each" of a list ("for each ticket, rate
its severity").
Delivers — the final step that sends, posts, saves, or shows the result.
Hold these disciplines while you shape it — they decide whether the spec is real:
- Ask the guardian for facts only they can supply; never invent them. A
threshold amount, a recipient, a channel, which account, which event fires the
trigger — a made-up "$5,000" looks authoritative and gets approved by accident.
When a fact like this is missing, ask for it in your reply rather than guessing.
- Resolve design questions in conversation, not in the spec. Anything that
changes the shape — whether to branch, what to do per item — gets settled with
the guardian before you present the spec, not parked as an open question in it.
- Every workflow must deliver. A spec that only fetches and computes, with no
step that sends/posts/saves/shows a result, has no destination and is never
finished. If the guardian didn't say where the result goes, that's a fact to ask
for (see above).
- Don't let vague quantifiers pass. "the top labs", "the latest news", "key
themes", "top outlets" each hide a fact — how many, which sources, what time
window. If it changes what the automation does, pin it down with the guardian.
- Keep it statically structured. The full space of what it does must be
knowable before it runs: ordered steps, parallel work, a decision, or bounded
per-item fan-out. No "keep polling until…", no unbounded loops.
Keep the spec itself conversational and free of technical artifacts — no JSON, no
flow chart, no node/combinator vocabulary. Talk about what it will do.
Phase 2 — Get approval
Present the spec and ask the guardian to approve it or tell you what to change.
Make the ask explicit ("Want me to build this, or change anything first?"). If
they ask for a change, revise the spec and ask again. Build only after a clear
yes — don't start scaffolding on a maybe.
Phase 3 — Build it
On approval, build the workflow into a new, runnable Rome app. Load the
coding:workflow_creation skill and follow it end to end — it owns the real work:
deriving the control flow, scaffolding the workflow template, authoring
src/workflow/definition.ts in plain TypeScript (await/if/for/Promise.all),
the system:summon discipline for generative steps, the connector:connector_proxy discipline for
SaaS calls, the ctx.dryRun guard on every write, the display envelope, the web
surface, and the install. Translate the approved spec into its control flow
faithfully — don't redesign the automation while coding it.
Two cautions specific to building from an approved spec, beyond what
coding:workflow_creation already covers:
- Build first, connect after. The toolkits you can use are listed in your
context, so don't probe to discover them and don't gate the build on whether an
account is connected yet. Build and install the workflow, then name the toolkits
it needs and ask the guardian to connect any that aren't — it's ready to run once
they do. Never fake a connection or swap in fixture data to dodge a missing one.
- Never fan a
system:summon call across a map or parallel. A generative step that
runs per-item is fine as a per-item system:summon call; what's forbidden is structuring the
flow so one system:summon call is itself spread across the fan-out. If the approved spec
seems to require that, surface it as a problem rather than rewriting the plan
silently.
The guardian is watching this session live, so narrate as you go: one plain,
friendly sentence per step ("Setting up the app…", "Wiring the email step…",
"Installing it now…") — not file paths, JSON, or technical artifacts.
You're done when the app is actually installed. Tell the guardian plainly what you
built, then point them at any toolkits they still need to connect for it to run.
If you hit a real blocker — a spec that can't be implemented as written — say
what's wrong and stop; never claim it's built when it isn't.
1---2name: design-workflow3description: Turn a guardian's plain-language automation into a runnable Rome workflow app, in one conversation. Use whenever the guardian wants to build, create, set up, or design an automation or workflow ("every morning summarize my unread emails", "when I save a link, fetch and summarize it", "for each new ticket, look up the customer and draft a reply"). You shape the idea into a short spec, get the guardian's approval, then build and install the workflow yourself — no separate planner or builder.4---56# Design a workflow78The guardian described an automation. You take it from idea to an installed,9runnable workflow app in this one conversation, in three phases: **shape it into a10spec → get approval → build it**. There is no separate design surface, no11intermediate plan format, and no hand-off — you do all three.1213## Phase 1 — Shape the idea into a spec1415Turn what the guardian said into a short, plain-language spec they can read and16sign off on. The spec is the thing they approve, so write it for a non-technical17reader — what the automation *does*, not how it's coded. Use this shape:1819> **Trigger** — what kicks it off (a schedule, an event, a "run now").20> **Steps** — the ordered things it does, one short verb phrase each21> ("fetch my unread emails", "summarize them", "post the digest to my chat").22> **Decisions** — any branch ("if the total is over $5k, escalate; otherwise file23> it"), stated as plain conditions.24> **Per-item work** — anything done "for each" of a list ("for each ticket, rate25> its severity").26> **Delivers** — the final step that sends, posts, saves, or shows the result.2728Hold these disciplines while you shape it — they decide whether the spec is real:2930- **Ask the guardian for facts only they can supply; never invent them.** A31 threshold amount, a recipient, a channel, which account, which event fires the32 trigger — a made-up "$5,000" looks authoritative and gets approved by accident.33 When a fact like this is missing, ask for it in your reply rather than guessing.34- **Resolve design questions in conversation, not in the spec.** Anything that35 changes the *shape* — whether to branch, what to do per item — gets settled with36 the guardian before you present the spec, not parked as an open question in it.37- **Every workflow must deliver.** A spec that only fetches and computes, with no38 step that sends/posts/saves/shows a result, has no destination and is never39 finished. If the guardian didn't say where the result goes, that's a fact to ask40 for (see above).41- **Don't let vague quantifiers pass.** "the top labs", "the latest news", "key42 themes", "top outlets" each hide a fact — how many, which sources, what time43 window. If it changes what the automation does, pin it down with the guardian.44- **Keep it statically structured.** The full space of what it does must be45 knowable before it runs: ordered steps, parallel work, a decision, or bounded46 per-item fan-out. No "keep polling until…", no unbounded loops.4748Keep the spec itself conversational and free of technical artifacts — no JSON, no49flow chart, no node/combinator vocabulary. Talk about what it will *do*.5051## Phase 2 — Get approval5253Present the spec and ask the guardian to approve it or tell you what to change.54Make the ask explicit ("Want me to build this, or change anything first?"). If55they ask for a change, revise the spec and ask again. Build **only** after a clear56yes — don't start scaffolding on a maybe.5758## Phase 3 — Build it5960On approval, build the workflow into a new, runnable Rome app. **Load the61`coding:workflow_creation` skill and follow it end to end** — it owns the real work:62deriving the control flow, scaffolding the `workflow` template, authoring63`src/workflow/definition.ts` in plain TypeScript (`await`/`if`/`for`/`Promise.all`),64the `system:summon` discipline for generative steps, the `connector:connector_proxy` discipline for65SaaS calls, the `ctx.dryRun` guard on every write, the display envelope, the web66surface, and the install. Translate the approved spec into its control flow67faithfully — don't redesign the automation while coding it.6869Two cautions specific to building from an approved spec, beyond what70`coding:workflow_creation` already covers:7172- **Build first, connect after.** The toolkits you can use are listed in your73 context, so don't probe to discover them and don't gate the build on whether an74 account is connected yet. Build and install the workflow, then name the toolkits75 it needs and ask the guardian to connect any that aren't — it's ready to run once76 they do. Never fake a connection or swap in fixture data to dodge a missing one.77- **Never fan a `system:summon` call across a `map` or `parallel`.** A generative step that78 runs per-item is fine as a per-item `system:summon` call; what's forbidden is structuring the79 flow so one `system:summon` call is itself spread across the fan-out. If the approved spec80 seems to require that, surface it as a problem rather than rewriting the plan81 silently.8283The guardian is watching this session live, so narrate as you go: one plain,84friendly sentence per step ("Setting up the app…", "Wiring the email step…",85"Installing it now…") — not file paths, JSON, or technical artifacts.8687You're done when the app is actually installed. Tell the guardian plainly what you88built, then point them at any toolkits they still need to connect for it to run.89If you hit a real blocker — a spec that can't be implemented as written — say90what's wrong and stop; never claim it's built when it isn't.
rome-os