---
title: "Ed AI Assistant — Visual Design Studio 0.1 documentation"
description: "Ed includes an AI assistant that can help authors work with BPMN diagrams and supporting process files. Use it as an authoring assistant, not as a substitute for reviewing and running the model."
source_url: https://spiff.works/docs/ed/ai_assistant.html
---

☰ Menu

# Ed AI Assistant[](#ed-ai-assistant "Link to this heading")

Ed includes an AI assistant that can help authors work with BPMN diagrams and supporting process files.
Use it as an authoring assistant, not as a substitute for reviewing and running the model.

## What the Assistant Can Help With[](#what-the-assistant-can-help-with "Link to this heading")

The assistant can help:

- inspect the current BPMN diagram;
- suggest or make BPMN changes;
- create or update form schema files;
- explain workflow behavior;
- run a diagram during authoring;
- debug common form, script, and routing issues;
- draft documentation for process models;
- query the built-in Ed documentation reference when the answer depends on documented Ed behavior;
- read the project collaboration journal and artifact index when they exist;
- create advisory project journal entries when team notes appear to drift from the project description.
- create offline Jira draft files from journal entries when the team wants planned or completed work represented as ticket-ready artifacts.

## Good Requests[](#good-requests "Link to this heading")

Useful requests are concrete and include the intended outcome.

Examples:

- “Add a User Task that collects requester name and email, then run the diagram to the form.”
- “Review this diagram for disconnected paths and unclear gateway labels.”
- “Create a Jinja-rendered dropdown from the `fruits` task data variable.”
- “Explain why this gateway is taking the fallback branch.”

## Review the Assistant’s Work[](#review-the-assistant-s-work "Link to this heading")

After the assistant changes a model:

- inspect the BPMN diagram visually;
- check generated JSON Schema and UI Schema files;
- run the diagram with realistic data;
- confirm task data contains only values that should persist;
- confirm the final model still matches the business process.

## Project Collaboration[](#project-collaboration "Link to this heading")

When a workspace includes `project-description.md`, `collaboration/artifact-index.md`, and `collaboration/journal/*.md`, the assistant uses them as project context.
Team notes remain project files so they can be reviewed, synced, and versioned with the BPMN source.

The assistant may add an `ed_guidance` journal entry when it sees possible drift from the project description, but it should not silently rewrite another team member’s note.

## Ed Documentation Reference[](#ed-documentation-reference "Link to this heading")

The assistant can search Ed’s built-in documentation reference with `query_ed_docs_reference`.
This reference includes the AI assistant, BPMN authoring, forms, run/debug, workspace/file, files service, GitHub sync, and Arena-vs-Ed docs.

When asked to audit Ed chat behavior, identify documentation deficiencies, or answer questions about documented Ed capabilities, the assistant should query this reference first and cite relevant doc paths in its response.
For Ed chat audits, the `ed/docs/ai_assistant.md` reference is the primary source.

## Jira Drafts[](#jira-drafts "Link to this heading")

When a workspace includes `collaboration/jira/`, the assistant can create Jira-ready draft files and update the local SS-to-Jira link map.
This is an offline drafting workflow until a connector proxy operation is configured for a real Jira project.

The assistant should be explicit that it created a local Jira draft, not a live Jira ticket.

## Documentation Check[](#documentation-check "Link to this heading")

When the assistant discovers or applies a reusable pattern, such as a form widget, Jinja schema pattern, BPMN modeling convention, or debugging approach, check whether the public documentation already explains it.
If it is not documented, add a documentation note to your task or update the docs with the same change.

This keeps Ed, Spiff Arena, and process authoring documentation aligned with real work.