The workflow editor

The workflow editor is where a custom workflow takes shape: you lay its machines out on the dashboard, tell each one what to do, draw each one however you like, and pass what one stage produces to the next. Everything you change is saved into the workflow's own folder as you go.

I Open the editor

Select a custom workflow in the workflow picker on the right side of the dashboard and switch on Edit, beside the picker. A workflow you've just created opens with the editor already on. While it's open, the Execution Console, the run panels and the ticket counts step aside so the whole canvas is in reach. Switch Edit off, or pick another workflow, to leave. The switch is locked while a run is in progress. PR Pro, once installed, opens the same way: pick it in the picker and switch on Edit, and its six machines fill the canvas.

II Name and describe it

While the editor is open, the header holds the workflow's details. Click one to change it; Enter saves and Escape discards.

• Name — what the workflow is called in the header and the picker: PR Pro.
• Description — one line on what the workflow is for, shown beside its name. PR Pro's reads “Reviews the open pull requests in your repositories and posts what it finds as a comment on each one.” Click + Add description when there isn't one.
• Id — the small line under the name, and the name of the workflow's folder: lowercase letters, digits and hyphens, so pr-pro. Changing it moves the folder, and the workflow's settings move with it.
• Version — a whole number such as v2. Every workflow starts at 1, where PR Pro still is; raise it when the workflow changes in a way people should notice.
• Repository URL — a web address where the workflow's source lives, so anyone running a copy can look for newer versions. PR Pro's points at github.com/alfonsocejudo/pr-pro. Click + Add repository URL to set one.

Beside the version is the email of the account that created the workflow. It's recorded once and can't be changed.

III Place the machines

Each stage is a machine on the dashboard. To add one:

1. Click Add Machine. In an empty workflow the first machine is placed straight away; after that, a placeholder machine appears below the row.
2. Drag the placeholder over the row. A line marks the gap it will land in — drop it there. Drop it onto an existing machine instead to stack the two (section V).
3. Choose what kind of stage it is.

To back out, click Cancel below the placeholder, click elsewhere on the canvas, or press Escape. Drag a machine along the row to reorder it, or hover it and click the × at its corner to remove it. Click the label above a machine to rename it. The row shrinks as it grows, so every machine stays in view. PR Pro's row runs left to right in the order its machines were placed: PR Scan, Discussion, Correctness, Quality, Evidence, Publish.

IV The ticket loop

Adding a stage that makes tickets — Ticket Scanner, Specifications, Single Prompt, or a Custom Code stage that outputs tickets — makes the workflow ticket-based. Two lines split the canvas into three zones:

• Before tickets — runs once, first. The stage that makes the tickets sits here, with its Scan or Create button.
• For each ticket — runs once per ticket. Only stages here see the ticket: an agent stage gets its key, summary and description with its prompt.
• After all tickets — runs once, when every ticket is done.

The zone you drop a machine into sets when it runs, and each zone's picker offers only the stages that belong there. Failures land differently too: one before the loop ends the run, one inside it sets that ticket aside in Attention while the others carry on, and one after it is reported without undoing the finished work. Hover the ? beside a zone's name for a summary. With Single Prompt, the zones read Before the ticket, For the ticket and After the ticket. PR Pro uses two of the three: PR Scan stands before the loop with the Scan button, and the other five machines run for each ticket — once per open pull request, so a review that fails sets that pull request aside while the rest carry on.

V Stack two stages

One machine can carry two stages, the way the built-in workflows put Documentation and Publish on one machine. Drop a new or existing machine onto another — it highlights while you hover — and the two run one after the other, top label first. PR Pro stacks nothing: each of its six stages keeps a machine of its own.

• The bottom stage is optional: its tab in Config → Workflow starts with an Enabled switch. Switched off, runs skip it and its label dims.
• Click unstack beside the bottom label to move it back to a machine of its own.
• A stack holds two stages, the stage that makes tickets keeps a machine to itself, and both stages have to sit in the same zone.
• Deleting a stacked machine removes both stages. To keep one, unstack it first.

VI Set up a stage

Click the gear above a machine's label. At the top, a switch picks AI Agent or Custom Code, and a Description field holds your own summary of the stage, shown as its About section in Config → Workflow — the paragraph each PR Pro stage shows there is this field. Below are three tabs:

• Prompt — for an AI Agent stage, the instructions the agent follows. The stage's inputs, outputs and settings sit under the field as pills; click one to drop its name in at the cursor. An empty prompt stops the run at that stage. For a Custom Code stage, the tab links to the stage's file instead, and Stage reference lists everything your code can reach. Every PR Pro stage is Custom Code, so its tab points at a file: stages/correctness.ts for Correctness.
• I/O — what the stage reads and writes (section VII).
• Settings — knobs you can change from run to run (section VIII).

Save keeps your changes; closing the dialog any other way discards them. Built-in stages bring their own logic, so their gear describes what they do. The agent that drives an AI Agent stage, and its model, are chosen in the stage's tab in Config → Workflow; until you choose, it runs on your first registered agent. A Custom Code stage whose code calls an agent has the same picker: PR Pro's Correctness, Quality and Evidence each do.

VII Pass work between stages

Stages hand work to one another through Workflow Shared Data, at the top of the gear dialog: named fields, such as researchNotes, that belong to the whole workflow. A name starts with a letter and uses letters, numbers and underscores. PR Pro has five: existingComments, correctnessFindings, qualityFindings, verifiedReview and reviewScreenshots.

