Guide / Draw and edit
Review the changes an agent proposes
When an AI agent wants to change a diagram, the change is drawn on the canvas as ghost elements, checked, and waits for you to accept or reject it. You can look at the picture, or at the file's own diff, before you decide.
What it is
An agent in the AI chat never writes to your project without asking. It stops with a question, Apply 3 changes to order-process.bpmn?, and waits. For a diagram, that question comes with the change drawn in terms of the diagram, not as XML: a list of the changes, a small picture of the part it touches, and the proposal on the canvas as ghosts. You decide on the card or on the canvas. Either answers the same question.
Raw XML never stands in the conversation as an answer's text. The source of every change is one press away, for the cases a picture cannot show.
Review a proposal
- Ask the agent for a change in the chat. When it is ready, the card shows a question with the changes as a list:
+for what is added,~for what is changed and-for what is removed. Each name in it is a chip. Hover a chip to light the element on the canvas. - Read what Penstock checked. For a diagram, a line says Check is clean or N problems to look at. It is the diagram check run on the changed diagram.
- Press Show on canvas to see the proposal on the diagram. The card folds to give the canvas room.
- Press Allow to apply the change, or Deny to refuse it. Deny holds the focus, and Enter does not press it.
The note next to the buttons says that undo takes an allowed change back. An answer to a write holds for that one question and is not remembered: there is no Always.
The receipt
After a change is written, Penstock records a verification receipt: what changed, the Check result before and after with the new findings named, the scenarios run, and a verdict. The chat shows it as a card under the answer, and Pro hands new errors back to the agent to fix. See AI receipt and auto-repair.
The picture and the source
Each change has a small switch, Picture and Source.
| Picture | A small drawing of the part of the diagram the change touches. What is added is in the success colour, what is removed in the error colour, and the rest is muted. There is at most one picture to an answer. Anything that is a name is a chip instead. |
| Source | The file's own diff, drawn by Penstock: changed lines tinted and marked with + and -, line numbers, three lines of context, and the unchanged stretches folded. A folded stretch opens when you press it. It scrolls inside the card. |
| Open diff | Opens the diff in the tool's own diff viewer where it has one, such as the diff window of a code editor. Otherwise a dialog shows the same diff. |
A change that has no picture opens on Source. That is a code file, or a change that no element shows: a listener, an input mapping, a script, the Java of a worker. The Chat tab may show more than the card does, but the card keeps the agent's work folded.
A change that was applied leaves one row, Changed 3 elements, whose chips flash the elements on the canvas.
The proposal on the canvas
While the question waits, the diagram you have open shows the proposal as ghosts: new elements and flows drawn as ghosts where they would go, and what would be removed or moved marked as such. A bar on the canvas, Proposed changes, holds the decision. Penstock checks the proposal first, and the bar says Checking the proposed changes… until the result is in.
- A file the agent writes whole. The bar offers Accept change and Reject change, because the agent writes the whole file and the change is accepted or rejected as one. This is the same answer as Allow and Deny on the card.
- A list of separate changes. The bar says how many of them are left to review, and shows one at a time, with a chip for its kind (Add, Connect, Delete, Rename, Move, Condition, Reference, Worker or Change) and its result: Passed, Warning, Error or Cannot be applied. Accept and Reject decide this one. Accept all and Reject all decide the rest. Each accepted change is one step you can undo. Show all changes opens the whole list.
With separate changes, J goes to the next change and K to the previous one, as long as the focus is not in a text field. There is also a field, Comment for the agent, to send a note about the change in view. Some changes cannot be drawn as ghosts, such as an element type that changes or a flow that is reconnected. The bar lists them as not shown as ghosts, and Source shows them.
What undo covers
Penstock keeps a checkpoint of the diagram before each accepted step, in memory. When the review is finished the bar says how many changes were accepted and rejected, and what undo does not cover:
- Comments you sent to the agent stay sent.
- Only this diagram is covered. Forms, decision tables and code the agent changed are not.
- A deployment made after accepting is not withdrawn.
- The checkpoint is gone when the editor is closed or reloaded.
What Penstock checks before it allows
A change an agent makes through Penstock's own tools goes through the same editing as penstock edit. The editor's modelling places and connects each new element, so the picture stays right. The diagram is read back and checked, on the old version and on the new one, so a problem that was already there is not blamed on the agent. An edit that would break the drawing is not written. The result is what the card shows as Check is clean or a count of problems, and what the bar shows for each change.
The agent can ask for an edit to be previewed first. The chat then reads Previewed an edit of order-process.bpmn and changes nothing.
The typed operations
An agent proposes a change as a short list of operations, the same vocabulary as penstock edit --ops and the MCP tool edit_diagram. Several operations apply together or not at all.
| Operation | What it does | Needs |
|---|---|---|
add | Adds an element after an existing one, placed and connected as the editor does it, with an optional name, id, event type and properties. | element and after |
connect | Draws a sequence flow between two elements, with an optional name and condition. | from and to |
set | Changes properties of an element or a flow. On a business rule task that includes the decision it calls: decisionRef on Camunda 7, decisionId on Camunda 8. | id and properties |
remove | Removes an element or a flow, with the flows attached to it. | id |
move | Moves an element by dx and dy, in diagram units. | id, dx and dy |
Only properties the engine of the diagram knows are accepted. penstock edit <file> --schema prints the contract for the file's engine, and it is free. In the command line, add, connect, set and remove can be spelled out in words, and move is given in the JSON of --ops. See Edit a diagram from the command line for the elements, event types and properties.
What you see
- A question in the card or the Chat tab with a list of changes, a result of the check, and Deny, Allow and Show on canvas.
- Ghost elements on the canvas and a bar to accept or reject them.
- A Picture and Source switch and an Open diff link on each change.
Common problems
- Show on canvas is not there.
- It is shown for a change to a BPMN file. A change to a code file, a form or a decision opens on Source instead. When the diagram of the change is not the one in this editor, the button opens that file.
- The change shows no picture.
- Nothing in it can be drawn. Press Source.
- The Accept button is disabled.
- The change cannot be applied: it needs a change that was rejected, or it no longer fits the diagram. The bar says why.
- The diff is too large to show.
- The card says the change is too large to show there. Open diff opens it in the tool's diff viewer.
- I allowed a change and want it back.
- Undo. For a diagram, one undo takes back one accepted step. Forms, decisions and code are not covered.