Ed AI Assistant

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

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

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

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

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

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

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

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.