flowRun

A generic engine for running operator workflows, exposed via the Model Context Protocol.

The intent: let AI agents drive real workflows by hosting them as plugins. The engine is domain-agnostic; what gets run is up to the plugin.

The first plugin is ghostMarketingFlow, which markets subCancel. Built in public.

knowledge-base files

Each framework idea drops one file into knowledge-base/. These are the real files for flowRun, building up across the framework. Each links back to the idea that produces it.

user.md

Infrastructure consumed via an AI agent. The user is technical and wants determinism: same input, same output, every time. Use this shape if you are building a platform, a library or developer tooling.

# knowledge-base/user.md

User: A small-shop operator with multi-step workflows they want an AI agent to drive deterministically, not via copy-paste-into-chat

Trigger: A repeatable operation (publish + email, deploy + verify) needs running and the operator triggers it via their AI agent through flowRun

Outcome: The workflow runs the same way every time with inspectable state at each step

From 1.1.1, If You Can't Name the User, You're Guessing What They Want.

problem.md

A pain about consistency: a process that should be repeatable is not. The user is technical and the pain shows up as errors and re-invention. Use this shape if the pain you are naming is about determinism, repeatability or AI agent reliability.

# knowledge-base/problem.md

Pain: Repeatable operations are scattered across docs, code snippets and chat threads, so the AI agent has to be re-instructed each time

Trigger: A standard operation needs running for the third time this month and the operator cannot remember what worked last time

Cost: Each repeat is partially re-invented, errors compound and the agent's deterministic promise breaks down

From 1.1.2, Describe the Pain Without Mentioning the Solution.

promise.md

A promise framed around determinism and inspectability for technical users. Boundaries protect against trying to do everything an agent might want to delegate. Use this shape if your user wants infrastructure they can read and verify, not magic.

# knowledge-base/promise.md

User: A small-shop operator with multi-step workflows they want an AI agent to drive deterministically, not via copy-paste-into-chat

Promised outcome: A plugin contract that turns any workflow into a JSON definition the engine can run the same way every time, with inspectable state at each step

Boundary: Does not write the workflows for you, does not host or persist long-running state beyond a run and does not replace human review of the final output

From 1.1.3, The One-Line Promise That Keeps Your Build Honest Throughout.

positioning.md

Positioning aimed at the technical buyer who values consistency over features. The useful result is infrastructure that gives them determinism. Use this shape if your product is a technical primitive.

# knowledge-base/positioning.md

User: A small-shop operator who wants their AI agent to run repeatable multi-step workflows

Problem: Workflows that should be deterministic end up re-instructed each run, with state opaque mid-flight and errors compounding

Useful result: An MCP-driven engine that runs JSON-defined plugins the same way every time, with inspectable state at each step

From 1.2.1, Can You Explain This in 30 Seconds Without Mentioning the Tech?.

success.md

Success measured in author velocity: can a first-time user successfully use the tool. Use this shape if your product is a developer primitive whose success is measured in adoption friction.

# knowledge-base/success.md

Outcome: A plugin author can write a working flowRun plugin from scratch and run it via Claude in under an hour

Metric: Time from blank repo to "AI agent runs the plugin successfully" on a fresh dev setup

Threshold: 60 minutes or less for three independent first-time authors

From 1.2.2, What Does "Success" Actually Mean for the First Version You Ship?.

risks.md

A risk about ecosystem: single-plugin engines die. Use this shape if your product's value depends on adoption beyond the original use case that justified it.

# knowledge-base/risks.md

Likely failure: Plugin authors find the JSON DSL too rigid for real workflows and either fork the engine or stop writing plugins, so the engine has one plugin and no ecosystem

Affected user or workflow: Future plugin authors; the value of flowRun-as-engine collapses if only one plugin ever runs on it

