Draw how your work moves from state to state. Spoletta runs it, with AI agents doing the steps in between.
Spoletta is a visual builder and engine for processes that AI agents, bash scripts, people and built-in connectors carry out together. You model the process: what the work is about, the states it goes through, and what moves it on. Agents are the glue between those states. Each gets one job, with known inputs and a contract for what it hands back, and the process, not the agent, decides what happens next.
The full documentation is at spoletta.com/docs.
Give an agent a long prompt and every tool, and it may well get there. But the process is then hidden in a prompt. You can't see where a run is or why it went one way, nobody can sign off halfway, a failure at the ninth step means starting again from the first, and changing the process means rewording the prompt and hoping.
Most of what engineers do already follows a process. A ticket is triaged, a bug is fixed, a risky change waits for the tech lead, a release is written up and announced. Each is a state machine nobody wrote down. Spoletta has you write it down, as a board, and runs it.
The board is modelled on OPM, the Object-Process Methodology (ISO 19450), which describes any system with two kinds of thing:
- Objects are what the work is about: a ticket, a patch, a pull request. Each holds JSON with a known shape, and can be in one of several states, such as bug or feature, approved or changes requested. An object can be stored, so each run knows what earlier runs handled and the same issue isn't worked on twice.
- Processes make objects, change them, or move them to another state. An AI agent, a bash script, a person or a connector carries out each one.
Processes connect through the objects they make, not through arrows from
one step to the next: a process runs once what it takes exists, or when an
object enters the state it waits for. An agent can be swapped for a script,
or a script for a person, and what comes before and after stays as it is.
So each does what it is best at: a script with jq what a rule can decide,
a person the calls that are theirs, and an agent the judgement in between.
Every board reads as plain sentences, OPM's Object-Process Language (OPL), generated from the drawing. This is the flow above:
"Ticket" can be "bug" or "feature".
"Ticket" exhibits "title".
"Risk" can be "high" or "low".
"Risk" is "high" when score >= 7.
"Risk" is "low" when score < 7.
"Risk" exhibits "score" and "why".
"Tech lead" is a person.
"Triage" is an agent process, which an AI agent carries out.
"Triage" requires "Triage guide", which it doesn't change.
"Triage" yields "Ticket" as "bug" or "feature", deciding which.
"Fix" is an agent process, which an AI agent carries out.
"Fix" occurs if "Ticket" is "bug", and is skipped otherwise.
"Fix" yields "Risk".
"Merge" is a script process.
"Risk" entering "low" triggers "Merge".
"Approve risky fix" is a human process, which a person carries out.
"Tech lead" handles "Approve risky fix".
"Risk" entering "high" triggers "Approve risky fix".
"Plan" is an agent process, which an AI agent carries out.
"Ticket" entering "feature" triggers "Plan".
The flow starts with "Triage".
Look at what picks the branch. Fix only scores its change. Which score is
too risky to merge without the tech lead is the rule score >= 7, on the
board, where anyone can read it, change it and see it in the flow's
versions, rather than somewhere in a prompt. Agents can be given these
sentences too, so each knows the process it is part of.
A run of that flow. Triage marked the ticket a bug, Fix scored its change 10, so Risk came out high and the tech lead decided. Merge and Plan never ran.
| A process | is carried out by |
|---|---|
| Agent | an AI coding agent (pi) on the model you pick, optionally in git checkouts of the flow's repositories, with MCP servers, skills and credentials |
| Script | bash, with curl and jq |
| Human | a person, approving, sending work back with instructions, or filling something in |
| Connector | Spoletta itself, carrying out one operation of GitHub, Slack, Telegram, Google Sheets and Docs, Home Assistant or any HTTP API |
| Flow | a board of its own, zoomed into, run once or once per item of a list |
| Subflow | another flow, a procedure reused across jobs |
An object's attributes are the contract between the step that makes it and the steps that take it. An agent hands in its work through a tool that checks it against the contract; a reply that doesn't fit is sent back once with what was wrong, and then fails the step. A failure ends its branch, or goes to a handler you draw. Steps take timeouts and retries, a reviewing agent that sends work back is held to a number of rounds, and any other loop asks a person before it goes round too often, or round again on what it took before. Runs end; they don't spin.
A writer and a critic. The critic sent the post back three times, the most its rounds allow, so it failed the fourth time, and the editor took over through the failure connection drawn from it.
Agents work in git checkouts of the flow's repositories. What a step leaves is committed to the run's branch, with the run, the step and the agent's session as commit trailers, and the step shows its diff, file by file. A re-run starts from the commit the branch was at when its process first ran.
Each process that runs is a step you can open: what it took, what it handed
back, the agent's whole conversation, the files it changed, its log and what
it cost. Follow a run on a timeline of what ran at once and what waited, or
put two runs side by side to see where they parted. Re-run an ended run from
any process, editing what it takes, or try one process alone on inputs you
give. Search a flow's runs and the values they left with a faceted query such as
status:failed @Ticket.state:bug started:>now-7d. And ask the flow's
assistant why run 412 failed: it reads that run's steps, decisions and log.
A step's terminal. The agent's first hand-in didn't fit the contract, so it was told what was wrong, and its second was taken.
The same review loop on a timeline: the writer and the critic taking turns, the critic failing, the editor's decision (hatched while it waited for a person), then Publish.
Home lists every flow, task board, procedure and struct you see. Each flow
shows its latest runs as a strip, failures standing tallest in red, a click
on one opening that run, and chips count the flows failing, running or
waiting on you, each narrowing the list to them. Search finds anything by
name or tag: / goes there, Enter opens the first found. A side menu
narrows to a kind, a tag or an owner, and stays beside Activity, which
charts runs, failures, spending and how long reviews take across every
flow.
Task boards lay shared structs' records out in columns, each a struct and a
query of its records, such as Jira tickets state:new beside pull requests
state:in_review. As a flow or a person moves a record into another state it
moves to that column, so the states a flow works through read as its queue,
and a card opens its record to correct it or starts a flow on it. The
board's settings pick what its cards show, their ID linking to the
record's own page, such as the ticket in Jira.
A task board can drive records through their whole lifecycle too, a flow over flows. Lay its columns out from a struct's states, one for each, and press Play: while it plays, every record no flow is working on goes to the flow taking records in its state, such as triage for new exceptions and implementing for filed tickets, a run per record and as many at once as you allow, the rightmost columns first. A column's settings say which flow takes its state: the one naming it, else one taking records in any state. Where none does, or the column lets them rest, as a column of done ones should, records rest, and where several do, you pick one for the column. A card whose record is being run says so, with the flow, the step it is at and for how long. A record whose run fails, or ends leaving it where it was, is marked stuck on its card, with why, rather than started again for ever, and tried again with a click.
A review goes to the people whose role it names ("Finance handles Approve payment"). It shows in their inbox, across every flow, and they are told by email or on Slack, reminded while it waits, and past a time limit it fails over to the handler you drew: an escalation, say, or an agent making a default decision.
Every save is a version, and any two can be diffed. Publish one, and schedules, webhooks and the HTTP API run it while you go on editing the draft; publish an older one to roll back. The board lists what is wrong with a flow before it runs. The whole setup (flows, procedures, structs, skills and MCP servers) exports as a YAML file to keep in git, review in a pull request or have a model write. And each flow has an assistant that changes it from a description of what you want, then highlights what it changed.
Every board is a setup file too: the flow above, as YAML.
Agents and scripts run code nobody reviewed. They never hold a model key or a credential's secret: they reach models, MCP servers and your services through the webapp's proxies, with tokens that end with the step. Outside development, each step also runs in a container or Kubernetes pod of its own, which sees only its own directories and reaches only the webapp, and through it the internet only at the hosts admins allow. Admins cap what a run and a person may spend, and an audit log records every token handed out and every call through a credential.
A Go webapp on MySQL, with few dependencies. Run as many replicas as you like on one database: a run whose replica stops for a deploy is taken over by another and carries on from what it stored, its reviews still waiting. Other systems start flows over an HTTP API with idempotency keys, or through signed webhooks from GitHub, Slack or anything else, and flows run on schedules.
Six flows ship as templates to start from:
- Triage a ticket: an agent decides whether a ticket reports a bug or asks for a feature, and a fix is attempted or a spec written.
- Fix with an approval by risk: an agent fixes a bug and rates its change; a low-risk fix goes straight to a pull request, a risky one waits for the tech lead.
- Write and critique: one agent writes, another critiques until it is good, and an editor decides once the critic gives up.
- Daily digest to Slack: every weekday morning, an agent sums up what a channel said the day before and posts it.
- Answer each question of a list: an agent answers each question in a run of its own, and another gathers the answers into one page.
- Expense claim: a rule approves a small claim, finance a larger one.
The authoring guide works through more: fixing the top Sentry errors every weekday, each on a branch of its own and never the same issue twice; release notes with a person's sign-off; a quorum of reviewers.
podman compose up --buildThen open http://localhost:8080 and start from a template. docs/INSTALL.md covers models, repositories, signing in, secrets and running steps in a sandbox.
- The user manual: building and running flows in the app.
- Installing: running Spoletta, and what to set before others reach it.
- Authoring flows: OPM as Spoletta uses it, how a run goes, what each step sees and hands in, and worked examples.
- Setup files: the YAML format, field by field.
- Sandboxes: the threat model, what a step can reach, and Podman, Docker and Kubernetes.
- Secrets: how the database keeps secrets sealed, and
rotating
SECRET_KEY. - Replicas: running several webapps on one database.
- Migrations: writing one, and migrating down to run an older version.
- Development: building, testing and the code's layout.
Apache License 2.0, see LICENSE. The name "Spoletta" is not licensed for use by derivative works; see NOTICE.