Add ADR for Shared CNCF Workflow Specification Editor

adr/v1.0-adr-shared-workflow-editor.md

@@ -0,0 +1,194 @@
+# ADR: Shared CNCF Workflow Specification Editor & Multi-Maintainer Collaboration Model
+
+## Status
+
+Proposed
+
+## Context
+
+There is a need for a shared editor for the CNCF Serverless Workflow Specification that
+can be used consistently by multiple implementations (e.g. Quarkus Flow,
+SonataFlow, ZigFlow, Synapse, Lemline), as different tools provide inconsistent
+authoring and visualization experiences, leading to duplicated effort and fragmented tooling.
+
+Today we have:
+
+- An existing (but aging) VS Code extension for Serverless Workflow
+- Several product-specific editors embedded in consoles or IDEs
+- Fragmented UX and duplicated effort around:
+   - YAML/JSON authoring
+   - Visual diagramming
+   - Validation against the spec schema
+
+We want to converge on a single core editor stack driven by the CNCF
+Serverless Workflow Specification, with a collaboration model that allows
+multiple vendors/maintainers to contribute and embed it.
+
+This ADR formalizes the decision to build a shared editor, with a strictly
+scoped MVP, aligned with the proposal outlined in
+[serverlessworkflow/specification#1131](https://github.com/serverlessworkflow/specification/issues/1131) and further refined through MVP
+scoping discussions.
+
+## Decision
+
+After evaluating existing solutions, potential approaches, and their
+associated dependencies, we decided to build the editor from scratch to
+retain full ownership of the architecture and release process, prioritize
+architectural simplicity, enable CNCF hosting and long-term sustainability,
+at the cost of slower initial delivery.
+
+## Licensing
+
+- Apache 2.0.
+- All dependencies must be CNCF compatible.
+- React Flow is MIT licensed and acceptable.
+
+## Governance & Community Alignment
+
+We want a multi-maintainer editor project that does not belong to a single
+vendor.
+
+### Proposed model
+
+- Repository ownership
+   - New repo under the CNCF Serverless Workflow Specification org, e.g. `workflow-spec-editor` (name TBD).
+
+- Maintainers
+
+   - Initial maintainers: representatives from at least:
+     - CNCF Serverless Workflow Specification maintainers
+     - Quarkus Flow / SonataFlow
+     - Other interested engine maintainers (e.g. ZigFlow / Synapse / Lemline etc.).
+
+- Decision process
+
+   - Use the spec’s existing governance as a reference (PR review rules, approvals).
+
+   - Editor decisions should:
+     - Respect the spec as the single source of truth
+     - Avoid baking in engine-specific opinions by default
+
+- Integration responsibilities
+
+   - Core editor project provides:
+
+     - NPM package(s)
+     - Reference VS Code extension
+     - Docs and examples
+
+   - Each implementation (Quarkus Flow, Synapse, etc.) owns:
+
+     - Their integration/embedding
+     - Optional extension/profile configuration
+
+- Release strategy
+   - Align with spec releases when possible (e.g. new spec fields -> new editor release).
+   - Support at least the latest minor and one previous minor version of the spec.
+
+## Initial Scope (v1.0)
+
+### 1. In Scope
+
+- Read-only visual representation of YAML / JSON workflow definitions
+- Visualize all task types and transitions
+- Fully expanded nested task visualization
+- Indication of basic validation issues
+- Editor available via NPM package
+- A simple demo app showing how to embed the editor as a component
+- Documentation for integrators
+
+### 2. UX & Design Decisions
+
+- Light and dark theme support
+- Localization infrastructure in place, English only content for MVP
+- Rely on out-of-the-box accessibility from React Flow
+- Responsiveness is not a focus for MVP, as the editor is intended for
+  desktop usage rather than mobile devices
+
+### 3. Diagram Semantics & Representation
+
+- Support all task types defined by the Serverless Workflow specification.
+- Twelve task types represented visually.
+- Task types differentiated using icons, custom node shapes are avoided for MVP due to layout complexity.
+
+### 4. Validation
+
+- The editor performs lightweight client-side schema/structural validation to determine whether the workflow can be rendered.
+- The backend (runtime implementation) remains the source of truth for full specification conformance and advanced validation rules.
+  - Edge cases to handle: validation discrepancies between the TypeScript SDK and the backend (runtime implementation).
+- If structural validation passes and rendering is possible, render the workflow.
+- If structural validation fails and rendering is not possible, do not attempt to render a partial/invalid diagram; provide clear, actionable error feedback to the user instead.
+
+### 5. Nested Tasks & Layout Strategy
+
+- All nested tasks are fully expanded in the diagram.
+- No collapsing or layered presentation in MVP. Collapsible or hierarchical views are deferred due to layout and UX complexity.
+- Nested workflow UX will be revisited post MVP.
+
+### 6. Development & Tooling Decisions Overview (MVP)
+
+- Web-based implementation
+- React/TypeScript-based architecture
+- Diagram rendering via React Flow
+- Webpack for application bundling
+- Jest for unit testing
+- Playwright for end-to-end testing
+- Storybook for component development and documentation
+- Node.js for development and build tooling
+- pnpm for dependency management
+- GitHub Dependabot for dependency security and updates
+
+## Consequences
+
+### Positive
+
+- CNCF-aligned ownership
+- Lowers the entry barrier to the CNCF Serverless Workflow Specification
+- Encourages understanding and usage of workflow semantics
+- Reduces duplicated tooling effort across runtimes
+- Provides a shared, consistent user experience
+- Enables incremental evolution without over-engineering MVP
+- Clear architectural simplicity and long-term maintainability
+- Full control over release cadence and scope
+
+### Trade-Offs
+
+- Slower initial feature delivery compared to reuse-based approaches
+- Temporary feature gap relative to existing editors, as the initial scope
+  must remain conservative while the editor is built from the ground up
+- Increased upfront engineering investment
+- Limited UX sophistication in MVP
+- Requires ongoing coordination to keep the editor aligned with evolving
+  specification versions
+
+## Milestones
+
+### Milestone 1 (August 2026) - MVP Editor
+
+- Editor available via NPM package
+- Read-only visual representation of workflows
+- Light/dark theme support
+- English only locale setup
+- Basic error feedback when rendering fails
+- Demo web app
+
+### Milestone 2 (December 2026) - Dual Visual/Text Editor for YAML/JSON workflows
+
+- Dual visual and text editor
+- Text and visual toggles
+- The editor should be able to write back to disk, and users should be able
+  to have complete freedom to create, update, and delete nodes - including
+  creating a new workflow from the ground up
+- Syntax highlighting and validation
+- VS Code and Chrome extensions
+
+### Milestone 3 (TBD/2027) - External Catalogs and Messaging Support
+
+- Add every OpenAPI spec available in the context to ease creation of
+  OpenAPI-based tasks
+- Connect to external catalogs such as Apicurio (others to evaluate and
+  explore at the time) to ease creation of OpenAPI and HTTP-based tasks
+- Interfaces to start workflows with CloudEvents – support for events data
+  structure (pluggable via HTTP to connect to any backend)
+- Mock services from the OpenAPI catalog, so users won't need to have all the
+  services available to test their workflows while editing