Mitigation: Track which DSL extensions plugin authors ask for; for repeated asks, add primitives carefully (each one expands the engine's surface) rather than telling authors to work around limits

From 1.2.3, The Risks You're Avoiding Naming Are the Ones That Bite You.

goal.md

A goal about category shift (toy to infrastructure). Use this shape if your product moves something from "experimental" to "dependable" in the user's mind.

# knowledge-base/goal.md

User outcome: Operators move from "AI workflows that mostly work" to "AI workflows that run the same way every time, with state you can read"

Why it matters: Determinism is the difference between AI as a toy and AI as infrastructure; for small shops without a platform team, that gap is the wall between interesting and dependable

Proof signal: An operator can hand a flowRun plugin to an AI agent twice and get the same output, with each step's state visible after the fact

From 1.3.1, The One Outcome That Makes This Build Worth Doing in the First Place.

scope.md

Cuts that protect against becoming a platform when the value is in the engine. Use this shape if your product is a primitive whose value would dilute by adding the layers that usually sit on top of one.

# knowledge-base/scope.md

Keep in: The JSON DSL for workflow definition, the engine that interprets it, the MCP server that exposes plugins to AI agents and an inspectable state-at-each-step view

Leave out: A visual editor, hosted execution (we run in-process or on the user's infrastructure), durable retries across restarts and any built-in observability dashboard

Why the cut helps: The product is the engine, not the platform; visual editors and dashboards become full products of their own and would dilute the "run a plugin reliably" core

From 1.3.2, What This Will Not Do (On Purpose) Is Half the Decision.

path.md

A path through a dev cycle (write, run, inspect, fix, re-run, expose). Use this shape if your product is a developer tool whose first happy path is iterative rather than a single straight run.

# knowledge-base/path.md

User: A plugin author with a workflow they want to package

Trigger: They write the workflow as JSON, install flowRun via npm and pair it with the action handlers

Path to outcome: Run the plugin locally, inspect state at each step, fix the action that failed, re-run, then expose the plugin via the MCP server so an AI agent can drive it end-to-end

From 1.3.3, Describe One Main Path First, Then Ignore Everything Else.

build/prototype-path.md

A prototype path that tests the developer experience for a fresh-eyes author. Use this shape if your build is a developer primitive that lives or dies on day-one usability.

# knowledge-base/build/prototype-path.md

Learning goal: Whether a plugin author can write a useful flowRun plugin in under an hour from the docs alone, or whether the DSL is too restrictive

Path to test: A first-time author reads the docs, writes a small plugin (publish a Ghost post then send an email), runs it via Claude

Proof signal: The plugin runs end-to-end without the author asking for help or extending the DSL

From 2.1.1, The Only Path Your Prototype Actually Needs to Walk.

build/value-moment.md

A value moment in handover (giving the AI agent something that just works). Use this shape if your product's wedge is reducing the friction of one specific handoff.

# knowledge-base/build/value-moment.md

User: A plugin author who has written workflows as code before but has never had AI agents drive them

First value moment: The moment they hand Claude a JSON plugin and it runs, with each step's state showing up as the agent reports back

Step that gets them there: A minimal getting-started recipe that takes them from npm install to agent-successfully-ran-the-plugin in five steps or fewer

From 2.1.2, Where the User First Feels Value Is Where to Start Building.

build/learning-goal.md

A hypothesis about developer experience trade-offs. Use this shape if the build's central bet is choosing one DX axis to optimise over another.

# knowledge-base/build/learning-goal.md

Hypothesis: A plugin authoring experience that prioritises inspectability over expressiveness will produce more working plugins than a DSL that supports more cases but is harder to debug

Question: When something goes wrong with a plugin, does the author fix it faster with inspectable state or with richer language primitives

Signal that answers it: First-time plugin authors hit their first working version sooner with the inspectable-state minimal DSL than with the richer-DSL alternative

From 2.1.3, What This Build Is Meant to Teach You, Not Just to Ship.

build/routine-checklist.md

Routine work that protects an ecosystem; one regression hurts every downstream user. Use this shape if your routine work guards a contract others depend on.

# knowledge-base/build/routine-checklist.md

Recurring task: Before publishing each new plugin or DSL change, run the full plugin test suite end-to-end via the MCP server with a fresh database and a real AI agent driving it

Owner: The engine maintainer, because a regression in the DSL breaks every plugin in the ecosystem at once and authors stop trusting the contract

Done condition: All shipped plugins pass their own integration tests AND the canonical publish-and-email plugin runs successfully when invoked by Claude on a fresh checkout

From 2.2.1, The Routine Work Checklist Nobody Talks About.

build/buy-vs-build.md

A buy decision about a generic technical capability where the bought-in library has battle-tested it for you. Use this shape if your differentiator is the semantics on top of a well-known primitive.

# knowledge-base/build/buy-vs-build.md

Decision area: Whether to build a custom JSON validator for the DSL or use Zod

Reason to buy or build: Buy it through Zod, because schema validation is solved work and the time saved goes into the engine and the plugin contract that are the actual product

Deciding constraint: The product is the engine and the DSL semantics, not the bytes-to-AST parsing; choosing a battle-tested validator lets the team focus on what plugin authors actually pay attention to

From 2.2.2, Buy vs Build Is a Strategy Choice, Not an Engineering One.

build/system-shape.md

A shape with strict layered contracts between engine, plugin and MCP. Use this shape if your product depends on a stable interface between independent layers.

# knowledge-base/build/system-shape.md

Boundary: The engine owns interpret-the-JSON-DSL and run-a-workflow-step; the plugin contract owns what action handlers must implement; the MCP server owns expose-plugins-to-AI-agents

Dependency: The engine depends on the contract; the MCP server depends on the engine; plugins depend on the contract and on whatever third-party SDKs their action handlers call (Ghost, Resend, etc.)

Handoff: The MCP server receives the invoke from the AI agent, loads the plugin, hands the workflow to the engine, the engine calls each action handler in order and returns inspectable state at each step

From 2.2.3, Understanding the Shape of the System Before You Change It.

build/differentiation.md

Differentiation in the readability and AI-driveability of the artifact. Use this shape if your edge is making something legible that the alternatives obscure.

# knowledge-base/build/differentiation.md

Real advantage: Plugins are JSON definitions plus action handlers, so any operator can read the workflow without learning a state-machine library and any AI agent can run it without learning a new SDK

Where it shows up: In the moment a non-author reads someone else's plugin and understands exactly what it does, plus the moment a fresh AI agent successfully runs it without specific training

What stays standard: Schema validation, JSON parsing and MCP transport stay on battle-tested libraries (Zod, the MCP SDK) because nothing about the wire format or the validation is worth making different

From 2.3.1, Where the Real Differentiation Actually Lives in Your Build.

build/not-in-v1.md

A cut that protects the engine from becoming a platform. Use this shape if your v1 risk is layering features that turn a primitive into a full product.

# knowledge-base/build/not-in-v1.md

Core path: A plugin author writes JSON, the engine runs it, an AI agent invokes it via MCP, state is inspectable at each step

Feature to cut: A visual workflow editor that lets non-JSON-comfortable users design plugins by dragging blocks, tempting for v1 but pulling the product from engine into platform

Why the cut strengthens it: A visual editor is a full product of its own; v1 keeps the engine sharp by trusting that plugin authors who care about JSON workflows can read and write JSON workflows

From 2.3.2, Why Cutting Features Is a Design Skill Most Builders Skip.

build/proof-metric.md

A metric on independent adoption: others writing and running plugins, not just you. Use this shape if your product needs an ecosystem to prove it works.

# knowledge-base/build/proof-metric.md

Metric: The number of independent plugins running successfully via the MCP server in production-like use

User behaviour: A plugin author writes a plugin, an AI agent invokes it for real work, the workflow completes deterministically

Threshold: Five independent plugins from three independent authors running successfully in real use before extending the engine beyond v1

From 2.3.3, The One Metric That Proves This Works for Real Users.

launch/sharing-plan.md

An audience that exemplifies the developer profile you are targeting. Use this shape if your product is a developer primitive and the early test is whether developers can read what you wrote.

# knowledge-base/launch/sharing-plan.md

Audience: Two or three developers who already use Claude or other AI agents day-to-day and have workflows they wish were repeatable

What to show: The minimal getting-started recipe plus one fully working plugin, so they can install, run and read the JSON without inventing their own use case first

Question to answer: Whether they can read the plugin and predict what it will do before running it, which is the real test of the DSL's legibility

From 3.1.1, Why Sharing Early Creates the Learning Your Build Needs.

launch/decision-signal.md

A signal read from usage repetition (ran more than once). Use this shape if your signal is integration into ongoing use rather than first-time use.

# knowledge-base/launch/decision-signal.md

Observable signal: Whether a plugin author runs their plugin via the MCP server more than once in the same week, read from invocation logs not from feedback

Behaviour behind it: An author finding the plugin useful enough to integrate into their actual workflow, not just an experiment

Decision it changes: Whether the engine is ready for second-plugin authoring, or whether the first plugin's friction needs more rounds of polish before more authors are invited in

From 3.1.2, Ask for Signals, Not Opinions, From the People You Trust.

launch/decision-threshold.md

A threshold for the developer onboarding experience. Use this shape if your launch hinges on independent authors succeeding without your help.

# knowledge-base/launch/decision-threshold.md

Threshold: If two consecutive first-time plugin authors hit a blocker that requires direct engineer help in the first hour, the docs or the DSL primitives are wrong, not the authors

Evidence source: Support questions and stuck-on tickets from the early-author group, plus the plugin code they shipped vs the one they wanted to ship

Action if met: Hold inviting more authors and rework the getting-started recipe and the most-asked-for primitive before expanding the ecosystem

From 3.1.3, Decide in Advance What Would Change Your Mind.

launch/learning-signal.md

A diagnostic question that separates capability gaps from documentation gaps. Use this shape if your authors are stuck and you cannot tell whether the tool or the explanation is at fault.

# knowledge-base/launch/learning-signal.md

Question: Are plugin authors stalling because the DSL cannot express what they need, or because the documentation does not show them how to use what is already there

Signal that answers it: Requests for new primitives that AI-agent searches show are unsolvable with current ones point at DSL gaps; requests already solvable point at docs gaps

Decision that follows: Add primitives sparingly when truly missing; otherwise add examples to the docs and link them from the place authors search

From 3.2.1, The Difference Between Learning and Being Stuck.

launch/review-context.md

A trade-off between declarative simplicity and expressive power. Use this shape if your reviewable decision is where to draw the line between configuration and code.

# knowledge-base/launch/review-context.md

Decision: The plugin DSL stays JSON-only rather than supporting an embedded scripting language for action handler logic

Trade-off: JSON keeps the plugin readable to non-authors and AI agents but pushes any conditional or computational logic into the action handler code

Question for the reviewer: Does JSON-plus-handlers stay readable as plugins grow, or does the split between declarative JSON and imperative handler become harder to follow than a single embedded language would have been

From 3.2.2, Explain Your Decisions Before Asking for Review.

launch/iteration-value-test.md

An iteration that improves debuggability for the technical user. Use this shape if your iteration is about reducing the cost of failure for someone using your primitive.

# knowledge-base/launch/iteration-value-test.md

What changed: The MCP server error responses moved from generic plugin-failed to including the plugin name, the failing step, the inputs and the exact contract violation

Meant to improve: Time for a plugin author to diagnose what went wrong when their plugin fails during AI-agent invocation

Signal it worked: Author-reported diagnose-then-fix times drop on follow-up failures, and support questions shift from what-went-wrong to is-this-the-intended-behaviour

From 3.2.3, Iteration Should Increase Value, Not Just Add Surface Area.

launch/readiness-rule.md

Readiness measured by independent authors completing the getting-started without help. Use this shape if your launch readiness is about onboarding success across operating systems and people.

# knowledge-base/launch/readiness-rule.md

What has to be true: A plugin author can install flowRun, write the canonical publish-and-email plugin, expose it via MCP and have Claude run it end to end with each step's state visible

How it is checked: Three independent first-time authors complete the getting-started recipe on three different operating systems without engineer help

Who owns remaining risk: The engine maintainer signs off DSL changes until at least five independent plugins ship and the test suite is broad enough to catch the kinds of regressions authors actually report

From 3.3.1, What "Ready" Actually Means Once Real Users Are Looking.

launch/launch-risks.md

A launch risk about a contract that ecosystem depends on (DSL stability). Use this shape if your launch's biggest risk is downstream breakage from upstream changes.

# knowledge-base/launch/launch-risks.md

This file accumulates one named risk at a time. Each risk follows the
same three-line shape: the likely failure, what triggers it and the
response that is ready before users hit it.

---

## Risk 1: A DSL change silently breaks already-shipped plugins

Failure mode: An engine update changes how a primitive interprets its inputs, and a plugin author's working plugin starts producing wrong output without throwing an error

Trigger: A small refactor of a primitive's edge-case behaviour that was not covered by the test suite because the original use was implicit

Response: Treat any change to a primitive's behaviour as a breaking change behind a versioned DSL field, plus a contract-test suite that runs every shipped plugin against every engine candidate before release

From 3.3.2, Name the Risks Yourself Before Users Find Them in Production.

launch/ownership-check.md

An imperfection that a later layer could address. Use this shape if your launch ships a primitive without the more-advanced capabilities, knowing those can land as separate layers.

# knowledge-base/launch/ownership-check.md

Still imperfect: The engine runs plugins in-process rather than offering hosted execution or durability across restarts, so a long-running plugin that crashes mid-flight loses its state

If it failed: An AI agent could trigger a multi-step plugin that fails halfway, leaving the user with no easy way to resume from where it stopped

Why shipping is acceptable: v1 targets shorter workflows where re-running from the start is acceptable, and the inspectable-state-at-each-step model lets the author or agent know exactly where the previous run stopped; durable execution can be added later as a separate plugin or layer without changing the core engine

From 3.3.3, Are You Comfortable Putting Your Name on This Build?.