diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index e40638e..d865199 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,10 +15,12 @@ No compatibility guarantees before 1.0. ## Dependency Graph -Two parallel implementation tracks converge at v0.50.0 (MVP). The -extension track builds the package ecosystem and workflow capabilities. -The operations track builds production readiness for multi-team -deployment. Neither blocks the other until the MVP gate. +Three parallel implementation tracks converge at v0.50.0 (MVP). The +extension track (v0.38.x) builds the package ecosystem that dynamic +workflows depend on. The workflow track (v0.39.x) builds both simple +and dynamic workflow capabilities on that foundation. The operations +track builds production readiness. A polish series (v0.40.x) follows +to stabilize for MVP. ``` v0.9.x–v0.28.7 Foundation through Platform Polish ✅ @@ -52,17 +54,23 @@ v0.9.x–v0.28.7 Foundation through Platform Polish ✅ │ v0.37.17–18 Surfaces ✅ │ │ v0.37.19 Tag │ │ │ │ - │ v0.38.x Workflow │ - │ Product Maturity │ + v0.38.0–.4 │ │ + Extension │ │ + Continuation │ │ │ │ │ - v0.39.0 │ │ - v0.39.1 │ │ - v0.39.2 │ │ - v0.39.3 │ │ + ├────────────┤ │ + │ │ │ + │ v0.39.x Workflow │ + │ Product Maturity │ + │ (simple + dynamic) │ + │ │ │ + │ v0.40.x Polish │ + │ (bug hunt, dead │ + │ code, stabilize) │ │ │ │ ══════╪════════════╪═════════════════╪══════ │ MVP v0.50.0 │ - │ (all three tracks complete │ + │ (all tracks complete │ │ + mobile + deploy docs) │ ══════╪════════════╪═════════════════╪══════ │ @@ -254,36 +262,81 @@ light mode CSS audit, dead code hunt. Every capability has a UI. --- -## v0.38.x — Workflow Product Maturity - -See [ROADMAP-0.38](Workflow/ROADMAP-0.38.md) for full version plan. - -Visual workflow builder series. Bridges .37 plumbing to MVP gate -("team admins build workflows visually"). - -| Version | Summary | MVP Role | -|---------|---------|----------| -| v0.38.0 | Form Builder | **Blocker** — visual field editor replaces JSON textarea | -| v0.38.1 | Stage Reorder + Bulk Ops | DnD reorder, multi-select operations | -| v0.38.2 | SLA Alerting | Scheduled scanner, breach notifications | -| v0.38.3 | Visitor Experience | Branding, progress indicator, email notifications | -| v0.38.4 | Workflow Templates + Clone | 5 built-in templates, deep copy | -| v0.38.5 | Analytics Dashboard | Throughput, cycle time, SLA compliance | - ---- - -## v0.39.x — Extension Track Continuation +## v0.38.x — Extension Track Continuation Resumes the extension track (v0.29–v0.31 ✅) with three new platform -primitives: multi-file Starlark packages, extension connections, and library -packages. See design docs for full specifications. +primitives: multi-file Starlark packages, extension connections, and +library packages. Culminates in a git-board rewrite that validates the +entire stack. **Must ship before v0.39.x** — dynamic workflows depend +on `load()`, connections, and libraries. + +See design docs for full specifications. | Version | Summary | Design Doc | |---------|---------|------------| -| v0.39.0 | Multi-file Starlark | [DESIGN-MULTI-FILE-STARLARK.md](DESIGN-MULTI-FILE-STARLARK.md) — `load()` support, disk-based scripts, package-scoped loader. Prerequisite for libraries. 5 backend changesets. | -| v0.39.1 | Extension Connections | [DESIGN-EXT-CONNECTIONS-LIBRARIES.md](DESIGN-EXT-CONNECTIONS-LIBRARIES.md) Part 1 — `ext_connections` table, scoped CRUD (personal → team → global resolution), `connections` Starlark module, 3 management UIs. | -| v0.39.2 | Library Packages | Part 2 — `library` package type, `ext_dependencies` table, `lib.load()` with per-library permission context, dependency resolution, uninstall protection. | -| v0.39.3 | Full Composition | Part 3 — Libraries declare connection types for consumers, reference `gitea-client` library, migrate `git-board` to library-backed surface. | +| v0.38.0 | Multi-file Starlark | [DESIGN-MULTI-FILE-STARLARK.md](DESIGN-MULTI-FILE-STARLARK.md) — `load()` support, disk-based scripts, package-scoped loader. Prerequisite for libraries. 5 backend changesets. | +| v0.38.1 | Extension Connections | [DESIGN-EXT-CONNECTIONS-LIBRARIES.md](DESIGN-EXT-CONNECTIONS-LIBRARIES.md) Part 1 — `ext_connections` table, scoped CRUD (personal → team → global resolution), `connections` Starlark module, 3 management UIs. | +| v0.38.2 | Library Packages | Part 2 — `library` package type, `ext_dependencies` table, `lib.load()` with per-library permission context, dependency resolution, uninstall protection. | +| v0.38.3 | Full Composition | Part 3 — Libraries declare connection types for consumers, reference `gitea-client` library. | +| v0.38.4 | Git-board Rewrite | Capstone validation — rewrite git-board as multi-package, multi-platform extension (Gitea/GitLab/GitHub). Proves the entire extension architecture works end-to-end. Reference implementation for future extension authors. | + +--- + +## v0.39.x — Workflow Product Maturity + +See [ROADMAP-0.39](Workflow/ROADMAP-0.39.md) for full version plan. + +Dual workflow architecture: **simple** (static stages, fixed forms, +declarative rules) and **dynamic** (Starlark-driven branching, API-backed +pre-screening, tailored data collection). A single workflow graph can +mix both types. + +Depends on: v0.38.x (dynamic stages require `load()`, connections, +and libraries for external API calls and reusable logic). + +### Stage Graph Architecture + +Three node types in the workflow graph: + +- **Simple stage** — declarative form, fixed fields, built-in renderer. + Team admins author these visually (form builder). +- **Dynamic stage** — Starlark hook runs at entry, returns form + config/routing based on customer data. Developers author these. +- **Automated stage** — no UI, Starlark execution only (API calls, + data transforms, pre-screening). Invisible to visitors. + +**Branching:** layered approach — declarative rules (`if customer.type +== enterprise → stage A`) for simple cases, optional Starlark hook for +complex branching logic. Progressive complexity. + +**Visitor surface:** standalone portal (branded URL, no chat chrome). +The portal renders whatever the current stage dictates — it doesn't +care whether the stage config came from static definition or Starlark. + +### Version Plan + +| Version | Summary | MVP Role | +|---------|---------|----------| +| v0.39.0 | Stage Graph Engine + Form Builder | **Blocker** — graph execution engine with simple/dynamic/automated node types; visual field editor replaces JSON textarea | +| v0.39.1 | Stage Reorder + Bulk Ops | DnD reorder, multi-select operations | +| v0.39.2 | SLA Alerting | Scheduled scanner, breach notifications | +| v0.39.3 | Visitor Portal | Standalone branded portal, progress indicator, email notifications, session resume | +| v0.39.4 | Workflow Templates + Clone | Built-in templates, deep copy | +| v0.39.5 | Analytics Dashboard | Throughput, cycle time, SLA compliance | + +--- + +## v0.40.x — Polish + +Bug hunt, dead code hunt, stabilization. As many sub-versions as +needed to reach a polished MVP-ready product. May pull in features +from ongoing stakeholder meetings. + +- [ ] UI bug fixes +- [ ] Dead code removal +- [ ] Performance audit +- [ ] Accessibility pass +- [ ] Additional features TBD from stakeholder input --- @@ -294,13 +347,19 @@ on a 3-node cluster. An IT team can operate the platform without reading Go source code. Team admins build workflows visually. **Requires all of:** -- Extension track through v0.31.2 (full package ecosystem, visual - workflow builder, SDK-based surfaces, team workflow self-service) +- Extension track through v0.31.2 (package ecosystem, SDK-based + surfaces, team workflow self-service) ✅ - Operations track through v0.34.0 (multi-replica HA, observability, data portability) ✅ - Workflow product v0.35.0 (form rendering, data pipeline, conditional - routing, structured review, monitoring dashboard) -- Full OpenAPI spec v0.36.0 (complete API documentation for all domains) + routing, structured review, monitoring dashboard) ✅ +- Full OpenAPI spec v0.36.0 (complete API documentation) ✅ +- UI rewrite v0.37.x (Preact+htm migration, all surfaces) ✅ +- Extension continuation v0.38.x (multi-file Starlark, connections, + libraries, git-board rewrite) +- Workflow maturity v0.39.x (stage graph engine, simple + dynamic + workflows, visitor portal, analytics) +- Polish v0.40.x (bug hunt, dead code, stabilization) **Additionally requires:** - [ ] Deployment guide: step-by-step for IT team (PG cluster, diff --git a/docs/Workflow/ROADMAP-0.38.md b/docs/Workflow/ROADMAP-0.39.md similarity index 67% rename from docs/Workflow/ROADMAP-0.38.md rename to docs/Workflow/ROADMAP-0.39.md index 226685c..8b0cd72 100644 --- a/docs/Workflow/ROADMAP-0.38.md +++ b/docs/Workflow/ROADMAP-0.39.md @@ -1,11 +1,56 @@ -# ROADMAP-0.38 — Workflow Product Maturity +# ROADMAP-0.39 — Workflow Product Maturity Everything deferred from v0.37.15 plus what the MVP gate actually requires: "Team admins build workflows **visually**." v0.37.15 delivers the plumbing — cancel, unclaim, reassign, stage CRUD -in the FE, queue views. This series builds the product on top of that -plumbing. +in the FE, queue views. v0.38.x delivers the extension infrastructure +(multi-file Starlark, connections, libraries) that dynamic workflows +depend on. This series builds the product on top of both foundations. + +**Two workflow camps:** +- **Simple workflows** — static stages, fixed forms, declarative rules. + Team admins author these visually. +- **Dynamic workflows** — Starlark-driven branching, API-backed + pre-screening, tailored data collection based on customer context. + Developers author these for team admins to deploy. + +A single workflow graph can mix simple, dynamic, and automated stages. + +--- + +## Stage Graph Architecture + +Three node types in the workflow graph: + +| Node Type | UI | Author | Example | +|-----------|-----|--------|---------| +| **Simple** | Declarative form, fixed fields, built-in renderer | Team admin (form builder) | "Collect name, email, issue type" | +| **Dynamic** | Starlark hook returns form config/routing at runtime | Developer | "Check CRM, skip fields we already know, route by customer tier" | +| **Automated** | No UI — Starlark execution only | Developer | "Call external API, transform data, pre-screen eligibility" | + +**Branching:** Layered approach — declarative rules for simple cases +(`if customer.type == enterprise → stage A`), optional Starlark hook +for complex branching. Progressive complexity: team admins use rules, +developers add hooks when needed. + +**Visitor surface:** Standalone portal (branded URL, no chat chrome). +The portal renders whatever the current stage dictates — it doesn't +care whether the stage config came from static definition or Starlark. + +### Example Mixed Workflow + +``` +[Pre-screen (automated: CRM lookup via Starlark)] + │ +[Branch: known customer?] + yes → [Verify Info (simple: pre-filled form)] + no → [Full Intake (dynamic: Starlark picks fields)] + │ +[Review (simple stage)] + │ +[Provision (automated: external API call)] +``` --- @@ -13,17 +58,21 @@ plumbing. ``` v0.37.15 Workflow Ownership & Lifecycle (plumbing) -v0.37.16 Projects Surface -v0.37.17 Debug / Model Surface +v0.37.16–18 Projects, Workspaces, Debug surfaces +v0.37.19 Tag ("UI Complete") │ - ── 0.37 tag ── +v0.38.0–.4 Extension Continuation (Starlark, connections, libraries, git-board) │ -v0.38.0 Form Builder ← team admins stop writing JSON -v0.38.1 Stage Reorder + Bulk Ops ← queue management at scale -v0.38.2 SLA Alerting ← stale queues self-report -v0.38.3 Visitor Experience ← the public face -v0.38.4 Workflow Templates + Clone ← reuse across teams -v0.38.5 Analytics Dashboard ← throughput, bottlenecks, SLA compliance + ── 0.38 tag ── + │ +v0.39.0 Stage Graph Engine + Form Builder ← graph execution + visual editing +v0.39.1 Stage Reorder + Bulk Ops ← queue management at scale +v0.39.2 SLA Alerting ← stale queues self-report +v0.39.3 Visitor Portal ← standalone branded experience +v0.39.4 Workflow Templates + Clone ← reuse across teams +v0.39.5 Analytics Dashboard ← throughput, bottlenecks, SLA compliance + │ +v0.40.x Polish (bug hunt, dead code, stabilize) │ ─ ─ ─ MVP v0.50.0 gate ─ ─ ─ ``` @@ -33,23 +82,65 @@ v0.38.5 Analytics Dashboard ← throughput, bottlenecks, SLA compl | Milestone | Gate | Meaning | |-----------|------|---------| | v0.37 tag | **UI Complete** | Every platform capability has a surface; no features require raw API calls | -| v0.38.0 | **Self-service** | A team admin can build a complete workflow without touching JSON or asking a global admin | -| v0.38.2 | **Operational** | Stale work surfaces automatically; team admins can manage queues without monitoring dashboards | -| v0.38.5 | **Measurable** | Team leads can answer "how long does stage X take" and "where are we bottlenecked" | +| v0.38 tag | **Extensible** | Extensions can load modules, manage connections, and compose libraries; git-board proves it | +| v0.39.0 | **Self-service** | Team admins build simple workflows visually; developers can add dynamic stages | +| v0.39.2 | **Operational** | Stale work surfaces automatically; team admins can manage queues without monitoring dashboards | +| v0.39.5 | **Measurable** | Team leads can answer "how long does stage X take" and "where are we bottlenecked" | --- -## v0.38.0 — Form Builder +## v0.39.0 — Stage Graph Engine + Form Builder + +**The foundational version.** Two deliverables: + +### 1. Stage Graph Engine + +The workflow execution engine gains awareness of node types. Each stage +in the workflow definition includes a `stage_type` field: + +```go +// Stage model additions: +type StageType string + +const ( + StageSimple StageType = "simple" // declarative form, built-in renderer + StageDynamic StageType = "dynamic" // Starlark hook returns form/routing + StageAutomated StageType = "automated" // no UI, Starlark only +) + +// Branching rule (declarative): +type BranchRule struct { + Field string `json:"field"` // form field key or context var + Op string `json:"op"` // eq, neq, gt, lt, contains, exists + Value any `json:"value"` // comparison value + NextStage string `json:"next_stage"` // stage ID to route to +} + +// Stage additions: +type Stage struct { + // ... existing fields ... + StageType StageType `json:"stage_type"` + BranchRules []BranchRule `json:"branch_rules,omitempty"` // declarative + StarlarkHook string `json:"starlark_hook,omitempty"` // package:function +} +``` + +The engine evaluates branch rules first; if no rule matches and a +Starlark hook is configured, it calls the hook. Default fallback is +next ordinal (existing behavior). + +For automated stages, the engine calls the Starlark hook immediately +on entry and auto-advances when it returns. + +### 2. Form Builder **The single biggest gap.** `form_template` is currently raw JSON in a textarea. The MVP gate says "build workflows visually" — this is the make-or-break. -### Scope - A visual form builder embedded in the stage editor (E2 from the .15 design). Not a standalone surface — it's a panel that opens when you -click "Edit Form" on a `form_only` or `form_chat` stage. +click "Edit Form" on a `simple` or `form_chat` stage. ### Fields supported (matching existing TypedFormTemplate) @@ -87,7 +178,6 @@ function FormBuilder({ initial, onSave, onCancel }) { required: false, }; if (useFieldsets && targetFieldset !== undefined) { - // Add to specific fieldset setFieldsets(fs => fs.map((f, i) => i === targetFieldset ? { ...f, fields: [...f.fields, field] } : f )); @@ -209,27 +299,24 @@ function FieldEditor({ field, onChange, onRemove, allFields }) { } ``` -### BE changes - -None. The form builder is pure FE — it produces the same -`TypedFormTemplate` JSON that already exists. The BE validation -in `models/workflow.go` is unchanged. - ### Deliverables | File | What | |------|------| +| `server/models/workflow.go` | `StageType`, `BranchRule` types; stage model additions | +| `server/engine/graph.go` | Graph execution: branch rules → Starlark hook → ordinal fallback | +| `server/engine/automated.go` | Automated stage runner (call hook, auto-advance) | | `src/js/sw/components/form-builder/index.js` | FormBuilder root | | `src/js/sw/components/form-builder/field-editor.js` | FieldEditor, type-specific validators | | `src/js/sw/components/form-builder/fieldset-editor.js` | Fieldset grouping | | `src/js/sw/components/form-builder/condition-editor.js` | Conditional visibility | | `src/js/sw/components/form-builder/preview.js` | Live form preview | | `src/css/form-builder.css` | Styles | -| Integration into StageEditor (E2 from .15) | "Edit Form" button opens builder | +| Integration into StageEditor (E2 from .15) | "Edit Form" button opens builder; stage type picker | --- -## v0.38.1 — Stage Reorder + Bulk Ops +## v0.39.1 — Stage Reorder + Bulk Ops ### Stage drag-and-drop @@ -297,7 +384,7 @@ patch. YAGNI for now. --- -## v0.38.2 — SLA Alerting +## v0.39.2 — SLA Alerting The monitor already computes `sla_breached`. This version makes it proactive instead of requiring someone to check the dashboard. @@ -340,31 +427,37 @@ The queue items (E1, E4) already render `sla_breached` badges. Add: --- -## v0.38.3 — Visitor Experience +## v0.39.3 — Visitor Portal -The visitor currently gets a raw workflow surface. After .15 they get -a terminal screen (E5) when their stages are done. This version makes -the visitor experience feel like a product. +The visitor currently gets a raw workflow surface embedded in the +app shell. This version delivers a **standalone branded portal** — +a dedicated URL with no chat chrome, optimized for the visitor +experience. ### Scope -1. **Branded entry page** — the workflow landing page already supports +1. **Standalone portal surface** — `/w/:id/:slug` renders a + full-page portal outside the app shell. No sidebar, no user menu, + no chat chrome. The portal renders the current stage's form + (simple or dynamic) and handles stage transitions. + +2. **Branded entry page** — the workflow landing page already supports branding (`accent_color`, `logo_url`, `tagline`). Extend with: - Custom welcome text (markdown) - Background image/gradient - "Powered by" toggle (hide/show Switchboard branding) -2. **Progress indicator** — visitor sees "Step 1 of N" for their +3. **Progress indicator** — visitor sees "Step 1 of N" for their visible stages only. Internal team stages are invisible. The progress bar counts only stages where the visitor is the audience. -3. **Email notifications** — optional. When configured on the workflow: +4. **Email notifications** — optional. When configured on the workflow: - Collect email at stage 0 (or extract from form data) - Send "request received" confirmation - Send "your request is complete" when workflow completes - No notifications for internal stage transitions -4. **Session resume** — visitor who closes the browser can return to +5. **Session resume** — visitor who closes the browser can return to `/w/:id/:slug` and resume where they left off. Already partially implemented via `sb_session` cookie. Polish the UX: show "Welcome back, pick up where you left off" instead of starting fresh. @@ -401,16 +494,15 @@ the workflow editor with a hint. /** * VisitorProgress — step indicator for visitor-facing stages * - * Mount: workflow surface, above the stage content + * Mount: workflow portal, above the stage content * Only counts stages where audience = visitor. */ function VisitorProgress({ stages, currentStage }) { - // Filter to visitor-facing stages only const visitorStages = stages.filter(s => !s.assignment_team_id); const visitorIndex = visitorStages.findIndex(s => s.ordinal === currentStage); const total = visitorStages.length; - if (total <= 1) return null; // Single stage = no progress bar + if (total <= 1) return null; return (
@@ -431,7 +523,7 @@ function VisitorProgress({ stages, currentStage }) { --- -## v0.38.4 — Workflow Templates + Clone +## v0.39.4 — Workflow Templates + Clone Team admins shouldn't rebuild common patterns from scratch. Two features: @@ -439,8 +531,9 @@ features: ### Clone workflow "Duplicate" button on the workflow editor. Creates a new workflow with -the same stages, form templates, and routing rules. New slug, new name -(appended "- Copy"). No versions carried over (must re-publish). +the same stages, form templates, branch rules, and Starlark hooks. +New slug, new name (appended "- Copy"). No versions carried over +(must re-publish). ``` POST /api/v1/teams/:teamId/workflows/:id/clone @@ -451,15 +544,16 @@ Pure BE operation — deep-copies workflow + stages, generates new IDs. ### Built-in templates -Seed a `workflow_templates` table with 3-5 common patterns: +Seed a `workflow_templates` table with common patterns covering both +simple and mixed workflows: -| Template | Stages | Description | -|----------|--------|-------------| -| Customer Intake | form → review | Public form, team reviews | -| IT Help Desk | LLM chat → triage → resolution | AI-assisted intake | -| Approval Chain | form → approve → approve → notify | Multi-level approval | -| Feedback Survey | form (multi-step) → analytics | Data collection | -| Onboarding | form → team A → team B → team A | Multi-team handoff | +| Template | Stages | Type | +|----------|--------|------| +| Customer Intake | form → review | Simple | +| IT Help Desk | LLM chat → triage → resolution | Simple | +| Approval Chain | form → approve → approve → notify | Simple | +| Smart Intake | automated (CRM lookup) → dynamic (tailored form) → review | Mixed | +| Onboarding | form → team A → team B → automated (provision) | Mixed | "New from template" in the team-admin workflow creation flow. Templates are read-only platform data, not user-editable. They @@ -469,11 +563,11 @@ serve as starting points — clone and customize. - "Duplicate" button in workflow editor header - "New from Template" option in workflow creation flow -- Template picker modal with descriptions +- Template picker modal with descriptions and type badges --- -## v0.38.5 — Analytics Dashboard +## v0.39.5 — Analytics Dashboard Team leads need to answer: how long does each stage take, where are we bottlenecked, what's our SLA compliance rate. @@ -555,30 +649,38 @@ too high on large datasets (unlikely at 50-user scale). | Version | Estimated CS | Heaviest piece | |---------|-------------|----------------| -| v0.38.0 | 4 | Form builder component tree (5+ files) | -| v0.38.1 | 2 | Drag-and-drop is fiddly but small | -| v0.38.2 | 3 | SLA scanner + notification plumbing | -| v0.38.3 | 4 | Visitor branding + email + progress | -| v0.38.4 | 2 | Clone is one BE endpoint + FE button | -| v0.38.5 | 3 | Analytics query + chart components | -| **Total** | **~18** | | +| v0.39.0 | 5 | Graph engine + form builder (10+ files) | +| v0.39.1 | 2 | Drag-and-drop is fiddly but small | +| v0.39.2 | 3 | SLA scanner + notification plumbing | +| v0.39.3 | 4 | Standalone portal + branding + email + progress | +| v0.39.4 | 2 | Clone is one BE endpoint + FE button | +| v0.39.5 | 3 | Analytics query + chart components | +| **Total** | **~19** | | --- ## Risk Notes -**v0.38.0 (Form Builder) is the long pole.** If this slips, the MVP -gate phrase "build workflows visually" fails. Prioritize this over -everything else in the series. If time is tight, ship a simplified -version (no fieldsets, no conditional visibility) and add those in a -patch. +**v0.39.0 (Graph Engine + Form Builder) is the long pole.** Two +major deliverables in one version. If this slips, the MVP gate phrase +"build workflows visually" fails. Prioritize this over everything +else in the series. If time is tight, ship the graph engine with +simple stages only (dynamic/automated as stubs) and a simplified +form builder (no fieldsets, no conditional visibility), then add +dynamic/automated execution and form builder polish in a patch. -**v0.38.3 (Email) depends on platform SMTP.** If SMTP isn't +**v0.39.3 (Email) depends on platform SMTP.** If SMTP isn't configured, the feature is invisible. Consider making the email config a prerequisite admin step with a setup wizard, or defer email -to v0.38.5 and keep .3 focused on branding + progress. +to v0.39.5 and keep .3 focused on the standalone portal + branding ++ progress. -**v0.38.5 (Analytics) can be cut.** If the series is running long, +**v0.39.5 (Analytics) can be cut.** If the series is running long, analytics is the most deferrable item — it's nice-to-have, not gate-blocking. The existing monitor + funnel endpoints cover the critical "is anything stuck" question. + +**Dynamic stage authoring DX.** Developers need clear docs and +examples for writing Starlark hooks. The git-board rewrite (v0.38.4) +should establish patterns, but workflow-specific examples are needed. +Consider a "dynamic stage cookbook" as part of v0.39.0.