• On the stage that produces something, pick the field under Outputs. On the stages that use it, pick it under Inputs. In PR Pro, Discussion outputs existingComments and the three review stages each take it as an input; each review stage also reads the findings of the ones before it, and Evidence hands verifiedReview and reviewScreenshots on to Publish.
• An AI Agent stage gets each input with its prompt, under the field's name. With one output, the agent's whole reply is saved to it; with several, say in the prompt what belongs in each.
• A Custom Code stage reads its inputs and writes its outputs in code, and has to declare every field it touches. When the code reaches a field that isn't declared, the I/O tab names it and the machine wears a warning badge. PR Pro's Evidence declares three inputs and two outputs this way.

The dialog points out a prompt that never mentions one of its inputs — or, with several outputs, one of its outputs — since the agent would get it without knowing what it's for. It's a hint; Save still works.

VIII Add settings

On the Settings tab, add a setting, name it, give it a help line if you like, and pick a kind. PR Pro's PR Scan has seven settings, across five of the kinds:

• Number — with a minimum, maximum and default: Updated in the last N days, 0 to 365, default 0.
• Choice — a list of options with a default.
• On / off: Include draft pull requests and Include already-reviewed pull requests, both off by default.
• Text — free-form, with a default: Only these authors, empty by default.
• Date — picked from a calendar; left empty, it means no date: Updated on or after and Updated on or before.
• Folder — a path, with Browse….
• Repositories — some of the repositories in Config → General → Local repositories: Repositories to scan.

Values are set in the stage's tab in Config → Workflow and apply every time it runs. An AI Agent stage gets each value with its prompt, so a setting changes what the agent does without any code. Text, Date, Folder and Repositories settings can be marked Required: while one is empty, the machine wears a warning badge and the stage won't run. Repositories to scan is PR Pro's one required setting, so a fresh install wears the badge until you pick a repository.

IX Where your work is saved

The editor saves as you work, into the workflow's folder: the row of machines into workflow.json, and each machine into its own file under stages/, named after its label — PR Scan becomes stages/pr-scan.ts. Once a stage has a prompt, code, artwork or a model of its own, its file name stays put and only the label changes. The files are yours: the editor writes a starter and never overwrites your edits. Each machine's picture is an SVG file beside its stage file (section X). If a change can't be saved, a message says so. PR Pro's folder is laid out this way, with a few files more: a Test twin beside each stage, such as stages/pr-scan.fixture.ts, helpers the stages share, and a README. A file under stages/ that isn't a machine only has to keep clear of the machines' names. Edit a workflow you got from someone else and its approval lapses — the next run asks you again.

X Draw the machines

Every machine is a picture, and the picture is yours. A new machine is drawn as the standard machine — the dark box with a beacon on top — and that drawing is an SVG file beside the stage's file, named after it: stages/pr-scan.svg for PR Scan. Open it in any SVG editor, or a text editor, and draw whatever the stage should look like; the dashboard shows your drawing in the machine's place, in the editor and during runs. Delete the file and the standard machine is back. A few rules keep a drawing in step with the scene:

• The box is 150 wide by 130 high, with the ground line along its bottom edge — the machine stands on the platform at that line. Keep the file's viewBox as the starter has it.
• Keep everything inside the file. The drawing is placed into the page, not loaded as an image, so it's cleaned on the way in: scripts, links to other files and SVG's own <animate> don't survive. Gradients, filters and CSS animations do.
• Prefix your names. Every machine's drawing shares one page, so an id or class name used by two files collides. PR Pro prefixes each machine's with its own tag, cor- for Correctness.
• A stacked pair shows the top stage's drawing; the bottom stage has none of its own.

The drawing can react to the run. While a workflow runs, the dashboard marks each machine with its phase — pending, active or done — and with a state name the stage sets for itself: a Custom Code stage calls ctx.machine.setState("…") with any name it likes, as often as it likes. A rule in the file's <style> block picks either up, [data-machine-phase="active"] or [data-machine-state="inspecting"], and animates or recolours whatever it selects; the starter already pulses its beacon while its stage runs. Under each machine in the editor, a dropdown previews the drawing in any of those moments without running anything: the run's own states — Pending, Active, Complete, Failed, Aborted, Filtered — and, under Artwork states, every state the file has a rule for, read out of the file itself, so a rule you add is offered the next time the drawing loads. An edit to the drawing shows the next time the workflow is opened; an edit to the stage's code needs the app restarted.

XI Try it

Switch Edit off and the machines stand ready, each with the same Live/Test pill the built-in stages have. A stage pinned to Test skips the real agent call, so you can watch the whole sequence run end to end before spending anything. Every PR Pro stage has a Test twin, so on Test a Scan queues canned pull requests, the reviews return canned reports with no agent calls, and Publish shows the real preview dialog without posting anything. Custom workflows covers how a run starts.

XII Delete a workflow

Delete Workflow, in the editor's bottom-left corner, asks what to remove: the workflow — its folder, or, for a folder of your own, just its place in the app — and, if you tick it, its saved runs in every workspace. Whatever you tick is gone for good. PR Pro linked from its clone is the second case: Remove this workflow from the app leaves the clone where it is, with every file. Sharing a workflow is covered in Custom workflows.