root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

FN-5729: document custom non-coding workflow MVP spec

Browse Source 
Add a decision-ready MVP spec for user-authored non-coding workflows.

- Add docs/custom-workflows-mvp-spec.md covering user needs, minimal YAML contract, lifecycle mapping, mission relationship, one-week MVP slice, success metrics, and launch risks/open questions.
- Link the new spec from docs/README.md under Task & Project Management.

Files changed:
 docs/README.md                    |   1 +
 docs/custom-workflows-mvp-spec.md | 171 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 172 insertions(+)

Fusion-Task-Id: FN-5729

Fusion-Task-Lineage: 1d4e210a-b672-4846-8b39-220a399cb4fa
This commit is contained in:
gsxdsm
2026-05-30 13:03:11 -07:00
parent 5ff7f37c24
commit 797ee8df5e
2 changed files with 172 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/README.md
View File

@@ -34,6 +34,7 @@ For a full walkthrough (installation, onboarding, first task, and daily workflow
| [Research](./research.md) | Research runs, provider setup, dashboard/CLI usage, findings, exports, and task integration |
| [Research View UX Spec](./research-view-ux-spec.md) | Canonical layout and capability-state messaging spec for the Research dashboard view (FN-4138, informs FN-4134/FN-4135) |
| [Workflow Steps](./workflow-steps.md) | Reusable quality gates, templates, pre/post-merge phases, and workflow execution results |
| [Custom Non-Coding Workflows MVP Spec](./custom-workflows-mvp-spec.md) | Decision-ready MVP spec for user-authored non-coding workflow definitions, lifecycle mapping, metrics, and risk checklist |
| [Task Evaluations](./evals.md) | Eval scoring contract, evidence persistence, score categories, and evaluation pipeline |
| [Multi-Project](./multi-project.md) | Central registry architecture, project management, isolation modes, and migration paths |

171
docs/custom-workflows-mvp-spec.md Normal file
View File

@@ -0,0 +1,171 @@
# Custom Non-Coding Workflows MVP Spec (FN-5729)
[← Docs index](./README.md)
## Purpose
Define a one-week MVP that lets non-coding users declare and run custom workflows in Fusion, while reusing current workflow-step and lifecycle primitives where possible.
## 1) User-Needs Validation (v1 target users)
### User story 1 — Research ops lead
- **Who:** Product/research lead running weekly competitive scans.
- **What they do:** Trigger a multi-step flow (collect sources → summarize findings → produce decision memo).
- **Current pain:** Handoff between docs/spreadsheets/manual prompts is brittle and not repeatable.
- **Why Fusion helps:** Existing agents, task docs, and workflow gates can turn this into a reusable declared flow with observable state.
### User story 2 — Content operations manager
- **Who:** Content lead publishing launch briefs.
- **What they do:** Intake brief → draft copy → style/brand check → publish checklist.
- **Current pain:** Steps are tracked in chat threads; no durable execution record.
- **Why Fusion helps:** Task lifecycle + workflow-step verdict contracts already provide checkpointing and auditable outcomes.
### User story 3 — Support triage coordinator
- **Who:** Support manager routing high-priority tickets.
- **What they do:** Classify ticket → enrichment research → assign owner → produce response draft.
- **Current pain:** Routing quality varies by operator; escalation logic is implicit.
- **Why Fusion helps:** Declared states/transitions make routing policy explicit and measurable.
### User story 4 — Internal ops runbook owner
- **Who:** Ops generalist managing recurring incident-prep checks.
- **What they do:** Run a fixed checklist and collect artifacts for leadership review.
- **Current pain:** Runbooks live in docs but execution evidence is scattered.
- **Why Fusion helps:** Workflow-run artifacts can be persisted as task documents and reviewed through one lifecycle.
### Not solving in v1 (explicit cut list)
- Drag-and-drop visual workflow builder.
- Arbitrary external system actions (e.g., direct Jira/CRM writes) beyond existing Fusion tools.
- Multi-workflow orchestration/dependencies between workflows.
- Custom per-step RBAC model beyond existing toolMode/sandbox controls.
- Template marketplace/versioning.
## 2) Workflow-Definition Contract (minimum declarative schema)
### Proposed minimal contract
```yaml
id: "research-brief-v1"
name: "Research Brief Workflow"
entry:
taskTemplate: "Research brief: {{topic}}"
states:
- id: intake
- id: research
- id: synthesis
- id: review
- id: done
transitions:
- from: intake
to: research
- from: research
to: synthesis
- from: synthesis
to: review
- from: review
to: done
steps:
- state: research
mode: prompt
role: researcher
toolMode: readonly
gateMode: advisory
successVerdict: APPROVE|APPROVE_WITH_NOTES
- state: review
mode: prompt
role: reviewer
toolMode: readonly
gateMode: gate
successVerdict: APPROVE
artifacts:
required:
- key: findings
type: task_document
- key: summary
type: task_document
successCriteria:
- "All gate steps APPROVE"
- "Required artifacts exist"
```
### Mapping to existing primitives
| Contract element | v1 handling | Source alignment |
|---|---|---|
| `steps[].mode` prompt/script | **Extend existing** | `docs/workflow-steps.md` execution modes |
| `steps[].toolMode` readonly/coding | **Extend existing** | `docs/workflow-steps.md` tool-mode allowlist |
| `steps[].gateMode` gate/advisory | **Extend existing** | `docs/workflow-steps.md` gate semantics |
| `successVerdict` envelope | **Extend existing** | Structured verdict contract in `docs/workflow-steps.md` |
| States/transitions graph | **New (changed)** | Current system is lifecycle-fixed (`planning→...→done`) per `docs/architecture.md` |
| Role assignment (`role`) | **New (changed)** | Reuses agent role concepts but not currently workflow-declared |
| Artifact requirements | **New (changed)** | Leverages task documents but adds declarative requirements |
| `successCriteria` list | **New (changed)** | Complements existing completion semantics |
### Relationship to missions
- **Missions (`docs/missions.md`) remain decomposition/planning** (what to deliver: mission→milestone→slice→feature→task).
- **Custom workflows define execution behavior** (how a task runs through declared states/steps).
- v1 keeps them distinct: mission features may reference a workflow definition ID, but missions do not become workflow engines.
### v1 authoring surface decision
- **Chosen for v1: file-based YAML in repo (`.fusion/workflows/`)**.
- **Rationale:** fastest shippable path, reviewable in git, no immediate dashboard form complexity, aligns with one-week MVP.
- **Deferred to v2:** dashboard authoring/edit UI with validation and templates.
- **Explicitly not in v1:** dual-surface authoring (file + dashboard) to avoid sync/conflict complexity in the one-week slice.
### Persistence location (no implementation)
- v1 definition registry can be referenced from project settings (analogous to `settings.scripts` in `docs/settings-reference.md`), e.g., project setting storing file paths/active workflow IDs.
- Full dedicated workflow store is deferred to v2.
## 3) MVP Slice + Success Metrics
### Smallest end-to-end vertical (one week)
A non-coding operator can:
1. Add one YAML workflow definition.
2. Attach that definition to a new task.
3. Run the task through declared prompt/script steps using existing workflow-step engine behavior.
4. Observe run state + produced artifacts in task documents and workflow results.
Constraint: this vertical must ship without introducing a new workflow runtime separate from existing workflow-step execution.
### DONE criteria (Given/When/Then)
1. **Given** a valid workflow YAML with 3+ states and at least one gate step, **when** a task is started with that workflow ID, **then** Fusion executes declared steps in order and records per-step verdict output.
2. **Given** a step marked `toolMode: readonly`, **when** the assigned agent runs, **then** tool access is restricted to the existing readonly allowlist and violations fail closed.
3. **Given** required artifacts in the workflow definition, **when** run reaches terminal success, **then** all required task-document keys exist or the run is marked incomplete.
4. **Given** a gate step returns `REVISE`, **when** evaluation completes, **then** task follows existing revision-loop behavior rather than silently marking success.
### Out-of-scope guardrails (v2 deferrals)
- Workflow graph editor in dashboard.
- Cross-workflow triggers/event bus.
- External action connectors (Slack/Jira/Zendesk write-back).
- Advanced policy engine (per-step secret scopes, org-level approvals).
- Runtime migration/versioning of workflow definitions.
### Success metrics and instrumentation
1. **Time-to-first-run** (median time from workflow definition commit/registration to first completed run).
- **Telemetry status:** partially available via task/run timestamps; add explicit `workflow_definition_registered` and `workflow_run_started` events.
2. **Workflow completion rate** (% runs reaching success criteria without manual intervention).
- **Telemetry status:** needs new run-level status keyed by workflow definition ID.
3. **30-day adoption** (# distinct projects with ≥1 custom workflow run).
- **Telemetry status:** needs definition-ID tagging on task/workflow-step events.
## 4) Risks, Constraints, and Open Questions
### Conflicts with coding-tuned lifecycle invariants
- **Fixed lifecycle vs declared states:** `docs/architecture.md` assumes canonical task columns; v1 should map custom states onto internal step progression without altering board columns.
- **File-scope guards / `FileScopeViolationError`:** many non-coding workflows may be read-only and doc-artifact heavy; v1 should default to readonly/tool-limited steps and avoid introducing write steps that trigger code-oriented scope friction.
- **Squash-merge contract:** non-coding workflows may not produce code commits; success path should allow completion with zero code diffs when workflow is explicitly non-coding.
- **Self-healing expectations:** retry/recovery assumes coding task execution loops; v1 should constrain auto-retry semantics to step-level reruns without forcing branch mutation.
- **`autoMerge:false` semantics (AGENTS.md):** for projects with manual merge policy, `in-review` is terminal-until-human-merge, so custom non-coding runs must not be moved backward by self-healing routines after entering review/terminal states.
### Permissions and sandboxing
- Non-coding workflows should default to `toolMode: readonly` (`docs/workflow-steps.md`) with explicit opt-in to coding mode.
- For research-style flows, allow readonly file/docs inspection plus `fn_web_fetch` and insight/task-list tools; deny mutation tools by default.
- Sandbox posture should align with `docs/sandbox.md`: maintain port-4040 guard, deny unnecessary writes, and keep worktree/document boundaries explicit.
### CEO/CTO decision checklist (open questions)
1. Should v1 permit **any** `toolMode: coding` steps, or enforce readonly-only for launch safety?
2. Should custom workflow state names be user-visible only, while internal lifecycle columns remain unchanged?
3. Is file-based authoring acceptable for first launch, or is minimal dashboard create/select required for market validation?
4. What is the minimum telemetry event set required before launch (must-have vs nice-to-have)?
5. Should mission features be allowed to require a workflow ID at triage time in v1, or deferred?
## 5) Summary Recommendation
Ship a constrained v1 that reuses workflow-step primitives (prompt/script, gateMode, toolMode, verdict contract), adds a minimal declarative workflow definition contract, and limits launch to one file-authored workflow path with clear telemetry and safety guardrails. This delivers the CEO/CTO inversion-of-control goal in a week without destabilizing core coding lifecycle contracts.