fusion/docs/custom-workflows-mvp-spec.md

Custom Non-Coding Workflows MVP Spec (FN-5729)

← Docs index

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

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.