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 or directly from the current conversation;

  • review conversational Jira drafts and record explicit human approval before an exact action can be proposed.

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 And Proposed Actions

The assistant can use create_jira_draft_from_context when the user says “Write a Jira ticket for that,” even before a Jira workspace exists. The resulting file is an unapproved draft. review_jira_draft records the final human-reviewed text and promotes an approved draft to ready; unapproved drafts cannot produce a create-issue proposal.

When a workspace includes collaboration/jira/, the assistant can also create Jira-ready draft files from journal entries and update the local SS-to-Jira link map. The assistant can also create human-reviewable Jira action files in collaboration/jira/actions/ with exact create, update, comment, transition, sprint/backlog, or rank payloads for a connector proxy.

The assistant should be explicit when it created a local Jira draft or proposed action, not a live Jira ticket. It should only describe a live Jira issue as created or updated when a connector result or host integration confirms the live Jira call.

The safe sequence is: draft, human review, ready draft, exact proposed action, separate live-write approval, connector result, and applied or failed audit record. Credentials are runtime-only and must never be written to project files.

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.