Visual Workflow Composer: design multi-stage workflows on a canvas and compile them into Squads

[mostafashokiel]

Summary

Add a workflow definition concept to Multica: a versioned, structured description of a multi-stage process (agent stages, human approval gates, conditions, rework loops). Teams draw it on a drag-and-drop canvas, and Multica compiles it into the primitives it already has: a Squad with a leader, generated leader instructions, a workflow skill, and stage labels. The same definition then drives a stage view of issues and, optionally, gate checks.

We're building a companion prototype for our own SDLC and would like to align with maintainers early, so that whatever we build can be contributed upstream in the shape you'd want.

Problem

Squads are a great routing primitive. When teams use them for multi-stage processes with human sign-off (requirements → stories → architecture review → build → QA → release), we run into four gaps:

1. The workflow lives in prose. The process is encoded in the leader's instructions. It's hard to review, diff, reuse across squads, or reason about (unreachable stages, unbounded rework loops, missing approvers).
2. There's no stage view. The board shows fixed issue statuses, while the real process stage is tracked by convention (e.g. phase:* labels, as in the community multica-workflow skill). Nobody can see at a glance where items wait or for how long.
3. Gates are advisory. Whether a human approval happened is decided by the leader agent's judgment. For teams in regulated environments, approvals need to be checked deterministically, not interpreted by a model.
4. Setup is manual and drifts. Creating labels, writing instructions, attaching skills and keeping them consistent across squads is repetitive, and nothing detects manual drift.

Proposal

1. Workflow definition (data, not prose)

A small declarative schema, stored and versioned per workspace (or as YAML in Git):

apiVersion: multica/workflow-v1
kind: Workflow
metadata:
  id: feature-delivery
  version: 3
target:
  squad:
    name: Delivery Squad
    leader: orchestrator-agent
approvers:
  product: [user:<id>]
  architects: [user:<id>]
start: requirements-review
stages:
  - id: requirements-review
    type: agent
    agent: requirements-reviewer
    skills: [requirements-checklist]
    next: requirements-approval
  - id: requirements-approval
    type: human_gate
    approvers: product
    on_approve: design
    on_reject: requirements-review
    max_rework: 3
    escalate_after_hours: 24
  - id: design
    type: agent
    agent: architect-agent
    next: risk-check
  - id: risk-check
    type: condition
    when: has_label("high-risk")
    then: security-approval
    else: design-approval
  - id: security-approval
    type: human_gate
    approvers: security
    on_approve: design-approval
    on_reject: design
  - id: design-approval
    type: human_gate
    approvers: architects
    on_approve: done
    on_reject: design
  - id: done
    type: end

Stage types: agent, human_gate, condition (a small expression language over labels, no arbitrary code), fan_out / join (one run per sub-issue, then roll up the parent), end.

Validation: unique ids, every stage reachable, an end reachable from every stage, every cycle bounded by a gate with max_rework, every gate has approvers, referenced agents and skills exist.

2. Visual composer

A canvas in the web app (React Flow / xyflow fits the existing Next.js frontend):

• Palette of stage types, properties panel with pickers for agents, skills and members, and live validation.
• Two-way sync with a YAML view. The definition is the source of truth; canvas positions are stored separately so layout changes don't create noisy diffs.
• Preview of the generated leader instructions and skill before applying.

3. Compile to existing primitives

"Apply" turns a definition into objects Multica already understands:

Output	Multica primitive
Squad, leader, members	Squads
Routing policy	Generated squad/leader instructions with a managed-by header
Stage table, entry/exit criteria, handoff protocol	Generated skill attached to the leader and stage agents
phase:<stage>, gate:<gate>-approved/-rejected	Labels
Approver lists, anti-loop rules	Workspace context

Apply should behave like plan/apply:

• It shows a diff first.
• It is idempotent: the same definition gives no changes.
• It only touches objects it manages.
• It reports drift when someone edits a managed object by hand.

flowchart LR
  A[Canvas / YAML] --> B[Validate]
  B --> C[Plan diff]
  C --> D[Apply]
  D --> E[Squad + leader instructions]
  D --> F[Workflow skill]
  D --> G[Labels + context]
  E & F & G --> H[Agents and humans work issues]
  H --> I[Stage view + gate checks]

Loading

4. Stage view

A board per workflow:

• Columns are the workflow's stages, in order.
• Cards show time in stage.
• Gate columns show the approver group and highlight items waiting longer than escalate_after_hours.

This is the view teams currently can't get from fixed statuses.

5. Deterministic gate checks (optional, later)

A server-side check, not an agent, that:

• Accepts approvals as a comment command (/approve <gate-id>, /reject <gate-id> <reason>) only from that gate's approvers, then sets the gate label.
• Flags or reverts transitions that skip a gate or don't follow the graph.
• Escalates stalled gates, and rolls up parent issues when all sub-issues reach end. As far as we can tell, parents don't currently change status automatically when children finish.

The leader agent still does the routing. The check makes sure the routing followed the definition.

Suggested phasing

Phase	Scope	Server changes
1	Schema, validator, compiler as a CLI/companion package (multica workflow validate/plan/apply)	None. Uses existing CLI/API
2	Visual composer in the web app	UI only
3	Stage view board per workflow	Read-only queries over labels/issues
4	Gate checks, escalation, parent roll-up	Yes: event handling and permission checks

Phases 1–3 add value without changing the core model. Phase 4 is where we'd most want maintainer guidance.

Alternatives considered

• Keep using prose instructions plus a label convention. This works today but can't be validated or visualized, and gates stay advisory.
• An external workflow engine (e.g. Temporal-style). Powerful, but it duplicates Multica's own issue, squad and agent model and adds heavy infrastructure for self-hosters.
• A companion tool only, never upstream. This is our fallback. A native concept would benefit more teams and avoid every group reinventing the same phase:* convention.

Open questions for maintainers

1. Does a first-class workflow definition fit Multica's vision, or would you rather keep it a convention on top of Squads?
2. Where should it live: core server object, a package in the monorepo, or a separate multica-ai/* repo?
3. Should the stage view use labels (as proposed) or a first-class stage field on issues?
4. For gate checks, would you accept server-side permission checks on specific labels or transitions, or prefer a comment-command protocol handled outside the core?
5. Is there an existing roadmap item or RFC this should merge into?

What we can contribute

We're prototyping phases 1–3 as a companion tool against a self-hosted instance, with the schema, validator, compiler (plan/apply/drift), designer and stage dashboard. We're happy to:

• Share the schema and design docs for feedback before writing more code.
• Contribute the schema and validator first, as small PRs following CONTRIBUTING.md.
• Adapt the design to whatever integration points you prefer.

Feedback on the overall direction would help us build this in a way that can be merged rather than forked.